repo-initlisted

# 通用项目上下文初始化与更新优化（AGENTS.md） ## 核心理念 AGENTS.md 是**单一事实源**：一份跨工具通用的项目简报，所有主流 AI 编码 agent 自动读取，无需为每个工具各建一份记忆。它是一份**无状态、低频更新**的稳定文档——只存放每次对话 agent 都必须得知的上下文与约定，**禁止**写入待办/未决/任务进度/本次会话状态（详见 `03` §14）。本技能只产出 / 更新这一份 AGENTS.md，不生成任何工具专属记忆文件、不写工具 hack。两个一等能力： 1. **冷启动初始化**（新建）：仓库尚无 AGENTS.md 时，扫描项目生成一份。 2. **更新优化**（已有）：基于当前仓库信号做**增量更新**——修正过期命令、补全缺失 section、删除失真项，**绝不整份覆盖、不丢弃用户手写内容**。 ## 何时使用本技能（判定表） | 信号 | 判定 | |------|------| | 用户说"生成 / 更新 AGENTS.md / init / 给 AI 写或改项目说明" | 激活 | | 新克隆仓库、首次让 AI 接手任务、缺乏项目简报 | 激活（走**初始化**路径） | | 已有 `AGENTS.md` 但内容过期 / 不完整 / 与现状不符 | 激活（走**更新优化**路径） | | 已有人工维护且团队满意的 `AGENTS.md` | 不适用 → 仅做增量建议，不覆盖 | | 用户要"为 Cursor / Claude / WorkBuddy 各建一份记忆" | 不适用 → 引导回单一 AGENTS.md | | 纯一次性脚本、无协作维护价值 | 不适用 | > **检查点**：判定为「不适用」→ 告知用户当前目标不在本技能范围，建议退出或调整诉求。 ## 能力与参考路由 | 能力 | 详见 | |------|------| | 冷启动新建 + 已有文件增量更新（diff 式，不覆盖） | §流程 Path A / Path B | | 锚定官方 5 section 骨架（≤200 行信息密度护栏，非硬限；section 标题建议英文） | §强约束 3、`references/02-output-template.md` | | 15 条 antipattern（错误→正确→为什么） | `references/03-antipatterns.md` | | 8 条核心强约束 | §强约束 | | 4 个关键决策检查点（C1 已有文件 / C2 命令真实 / C3 嵌套 / C4 工具无关） | §关键决策检查点 | | 7 类扫描信号（构建/入口测试/CI/linter/已有上下文/陷阱/i18n） | `references/01-scan-signals.md` | | Token 经济学 7 铁律（限定范围/元数据优先/懒加载/Bash 聚合/签名提取/Git 增量/先聚后出） | `references/01-scan-signals.md` §0 | | 标准化 section + 完整示例 | `references/02-output-template.md` | ## 流程（两条路径，共用扫描与落盘） ### 通用前置：探测信号 按 `01-scan-signals.md` 扫描构建文件、测试、CI、linter、已有上下文（含已有 AGENTS.md 的实际内容）。 **全程遵守 `01` §0 Token 经济学铁律**（限定范围、元