项目规格与决策记录

将重要改动的原因保存在项目中。实施前写简短方案，实施后根据证据记录结果。保留决策，不收录聊天全文和日常工作流水账。

确认项目上下文

1. 阅读适用的项目指令，调查受影响的代码。
2. 检查已有 docs-ai/ 条目和相关设计记录。同一决策继续使用对应条目；已有权威规格通过链接引用，不复制成另一份需要同步维护的文档。
3. 使用实际承载改动的项目根目录。不在用户配置目录、无关父目录或其他项目中创建 docs-ai/。没有明确项目且位置会影响正确性时，先确定归属。

起草与讨论

新决策沿用现有编号顺序，选择下一个未使用的编号，至少三位数字，并使用简短的英文目录名：

docs-ai/NNN-short-slug/
  000-plan.md
  001-action.md
  002-topic.md

只创建当前阶段需要的文件，不覆盖或重新编号其他条目。写入前再次确认编号未被占用。不为存放规格而初始化版本管理或创建提交。

使用方案模板编写 000-plan.md，只保留有实际信息价值的章节。文档标题、正文和状态默认使用简体中文；文件名、代码块、代码标识符和命令使用英文。用户明确要求其他语言时遵从。引用已有英文规格时保留原文，不为统一语言重写无关文档。

方案必须明确：

• 用户可感知的目标、明确不做的事项和约束。
• 推荐方案、影响边界、重要备选及选择理由。
• 可观察的验收标准，以及每项标准的验证方式。
• 尚未确定的决策，以及需要哪些证据或用户输入才能解决。

每项验收标准使用稳定编号，如 AC-01。实施结果引用同一编号，不按结果重编号；新增项使用新编号，删除或替换项保留变更原因。每项写明必要验证条件、方法、环境和证据。必要性按目标和风险判断，不默认要求所有项目都跑真机或端到端测试。

独立审核是否为交付必要条件，也在方案中说明。重要功能默认需要独立审核；小修可自检并明确未独立审核。数据迁移、权限、支付和公共 API 的改动必须独立审核关键边界。确需调整必要验证或审核条件时，说明依据并解决重要范围变化，不能为宣布完成而事后降级。

向用户展示方案，简要说明需要关注的决策，并根据讨论更新草稿。实施前解决重要的产品、架构、API 和迁移选择。

用户已有确认或明确委托，在相应范围内视为完成对齐。记录依据后直接推进，不重复索取确认。未经确认的建议不能标为已定稿。仅要求讨论或编写规格，不等于授权实施。

定稿前可在授权范围内继续调查、临时实验和草稿整理，不实施尚未确定的设计。简单任务没有长期记录价值时，直接完成，不创建条目。

实施与结果记录

以定稿方案为基准，小范围实施偏差写入结果记录。新证据改变重要决策时，先说明取舍并完成对齐，再继续受影响的实施；已确认且仍在范围内的决策继续沿用。

实施完成后，使用结果模板编写 001-action.md。核对最终代码和实际验证输出，记录：

• 实际改动及每个验收编号是否达成，逐项填写通过、未通过、未验证、受阻或不适用及依据。不适用不能用于豁免已约定的必要条件。
• 真正执行过的命令或操作、观察结果和证据位置。
• 与计划的偏差及原因。
• 未解决问题、受阻检查和未验证行为。

分开记录实施、验证和审核状态，不用一个“已完成”概括三者。实施可为未开始、进行中或已完成；验证可为未验证、部分通过、通过、未通过或受阻；审核可为未审核、未独立审核、通过、有问题、未完成、已过期或不适用。每个状态注明范围和依据，审核通过不代替验收通过。

只有约定实施已完成、所有必要验收项通过，且必要审核针对最终版本通过时，才能报告任务完成。必要检查缺失或受阻时，即使代码已写完，整体仍为部分完成或受阻。非必要检查的限制也须披露。报告审核基线、目标版本、规格版本和证据版本；工作区内容摘要可用于识别未提交内容。状态及证据只覆盖对应版本，后续变更须评估影响并补审或补验，不能直接沿用旧结论。

工作中途停止且需要交接时，将整体结果标为部分完成，并列出剩余工作。仅记录“未验证”不能满足必要验收条件。

保留定稿方案作为决策基线。有价值的后续扩展或修正写入 002-<topic>.md 等文件，并链接相关旧记录。根本性更换方向时，在新的编号目录记录方案，将旧方案标为已被取代并链接新方案。明确说明事实纠正，不悄悄改写历史来迎合最终结果。

证据与维护

• 核实引用的现有文件和符号；计划新增的文件明确标注为拟新增，不写成现有实现。
• 区分观察事实、假设和未知事项。没有执行的构建或测试不能写为通过。
• 验证环境影响结论时必须注明。源码检查、构建、模拟器、真机和远端服务状态分别证明不同的事情。
• 不为获得通过结果而迁就实现修改测试或验收标准。确需调整标准时说明原因；重要范围变化先完成对齐。
• 优先链接项目内可长期访问的证据。必须引用本机或临时产物时注明限制。文档不保存凭据和用户隐私数据。
• 避免重复方案、空后续文件、聊天全文和日常进度日志。没有证据时，不把补写的历史决策当成事实。