功能目录中由人和 /req 维护的文件
除 spec.md（见 spec.md）外，功能目录 docs/features/<日期>-<名称>/ 中还有以下约定格式的文件。
decisions.tsv
决策记录，由流水线各步骤追加。制表符分隔，UTF-8，第一行为表头：
time step ref decision alternatives reason kind needs_human| 列 | 内容 |
|---|---|
time | YYYY-MM-DD HH:MM |
step | 步骤名和轮次，如 代码评审 第2轮 |
ref | 相关的 FR / AC / CR 编号或文件，没有写 - |
decision / alternatives / reason | 各一句话，不含换行和制表符 |
kind | 假设 / 取舍 / 偏离方案 / 驳回意见 / 不修复 |
needs_human | yes / no。yes 的行会被完成报告列入"需要你确认的决定" |
changes.md
需求变更记录，由 /req 的"修改需求"手册追加，每次修改一节，新的在后：
## 第 2 版（2026-10-14）
- 变更内容：<改了哪些 FR / AC，新增或删除了什么>
- 原因：<需求方给出的原因>
- 对进度的影响：<流水线当时的状态；继续后从方案设计重新开始 / 尚未开始开发>
- 提出人：<姓名或角色>spec.md 头部的"版本"与最新一节一致。
handoff.md（提测说明）
1.7.0 起由流水线研发阶段的最后一步（"提测说明"）写入并提交。分阶段执行时它是交给测试的单据，连续执行时是功能验证的输入，"只做研发"时是人工测试的依据。六节：这次改了什么（按 FR，附分支和提交范围）、怎么跑起来、自测结果、建议重点测试、已知问题和未完成项、测试需要的准备（只写在哪里取，不写口令）。测试退回后修复时追加"第 N 次提测"一节。
test-env.md（测试环境说明）
1.7.0 起。在已部署的测试环境中做测试验证（--verify-env deployed 或配置 phases.verify.environment）时必须有，由 /req 的"开始测试验证"手册和用户一起写。流水线只使用其中列出的环境、账号和数据：
# 测试环境：<需求名称>
- 地址：https://<测试环境地址>
- 被测版本怎么确认：<版本号接口 / 页面底部的提交号 / 部署平台上的记录>
- 账号：<测试账号>，口令在 <环境变量 TEST_PASSWORD / 本机文件 ~/.config/xxx>（不写口令本身）
- 可以使用的测试数据：<数据范围、可以新建和删除的数据>
- 不能碰的：<共享数据、会触发外部通知的操作等>
- 清理方式：<测试数据如何清理>只能是测试用途的环境；不写任何生产环境的地址和凭据。
changes.md 中的"测试验证退回"
1.7.0 起，测试验证按 defects: handback 把缺陷退回研发阶段时，流水线在 changes.md 末尾追加一节"<日期> 测试验证退回（第 N 次）"，来源为"测试验证"，缺陷清单在 verification.md 最后一轮。研发阶段随后从方案设计开始只处理这些缺陷。
preview.md 与 prototype/（给需求方确认的预览）
1.8.0 起，方案确认点开启时（designApproval，默认标准档的界面改动）由方案设计写入，方案修订时同步更新。preview.md 五节：做完后你会看到什么（按操作顺序，注明 AC）、界面原型（列出 prototype/ 中的文件和对应的状态）、接口示例（改接口时）、需要你确认的假设（影响界面、数据、权限的）、不会变的。prototype/ 中是静态 HTML 页面，只用内联的 HTML 和 CSS，不引用外部文件、不连接服务，只用于确认，不是产品代码。需求方确认后，实现和功能验证都以它们为准。
diagnosis.md、assessment.md
1.8.0 起。缺陷类型的"复现与定位"写 diagnosis.md：现象与复现（复现测试或脚本的位置、命令、修复前的失败输出）、根因（带代码位置）、排除的其他原因、影响面、修复思路。评估类型的"调研评估"写 assessment.md（代替 design.md）：结论摘要、现状、可选方案（含工作量的大小和主要工作项）、推荐、风险与未知、如果要做（需求草稿）。
card.json（外部系统的卡片字段）
1.9.0 起。团队配置了外部系统对接（integrations）、且其中写了 cardFields 时，由 /req 在需求说明确认时和需求方一起确认后写入，与 spec.md 一起提交：
{ "title": "<卡片标题，可省略，默认用需求说明的标题>", "body": "<卡片描述，可省略，默认用 spec.md 全文>", "fields": { "<字段>": "<值>" } }fields 的名称来自 cardFields，在命令参数中写作 {card.<字段>}。没有写的字段用 defaults / integrationDefaults 中同名的值，都没有时这个参数和它前面的选项一起省略。
source.json、card-source.md、card-ai.md（从卡片开始的需求）
1.10.0 起。用 req start --from <系统>:<卡号> 从卡片开始的需求才有。
source.json 由引擎维护：
| 字段 | 含义 |
|---|---|
v | 格式版本，1 |
system、id、url | 对接配置中的系统名称、卡号、链接（没有时为 null） |
title、author、subsystem、state | 卡片的标题、提出人、子系统、状态（最近一次读取时） |
fetchedAt | 开始时读取卡片的时间 |
sourceRepo | 需求开始时所在的仓库（流水线之后可能把它移到自己的工作区） |
sessionAgentId | 需求会话的 agent ID |
originalHash、replyHash | 最近一次转给需求会话时，需求方的描述和回复的摘要；用来判断有没有新内容 |
confirmedAt、planConfirmedAt | 需求方的"确认：同意""方案确认：同意"转给需求会话的时间 |
progress、publishedAt | AI 区中的进度和最近一次写入卡片的时间 |
card-source.md 是卡片的副本（标题、卡号、状态、提出人、子系统，需求方的描述放在 <card-description> 中），由引擎在开始时和需求方修改描述后写入。card-ai.md 由需求会话写，是卡片 AI 区的正文（Markdown；问题用 - Q1、- Q2 编号），req card publish 把它写进卡片。
contract.md（联合需求的接口约定）
1.8.0 起，联合需求（spec 的 - 联合开发：）的方案设计在主仓库写入：每个接口一节，路径和方法、请求字段（类型、是否必填、取值范围）、响应字段、错误码和提示、一两组真实的请求和响应示例。方案审核通过后冻结，各仓库按它同时开发：提供接口的一边用示例写接口测试，调用的一边用示例做测试替身。主仓库的需求说明、访谈记录、方案、接口约定和预览在实现前同步到其他仓库工作区的同名功能目录并提交；其他仓库的实现、评审和缺陷处理记录写在它们自己的功能目录中。
lessons.tsv（可以变成规则的问题）
1.8.0 起，完成报告从评审意见、质量门和缺陷中挑出一条项目规则就能挡住的问题写入，没有就不写。制表符分隔，UTF-8，第一行为表头：
category finding source rule layer| 列 | 内容 |
|---|---|
category | 问题的类别，两到六个字，如"SQL 拼接"。同类问题在各个需求中沿用同一个名字 |
finding | 这次的问题，一句话 |
source | 出处，如 CR-3、缺陷 D-2、质量门 lint |
rule | 建议的规则，一句话 |
layer | lint / 类型 / 测试 / 项目说明 |
req digest 把在两个以上需求中出现的类别列为"反复出现的问题"。已经变成规则（或决定不做）的类别写在仓库的 .requirement-pipeline/lessons-handled.txt 中，一行一个，# 之后是注释，总览不再提示它们。
acceptance.md
验收记录，由 /req 的"验收"手册写。验收标准本身只在 spec.md 中维护，这里只记录结果：
# 验收记录：<需求名称>
- 验收结论：通过（2026-10-15） / 不通过（2026-10-15） / 进行中
- 验收人：<姓名或角色>
- 对照的需求版本：2
- 对照的报告：report.md（流水线结论：已完成，可以验收）
| AC | 结果 | 怎么验证的 | 备注 |
| --- | --- | --- | --- |
| AC-1.1 | 通过 / 不通过 / 未验 | <亲自操作 / 执行的命令> | <现象、截图路径> |
## 不通过的处理
- AC-2.3：<现象> → 作为缺陷处理 / 作为需求修改 / 接受现状（理由）start-pipeline --list 读取"验收结论"一行来显示"已验收"或"验收未通过"。
需求总览
需求总览不是一个提交进仓库的文件。每个需求在自己的工作区和分支上，共用的索引文件会在合并时冲突，所以总览由 start-pipeline --list 现场生成：扫描这个仓库所有 worktree 中的 docs/features/*/spec.md、状态文件和验收记录。
本页由仓库中的 contracts/feature-files.md 生成。在 GitHub 上编辑