> 约束即自由。给 AI 严格的框架，它才能在框架内交出可靠的工作。
> 本 Skill 的每个规则都必须通过检查点验证，未通过则阻断流程。
当 ReqPlan-v3 被激活时（用户表达了开发/修复/分析等意图），AI 必须立即执行以下流程，不得等待用户额外指令：
Step 1: 运行强制入口清单（见下方）
Step 2: 读取接力棒 → 确定当前状态
Step 3: 如果接力棒不存在 → 创建接力棒，状态 START
Step 4: 如果状态是 X → 直接从 X 阶段续跑
Step 5: 按状态路由表执行当前阶段任务
Step 6: 完成阶段任务 → 更新接力棒 → 自动进入下一阶段
Step 7: 重复 Step 5-6，直到 CONFIRM 或 DONE
> 🔗 自绑定条款（不可绕过）：
> - 本条 skill 的 所有规则、约束、状态机均无条件适用于一切被激活的场景，包括但不限于：
> 1. 常规开发/修复/分析任务
> 2. 元任务：审查/检查/修复本 Skill 自身
> 3. 元任务：评估本 Skill 的执行质量或完整性
> 4. 被 Task 子Agent 调用时的任何子任务
> - 以下理由 不构成绕过状态机的合法依据：
> - "我正在审查Skill本身，所以不需要走状态机"
> - "我先读取所有文件了解一下，之后再走状态机"
> - "我用Task子Agent来做，子Agent不需要遵守状态机"
> - "我不知道当前状态是什么，所以从零开始做"
> - 违规后果：如果在任何回复中发现AI绕过了状态机（未输出"当前状态"、未创建接力棒、未按阶段执行），用户可判定本 Skill 无效。
AI 不得：
/reqplan start 命令才开始规则：{项目路径} 的优先级
1. 用户明确指定的路径 → 使用该路径
2. 当前工作目录（本次对话的 cwd） → 使用该路径
3. 以上都不可用时 → 使用当前工作目录作为兜底
元任务路径选择（重要）：
当用户要求审查/检查/分析 Skill 本身时（元任务）：
- 优先使用当前工作目录下的 .trae/skills/{Skill名称}/ 路径
- 当前工作目录 = AI 本次对话的工作目录（cwd），通常是项目根目录
- Skill 名称对应的目录必须包含 SKILL.md 文件，否则回退到规则 1-3
- 如果当前工作目录下无 skills 目录，则回退到规则 1-3 的标准优先级
注意：元任务的接力棒文件依然存放在 `{项目路径}/.agent/harness/`，以保持产物路径统一。
即使你的任务是"审查 Skill 本身"（元任务），也必须选定一个项目路径。
不要让路径模糊成为跳过状态机的理由。
## 🚨 强制入口清单（激活后第一步必须完成）
在回答用户任何问题、执行任何分析、写任何代码之前，必须：
- [ ] 已确定项目路径（按规则 0）
- [ ] 已执行 read {项目路径}/.agent/harness/_baton.md
- [ ] 已确认接力棒存在与否
- 存在 → 解析当前状态，准备续跑
- 不存在 → 创建目录和接力棒，状态 START
- [ ] 已执行 write {项目路径}/.agent/harness/_baton.md（如果不存在）
- [ ] 已在回复**第一行**输出 "当前状态：[状态名]，下一步：[操作]"
**任何为未完成以上项目 → 禁止执行后续步骤 → 必须先完成入口清单**
**验证方式**：用户可在任何时候要求检查入口清单是否全部打勾。
这是 本 Skill 的最后一道自强制防线，在所有规则之上：
## 🛡️ 首次响应守卫
当 ReqPlan-v3 被激活时，AI 的**第一次回复**必须满足以下条件，否则视作违反本 Skill：
**条件一：回复第一行必须是** ✅
当前状态：[状态名]，下一步：[操作]
例：`当前状态：START，下一步：创建接力棒，进入 ANALYZE`
**条件二：回复中必须包含入口清单的明确执行记录** ✅
- 不能只是在心里想"已完成"——必须写出实际执行的命令结果
- `read {项目路径}/.agent/harness/_baton.md` → 显示文件内容或"文件不存在"
- `write {项目路径}/.agent/harness/_baton.md`（如不存在）→ 显示写入确认
**条件三：回复中不得包含实质性工作** ✅
（实质性工作 = 分析代码、搜索文件、写代码、修改文件、读取非入口文件的文档）
- 在 CONFIRM 阶段之前，**禁止执行任何不属于入口清单的操作**
- 如果用户的问题是"审查这个Skill"，第一次回复只能说"当前状态：START，正在初始化..."
- 执行分析/搜索/读取等操作必须等START→ANALYZE阶段
**违规检测规则**：
⚠️ 如果AI的第一次回复：
- 没有输出"当前状态"行 → 违反
- 直接开始读文件/搜索/分析 → 违反
- 输出"让我先看看文件结构" → 违反
- 直接使用Task子Agent执行实质性工作 → 违反
- 把入口清单在心里想一遍就当完成了 → 违反
**违反后果**：如果用户判定AI未通过"首次响应守卫"，用户有权要求AI立即停止并重新执行入口清单。
**条件性例外（修正）**：
- 状态转换（START→ANALYZE）属于"入口清单"流程的一部分，不视为"实质性工作"
- 即首次回复可以推进 START→ANALYZE 的状态转换和接力棒更新
- 但 ANALYZE 的实际分析工作（读文件、搜索、写分析报告）必须等第二次回复开始
每次回复结束时，必须检查：
- [ ] 我在本次回复中是否输出了 "当前状态" 和 "下一步"？
- [ ] 如果没有 → 说明已偏离状态机 → 立即返回并修正
> ReqPlan-v3 仅处理项目代码和用户直接提供的文本信息。使用过程中请遵循以下规范。
.agent/harness/ 目录中，不会上传到外部服务器或第三方服务以下为使用 ReqPlan-v3 过程中可能涉及的典型安全风险场景及处理规范：
| 风险类型 | 等级 | 具体场景 | 违规后果 | 正确做法 |
|---|---|---|---|---|
| --------- | ------ | --------- | --------- | --------- |
| SQL注入 | P0 | AI 在分析阶段建议拼接 SQL 字符串构建查询，如 f"SELECT * FROM users WHERE id = {user_input}" | 攻击者可构造恶意输入窃取、篡改数据库全部数据 | 强制使用参数化查询或 ORM，如 cursor.execute("SELECT * FROM users WHERE id = ?", (user_input,)) |
| 硬编码凭据 | P0 | AI 在产物或代码示例中直接写入 API Key、数据库密码、JWT Secret，如 SECRET_KEY = "my-secret-key-123" | 凭据泄露后可被用于身份仿冒、数据窃取、服务接管 | 使用环境变量注入：SECRET_KEY = os.getenv("SECRET_KEY")，模板中使用占位符如 your_secret_here |
| 越权访问 | P1 | AI 在接口设计中未包含权限校验，普通用户可以调用管理员接口，如未在 API 路由添加 @admin_required 装饰器 | 低权限用户可执行高权限操作，造成数据泄露或系统破坏 | 在 _design.md 的接口定义中明确标注每个接口的权限要求，实现时拦截非授权请求 |
| IDOR（不安全的直接对象引用） | P1 | AI 在代码中使用用户直接传入的 ID 查询资源而未验证所有权，如 db.get_order(request.args.get("order_id")) | 用户可通过遍历 ID 访问不属于自己的资源 | 添加所有权验证：order = Order.query.filter_by(id=order_id, user_id=current_user.id).first() |
> P0 = 必须修复：一旦发生即导致严重安全事件（数据泄露、系统入侵）\
> P1 = 建议修复：可能存在安全隐患，需要开发者评估风险和优先级
{项目路径} 占位符替代.agent/harness/ 目录建议加入 .gitignore，避免产物文件提交到公开仓库your_password_here），不得包含真实敏感值> 违反以上规范的处理：如果 AI 发现自身输出可能包含敏感信息，必须立即停止当前操作并通知用户。
> 用户发现产物中包含敏感信息时，有权要求立即删除相关产物并重新执行对应阶段。
| 当前状态 | 自动推进 | 必须做的事 | 禁止做的事 |
|---|---|---|---|
| ---------- | --------- | ------------- | ------------- |
| START | ✅ 自动 | 创建接力棒，进入 ANALYZE | ❌ 直接开始编码 |
| ANALYZE | ✅ 自动 | 读取 analyzer-agent.md，生成 _analysis.md，拉起 Quality Auditor 审核分析质量 | ❌ 跳过分析直接设计 |
| CONFIRM | ⛔ 等待用户 | 展示摘要，等待用户响应 | ❌ 自动进入下一阶段 |
| DESIGN | ✅ 自动 | 读取 _analysis.md 和 designer-agent.md，拉起 Quality Auditor 审核设计质量 | ❌ 不读分析就设计 |
| IMPLEMENT | ✅ 自动 | 读取 _design.md 和 implementer-agent.md，拉起 Quality Auditor 审核实现质量 | ❌ 不读设计就编码 |
| VERIFY | ✅ 自动 | 读取 _design.md 和 verifier-agent.md，拉起 Quality Auditor 做独立盲审 | ❌ 不读设计就验证 |
| JUDGE | ✅ 自动 | 读取 _verification.md，拉起 Quality Auditor 做六维度最终全局判定 | ❌ 不看验证报告就做判断 |
| DONE/ABORT/FAILED | 终止 | 输出最终报告，流程结束 | ❌ 继续执行 |
| DONE（新任务） | ✅ 自动重置 | 用户发起新任务时，AI 自动重置接力棒为 START（保留历史产物），直接进入 START 阶段引导新任务 | ❌ 不重置 |
当用户在状态机执行过程中（非 CONFIRM 阶段或 CONFIRM 阶段）提出额外需求、问题或调整要求时，AI 必须执行以下流程：
## 中断处理流程
1. [ ] 立即暂停当前阶段操作
2. [ ] 向用户展示 3 个选项：
> ⚠️ 我注意到您在流程执行中提出了新的需求/问题。
> 请选择处理方式：
>
> **① 立即重置**：中断当前流程，回到 ANALYZE 阶段重新分析并包含新需求
> **② 记入 TODO**：将新需求记入接力棒 "待办清单"，当前流程完成后自动重新发起任务
> **③ 仅讨论**：继续当前任务，暂不调整或新增（仅做讨论/解答）
3. [ ] 根据用户选择执行：
- **选项① 立即重置** → 更新接力棒状态为 ANALYZE（保留已有产物），记录中断原因和新需求，进入 ANALYZE 阶段重新分析
- **选项② 记入 TODO** → 在接力棒新增 "待办清单" 章节，记录新需求，继续当前阶段/流程。当前流程 DONE 后，自动触发 "DONE（新任务）" 规则重新发起任务
- **选项③ 仅讨论** → 回答用户问题/讨论后，继续当前阶段操作，不修改任务范围
4. [ ] 更新接力棒：记录中断时间、原因、用户选择
注意：此机制覆盖 AI "激活即执行" 的自动推进行为。当用户主动介入时，AI 应优先响应用户中断而非自动推进。
START → ANALYZE → CONFIRM → DESIGN → IMPLEMENT → VERIFY → JUDGE
↑ │ ↓
└────────┘ ┌─────────────────┼─────────────────┐
(修改) ↓ ↓ ↓
✅ DONE 🔧 DESIGN 🔄 IMPLEMENT
(修复模式) (重试模式)
当用户需求超出 ReqPlan-v3 能力范围时，AI 必须遵循以下引导规范，不得拒绝用户也不得随意承诺。
用户：帮我连接外部数据库并导出100万条数据
AI：当前技能无法直接执行数据库外部连接和大规模数据导出操作。
建议方案：
1. 我可以帮您生成数据库导出脚本（Python/Shell），您在本地执行
2. 需要我帮您分析数据库表结构并生成导出方案？
用户：帮我写一个电商网站，再帮我学英语
AI：我理解您有两个不相干的需求。
ReqPlan-v3 一次只能处理一个项目的任务。建议您：
1️⃣ 先完成电商网站的开发和交付
2️⃣ 完成后我自动触发"新任务重置"机制，再处理英语学习需求
请选择优先处理哪一个？
用户：帮我把整个系统从单体架构迁移到微服务，同时不改动任何代码
AI：从单体到微服务的架构迁移必然涉及代码改动（服务拆分、接口适配、数据分离）。
建议方案：
1. 先进行架构分析（进入 ANALYZE 阶段），评估影响范围
2. 制定渐进式迁移计划，分阶段实施
3. 如需"不改代码"的微服务化，可以考虑数据库层面读写分离作为过渡方案
是否先做架构分析？
> 更多超范围场景处理方式请参考 reference/anti-patterns.md 的反模式说明。
AI 在每个阶段的输出必须提供可验证的证据链：
read 命令确认写入成功flowchart TD），不得使用 ASCII 文字画框> 自检清单的权威来源：每个阶段执行时，Agent 自检清单以 artifacts/template-artifacts.md 中对应产物的"完成后检查清单"为最终标准。
> Agent 定义文件中的自检清单与之一致，如有差异以模板文件为准。
所有产物放在 {项目路径}/.agent/harness/：
| 文件 | 说明 | 生成阶段 |
|---|---|---|
| ------ | ------ | ---------- |
_baton.md | 接力棒（状态+进度+任务追踪） | START（持续更新） |
_analysis.md | 需求分析报告 | ANALYZE |
_design.md | 技术设计文档 | DESIGN |
_implementation.md | 实现摘要 | IMPLEMENT |
_verification.md | 验证报告 | VERIFY |
_quality_audit_analysis.md | 分析质量审核报告 | ANALYZE→CONFIRM 间 |
_quality_audit_design.md | 设计质量审核报告 | DESIGN→IMPLEMENT 间 |
_quality_audit_implement.md | 实现质量审核报告 | IMPLEMENT→VERIFY 间 |
_quality_audit_verify.md | 验证质量审核报告 | VERIFY→JUDGE 间 |
_quality_audit_judge.md | 最终全局判定报告 | JUDGE 阶段 |
长期归档（跨任务）：docs/harness/history.yaml、docs/harness/decisions.yaml
| 错误类型 | 策略 | 计入重试 | 说明 |
|---|---|---|---|
| ---------- | ------ | ----------- | ------ |
| ARCHITECTURE_VIOLATION | DESIGN(修复) | ✅ design_fix_retry | 架构问题，最多修复2次 |
| REVIEW_VIOLATION | IMPLEMENT(修复) | ❌ | 代码规范问题 |
| RUNTIME_FAILURE | IMPLEMENT(重试) | ✅ retry | 测试失败，最多2次 |
| ENVIRONMENT | 报告用户，等待处理 | ❌ | 需人工介入 |
| 意图 | 典型触发词 |
|---|---|
| ------ | ----------- |
| 代码开发 | "开发"、"实现"、"写"、"新增"、"创建" |
| Bug修复 | "修复"、"修"、"改"、"调整"、"出错了"、"报错了" |
| 设计评审 | "看看"、"审查"、"评审"、"分析"、"检查一下" |
| 需求规划 | "规划"、"方案"、"怎么做"、"如何"、"计划" |
| 文档完善 | "文档"、"写文档"、"补充文档"、"完善文档" |
| 架构重构 | "重构"、"架构"、"技术债务"、"重写" |
| 测试优化 | "测试"、"写测试"、"覆盖率"、"单元测试" |
| 命令 | 用途 | 详细指引 |
|---|---|---|
| ------ | ------ | ---------- |
/reqplan start | 启动引导，选择流程 | 进入 7 阶段状态机 |
/reqplan init | 初始化项目 Harness 目录 | 创建 .agent/harness/ + docs/harness/ |
/reqplan status | 查看当前状态 | 读取 _baton.md 展示进度 |
/reqplan guide | 智能引导下一步 | 按 chunk-01-guide.md 引导用户澄清意图 |
当您不确定应该使用哪个功能入口时，按以下决策流程选择：
flowchart TD
A[您的需求是什么？] --> B{需要做什么？}
B -->|开发新功能/迭代| C[开发模式]
B -->|审查/分析现有代码| D[分析模式]
B -->|修复Bug/排查问题| E[修复模式]
B -->|完善文档/补充文档| F[开发模式 → 文档完善流程]
B -->|架构优化/重构| G[修复模式 → 架构重构流程]
B -->|审查Skill自身| H[元任务 → 自绑定审查流程]
C --> I[完整7阶段状态机]
D --> J[可跳过IMPLEMENT阶段]
E --> K[完整7阶段状态机]
F --> L[可跳过DESIGN阶段]
G --> M[完整7阶段状态机]
H --> N[完整7阶段，禁止跳过]
| 判断条件 | 推荐流程 | 执行路径 | 详细指引 |
|---|---|---|---|
| --------- | --------- | --------- | --------- |
| 我想开发新功能、模块、API | 开发流程（流程1/4） | 完整7阶段 | SKILL-execution.md → 4.1节 流程1 |
| 我想做代码审查、设计评审 | 分析流程（流程3） | 可跳过IMPLEMENT | SKILL-execution.md → 4.1节 流程3 |
| 系统报错了，帮我排查修复 | 修复流程（流程4） | 完整7阶段 | SKILL-execution.md → 4.1节 流程4 |
| 我想写测试、提高覆盖率 | 测试优化流程（流程5） | 完整7阶段 | SKILL-execution.md → 4.1节 流程5 |
| 我想补充项目文档 | 文档完善流程（流程6） | 可跳过DESIGN | SKILL-execution.md → 4.1节 流程6 |
| 我要重构架构、清理技术债务 | 架构重构流程（流程7） | 完整7阶段 | SKILL-execution.md → 4.1节 流程7 |
| 我要审查/优化 ReqPlan 自身 | 自绑定审查流程（流程8） | 完整7阶段，禁止跳过 | SKILL.chunks/chunk-02-flows.md → 流程4 |
| 我不确定需求是什么 | 先引导 → 再匹配 | 先走 /reqplan guide | chunk-01-guide.md |
> 选择流程后，AI 会自动按对应路径执行状态机。无需手动指定阶段。
> 以下为使用 ReqPlan-v3 的常见问题。如需深入的技术细节和边缘场景（工具兼容、接力棒恢复、审核不通过处理等），请查阅 reference/faq-deep.md（10题深度FAQ）。
如果您不确定当前需求属于哪个模式，参照以下原则：
也可以直接描述您的需求，AI 会自动识别场景类型。详见上方的"功能选择决策表"。
输入 /reqplan guide 或直接告诉我您的大致目标，AI 会引导您逐步明确需求：
无需完整的 PRD 才能开始，逐步澄清即可。
可以。ReqPlan-v3 设计了专门的"用户中断处理机制"（见第5节）：
| 对比项 | 主文档 FAQ（本文） | 深度 FAQ（reference/faq-deep.md） |
|---|---|---|
| -------- | ------------------ | -------------------------------- |
| 定位 | 引导型FAQ，帮助快速上手 | 技术型FAQ，覆盖边缘场景 |
| 题量 | 6题 | 10题 |
| 覆盖范围 | 模式选择、入门引导、中断恢复、质量审核 | 工具兼容、接力棒恢复、多人协作、语言适配、产物回滚 |
| 适用人群 | 初次使用 ReqPlan 的用户 | 有特定技术问题的进阶用户 |
不可以。质量审核是阻断点，未通过审核不能进入下一阶段：
_quality_audit_{阶段}.md 中的"待修复问题清单"如需了解审核不通过的具体处理方式，请查阅 reference/faq-deep.md 的 Q3。
ReqPlan-v3 设计上适用于各类软件工程任务（开发、分析、修复、文档、测试等），主要面向编程项目。对于非编程项目（如纯文档编写、数据分析报告等），可以使用一部分功能：
但完整的状态机（含 VERIFY 阶段的代码验证）主要针对编程项目设计。对于非编程项目，可以在 CONFIRM 阶段明确说明项目性质，AI 会做适当简化。
| # | 问题分类 | 问题 | 核心要点 |
|---|---|---|---|
| --- | --------- | ------ | --------- |
| 1 | 模式选择 | 如何选择开发/分析/修复模式 | 新增→开发，审查→分析，修复→修复 |
| 2 | 入门引导 | 需求不清晰如何开始 | 输入 /reqplan guide，逐步澄清 |
| 3 | 中断恢复 | 流程中断后如何恢复 | 接力棒自动恢复，支持跨Session续跑 |
| 4 | FAQ体系 | 主FAQ和深度FAQ的区别 | 主FAQ引导上手，深度FAQ解决边缘问题 |
| 5 | 质量审核 | 审核不通过能否跳过 | ❌ 不可跳过，必须修复后重审 |
| 6 | 适用范围 | 是否支持非编程项目 | 部分支持，需在CONFIRM阶段说明 |
> 更多边缘场景和深度问题（共10题）请查阅 reference/faq-deep.md。
版本: v5.1 (TRACE 优化完善版)
更新日期: 2026-05-28
核心设计:
v5.1 更新内容（TRACE 优化完善版）:
共 2 个版本