--- title: AI友好型需求文档编写指南 - Agent 技能 type: article slug: ai-prd category: 智域 created: 2026-04-17 08:41:42 modified: 2026-04-17 08:41:42 author: reddish hits: 4 id: 369 catid: 19 keywords: PRD三原则 description: AI友好型需求文档编写技能 - 为 AI Agent 优化的 PRD 方法论 PRD三原则 AI友好型需求文档编写技能，指导 AI Agent 如何编写结构化、机器可读的需求文档。核心包括 PRD 三原则（指南、指导、守卫）、SSOT 单一事实来源、Markdown 表格格式规范。提供完整工作流程和实用模板，解决 AI 编程中的上下文腐烂和注意力飘忽问题。 language: * access: 1 featured: false url: https://srs.pub/agentia/ai-prd.html --- AI友好型需求文档编写技能，指导 AI Agent 如何编写结构化、机器可读的需求文档。核心包括 PRD 三原则（指南、指导、守卫）、SSOT 单一事实来源、Markdown 表格格式规范。提供完整工作流程和实用模板，解决 AI 编程中的上下文腐烂和注意力飘忽问题。# AI友好型需求文档编写指南 > **技能标识**：`srs-for-ai` > **允许工具**：read_file, write_file, edit_file, sessions_spawn, memory_search ## 触发条件 当用户出现以下需求时，应主动调用本技能或加载此文档： - "帮我写一份`需求文档` [^xuqiuwendangdebianxie]" - "帮我分析/设计XXX功能" - "帮我澄清一下XXX的需求" - "这个系统需要哪些模块" - "帮我完善这个方案" - 用户提供的需求描述模糊、不完整或前后矛盾 - AI生成的结果与用户期望存在明显偏差 ## 核心概念 ### 1. 为什么AI需要特殊的需求文档？ AI编程时代存在两大核心挑战： | 挑战 | 表现 | 原因 | |------|------|------| | **上下文腐烂** | AI越往后生成，错误越多 | 上下文过长导致"中间丢失"效应 | | **注意力飘忽** | AI偏离核心任务 | 长文本中AI难以识别重点 | **结论**：不能简单依赖扩充上下文解决问题，需要专门为AI优化需求文档。 ### 2. SSOT 单一事实来源 **定义**：Single Source of Truth，确保所有信息都从一个权威来源产生或引用。 **对AI的价值**： - 消除冗余和矛盾 - 保证信息一致性 - 提高AI理解准确性 **实践原则**： - 每条需求只在一个地方定义 - 其他内容必须引用SSOT - 避免"人类默契"式的省略 ### 3. PRD三原则 | 原则 | 作用 | 具体内容 | |------|------|----------| | **指南 (Guideline)** | 共享理解 | `项目背景` [^xiangmushituyufanwei]、技术栈、架构决策 | | **指导 (Guidance)** | 演进提示 | 示例、模式库、最佳实践、`陷阱` [^traps]警告 | | **守卫 (Guardrails)** | 质量卡点 | 代码审查标准、质量检查点、风险识别 | ## 格式规范：Markdown表格格式 ### 为什么表格最有效？ 研究发现，对于AI来说，Markdown表格格式是最有效的结构化形式： **优势对比**： - JSON/YAML：结构严格但冗余 - 自然语言：人类友好但冗余且模糊 - **Markdown表格**：结构清晰、信息密度高、上下文友好 ### 表格模板结构 ```markdown | 字段 | 值 | 说明 | |------|-----|------| | 功能名称 | [名称] | 简洁的功能描述 | | 输入 | [参数/数据] | 格式和约束 | | 输出 | [返回值] | 结果和状态码 | | 约束 | [限制条件] | 性能、安全、兼容性 | | 依赖 | [关联模块] | 前置条件 | ``` ## 工作流程 ### PRD完整工作流程 ``` 初始设置 → 需求设计 → 细化指令 → 实施 → 重构 → 更新 ``` | 阶段 | 输入 | 输出 | Agent任务 | |------|------|------|-----------| | **初始设置** | 项目背景 | 基本规则+项目概述 | 建立项目知识库 | | **需求设计** | 模糊需求 | 明确的功能列表 | 补充缺失信息 | | **细化指令** | 功能列表 | 结构化提示词 | 生成机器友好格式 | | **实施** | 结构化提示 | 代码/文档 | 验证生成结果 | | **重构** | 初版成果 | 高质量版本 | 优化和改进 | | **更新** | `经验教训` [^congjingyanzhongxuexi] | 修订版PRD | 完善文档 | ## 实际模板 ### 模板1：功能需求表 ```markdown | 功能ID | F-001 | 优先级 | P0 | |--------|-------|--------|-----| | 功能名称 | 用户登录 | | 简要描述 | 支持邮箱密码登录和验证码登录 | | 触发条件 | 用户访问需登录页面或主动点击登录 | | 正常流程 | 1.输入邮箱 2.输入密码 3.点击登录 4.验证通过跳转首页 | | 异常流程 | 邮箱不存在→提示注册；密码错误→提示重试(最多5次)；验证码错误→刷新重试 | | 输入参数 | email:string(邮箱格式), password:string(6-20位), code:string(6位) | | 输出结果 | success:{token, userId} / error:{code, message} | | 前置依赖 | 用户已注册 | | 约束条件 | 登录失败5次锁定15分钟；token有效期24小时 | ``` ### 模板2：接口规格表 ```markdown | 接口 | /api/user/login | 方法 | POST | |-------|------------------|------|------| | 描述 | 用户登录接口 | | 请求头 | Content-Type: application/json | | 请求体 | {"email":"string","password":"string","loginType":"email\|code"} | | 成功响应 | {"code":0,"data":{"token":"jwt","userId":123}} | | 失败响应 | {"code":1001,"message":"密码错误"} | | 错误码 | 1001:密码错误 1002:用户不存在 1003:账号锁定 | ``` ### 模板3：数据模型表 ```markdown | 实体 | User | 表名 | users | |------|------|------|-------| | 字段 | id | 类型 | bigint PK AUTO_INCREMENT | | 字段 | email | 类型 | varchar(255) UNIQUE NOT NULL | | 字段 | password_hash | 类型 | varchar(255) NOT NULL | | 字段 | status | 类型 | tinyint DEFAULT 1 | | 索引 | email, status | | 说明 | 用户状态:1正常 0禁用 | ``` ## Agent执行指南 ### 当用户要求编写需求文档时 1. **先搜索**：检查memory中是否有相关项目上下文 2. **澄清需求**：如果需求模糊，主动询问关键信息 3. **选择模板**：根据需求类型选择合适模板 4. **填充内容**：使用表格格式，遵循PRD三原则 5. **验证完备性**：检查是否有遗漏字段 ### 当需要完善不完整的需求时 1. **识别缺失**：找出信息空白点 2. **补充缺失**：按照表格结构补全 3. **保持一致**：引用SSOT，避免重复定义 4. **标注疑问**：不确定的地方用 `[待确认]` 标注 ### 质量检查清单 - [ ] 每条需求有唯一ID - [ ] 输入输出定义完整 - [ ] 异常情况已覆盖 - [ ] 约束条件已说明 - [ ] `依赖关系` [^prioritizerequirements]已标注 - [ ] 无歧义表述 - [ ] 使用表格格式 ## 常见陷阱与避免 | 陷阱 | 表现 | 避免方法 | |------|------|----------| | 模糊描述 | "用户可以方便地管理" | 量化指标："支持增删改查操作" | | 隐含假设 | "按常规方式处理" | 显式说明："邮件格式验证" | | 重复冗余 | 多处描述同一功能 | SSOT原则，只定义一次 | | 人类默契 | "大家都知道" | 显式写出所有信息 | | 过度细化 | 30+字段的表 | 按需取舍，保持简洁 | ## 参考资源 - 原文：https://srs.pub/thinking/srs-for-ai.html - Prompt Engineering Guide: https://www.promptingguide.ai/ - SSOT概念：单一事实来源，数据管理最佳实践 [^traps]: 需求分析中的常见陷阱. [^prioritizerequirements]: 需求生命周期管理中的优先级排序需求. [^xiangmushituyufanwei]: 项目目标与范围. [^congjingyanzhongxuexi]: 商业分析中的五十种分析方法和技巧之27-从经验中学习. [^xuqiuwendangdebianxie]: 需求文档的编写.