Skip to content

AGENTS.md

Latest commit

 

History

History
342 lines (232 loc) · 26.9 KB

AGENTS.md

File metadata and controls

342 lines (232 loc) · 26.9 KB

全局协作约定

Python 项目包管理

  • 所有 Python 项目必须统一使用 uv 和项目内虚拟环境进行包管理。
  • 不得直接改动系统 Python 环境；依赖安装、运行和测试都应通过项目虚拟环境完成。

修改频率约定

为避免主观描述，本模板所有"修改频率"列统一使用以下四档：

档位 含义
仅初始化 项目立项 / 设计阶段一次性确定，后续基本不动
低频 协作约定或用户可见能力变化时才更新，单次会话内通常不动
随代码同步 与代码改动同 PR / 同次提交一起更新
每次会话同步 每次代理改动代码前后都必须回写

项目核心元文件（5 个，所有项目强制）

每个项目必须有以下 5 个文件，职责互不重叠：

文件 角色 修改频率 谁可以改
plan.md 大纲：定位 / 功能清单 / 数据模型 / 接口 / 验收标准 仅初始化 仅在 fix_<desc>.md 归档时（按需修正描述偏差）或 fix-plan_<desc>.md 最终确认后（新增 / 修订 plan 内容）回写；除明显的拼写错误外，禁止直接编辑
ARCHITECTURE.md 架构：代码目录分工 / 新增代码归属规则 / 项目启动与调用顺序流程 仅初始化 新增代码找不到合适归属时，或用户明确要求调整架构时
AGENTS.md 代理协作说明：状态约定、文件分工、同步要求、代理执行细节 低频 协作约定变化时
README.md 用户说明：项目用途、安装或打开方式、使用流程、配置说明、隐私与常见问题 低频 用户可见能力或使用方式变化时
TODO.md 执行台账：所有步骤 / 子项 / 阻塞 / 来源；既含待做也含已完成 每次会话同步 代理改动代码前后必须回写

概括：plan 管大纲，ARCHITECTURE 管代码组织，TODO 管具体执行，AGENTS 管代理协作，README 管用户说明。 测试与审查闭环由按需补充文件 fix_<desc>.md 承担（详见下文专节）。

按需补充文件（非强制，触发后创建）

以下文件不属于核心元文件，仅在满足触发条件后创建。每份文件职责单一，不与核心元文件重复。

文件 触发条件 修改频率 是否纳入默认读取
fix_<desc>.md 用户要求代码审查 / 安全审计 / 计划复核，或提供具体测试反馈 随代码同步（具有特殊地位，详见下文专节） 是（所有未归档批次按文件名排序）
fix-plan_<desc>.md 用户提出 plan 之外的新功能 / 新模块 / 验收标准扩展 随代码同步（写入 plan 的入口，详见下文专节） 是（所有未归档批次按文件名排序）
HUMAN.md fix_<desc>.md / fix-plan_<desc>.md / TODO.md 出现代理无法完成的人工事项，或出现需要人类决策且会影响项目方向、范围、架构或验收标准的问题时 低频 是（若存在）
INTERFACE.md 项目存在对外接口（前后端 / API / CLI / SDK 等）即必须创建 随代码同步 否（按需读取）
TEST.md 项目复杂 且 用户明确要求代理进行测试时；代理自发测试不创建 低频（仅在用户主动要求测试时更新） 否（按需读取）
NICKNAME.md 项目专有术语 ≥ 5 个时建立；< 5 个先在 AGENTS.md 中管理 低频 是（术语表优先读取）

HUMAN.md 补充文件

  • HUMAN.md 是按需补充文件，不要求每个项目默认存在。
  • 当 fix_<desc>.md / fix-plan_<desc>.md / TODO.md 中出现代理无法完成的事项时创建或更新，例如真实浏览器人工验收、登录账号验证、实体设备测试、外部权限操作。
  • 当代理发现会影响项目定位、功能边界、架构取舍、外部接口承诺或验收标准的 人工决策、AI 困惑 或 方向风险 时，也应创建或更新 HUMAN.md，而不是静默猜测。
  • HUMAN.md 不负责项目计划、开发 TODO、用户教程或审查闭环；只记录需要人类执行、确认或决策的事项、影响范围、状态、期望结果和反馈回填格式。
  • 代理应把自己无法完成或不应擅自决定的事项打包提交到 HUMAN.md；人类可随时通过修改条目状态、反馈或完成结果介入。代理暂停触碰受影响范围，同时继续推进其他不依赖该人工输入的可执行 TODO。
  • 阻塞具体执行的 HUMAN.md 事项必须对应一个原本的 TODO.md 条目，避免人工任务脱离执行台账。仅记录方向性决策或代理困惑、尚未阻塞具体执行项时，可先引用来源文件或会话上下文；一旦阻塞可执行工作，必须创建或确认对应 TODO。

INTERFACE.md 补充文件

  • 定位：管理项目所有对外接口的具体定义，供外部调用方、前端联调、第三方测试人员查阅。
  • 必须创建的场景：项目存在前后端接口、对外暴露的 HTTP/RPC API、CLI 命令、SDK 公开方法等任一种对外接口。
  • 应写内容：接口路径 / 方法 / 请求参数 / 响应格式 / 错误码 / 鉴权方式 / 调用示例。
  • 不写内容：内部模块间的私有调用、实现细节、性能优化记录。
  • 与 plan.md 的边界：plan.md 写"需要哪些接口"（What），INTERFACE.md 写"接口的具体定义、参数、返回值"（How）。
  • 修改频率：随代码同步，每次接口签名变化必须同步更新。接口变更不需走 fix 闭环。
  • 读取规则：不纳入默认读取顺序；仅在外部调用、前端联调、接口变更时按需读取。

TEST.md 补充文件

  • 定位：管理项目所有测试方法和流程的索引文档。
  • 创建条件：必须同时满足两点：项目已变得复杂，且用户明确要求代理进行测试。代理自发的小范围测试不触发创建。
  • 应写内容：测试分类（单元 / 集成 / E2E）、运行命令、测试数据准备方式、覆盖率目标、特殊环境依赖。
  • 不写内容：具体 bug 反馈（属于 fix_<desc>.md）、人工验收步骤（属于 HUMAN.md）。
  • 与 fix_<desc>.md 的边界：TEST.md 是测试方法本身（怎么测），fix_<desc>.md 是测试反馈的闭环（测出了什么问题）。
  • 更新触发：仅在用户主动要求进行测试时更新；代理日常运行测试命令不触发更新。
  • 读取规则：不纳入默认读取顺序；仅在用户要求测试时按需读取。

NICKNAME.md 补充文件

  • 定位：项目专有术语和命名取向说明，帮助新接手的代理或开发者快速理解项目内的特殊词汇、缩写、别名和命名习惯。
  • 创建条件：当项目内出现的专有术语数量 ≥ 5 个时建立专用文件；少于 5 个先在 AGENTS.md 中开辟一节管理，超过阈值后整体迁出到 NICKNAME.md。
  • 收录标准：满足以下任一条件即应收录：
    • 词义与大众理解明显不同（用户在本项目内对常见词的特殊定义）。
    • 用户自造的项目专有名词。
    • 后续开发者无法快速理解的缩写或代号。
  • 应写内容：术语 → 简短定义 → 一句话使用场景或例子；必要时记录旧称 / 别名 / 不应混淆的相近词。
  • 不写内容：通用编程术语、行业标准词汇、文档中已有充分上下文的临时代号。
  • 修改频率：低频。每次代理在会话中识别到新术语即追加。
  • 读取规则：纳入默认读取顺序，作为术语表优先读取；在读其他元文件前先读 NICKNAME.md，确保后续阅读时不被术语阻塞。

README.md 与 AGENTS.md 的边界

  • AGENTS.md 只给代理和自动化协作者阅读，记录协作规则、执行流程、状态同步、文件分工、注意事项和约束；不写面向用户的安装教程、功能介绍、使用指南、宣传文案或 FAQ。
  • README.md 只给最终用户阅读，记录项目是什么、能做什么、如何安装或打开、如何使用、如何配置、隐私说明、限制与常见问题；不写代理规则、内部 TODO、开发计划、测试命令、代码结构说明、审查记录、实现过程或任何仅开发者关心的内容。
  • 同一信息只放在它所属的文件中：用户需要知道的放 README.md，代理需要遵守的放 AGENTS.md，避免两边重复维护。

ARCHITECTURE.md 内容规范

ARCHITECTURE.md 应包含但不限于以下内容：

  • 目录结构与分工：列出顶层及关键子目录，说明每个目录的职责边界，以及新增代码应归属哪个目录的判断规则。
  • 模块依赖关系：各模块 / 包之间的依赖方向，禁止循环依赖的约束。
  • 启动与调用顺序：项目的入口文件、初始化顺序、核心调用链（可用流程图或有序列表描述）。
  • 扩展点约定：约定新增功能、新增模型、新增接口时应遵循的位置和命名规范。

ARCHITECTURE.md 不写具体实现细节、算法逻辑、数据格式定义（这些属于代码注释或 plan.md）。

模板修改边界

  • AGENTS.md 是项目代理协作协议。普通项目内的协作规则变化默认只修改当前项目 AGENTS.md。
  • 除非用户明确要求修改模板或明确要求把规则同步到模板，否则不得修改上游模板。
  • 针对上游模板本身的维护动作不写入下游项目 TODO.md；TODO.md 只记录当前项目的执行事项、代码事项和项目内元文件事项。

关键规则

新项目启动流程

任何采用本协议的新项目，必须按以下顺序产生文件，禁止跳步或并行创建：

  1. 第一个文件：AGENTS.md（从模板复制）。在生成任何其他元文件之前，先把 AGENTS.md 落到项目根，作为后续所有动作的协作约束基准；不得在它之前创建任何其他元文件。

  2. 第二个文件：plan.md，必须经过充分讨论后方可定稿。 总体原则为：讨论阶段充分发散，写入阶段严格收敛。

    • 讨论阶段（充分发散）：代理应主动与用户进行深入讨论，至少覆盖：项目定位、功能清单、数据模型、对外接口、验收标准；并主动识别计划中的潜在漏洞、未覆盖的边界场景、模糊的验收口径；代理可在讨论中延伸提出衍生功能、潜在风险、可选方案。
    • 提问机制：每一处不确定之处必须主动提问并等待用户确认，不得以猜测或默认值随意填入。
    • 写入阶段（严格收敛）：将内容写入 plan.md 时必须分两层处理：
      • 优先层 — 用户明确需求：用户已明确表达的需求必须全部落实，不得遗漏或自行裁剪。
      • 延伸层 — 代理建议：代理在讨论中提出的衍生想法、扩展功能、边界处理建议，必须逐项获得用户明确许可后方可写入 plan.md；未获许可的建议仅保留于讨论记录，不进入 plan。
    • 最终确认：plan 草稿完成后，必须由用户给出最终确认（"plan 定稿"或同等明确表态），代理方可将 plan.md 写入项目根，并进入后续步骤。

  3. plan.md 定稿并经用户最终确认后，再依次创建其余核心元文件：ARCHITECTURE.md → TODO.md → README.md。fix_<desc>.md 始终按需，不预建。

  4. 按需补充文件在触发条件满足后再创建，不在新项目启动阶段批量预建。

进入已有项目时

  1. 检查核心元文件是否齐全；缺哪个补哪个（plan.md / ARCHITECTURE.md / AGENTS.md / TODO.md / README.md 必有；fix_<desc>.md 与 fix-plan_<desc>.md 均按需创建）。
  2. 检查按需补充文件的触发条件是否已满足（如对外接口存在但缺 INTERFACE.md、专有术语 ≥ 5 个但缺 NICKNAME.md），缺则补建。
  3. 默认读取顺序：NICKNAME.md（若存在，术语表优先读取）→ 所有未归档 fix_<desc>.md（若存在，按文件名排序）→ 所有未归档 fix-plan_<desc>.md（若存在，按文件名排序）→ HUMAN.md（若存在）→ TODO.md → AGENTS.md → ARCHITECTURE.md → plan.md；需要确认用户使用方式时再读 README.md。
  4. INTERFACE.md / TEST.md 不纳入默认读取，仅在外部调用 / 前端联调 / 接口变更 / 用户要求测试时按需读取。

fix_.md：按需创建，但具有特殊地位

fix_<desc>.md 虽然属于按需补充文件，但它是修正 plan 描述偏差的唯一入口（与之对应，新增 plan 内容由 fix-plan_<desc>.md 承担）。它的地位与其他按需文件不同，单独成节说明。

命名规则

  • fix_ 后接对本批次内容的简短语义描述，使用小写连字符风格，例如 fix_gesture-scoring.md、fix_cold-start-bug.md、fix_ui-layout-review.md。
  • 禁止使用纯序号（如 fix_01.md），因为序号无法从文件名判断内容。

创建时机

仅在以下两种情况创建，代理不得擅自创建：

  • 用户手动要求做代码审查 / 安全审计 / 计划复核。
  • 用户提供具体测试反馈（人工验收发现的 bug、E2E 失败、外部 agent 的报告等）。

同期多份

同期可同时存在多个 fix_<desc>.md，分别代表不同审查批次或相近反馈集合；每份命名须能从文件名区分批次主题。

文件开头

每个 fix_<desc>.md 顶部必须注明本批次的大致内容、发生时间、来源和范围，例如"内容：Edge 人工验收反馈""时间：2026-05-03 21:30""来源：用户人工测试"。

默认来源假设

fix_<desc>.md 中的条目默认视为来自其他 agent 或测试人员的反馈，不是本会话代理的自我分析；除非用户明确要求"自审"，否则代理不应把自己临时发现的小问题登记到 fix_<desc>.md。

优先级

所有未归档 fix_<desc>.md > TODO.md。任一 fix_<desc>.md 有未完成条目时，先把这些条目登记到 TODO.md 对应步骤，再继续推进原 TODO；每次会话开始按 fix → TODO 顺序排查。

生命周期

创建后持续存在，直到该文件所有条目被解决（对应 TODO 全部 [x] 或 [~]）→ 把"对 plan 的影响"回写 plan.md → 把该 fix_<desc>.md 归档到项目根 archive/ 文件夹，命名 archive/fix_desc-YYYYMMDD.md（desc 与原文件名保持一致）。

多份 fix 归档

归档时分别移入 archive/，不得把不同批次强行合并。历史项目中已存在的 fix.md / fix_01.md 等旧格式可继续保留并兼容读取，新增批次统一使用语义命名。

fix-plan_.md：按需创建，扩展或修正 plan 的入口

fix-plan_<desc>.md 与 fix_<desc>.md 形式相似但语义完全不同：

  • fix_<desc>.md 处理对已完成内容的修复（实现偏离 plan 的 bug、审查指出的问题）。
  • fix-plan_<desc>.md 处理对计划本身的扩展或修正（plan 之外的新功能 / 新模块、既有 plan 条目修订、对验收标准的范围调整）。

命名规则

  • 前缀固定为 fix-plan_，后接简短语义描述，使用小写连字符风格。例如 fix-plan_audit-log.md、fix-plan_offline-mode.md。
  • 与 fix_* 同样禁止纯序号命名。

与 fix 严格区分

即使用户在同一次对话中同时提出"修复一个 bug"和"新增一个功能"，代理也必须分别建两份文件，不得合并。判别依据为文件名前缀：见到 fix_* 按缺陷反馈处理，见到 fix-plan_* 按计划扩展处理。

创建时机

仅在以下情况创建，代理不得擅自创建：

  • 用户明确提出 plan 之外的新功能、新模块。
  • 用户明确要求修改 plan.md 既有内容或调整既有 plan 条目。
  • 用户要求对验收标准、功能范围做扩展性调整（非修偏差）。

落地约束（与新项目 plan 创建一致）

fix-plan_<desc>.md 的内容在写入 plan.md 之前必须遵循与新项目 plan 创建相同的"讨论阶段充分发散，写入阶段严格收敛"原则：

  • 讨论阶段（充分发散）：代理应主动与用户讨论新增内容的定位、对现有功能的影响、边界场景、验收标准；并主动识别潜在漏洞与风险。
  • 提问机制：每一处不确定之处必须主动提问并等待用户确认，不得以猜测或默认值随意填入。
  • 写入阶段（严格收敛）：将内容写入 fix-plan_<desc>.md 与后续 plan.md 时必须分两层处理：
    • 优先层 — 用户明确需求：用户已明确表达的新增内容必须全部落实，不得遗漏或自行裁剪。
    • 延伸层 — 代理建议：代理在讨论中提出的衍生想法、扩展功能、边界处理建议，必须逐项获得用户明确许可后方可写入。
  • 最终确认：fix-plan_<desc>.md 草稿完成后，必须由用户给出最终确认，代理方可将其写入 plan.md；完成来源标注并归档 fix-plan 后，再进入 TODO 派生与实现阶段。

文件开头

每个 fix-plan_<desc>.md 顶部必须注明：内容、时间、来源、对 plan 的预期影响范围（哪些章节会被新增 / 修订）。

优先级

  • fix_* 高于 fix-plan_*：缺陷反馈必须先收敛，再做范围扩展。
  • fix-plan_* 高于 TODO.md：未归档的 fix-plan 代表 plan 改写闭环尚未完成；先完成 plan.md 写入、来源标注和 fix-plan 归档，再继续普通 TODO。

生命周期

  1. 创建：用户提出计划外新增需求时。
  2. 讨论与最终确认：按上述"落地约束"完成。
  3. 写入 plan.md：用户最终确认后，代理立刻按 fix-plan_<desc>.md 修改 plan.md。这是 plan.md 新增 / 扩展内容的唯一入口。
  4. 标注来源：plan.md 中每个由本次 fix-plan 新增或修订的条目，必须标明来源 fix-plan_<desc>.md（或归档后的 archive/fix-plan_desc-YYYYMMDD.md）和修改时间日期（至少 YYYY-MM-DD，能确定时写到 YYYY-MM-DD HH:mm TZ）。
  5. 检查已完成 TODO 影响：若本次 plan 修改会覆盖、改写或废除已完成 TODO，必须先在 TODO.md 查找对应步骤；若该步骤已归档，继续查阅对应 archive/done-YYYYMMDD.md，判断旧归档是否需要重新审核、补充说明或重新打开为新的 TODO。
  6. 快速归档 fix-plan：plan.md 更新并完成来源标注后，优先把 fix-plan_<desc>.md 移入 archive/fix-plan_desc-YYYYMMDD.md。理想情况下，fix-plan 不等待实现 TODO 完成；它只负责 plan 改写闭环。
  7. 拆 TODO：从更新后的 plan.md 派生 TODO 步骤；若影响已完成 TODO，按第 5 步的判断新增 TODO、标记旧 TODO 为 [!] / [~]，或在归档文件中补充重新审核记录。
  8. 实现与验证：按普通迭代流程推进。

与 fix 的 plan 改写权对比

入口 写入 plan 时机 plan 修改性质
fix_<desc>.md 归档时（按需，仅在现状与 plan 描述出现偏差时回写） 修正描述偏差
fix-plan_<desc>.md 用户最终确认后立即写入并标注来源 新增 / 扩展 / 修订 plan 内容

HUMAN.md 人工干预分流规则

  • fix_<desc>.md 中代理能修的 bug / review 条目仍进入 TODO.md，由代理完成代码或文档修复。
  • 代理修复完成后，若剩余事项只是人工验证或外部人工操作，不继续留在 fix_<desc>.md 阻塞归档；应转入 HUMAN.md。
  • 当代理发现某个困惑、取舍或风险会影响项目方向、范围、架构或验收标准时，应转入 HUMAN.md，标明受影响范围；代理不得继续修改该范围，但应继续推进不依赖该决策的其他 TODO。
  • 转入时，在 fix_<desc>.md / fix-plan_<desc>.md 条目中标记为已处理或已分流，并注明"人工验证/决策已转 HUMAN.md#H-..."；对应文件若已无代理可执行事项，可按原生命周期归档。
  • 阻塞具体执行的 HUMAN.md 条目必须引用一个 TODO.md 条目，例如 TODO 21.8；对应 TODO 保持 [ ]，并写明 阻塞：已转 HUMAN.md#H-...，待人工执行/决策。
  • 尚未阻塞具体执行的方向性决策或 AI 困惑 条目，可以先引用来源文件或会话上下文；一旦阻塞可执行工作，代理必须创建或确认对应 TODO。
  • 人类完成或决策后，代理根据反馈把对应 TODO 标为 [x] / [~]，或恢复受影响范围的 TODO、plan、fix、fix-plan 处理，再归档或清理 HUMAN.md 条目。
  • HUMAN.md 条目编号使用 H-YYYYMMDD-01 格式；每条必须包含来源、类型、状态、影响范围、代理暂停处理的部分、代理可继续推进的部分、为什么需要人工、人类需要执行或回答的内容、期望结果或决策生效方式、反馈回填格式；人工执行项还应包含前置条件和操作步骤。
  • HUMAN.md 完成条目只保留简短索引；详细完成内容可移入 archive/human-YYYYMMDD.md。

plan.md 的修改路径

普通会话中禁止直接编辑 plan.md，明显的拼写错误 / 链接错位除外。任何对 plan 的修改必须经由以下两类入口之一：

  • fix_<desc>.md：用于修正现状与 plan 描述之间的偏差（例如实现已发生但 plan 未对应记录）。在 fix 归档时按需回写 plan。
  • fix-plan_<desc>.md：用于扩展或修正 plan 的范围（新功能、新模块、新验收标准）。处理 plan 修改指令时，必须先创建 fix-plan_<desc>.md，再根据该文件直接修改 plan.md，并在 plan.md 对应新增 / 修订条目旁记录来源 fix-plan 与修改时间日期；随后优先归档该 fix-plan，最后再根据新版 plan.md 决定 TODO.md 的修改或新增。

详见 fix_<desc>.md 与 fix-plan_<desc>.md 各自的专节。

ARCHITECTURE.md 的修改路径

  • 正常迭代中禁止修改：新增功能、重构实现、修 bug 均不触发架构修改。
  • 允许修改的两种情况：
    1. 新增代码在现有目录分工下找不到合适归属，且无法通过调整代码设计解决。
    2. 用户明确要求对架构进行调整。
  • 修改时直接编辑 ARCHITECTURE.md，并在 TODO.md 对应条目注明"架构已同步更新"。

INTERFACE.md 的同步规则

  • 接口签名（路径 / 方法 / 参数 / 返回值 / 错误码）变更必须与代码改动同 PR / 同次提交同步更新。
  • 仅注释 / 内部实现变更不触发更新。
  • 接口变更不需要走 fix_<desc>.md 闭环；但若变更涉及破坏性改动且影响外部调用方，应在 TODO.md 中单独记一条"通知调用方"步骤。

NICKNAME.md 的维护规则

  • 代理在会话中首次识别到项目专有术语时，应当主动追加到 NICKNAME.md（或 AGENTS.md 术语节，视数量阈值而定）。
  • 用户使用某词且代理无法从训练数据 / 通用语料推断含义时，应先询问用户该词定义，再写入术语表。
  • 词条移除：仅在用户明确指出某词已废弃或重命名时移除；保留旧词条作为别名指向新词条更安全。

TODO.md 状态约定

  • [x] 已完成
  • [ ] 待完成
  • [!] 已修改：原条目仍部分有效但被新计划覆盖；同行注明"修改：<原因 / 指向新条目>"
  • [~] 已废除：原条目被新计划取消或替换；同行注明"废除：<原因 / 指向新条目>"。废除条目保留不删，便于回溯
  • 阻塞： 已阻塞并记录原因

TODO ↔ 代码同步要求

  • 每次代码修改前：确认 TODO.md 有对应条目；没有就先加。
  • 每次代码修改后：立即在 TODO.md 勾选 [x] / 写阻塞 / 加补子项，再向用户汇报。禁止先改代码再"回头补 TODO"。
  • 每次新计划出现（fix_<desc>.md 新增条目 / fix-plan_<desc>.md 新增条目 / 用户临时需求 / 测试反馈）：若属于 plan 修改，先创建并确认 fix-plan_<desc>.md，直接更新 plan.md 并记录来源与修改时间日期，归档 fix-plan 后再从新版 plan.md 派生或调整 TODO.md；若影响已完成 TODO，必须查阅当前 TODO 段或对应 archive/done-YYYYMMDD.md 后，再决定旧条目标 [!] / [~]、新增重新审核条目或补充归档说明。
  • 每次新增人工干预事项：若事项必须由人类完成，或需要人类决策且会影响项目方向、范围、架构或验收标准，写入 HUMAN.md；若阻塞具体执行，先在 TODO.md 建立或确认对应条目，再把 TODO 阻塞原因指向 HUMAN.md#H-...。代理暂停触碰受影响范围，同时继续推进其他不依赖该人工输入的 TODO。
  • 每次接口变更：若改动了对外接口签名，必须在 TODO.md 当前条目下补一句"已同步 INTERFACE.md"，否则该步骤不得标记 [x]。
  • 验证命令通过前不得把步骤标记完成；例外必须在条目旁记录原因。
  • 被阻塞的步骤保持未勾选，加 阻塞：<具体原因 + 下一步恢复动作>。

TODO 步骤归档约定

归档是 TODO 步骤完成闭环的一部分，不是可选清理动作。每次更新 TODO.md 后，都必须检查是否有步骤满足归档条件；一旦满足，必须在同次会话内完成归档并留下可追溯面包屑。

触发条件

TODO.md 中某个步骤的所有子项都已收敛为 [x] 或 [~]，且没有 [ ] / [!] / 阻塞 项时，必须归档。 仍被其他活跃步骤通过 [!] 修改：…见步骤 N 反向引用的步骤，暂不归档；引用关系闭合后必须立即归档。

归档动作

  1. 把整段 ### 步骤 N: <title> 连同所有子项剪切到 archive/done-YYYYMMDD.md。
  2. 同一天多步合并到同一个文件；同一天分批则 -2.md / -3.md 递增。
  3. 归档文件首行：# 归档：步骤 N、M、…（归档于 YYYY-MM-DD）。

TODO 留下的面包屑

原位保留一行，可回溯：

### 步骤 N: <title> — 已归档于 YYYY-MM-DD → archive/done-YYYYMMDD.md

不得归档的情况

  • 步骤含 [ ] / [!] / 阻塞 → 留在 TODO。
  • 步骤被活跃步骤反向引用 → 引用闭合后再归档。

归档约定

  • 每个项目根都使用统一的 archive/ 文件夹存放归档文件。
  • fix 归档命名：archive/fix_desc-YYYYMMDD.md（desc 与原文件名的描述部分保持一致）。历史 fix.md 归档时使用 archive/fix-YYYYMMDD.md。
  • fix-plan 归档命名：archive/fix-plan_desc-YYYYMMDD.md（desc 与原文件名的描述部分保持一致）。fix-plan 默认在完成 plan.md 修改和来源标注后立即归档，不等待后续 TODO 实现完成。
  • 人工处理归档命名：archive/human-YYYYMMDD.md。
  • 归档时不删除原始内容，仅整体移入并把 # 标题 加上"（归档于 YYYY-MM-DD）"后缀。

代码组织约定

  • 单文件超过 800 行时，必须评估是否需要拆分。
  • 新增代码的归属目录以 ARCHITECTURE.md 为准；找不到合适归属时先更新架构再写代码。

注释约定

  • 注释只解释"为什么这样做"，不重复描述"代码正在做什么"。