docs-ai-prd

PRD、规格说明与项目上下文

工作流

1. 选择交付物。
2. 收集证据、约束和依赖项。
3. 为目标工具或团队工作流选择规范的上下文载体。
4. 先写决策。
5. 添加验收标准、发布门槛和有来源支持的事实。若交付工作跨越多个会话或由多名工作者完成，请添加交付里程碑表。
6. 交接前，使用相关检查清单进行验证。对于来源清单，运行 python3 scripts/validate_sources.py --scan-only；该命令会排除存档文件和符号链接，遇到无效或空的扫描根目录以及无法读取的来源文件时会以状态码 2 退出。清单验证成功并不代表声明或实时 URL 已经过核实。

快速参考

需求	从这里开始
核心 PRD	assets/prd/prd-template.md
AI 功能 PRD	assets/prd/ai-prd-template.md
技术设计	assets/spec/tech-spec-template.md
故事地图或待办事项规划	assets/stories/story-mapping-template.md
验收标准	assets/stories/gherkin-example-template.md
交付里程碑（多会话工作）	references/delivery-milestones.md
规划检查清单	assets/planning/planning-checklist.md
Agent 交接	assets/planning/agentic-session-template.md
最简 Agent 上下文文件	assets/minimal-claudemd.md、assets/minimal-agents.md
跨工具上下文分层	assets/cross-tool-context.md
特定技术栈的项目上下文（填空即可，无需从头编写）	assets/web-app-context.md、assets/api-service-context.md、assets/cli-context.md、assets/library-context.md、assets/react-context.md、assets/nodejs-context.md、assets/python-context.md、assets/go-context.md

专家判断：为什么规格说明会让编码 Agent 失败

交接前，检查 Agent 是否可能在满足书面要求的同时，产生作者并不想要的行为。

导致 Agent 运行失败的歧义类别

检查以下六类歧义：

1. 指代歧义——出现“用户”“表单”“它”等说法，却没有明确的名词短语、ID 或架构引用。Agent 会绑定到最接近的合理指代对象，但这往往不是作者心中所指的对象。
2. 默认行为未说明的歧义——从未提及某种情况（重复邮箱、空列表、并发编辑），于是 Agent 会自行设定默认行为。这个默认行为很少会与系统的其他部分进行核对。
3. 范围边界歧义——规格说明描述了新行为，却从未说明哪些内容必须保持不变。Agent 可能会对相邻代码进行过度重构，或留下没人要求移除的无用路径。
4. 时间／顺序歧义——步骤只作暗示，却没有明确顺序（“验证并保存”——应在无法撤销的副作用发生前还是发生后验证？）。
5. 度量歧义——“快速”“可靠”“安全”“整洁”等词没有对应的单位、阈值、百分位数或测试方法。
6. 权威性歧义——规格说明与现有代码不一致，却没有说明以哪一方为准。Agent 会自行选择一方；下一个 Agent（或下一次会话）可能会选择另一方。

过度指定与指定不足：如何校准判断

• 过度指定：只需关注结果，却规定了实现方式（指定某个库、确切的变量名、逐行伪代码）。代价：指定的方法不适合代码库时，Agent 会反复折腾；或者照字面实现，而不是实现原意，直到审查时才发现不匹配。
• 指定不足：只给出标题和一段说明，却对所有非正常路径都含糊其辞。代价：Agent 会自行设定契约细节（错误格式、重试次数、空状态行为），而这些细节可能与其他三个调用点中已有的假设冲突——事后发现代价高昂，事前却不会发现。

应根据三个变量校准细节程度，而不是依照习惯或模板长度：

影响范围	可逆性	Agent 自主程度	合适的细节程度
高（支付、身份验证、删除、个人身份信息）	低（难以回滚）	任意	明确规定每个边缘情况，并列出“绝对不能做”的事项
中	中	逐步监督（人工审查每个步骤）	说明决策和待解决的问题；让审查循环处理其余边缘情况
低（原型、内部工具、由功能开关控制）	高（回退成本低）	任意	说明结果和正常路径；让 Agent 提出边缘情况并标记出来
中或高	任意	无人值守／自主运行（完成前没有人工介入）	明确规定每个边缘情况——运行过程中没有审查者来发现偏差

验收标准的可测试性：清单之外的判断

references/acceptance-criteria-patterns.md 介绍了格式和常见错误。还有两个判断要点需要在清单之外考虑：

• “想不出会失败的测试”信号。 一条读起来不错、却无法生成任何测试的验收标准，是不可证伪的。如果你无法描述行为错误时会失败的具体测试，这条验收标准就还没写完——交接前先重写，不要直接交付并指望 Agent 推断出缺失的部分。
• “两位称职的工程师”信号。 规范中最常见的单点失效，不是缺少验收标准，而是同一条验收标准可以同时适用于两种实质不同的实现。问问自己：“两位称职的工程师能否构建出不同的东西，却都能诚实地声称满足了这条验收标准？”如果答案是肯定的，就添加一项用于区分的条款（具体的输入／输出组合、明确的错误代码、明确的顺序），直到答案是否定的。

决策与未知项台账

不要把尚未解决的产品选择写进声明式需求。针对每个未知项，记录所需决策、当前假设、负责人、截止日期或阻塞里程碑、受影响的需求，以及能够解决该未知项的证据。标记依赖该假设的验收标准，确保实施者不会将占位内容误认为已批准的行为。

代码仓库只能说明系统当前如何运行，不能说明业务需要什么。切勿从代码推断 SLA、定价、合规或留存义务、优先级或目标用户；应将这些内容列入台账，作为待确认的假设，直到用户或权威文档明确说明为止。只有当错误猜测可能导致安全风险、数据丢失、不可逆迁移、合同或 API 破坏、重大成本，或破坏性外部操作时，才因未知项而暂停并询问用户；否则，记录假设后继续推进。

如果实施过程中发现某项验收标准无法满足，不要将其删除，也不要默默绕过。将其标记为 [revised]，说明限制，调整其范围或验证方法，提升规范修订版本，并重新提交更改过的标准。只有当修订改变了阻塞性决策，或削弱了安全性或正确性保证时，才要求明确确认。

决策确定后，应同时更新需求及其验收标准，然后记录决策来源并关闭台账条目。只有在所有阻塞性未知项均已解决、明确延期至范围之外，或已转化为具有指定默认值和回退方案的安全运行时／配置选项后，PRD 才算可供实施。

跨工具上下文规则

将项目记忆视为分层结构。表格列出了各工具通常使用的表面；运行时实际加载哪些文件，以及加载优先级如何，应通过 agents-memory 中的查询步骤确认。

工具	主要表面	辅助表面
Claude Code	如果已验证每位贡献者的原生加载方式，则使用 AGENTS.md；否则使用导入 AGENTS.md 的 CLAUDE.md	限定范围的 Claude 文件、Agent、技能、钩子
GitHub Copilot	.github/copilot-instructions.md	其他 GitHub 指令、AGENTS.md
Cursor	.cursor/rules/ 或根目录的 AGENTS.md	根目录的 CLAUDE.md、限定范围的规则文件
可移植基线	AGENTS.md	通过链接引用更深层的指南，而非重复内容

Claude Code 是否会原生读取 AGENTS.md，以及两个文件同时存在时哪个优先，会随版本发布而变化：不要在规范中注明支持状态。将 AGENTS.md 作为唯一信息来源。遵循 agents-memory 查询步骤，并针对每位贡献者的版本、提供方和配置，通过 /memory 验证已加载的文件。如果已确认所有人都能原生加载，且没有 CLAUDE.md 系列文件抑制该加载方式，则无需桥接。否则，在 CLAUDE.md 顶部导入 @AGENTS.md（下方放置仅适用于 Claude 的内容），或使用 CLAUDE.md → AGENTS.md 符号链接。

质量关卡

PRD 和规范质量

• 问题陈述清晰，并有证据支持
• 指定负责人和成功标准
• 验收标准可衡量
• 指标包含公式、时间范围和来源
• 明确风险、发布关卡和回滚条件

AI 功能质量

• 记录基线替代方案
• 在构建前定义评估目标和数据集计划
• 涵盖权限、提示词注入和数据外泄风险
• 明确监控、事件响应和紧急停用开关

项目上下文质量

• 文件路径和命令与代码仓库一致
• 指南已路由到正确的工具表面
• 不包含机密或敏感数据
• 共享指令与工具专属指令之间不存在冲突

导航

参考资料 — 核心（先加载）

• references/agentic-coding-best-practices.md — 面向 Agent 的写作规则；处理任何规格说明或上下文文件任务时加载
• references/requirements-checklists.md — PRD、规格说明和上下文文件质量的关卡检查清单
• references/acceptance-criteria-patterns.md — Gherkin、EARS、表格和二元检查模式
• references/security-review-checklist.md — AI 功能的权限、注入和数据外泄关卡
• references/tool-comparison-matrix.md — Claude Code、Copilot、Cursor 和 Codex 的能力对比
• references/code-graph-spec-patterns.md — 代码图谱和多仓库上下文的规格说明模式
• references/docs-audit-commands.md — 审查现有项目文档的 shell 命令
• references/operational-guide.md — 快速入门入口和常见工作流方案；需要了解方向时加载

参考资料 — 规格驱动开发与提示词编写

• references/spec-driven-dev-landscape.md — GitHub Spec Kit、EARS 表述法、Kiro、BMAD-METHOD：流水线形态和查找步骤；用于规格说明关卡式 Agent 流水线时加载
• references/prompt-engineering-patterns.md — 面向聊天和编码 Agent 的任务约定、上下文打包和输出约定模式；在规格说明中编写嵌入式提示词时加载，并结合 assets/prompting/prompt-playbook.md 和 assets/prompting/structured-prompt-examples.md
• references/vibe-coding-patterns.md — 迭代式提示词与 Agent 循环、人类与 Agent 的角色划分及规范规则；用于快速原型开发或氛围编程工作流时加载

参考资料 — 代码库上下文提取

• references/architecture-extraction.md — 从现有代码库提取入口点、分层和数据流的分步命令；从零开始编写技术规格说明时加载，然后填写 assets/architecture-context.md
• references/convention-mining.md — 从代码库检测命名、文件和导入约定的脚本；填写约定部分时加载，然后填写 assets/conventions-context.md
• references/tribal-knowledge-recovery.md — 通过 git 历史和注释挖掘技术，找回未记录的决策；加入旧代码库时加载，然后填写 assets/tribal-knowledge-context.md

利益相关方与团队流程（由 product-management 负责）

• product-management 的 references/prd-review-facilitation.md — 评审类型选择、议程模板、反馈标注和迭代工作流；开展 PRD 评审时加载

• product-management 的 references/prd-stakeholder-alignment.md — RACI 映射、异步／同步评审模式、冲突解决和决策日志模板；管理多方签核时加载

• product-management 的 references/pm-collaboration-guide.md — 面向人工 PM 团队的访谈复盘结构和 PRD 交接；处理从利益相关方访谈到 PRD 的任务时加载

• product-management 的 references/traditional-prd-writing.md — 面向人工团队的 PRD 分章节指南（Cagan／Wiegers 系谱）；受众是 PM 团队而非编码 Agent 时加载

• data/sources.json

其他资源

• assets/metrics/agentic-coding-metrics-template.md — 当规范或试点需要衡量编码助手的影响时加载
• assets/key-files-context.md — 当需要在 CLAUDE.md 或 AGENTS.md 中记录 Agent 必须了解的文件时加载
• assets/dependencies-context.md — 当需要在 CLAUDE.md 或 AGENTS.md 中记录外部服务和集成时加载

规范产物的输出格式：HTML 与 Markdown

供 Agent 使用的上下文文件（CLAUDE.md、AGENTS.md、.cursor/rules/）应使用 Markdown。对于较长、只需阅读一次、面向人的产物（超过约 100 行的 PRD、对比选项的探索性规范、交互式规范），可以考虑使用 HTML；应确保验收标准可提取为表格或代码块，并在交互式规范末尾提供导出控件（“复制为 JSON / 提示词 / 差异”）。决策表、权衡分析和示例方案见：references/html-vs-markdown-output.md。

边界：docs-ai-prd 与 docs-codebase

• docs-ai-prd 负责需求、规范、验收标准和上下文文件策略
• docs-codebase 负责 README、运行手册、API 参考、变更日志和规范文档质量

如果你要决定 Agent 需要哪些上下文，或如何组织规范，请留在此处。如果你要重写仓库文档，请使用 docs-codebase。

相关技能

• ../docs-codebase/SKILL.md
• ../dev-context-engineering/SKILL.md
• ../dev-workflow-planning/SKILL.md
• ../qa-docs-coverage/SKILL.md
• ../product-management/SKILL.md
• ../software-architecture-design/SKILL.md

经验沉淀循环

当以往的决策或陷阱与当前任务相关时，如果存在 learnings.consolidated.md，请查阅该文件；只有在需要查看历史记录或该文件是唯一可用选项时，才使用 learnings.md。否则跳过这两个文件。

应用经验后，如果你遇到了值得记住的模式、值得避免的错误，或令你意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目符号。不要修改 SKILL.md 本身。