使用者指南

req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 Paseo 的对话里把需求讲清楚、确认一份需求说明，之后的方案设计、写代码、评审、测试和报告由一组 AI agent 在后台完成，结果发回同一个对话。

适合测试、产品经理、项目经理等不写代码、但熟悉需求和测试的同事。你不需要读代码，但可以随时查看每一步的产物，也可以亲自执行测试命令核对结果。

第一次使用之前

请开发同事确认这台机器已经装好 req-kit（/req-doctor 全部正常），并且项目已经接入：在项目根目录的对话中运行过 /req-setup，生成了项目说明和验证方法。测试同事熟悉项目的话，也可以自己运行 /req-setup。

提一个需求

1. 准备工作区：每个需求最好有自己的 worktree 工作区，几个需求可以同时进行，互不影响。两种方式任选：
   • 直接在项目的对话里开始，AI 问到时选"开发时自动新建工作区"：照常谈需求，启动开发时流水线会自动新建工作区并在那里开发，这个对话不用动。
   • 自己新建：在 Paseo 中点 New workspace → 选择项目 → Isolation 选 New worktree → 起点选主分支，然后在新工作区的对话里开始。
2. 输入 /req 和一句话：例如 /req 登录页增加短信验证码登录。用 Pi 时输入 /skill:req ……。
3. 回答问题：AI 会先复述它的理解，然后一次问一个问题，给出选项和推荐。它会问到异常情况、权限、已有数据、测试数据和验证环境，这些往往是你最清楚的。拿不准时可以说"你定"，它会采用推荐项并记为假设，最后请你过目。
4. 独立审阅（标准档）：确认之前，AI 会请另一个模型把需求说明独立审一遍，几分钟后把发现的问题（歧义、遗漏、没法验证的验收标准）逐个问你。这一步常常能省掉开发之后的返工。
5. 确认需求说明：AI 给出一份 10 行以内的摘要，完整的需求说明在 docs/features/<日期>-<名称>/spec.md。确认后它会问是否开始开发。
6. 等待：开发在后台进行，通常需要几个小时，不需要盯着。期间你会收到几句进展（方案定了、开始验证等）。

小改动（改文案、样式、一个配置项）会走快速流程：只问 2–3 个问题，开发环节各做一轮。

需求的类型：AI 复述时会和你确认这是哪一类，流水线按类型走不同的做法：

类型	说法举例	流水线怎么做	你需要讲清楚的
新需求	"加一个……"	方案、实现、评审、验证	要什么、怎么算做对
缺陷	"……不对""报错了"	先复现、找到原因再修；复现不了会回来问你	复现步骤：环境、账号或数据、操作、看到的、应有的
重构	"整理一下……""升级依赖"	先用测试锁住现有行为，再小步改，确认行为没变	改进目标，以及哪些行为必须保持不变
评估	"能不能做……""影响多大"	只调研、写评估报告，由另一个模型审阅，不写代码	要回答的问题，结论用来做什么决定

评估做完后，可以直接说"按评估结果提一个新需求"。

前端和后端都要改：另一个仓库已经由开发同事登记过（/req-setup 时登记）的，AI 会问是否作为联合需求一起做：流水线先设计整体方案和双方的接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证，报告里写明每个仓库的分支和合并顺序。

验收标准带例子：AI 写验收标准时会给每条配上具体的数据（"输入 13800000000，60 秒内再点发送，提示'请 45 秒后重试'"）。请认真看这些例子：它们会直接变成测试检查的期望值，你确认的就是测试会检查的东西。

开工前先看一眼"做完后会看到什么"（标准档的界面改动）：方案审核通过后、写代码之前，流水线会停下来，AI 把 preview.md 的要点讲给你听：会看到什么变化、有哪些需要你确认的假设；界面改动还会有静态的原型页面（功能目录的 prototype/ 中），可以在浏览器里打开看。说"可以"就开始写代码；想改的直接说，AI 会更新需求说明，方案调整后再请你看一次。这时调整的成本最低。

研发和测试分开做（标准档，确定档位时 AI 会问，团队配置里定好了就不问）：

• 连续（默认）：研发完成后流水线接着做测试验证，一次跑完。
• 分阶段：研发完成、写好提测说明（handoff.md）后停下来通知你："研发完成，可以提测"。你或测试同事准备好之后说"开始测试验证"，AI 会讲一遍提测说明，问清在哪里测（本地，或已部署的测试环境）、发现缺陷怎么办（当场修复、退回研发修复后再提测，或只记录），然后开始；也可以预约时间。用"开发时自动新建工作区"开发的需求，测试同事可以在自己的对话里输入 /req 开始测试验证 <需求名称> 接手。
• 只做研发：做到提测说明和研发报告为止，测试由人完成，验收时 AI 会按提测说明带你逐条测试。

过程中

你想做的	在对话里说
看进度	"做到哪了"（会说明当前在哪一步、agent 最近在做什么，例如正在运行测试）
暂停	"先停一下"（当前步骤做到一半的工作不保留，已完成的步骤保留）
继续	"继续开发"
确认方案	收到"请确认方案"时，看过之后说"可以，按这个做"，或者说要改哪里
改需求	"我想改一下……"：先暂停，谈清变化的部分，更新需求说明（版本加 1，记入 changes.md）后继续，开发会在已有方案和代码的基础上只处理变化的部分。开发已经完成的也可以改
看看项目里有哪些需求	"现在有哪些需求"：列出所有工作区中的需求和各自的阶段
研发完成后提测	"开始测试验证"（分阶段执行时）；想晚点开始就说"等测试环境部署好，明早 9 点开始测试"
晚点再开始	确认需求后说"今晚 10 点开始""明天早上开始"：到时会在这个对话里自动开始，说"先停一下"可以取消
接手别人的需求	"这个需求之前是同事提的，现在什么情况"：讲清现状、待决事项和下一步

也可以不进对话，在终端里用 req 命令（需要开发同事装好并加入 PATH，见 安装与升级）：在项目目录中 req list 看所有需求，req status 看进度（多个需求时写名称的一部分，如 req status sms-login），req stop、req resume 暂停和继续。

装了 req-kit 插件的话（见 安装与升级 第 13 节），在 Paseo 侧边栏点"需求"：本机所有项目的需求一页看完，"需要你处理"的排在最前；点开一个需求能看到每一步的进度和用时、读需求说明、方案、确认预览和完成报告，也可以直接确认方案、停止、继续或开始测试验证。网页端、桌面版和手机上都能用。

1.14 起，需求从开始谈的时候就出现在插件里（状态"对齐中"）；需求说明确认了却还没开始开发（超过 30 分钟），或者上次启动没成功的，会出现在"等你处理"里，点"开始开发"就能开始，进展照常发回谈需求的那个对话。

1.12 起，首页最上面是"等你处理"：所有等你确认方案、回答问题、中断了的需求，等得最久的在前，每条写明要做什么、等了多久。方案可以直接确认，也可以写修改意见；方案审核的问题可以直接写回答，插件会转给这个需求的对话，效果和在对话里回答一样。首页的"配置"列出 req-kit 的全部设置：每一项是什么、现在的值、来自本机、团队还是项目的配置文件，可以按项目查看、搜索、只看改过的。

在原型上提意见（1.13 起）。 界面改动的需求，在请你确认方案时会有一份界面原型。在插件首页的"等你处理"或需求页面最上面，点**"审查原型并确认方案"**按钮（终端里是 req review <需求>），原型审查页就在 Paseo 里打开（手机上会在浏览器中打开；嫌窗口小时点右上角"在新窗口打开"）：

• 标着 ①②③ 的是这次要改的地方，右边写着各自对应的验收标准，顺着看就不会漏。
• 想改哪里就点哪里，选一种改法（文字改成…、大一点、换颜色、换位置、删掉、这里加东西……），再用自己的话补一句。不用想专业词汇，你点的是哪个按钮、原来是什么颜色和大小，页面会自动记下来交给 AI。
• 想换文字就双击文字，直接改成你想要的字。
• 正常、出错、空数据这些状态，以及电脑、手机宽度，在页面上方切换。
• 写的意见会自动保存。看完后点"提交修改意见"，需求会话会据此改需求说明，改好后请你再确认；改过的原型再打开时，会用绿色框标出这一版改了哪里。没有要改的，点"同意开始写代码"。

还要多久（1.13 起）。 本机做完过 3 个以上同档位的需求后，开始开发时会告诉你这类需求通常要多久、用多少 token；问"做到哪了"或在插件的需求页面里，会看到"预计还要约多久"（不含等人确认的时间）。

每个步骤都会出现在这个对话的子 agent 列表里（名字形如"[20261012-sms-login] 6-代码评审 第2轮"），点开可以看到它在做什么。功能目录下的 progress.md 按时间记录了每一步的结果。

可能收到的通知（团队接入了企业 IM 的话，这些通知也会发到 IM）：

• 需要你决定：方案审核发现只有你能回答的问题。AI 会逐个问你，然后继续。一天没有回答的话，会在对话里提醒一次。
• 研发完成，可以提测（分阶段执行时）：代码已写完并通过评审，提测说明在 handoff.md。一天没有开始测试验证的话，会在对话里提醒一次。
• 等待批准：某一步在等权限批准，按提示打开对应的 agent 处理，或请开发同事处理。1.13 起插件的"等你处理"里也会显示，列出要批准的操作，点"打开这个 agent"直接去处理。
• token 用量提醒（团队设了 token 预算时）：用到预算的一定比例时告知一次，开发照常进行；用完时做完当前步骤就停下，AI 会告诉你用了多少、问你是否继续。继续会再给一份预算。
• 中断：限流、网络中断这类临时问题会先自动等待重试，仍然不行才中断，并预约半小时后自动继续（说"先停一下"可以取消）。AI 会说明原因和日志位置。环境类问题（例如测试服务没启动）你可以自己处理；涉及配置或代码的请开发同事处理。处理后说"继续开发"。

验收

完成后你会收到结论和摘要，完整报告在功能目录的 report.md：

• 验收对照表：每条验收标准的结果，以及是怎么确认的（运行了什么命令、看到了什么、截图在哪里）。
• 需要你确认的决定：开发过程中替你做的假设和取舍，以及被驳回的评审意见里会影响结果的那些。请逐条表态。
• 遗留问题和需要你做的事。
• 用时与用量：各步骤 agent 合计用了多长时间、多少 token、大约多少费用，便于估算后续需求的成本。

然后说"我要验收"。AI 会按验收标准一条一条带你核对：告诉你怎么操作、应该看到什么；能用命令验证的给出命令，你可以自己执行。每条结果记入功能目录的 acceptance.md。

代码审查（1.14 起，给开发同事和评审人）。 需求页面上点**"代码审查"**（终端里是 req code-review <需求>），代码审查页在 Paseo 里打开：

• 列出这次改动的全部文件（相对需求分支的起点，需求文档排在最后、默认折叠），上面是提测说明里"这次改了什么"。
• AI 代码评审的每条意见放在它说的那一行旁边，标着级别（阻塞 / 重要 / 建议）和修复步骤的处理结果（已修复、判为不成立、决定不修复）；可以标要改或不用改，补一句话。
• 点任意一行代码写意见；最下面可以写总体意见。
• 审核人默认取自仓库的 CODEOWNERS（按改动的文件），提交前可以改；以后建合并请求时会用它。
• 退回修改：意见写进 code-review.md 的"人工评审"一节（HR-1 起）和 changes.md，流水线随即开始新的一次尝试，需求说明不变，从方案设计开始只处理这些意见，改完再经过 AI 代码评审和验证，进展发回需求的对话。评审通过：记下评审人和审核人；之后代码又有改动时，页面会提示需要重新评审。

在插件里自己验收（1.14 起）。 需求页面上点**"验收清单（可一键试用）"**（终端里是 req checklist <需求>），验收清单在 Paseo 里打开：

• 每条验收标准写着前置条件、怎么操作、应该看到什么，以及流水线的验证结果；流水线没验证或没通过的排在最前面，报告里"需要你确认的决定"也列在后面请你表态。

• 右上角**"把它跑起来试用"**（终端里是 req try <需求>）：用项目的 Paseo 服务脚本（paseo.json）在这个需求自己的工作区里把它启动起来，给出访问地址和提测说明里的测试账号、数据；用完点"停止试用"。项目没有服务脚本时，会给出提测说明里写的启动方法，也可以在需求的对话里说"帮我把它跑起来"。

• 每条点"通过"、"不对"（写下看到了什么）或"先不验"，进度自动保存。必须验的都核对完才能提交"通过"；有"不对"的就提交"不通过"。

• 提交后写成 acceptance.md 并提交。不通过时，不对的地方会转给这个需求的对话，它会和你一起确定怎么处理。

• 全部通过：请开发同事审阅代码并合并上线。流水线只做本地提交，不会自己合并或上线。

• 有不通过的：逐项决定怎么处理：做得不对的，补进需求说明后继续开发；发现想要的不是这样的，按改需求处理；也可以接受现状并记下理由。

测试同事可以把验收标准直接转成测试用例：每条都写成了"前置条件 / 操作 / 预期结果"。

记录会留下来（1.14 起）。 代码审查和验收的结论、评审人、每条意见都写在需求目录的 code-review.md、acceptance.md（退回修改的原因在 changes.md）里，随需求分支提交，合并后在主干上也能查。结论和数量另外记在本机的使用记录里，req stats 能看到人工评审退回了几次、验收通过率、合并进主干的需求和合并后发现的问题。

上线后发现问题

说"线上发现……不对"。AI 会先问这个问题是否正在影响真实用户：是的话，请马上联系开发同事或值班人员处理线上情况（req-kit 不碰生产环境）。然后它会问清现象、复现步骤、影响范围，关联到原来的需求，生成一份缺陷说明，按快速流程修复，修复后照常验收。缺陷说明里写明是哪个需求引入的问题，req stats 会把它算作那个需求"合并后发现的问题"；也可以在终端里手动记一笔：req outcome <需求> --issue "<问题>"。

注意

• 一个对话只谈一个需求；对话过程中不要切换工作目录。
• 需求属于另一个项目时，到那个项目里新开对话。
• 遇到"未启动"或其他看不懂的情况，输入 /req-doctor 做一次体检，或请开发同事看一下。

本页由仓库中的 docs/guide/使用者指南.md 生成。在 GitHub 上编辑