# AGENTS.md — 智能体通用工作规范 本文件是**跨项目通用**的智能体工作规范。本项目的技术栈、红线、环境等**硬规范一律在 [PROJECT.md](./PROJECT.md)**： > **开工前必读 PROJECT.md。** 它是项目规范的单一事实源；与本文件冲突时，以 PROJECT.md 为准。 ## 一、项目契约 - 红线、架构约束、环境与版本锁、质量门禁、验收标准、协作通道，全部以 PROJECT.md 为准； - 遇到 PROJECT.md 未覆盖的项目事实：先查证（读代码 / 实测 / 问用户），确认后**回写 PROJECT.md**——规范靠文档沉淀，不靠口头传承； - PROJECT.md 中带 `TODO` 标记的条目是未确认项，涉及时先与用户确认再动手。 ## 二、变更双记录（强制） 每次 **bug 修复、功能改造、新增功能**，必须同时记录以下两处，缺一不可： 1. **`CHANGELOG.md`**（仓库根，用户视角，简目）：归入对应日期/里程碑下的 Added / Changed / Fixed / Removed / Docs 分类；一行说清「改了什么 + 用户可感知的效果」；提交后补 commit hash；未合并的工作记在 `## Unreleased`，合并时移入对应日期。 2. **`docs/DEVLOG.md`**（开发视角，详录，倒序追加）：每条含 `日期 · 标题` / 背景 / 变更（文件级要点）/ 决策与理由 / 踩坑与修复 / 验证 / 关联（commit、文档）。 执行细则： - **记录时机 = 收口时一次性补记**：方案讨论、调研、多轮迭代过程中不逐轮记录；交付/合并/收口时统一补齐。一个功能的多批变更合并为一条 DEVLOG（批次列全）+ 一组 CHANGELOG 条目； - **bug 修复必须写根因**（不止症状与修法）；**功能改造必须写前后差异与动机**； - 设计方案、调研、拍板等文档类变更同样双记录（CHANGELOG 归 Docs）；调研类记录须附证据来源（代码路径 / 实测数据 / 在线核实），结论与拍板分开写。 ## 三、工作流 - **大功能**：调研 → 设计方案 → **用户拍板**（拍板通过前不实现）→ 实现 → 验证 → 用户验收 → 合并回流； - **小改动**：可直接实现，但验证与双记录不豁免； - **隔离开发**（worktree / 独立分支）：开工与每次阶段汇报时，主动说明路径、分支、未提交状态、回流路径（附 git 证据），不等用户来问； - **破坏性 / 外发操作**（删除文件、改写历史、发布到外部服务、对外发消息）：先确认，除非已获持久授权；删除或覆盖前先看目标内容，与描述不符时先上报。 ## 四、验证纪律 - **先验证后宣布完成**：跑 PROJECT.md 定义的全部质量门禁（typecheck / lint / 测试等），保留证据； - **只认直接证据**：UI / 布局类改动必须验证实际渲染结果（真实浏览器实测，断言尺寸、位置、填充关系），「编译通过」「HTTP 200」「class 存在」等间接信号不算通过；重渲染须回归事件重绑与状态还原； - 如实报告结果：测试失败就贴输出说失败，跳过了某步就说跳过，不得带着已知失败报「完成」。 ## 五、复用与依赖 - **复用优先**：生态/社区已有组件能满足需求时优先复用；自研替代前，必须拿组件自身的证据论证其不可用并主动呈现，同时给出「将来能回到生态」的演进路径；「内容复用、UI 自绘」也是可接受的复用形态； - 不轻易新增依赖：新增时说明为什么现有依赖不能满足； - 版本策略以 PROJECT.md 为准（有版本锁 / 哨兵机制时不追 latest，升级走显式评审）。 ## 六、协作默认 - 回复语言与用户可见文案语言，以用户全局配置与 PROJECT.md 约定为准； - 外部协作通道（咨询、评审、上游 PR、发布）按 PROJECT.md「协作与决策机制」执行；PROJECT.md 未记录的先问再用。 ## 七、文档与知识库 ### 文档流转（定稿区 / 过程区） - **同一文档迭代 = 在原文件上原地修改**，版本历史交给 git；禁止新开 `-v2`、`-new`、`copy`、`final-final` 之类版本号/后缀文件——多版本并存是歧义与污染的根源； - `docs/design/` 是**定稿区**：每个功能/专题一份最终文档（设计、调研结论），文件顶部标状态行：`> 状态：定稿 · 更新 YYYY-MM-DD · 关联：DEVLOG 条目 / commit`； - `docs/archive/` 是**过程区**（gitignored，永不推远端）：被取代的草稿、外部工具原始产出（如网页回复原文）、临时证据、废弃方案——**产生即移入**，不等收口再集中清理；**只归档不删除**，删除须用户拍板； - 正在评审、需要远端可见的工作文档（如设计稿）留在 `docs/` 正常演进（原地改），收口时按判定处理； - **收口判定**：对每份过程文档问「3 个月后谁还会读它？」——会读 → 定稿进 `docs/design/`（清过程噪声、补状态行）；不会读 → 移入 `docs/archive/<功能名>/`； - 归档文件在远端/新克隆/worktree 不可见：**DEVLOG 记录归档事实与位置，不链接归档文件当证据**；关键证据（数字、结论、关键输出）内联进 DEVLOG 或定稿文档。 ### 收口清单（与 §二双记录配套，收口时一次做完） 1. `CHANGELOG.md` 记账； 2. `docs/DEVLOG.md` 写条目； 3. **文档收口**：按上述判定归档/定稿，DEVLOG 条目里写明定稿路径 + 归档位置与文件数； 4. **知识蒸馏**：判断本次 DEVLOG 的踩坑与经验是否满足 KB 收录标准，满足则写入 `knowledge-base/`。 ### 知识库 knowledge-base/（仓库根，随仓库提交） - 一主题一文件；`knowledge-base/README.md` 是索引（一行一条：标题 + 一句话钩子），新增/修改主题必须同步索引； - **收录标准**（三条同时满足）：可复用（后续还会遇到）、非显然（读代码或官方文档推不出来）、已实证（在本项目验证过，注明来源）； - **三路分流**，不得混放：项目事实与规范 → PROJECT.md；一次性事件记录 → DEVLOG；可复用经验与方法论 → KB； - **读写闭环**：接到任务先扫 KB 索引，命中相关主题必读后再动手；**同一个坑踩第二次 = 该坑必须入 KB**； - 毕业路径：KB 主题成熟且跨项目通用 → 提炼成独立 skill；各工具私有记忆只存指向 KB 的指针，KB 是仓库内权威版本。