通用项目上下文初始化与更新优化（AGENTS.md）
核心理念
AGENTS.md 是单一事实源：一份跨工具通用的项目简报，所有主流 AI 编码 agent 自动读取，无需为每个工具各建一份实质内容记忆（工具专属文件最多留适配指针 stub，见 05）。它是一份无状态、低频更新的稳定文档——只存放每次对话 agent 都必须得知的上下文与约定，禁止写入待办/未决/任务进度/本次会话状态（详见 03 §3（changelog/wiki/进度日志））。两个一等能力：
- 冷启动初始化（新建）：仓库尚无 AGENTS.md 时，扫描项目生成一份。
- 更新优化（已有）：基于当前仓库信号做增量更新——修正过期命令、补全缺失 section、删除失真项，绝不整份覆盖、不丢弃用户手写内容。
何时使用本技能（判定表）
| 信号 | 判定 |
|---|---|
| 用户说"生成 / 更新 AGENTS.md / init / 给 AI 写或改项目说明" | 激活 |
| 新克隆仓库、首次让 AI 接手任务、缺乏项目简报 | 激活（走初始化路径） |
已有 AGENTS.md 但内容过期 / 不完整 / 与现状不符 |
激活（走更新优化路径） |
已有人工维护且团队满意的 AGENTS.md |
不适用 → 仅做增量建议，不覆盖 |
| 用户要"为 Cursor / Claude / WorkBuddy 各建一份记忆" | 不适用 → 引导回单一 AGENTS.md；Claude Code 兼容只需适配指针 stub（见 05） |
| 纯一次性脚本、无协作维护价值 | 不适用 |
> 检查点：判定为「不适用」→ 告知用户当前目标不在本技能范围，建议退出或调整诉求。
能力与参考路由
| 能力 | 详见 |
|---|---|
| 冷启动新建 + 增量更新（diff 式，不覆盖）+ 5 section 模板（≤200 行推荐上限，可超） | §流程、§强约束 3、references/02-output-template.md |
| CLAUDE.md 迁移与适配指针 | references/05-claude-md-migration.md |
| 13 条 antipattern / 8 条强约束 / 4 检查点 | references/03-antipatterns.md、§强约束、§检查点 |
| 7 类扫描信号 + Token 经济学 7 铁律 | references/01-scan-signals.md |
| Monorepo 嵌套策略 | references/04-monorepo-nesting.md |
流程（两条路径，共用扫描与落盘）
通用前置：探测信号
按 01-scan-signals.md 扫描构建文件、测试、CI、linter、已有上下文（含已有 AGENTS.md / CLAUDE.md 的实际内容）。
全程遵守 01 §0 Token 经济学铁律（限定范围、元数据优先、懒加载、Bash 聚合、Git 增量），避免 Token 浪费与上下文污染。
扫描若未命中任何构建元数据（纯脚本 / 无构建步骤前端 / 零散源文件），按 01 §1「无构建 fallback」处理，不臆造命令。
Path A · 冷启动初始化（仓库无 AGENTS.md）
- 探测信号（前置）。
- 读取 README / CONTRIBUTING 等辅助上下文。
- 按
02模板草拟草稿：标准模式目标 ≤150 行、推荐上限 ≤200 行（实际可超，超长建议说明原因）；小项目无信号 section 直接省略（见强约束 8），自然落短。命令必须可验证准确。 - 关键节点询问（克制）：是否嵌套子 AGENTS.md？项目特有硬约束？
- 落盘 + 提交建议，不自动 commit。
Path B · 更新优化（仓库已有 AGENTS.md）
- 探测信号（前置）——Git 增量优先（
01§0 铁律 6）：先git diff/git log看变更面，只重扫变更文件；未变文件复用上一版信号。比对更新信号：依赖升级 / 包管理器切换（package-lock→pnpm-lock）、架构调整（新增子包）→ 缺嵌套或描述过时、CI 规则变更（新增强制 lint / test / 覆盖率）、命令执行报错 / 约束已废除、出现CLAUDE.md等工具专属记忆 → 迁移并降 stub（见05）。 - 读取现有 AGENTS.md 全文，逐 section 与现状信号比对，产出三类标注：
- 🔴 过期/失真：命令失效（如npm实为pnpm）、路径变更、约束已废除
- 🟡 缺失：官方 5 section 中未覆盖的项（如缺Security considerations）、新子包未嵌套
- 🟢 仍准确：保留，不改动用户手写内容 - 生成更新建议（diff 式）：给出"新增 / 修订 / 删除"清单 + 修订后完整草稿，保留用户原有有效内容。
- 关键节点询问（克制）：过期项是否确认删除？缺失 section 是否补齐？是否需嵌套？
- 应用更新 + 提交建议，不自动 commit；绝整份覆盖。
关键决策检查点
| 检查点 | 触发 | 处理 |
|---|---|---|
| C1 已有文件 | 检测到 AGENTS.md / CLAUDE.md / 两者 |
按五象限矩阵处理：无文件→Path A；仅 CLAUDE.md 有实质内容→迁移；仅 AGENTS.md→Path B + 询问是否补 stub；两者皆有→双源去重；CLAUDE.md 已是 stub→Path B 且 stub 不动（见 05） |
| C2 命令真实 | 草拟/更新安装/构建/测试命令 | 必须从构建文件实际提取；无法确认标「需核实」或问，不臆造 |
| C3 是否嵌套 | monorepo / 多包大仓库 | 见 04-monorepo-nesting.md，默认根 + 子目录就近覆盖 |
| C4 工具无关 | 草拟/更新任何"如果你用 X 工具请…" | 删除；AGENTS.md 只描述项目事实，不含工具专属指令 |
> 检查点：任一检查点触发且无法自动判断 → 在对应节点向用户给选项，不擅自替用户决策。
强约束（生成 / 更新前必须满足）
- 内容唯一载体 = AGENTS.md：允许子目录嵌套（见
04）；禁止生成任何实质内容的工具专属记忆文件
（CLAUDE.md/.cursorrules/.windsurfrules/.clinerules/.workbuddy记忆等）。
例外（适配指针）：可将CLAUDE.md降为零内容适配指针（仅一行@AGENTS.md+ 可选 Claude 专属小节），
判据：指针文件不得含任何项目事实副本，一旦出现重复即退化为第二份记忆 → 违规（见05）。 - 已有则增量更新：检测到已有
AGENTS.md→ 走 Path B，合并/补充/修正 + 保留用户有效内容，
绝不覆盖、不整份重写、不生成第二份。 - 锚定官方核心标准：section 覆盖以官方 5 个推荐 section 为骨架（Project overview / Setup commands / Code style / Testing / Security considerations）；"≤200 行"是信息密度推荐上限（Claude Code 实践参考，非官方强制），实际可超（模板见
02）。 - 工具无关：只描述项目事实（命令/约定/架构/硬约束/陷阱）；禁止在 AGENTS.md 写任何 agent 专属指令或工具 hack（适配指针见
05）。 - 命令可验证：安装/构建/测试命令必须从构建文件或脚本实际提取；误写构建命令比不写更糟。
无法确认时显式标注「需核实」或询问，不臆造。 - 不自动 commit：给出落盘 + 提交建议，由用户决定。
- 无状态 / must-know-only：禁止把待办 / 未决 / 任务执行进度 / 本次会话状态写进 AGENTS.md；
只放"每次对话都必须得知"的稳定上下文与约定，写入门槛 = "不知道这条是否会在本次对话出错"。 - 无信号不写空段：无对应信号（无 CI → 无 PR 流程、无测试框架 → 无 Testing、无架构叙事 → 无 Architecture）时
直接省略该段，禁止写空壳或编造内容；极小型项目可只保留 must-know（overview / setup / 关键约束）。
例外（始终单列）：安全敏感类项目（认证 / 鉴权 / 支付 / 加密 / 数据合规）始终单列## Security considerations，
不并入 Hard constraints——此类信号几乎总是真实存在，即使未显式扫描到也应独立成段。
触发方式（明示触发，非自动）
本技能不自动触发，与 Claude Code /init 一致——仅当用户手动调用或明确要求时才创建/更新 AGENTS.md（触发词见 frontmatter description）。不主动做的事（避免与无状态/Token 经济学铁律冲突）：
- 不在每次新对话、每次接手任务、每次 git 操作前自动扫描或自动建议 init
- 不主动"监听"仓库变化并推送更新提醒
- 不因"发现现有 AGENTS.md 命令失效/缺 section"就自动发起更新——这类信号仅在用户已明示要更新时，作为 Path B 的输入被纳入
antipattern（硬价值）
完整清单与每条「错误 → 正确 → 为什么」见 references/03-antipatterns.md。最易犯的两条红线：
- 为多个工具各建一份实质内容记忆（漂移 + 重复维护；适配指针 stub 除外，见
05） - 更新时整份覆盖重写已有文件（应增量 diff，保留用户手写内容；见
03§12）
