工作原理
req-kit 由三部分组成：对话中的 skill（/req 等入口和方法）、后台的流水线引擎（驱动第 3–11 步），以及两者共用的原则和文件约定。
Paseo 对话（/req） 流水线引擎（后台进程）
访谈 → spec.md → 独立审阅 → 用户确认
执行启动命令 ─────────────────────────────────► 检查条件，后台启动，立即返回
研发：方案设计 → 方案审核 ⇄ 修订 → 实现
→ 代码评审 ⇄ 修复 → 提测说明
┄┄ 闸口（分阶段时停在这里，等待提测）┄┄
验证：服务启动 → 功能验证 → 缺陷修复 ⇄ 复验
→ 完成报告
◄── 需要业务决定：问题 + 继续命令 ─────────────── （暂停，还没写代码）
◄── 进展 / 等待批准 / 中断原因 ──────────────────
◄── 结论 + 摘要 + report.md ────────────────────步骤
每个步骤是一个新的 Paseo agent，作为子 agent 挂在发起的对话下，名字形如 [20261012-sms-login] 6-代码评审 第2轮。步骤之间不靠对话记忆，只靠功能目录里的文件交接。
| 步骤 | 执行者 | 产物 | 什么时候执行 |
|---|---|---|---|
| 方案设计 | builder | design.md | 总是；开启方案提案时先由几个 agent 各提一份 |
| 方案审核 ⇄ 修订 | reviewer ⇄ builder | design-review.md | 标准档最多 2 轮；发现只有需求方能回答的问题时暂停并发回对话 |
| 方案确认 | 你 | preview.md、prototype/ | 标准档的界面改动：写代码之前请你确认"做完后会看到什么" |
| 代码实现 | builder | 代码、implementation.md | 适合时用 TDD；标准档方案分了几片就逐片实现，每片一个新的 agent |
| 代码评审 ⇄ 修复 | reviewer ⇄ builder | code-review.md | 标准档最多 3 轮；第一轮由规格评审和规范评审并行，再汇总（开启评审小组时由小组成员并行） |
| 提测说明 | builder | handoff.md | 总是；研发阶段的最后一步 |
| 服务启动 | builder | service-start.md | 项目有常驻服务、档位开启时 |
| 功能验证 | reviewer | verification.md | 总是（只做研发时除外）；按验收标准逐条给出证据 |
| 缺陷修复 ⇄ 复验 | builder ⇄ reviewer | verification.md | 发现缺陷时，最多 3 轮 |
| 完成报告 | builder | report.md | 只要没有暂停或中断就执行 |
builder 和 reviewer 是两个角色，在配置中各选一个 agent，建议用不同的模型。
按需求类型走不同的做法
需求说明的"类型"一行决定做法。步骤还是这些步骤，但每一步要多做或少做的事不同：
| 类型 | 做法 |
|---|---|
| 新需求、小改动 | 上表的流程 |
| 缺陷 | 方案设计改为复现与定位：先提交一个修复前失败的复现测试，找到根因再修；复现不了就停下来，把需要补充的信息发回对话 |
| 重构 | 先用特征测试锁住现有行为，再小步改动、每步全绿；评审首先看行为有没有变 |
| 评估 | 只读：调研评估 → 评估审阅 ⇄ 修订 → 评估报告，不写代码；报告附需求草稿，可以接着提新需求 |
质量门
项目配置了检查命令（lint、类型检查、单元测试、构建，通常由 /req-setup 写入）时，流水线自己运行它们，不只听 agent 说"测试通过了"：
- 每次尝试开始时先运行一遍，记下哪些检查原本就失败（基线）。
- 代码实现（每一片）、评审问题修复、缺陷修复之后再运行。改动前通过、现在失败的，把输出发回那一步的 agent 修复，最多 2 次。
- 仍然失败就照常往下走，交给代码评审和报告，报告的结论最高为"有遗留问题"。
代码评审前，流水线还会比对实际改动的文件和方案列出的文件，清单之外的交给评审逐一说明（范围检查）。多模块的项目，检查可以只在对应的模块有改动时运行；其他仓库（例如后端）可以登记为关联仓库，供各步骤只读参考。详见 项目定制与运行规则。
让结果更符合预期
结果不符合预期，多半不是代码写错，而是"做成什么样"的理解不同，直到验收才发现。req-kit 让分歧更早暴露：
- 验收标准带例子：每条验收标准都有具体的输入和期望输出，测试直接用它们作为期望值。验收测试先单独提交，之后被改过的要由评审确认有依据。
- 开工前确认：界面改动在写代码之前停下来，请你看
preview.md和静态原型，确认后再开工。 - 术语表：
GLOSSARY.md把你的说法和代码里的名字对上，各步骤按它命名。 - 评审分两个方向：规格评审看"做的是不是要做的事"，规范评审看"做得是否符合项目的标准"。
- 反复出现的问题变成规则：完成报告把一条规则就能挡住的问题记进
lessons.tsv，几个需求里反复出现的，需求总览会提示把它变成 lint 规则或测试。
联合需求：前端和后端一起改
需求说明写了"联合开发：后端"时，主仓库（发起需求的仓库）负责方案、接口约定、提测、验证和报告；后端由流水线新建一个工作区，和主仓库同时实现、评审、修复，各用各的检查命令和项目说明：
主仓库 方案设计 → 方案审核（含接口约定 contract.md）→ 实现 → 评审 ⇄ 修复 ┐
├→ 提测说明 → 一起验证 → 报告
后端（新工作区） 需求说明、方案、接口约定同步过来 → 实现 → 评审 ⇄ 修复 ┘验证时两边的服务都由 Paseo 启动；每个缺陷发回它所在的仓库修复。每个仓库各有自己的分支，合并顺序写在报告里，由人来合并。
三条基本规则
结论只看结果文件。 每一步最后写一个 JSON 结果文件（例如 {"verdict": "changes_required"}），流水线据此决定下一步，不解析 agent 的回复文字。缺失或格式不对时，在同一个会话里提醒补写。
做事的和检查的分开。 审核、评审、验证由 reviewer 完成；验证步骤只登记缺陷、不改产品代码。
如实。 报告从严判定："已完成，可以验收"要求所有验收标准都有通过的证据；没验证的就写"未验证"。
功能目录
一个需求的所有产物都在 docs/features/<日期>-<英文短名>/ 中，随代码一起提交：
docs/features/20261012-sms-login/
├── spec.md 需求说明（你确认的版本）
├── alignment.md 访谈记录
├── design.md 方案（缺陷另有 diagnosis.md，评估写 assessment.md）
├── design-review.md 方案审核
├── implementation.md 实现记录
├── code-review.md 代码评审与处理记录
├── handoff.md 提测说明
├── verification.md 功能验证与复验
├── report.md 完成报告
├── decisions.tsv 过程中的决定（需要你确认的会列进报告）
├── progress.md 每一步的时间线
└── .pipeline/ 运行状态、结果文件、日志（不提交）出了问题怎么办
- 临时错误（限流、网络中断）：自动等待重试；仍然失败时中断，并预约半小时后在对话里自动继续。
- 需要你决定：方案审核发现只有需求方能回答的问题，或者缺陷复现不了，流水线在写代码之前暂停，问题发回对话。回答并更新需求说明后继续，从方案设计开始增量处理。
- 你改了需求：继续时从方案设计开始，在已有方案和代码的基础上只处理变化的部分。
- 进程意外退出：执行继续命令即可，已完成的步骤沿用结果。