第七章：新的文档范式

AOSE时代文档从静态记录转变为驱动执行的核心资产。BDD的Given-When-Then结构是连接人类需求与Agent执行的关键语言，配合项目级提示词与架构约束，共同构成人机协作的"活契约"。

1 重新审视敏捷宣言

2001年的敏捷宣言提出了一个至今仍被引用的价值观：

工作的软件 高于 详尽的文档

这句话常常被误读为"不需要文档"。但敏捷的本意并非如此——它强调的是价值优先级：如果一份文档不直接帮助交付工作的软件，它的优先级就应该降低。文档是手段，软件才是目的。

然而，在面向智能体的软件工程（AOSE）时代，这一价值观需要被重新审视。当AI Agent成为主要的执行主体时，我们发现：文档的形态决定了Agent的执行质量。模糊不清的文档会导致Agent"幻觉"，产生与需求不符的代码；而精确、结构化、可被Agent准确理解的文档，则能大大提升Agent一次做对的概率。

于是，AOSE对敏捷宣言给出了新的诠释：

Agent友好的表达方式 快速构建 可执行的软件

这里的"Agent友好的表达方式"是一种能被AI准确理解的需求描述形式——它既是人类思维的表达，又是机器可解析的执行指令。它不再只是"记录"，而是直接驱动软件开发的核心资产。

2 传统文档的三重困境

在深入探讨新范式之前，让我们先看看传统文档体系为何在AI时代难以为继。

静态性与滞后性：文档已死

BRD、PRD、TRD一旦定稿就趋于僵化。在传统开发中，文档与代码的偏离是常态——开发团队为了应对变化直接修改代码，却忘记同步更新文档。三个月后，文档描述的功能与真实系统已大相径庭。这种"文档已死"的现象让人宁愿读代码也不愿看文档。

在AOSE中，这一问题变得更加严重：如果Agent基于过时的文档生成代码，后果将是灾难性的。

模糊性与歧义性：AI幻觉的温床

自然语言本质上是模糊的。“用户体验好”、“性能高”、“适当展示"等描述在不同人脑中有不同解读。人类开发者可以通过沟通澄清歧义，但AI Agent面对模糊描述时，会基于训练数据"脑补”，产生难以预料的偏差。

这种"未定义状态"正是大模型幻觉的根源——Agent被迫自行填补信息空白，而这些填补往往与业务预期背道而驰。

执行断层：翻译链条中的信息损耗

传统文档无法直接驱动行为。业务人员写BRD，产品经理翻译成PRD，开发人员再翻译成代码，测试人员翻译成测试用例。每一次翻译都是信息衰减和错误引入的机会。

在AI时代，我们希望Agent直接理解需求。但自然语言文档与实现代码之间存在巨大鸿沟——Agent无法确定"提升用户体验"具体意味着什么。

3 BDD：连接人类需求与AI执行的桥梁

在AOSE中，BDD（Behavior-Driven Development，行为驱动开发）语言不再仅仅是一种测试工具，而是演变成了人类向AI Agent描述需求的高级需求表达语言。

Gherkin语法：需求的结构化表达

BDD最具代表性的语言形态是Gherkin语法。它通过高度结构化的自然语言格式（Given-When-Then），将人类的业务需求精准地转化为机器可以解析、验证和执行的指令。

案例对比：自然语言的歧义 vs BDD的精确

传统自然语言（模糊需求）：

“作为一个高级会员，如果我买的东西超过100块，结账的时候应该给我打九折。”

潜在歧义：普通会员呢？刚好100块打折吗？打折是算在运费前还是后？

BDD语言（精准需求）：

Feature: 购物车结算折扣规则

  Scenario: 高级会员满100元享受九折优惠
    Given 用户 "张三" 的会员等级是 "VIP"
    And "张三" 的购物车内商品总价为 "105.00" 元
    When "张三" 发起 "提交订单" 动作
    Then 系统计算的最终应付金额应为 "94.50" 元
    And 系统的订单状态应更新为 "待支付"

在BDD表达中，需求被清晰地锚定在"前置条件"、“触发动作"和"断言结果"上，没有任何歧义空间。

BDD与LLM Prompt的同构性

BDD之所以在AI时代如此高效，是因为它完美契合了大语言模型（LLM）的认知和推理机制：

直接将BDD剧本喂给Agent，Agent能够瞬间理解它需要构建什么样的系统逻辑。这种结构化的需求表达，正是消除AI幻觉的关键。

4 AI友好的新文档范式

在AOSE中，传统文档（BRD/PRD/TRD）被重新组织为两类面向AI的规范文档，既保持人类可读性，又具备机器可解析性：

1. 需求文档：人类向AI描述"想要什么”
2. AI智能体的规范文档：人类向AI规定"如何工作"

这两类文档共同构成人机协作的契约——前者确保Agent理解正确的业务目标，后者确保Agent以正确的方式实现。

需求文档

取代：BRD（业务需求说明书）+ PRD（产品需求说明书）

核心问题：我们期望达成什么目标？在什么场景下？用户应该如何感知？成功如何衡量？

需求文档使用BDD语言将业务目标与产品功能统一描述，不再区分"为什么要做"和"要做什么"，而是将价值主张与具体场景直接关联：

Feature: 提升付费会员权益感知
  作为业务负责人
  我希望在会员中心展示"优先处理"徽章
  以便提升年费会员的尊贵感和续费意愿

  Background:
    Given 当前年费会员续费率为62%
    And 客服咨询中35%与"优先处理权益"相关

  Scenario: 年费会员查看徽章
    Given 用户已登录
    And 用户会员等级为"年费会员"
    When 用户访问"会员中心"页面
    Then 页面应展示金色"优先处理"徽章
    And 徽章位置应在用户名旁边
    And 徽章颜色应为#FFD700

  Scenario: 普通会员不显示徽章
    Given 用户已登录
    And 用户会员等级为"普通会员"
    When 用户访问"会员中心"页面
    Then 页面不应展示"优先处理"徽章

  Scenario: 业务价值达成
    Then 会员权益知晓率应提升至68%
    And 续费率应提升至少5%
    And 权益相关客服咨询应减少50%

关键要素：

• 业务背景与价值主张（Feature描述 + Background）
• 功能场景与用户体验（Scenario）
• 正常/边界/异常场景覆盖
• 明确的验收标准（Then断言）
• 可量化的成功指标（业务Then）

需求文档的核心价值在于消除歧义。自然语言的需求描述往往充满隐含假设（“用户体验好”、“适当展示”），而BDD的Given-When-Then结构迫使需求方将每一个需求锚定在具体的条件、动作和结果上，让Agent无法"脑补"，只能精确执行。

AI智能体的规范文档

取代：TRD（技术需求文档）+ 开发规范文档

核心问题：Agent在什么边界内工作？如何确保质量符合项目标准？

AI智能体的规范文档不是描述某个具体功能的实现方案，而是定义Agent在项目中普遍适用的工作方式和质量边界。它分为两个相互关联的层次：

两者共同构成技术规范的持久化知识库，确保Agent在正确的边界内以符合项目标准的方式工作。

第一层：项目级提示词（Project-Level Prompts）

定位：Agent进入项目的"入职手册"，回答"在这个项目中我应该如何工作"

典型文件：

• .cursorrules（Cursor IDE）
• CLAUDE.md（Claude Code）
• .ai-context.md（通用）

内容结构：

# 项目技术规范

## 技术栈与架构
- 后端：Python FastAPI + SQLAlchemy
- 前端：React + TypeScript + Tailwind
- 数据库：PostgreSQL 14+
- 缓存：Redis Cluster

## 编码规范
- 所有API必须使用Pydantic模型进行请求/响应校验
- 数据库查询必须使用参数化，禁止字符串拼接SQL
- 异步函数统一使用`async`/`await`，禁止混用线程池

## 项目结构

src/ api/ # 路由定义，禁止包含业务逻辑 services/ # 核心业务逻辑 models/ # SQLAlchemy模型 schemas/ # Pydantic模型 infrastructure/# 缓存、队列等基础设施

## 特殊约束
- 用户表`users`的`id`字段是雪花算法生成，不是自增ID
- 所有涉及金额的计算必须使用`Decimal`类型，禁止float
- 遗留系统`legacy_order`表只读，禁止写入

价值：

• 让Agent在接收到具体任务前，已经理解项目的技术上下文
• 避免Agent在每次任务中重复询问"你们用什么框架"“代码放哪里”
• 将项目特定的约定（如"金额必须用Decimal"）编码为Agent可直接遵循的指令

第二层：架构约束（Architecture Constraints）

定位：通过自动化工具强制执行的质量边界，回答"什么是不允许的"

实现形态：

1. Lint规则（代码风格与基础质量）

# .pylintrc / pyproject.toml
[tool.ruff]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
ignore = ["E501"]  # 行长度由black处理

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.mypy]
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = true

2. 架构守护规则（复杂性与依赖控制）

# archunit.py - 架构测试示例
import archunit

class ArchitectureTest:
    """确保架构约束不被破坏"""

    def test_api_should_not_access_repository_directly(self):
        """API层禁止直接访问Repository，必须通过Service层"""
        archunit.assert_that("src.api").should_not_depend_on("src.repositories")

    def test_domain_should_not_depend_on_infrastructure(self):
        """领域层禁止依赖基础设施层（整洁架构）"""
        archunit.assert_that("src.domain").should_not_depend_on("src.infrastructure")

    def test_cyclomatic_complexity_should_be_below_10(self):
        """圈复杂度超过10的函数必须重构"""
        archunit.assert_complexity().is_less_than(10)

3. 安全与合规扫描（强制性边界）

# .semgrep.yml
rules:
  - id: no-raw-sql-in-api
    pattern-either:
      - pattern: requests.post(..., data=$X, ...)
    message: "API层禁止直接构造SQL，必须使用ORM"
    severity: ERROR

  - id: no-hardcoded-secrets
    pattern-regex: '(api_key|password|secret)\s*=\s*["\'][^"\']+["\']'
    message: "禁止硬编码密钥"
    severity: ERROR

价值：

• 自动化守门：Agent生成的代码必须通过所有约束检查才能提交
• 防止退化：即使Agent不断生成新代码，架构质量不会劣化
• 约束即质量：将"高质量"的抽象需求转化为可验证的具体规则

关键认知：

技术规范文档不是静态的"说明书"，而是人与Agent协作的"活契约"——项目级提示词提供沉淀下来的共同知识，架构约束通过自动化工具强制执行质量边界。两者共同确保Agent在正确理解业务需求的基础上，以符合项目标准的方式实现功能。

5 本章小结

从敏捷宣言的"工作的软件高于详尽的文档"，到AOSE的"Agent友好的表达方式，快速构建可执行的软件"，文档的角色经历了根本性转变。

核心转变

关键理念

1. BDD是需求的表达语言：Given-When-Then结构完美映射LLM的认知模式，消除歧义，防止幻觉

2. 文档即契约：需求文档与AI智能体规范文档构成人机之间的协作契约，Then语句直接转化为验收标准

3. 文档即代码：需求文档存储于版本控制，与代码一起演进，变更驱动自动化测试和实现更新

4. 约束即质量：技术需求通过项目级提示词和架构约束，将质量要求编码为可自动验证的规则（详见第8章）

5. 工作的软件仍然是目的：Agent友好的表达方式是手段，交付价值才是目的。文档的详尽程度应与业务风险和系统复杂度相匹配——如果缺少文档会导致Agent产生幻觉或引入系统性风险，就必须编写需求文档；如果代码本身足以表达需求，就不必额外文档。

在面向智能体的时代，优秀的产品经理不是写最多文档的人，而是能用最精炼的结构化语言表达最精确需求的人。这种能力——将模糊的业务需求转化为无歧义的Given-When-Then结构——将成为软件工程最核心的技能。