Repo Init

通用项目上下文初始化与更新优化（AGENTS.md）

核心理念

AGENTS.md 是单一事实源：一份跨工具通用的项目简报，所有主流 AI 编码 agent 自动读取，无需为每个工具各建一份实质内容记忆（工具专属文件最多留适配指针 stub，见 05）。它是一份无状态、低频更新的稳定文档——只存放每次对话 agent 都必须得知的上下文与约定，禁止写入待办/未决/任务进度/本次会话状态（详见 03 §3（changelog/wiki/进度日志））。两个一等能力：

1. 冷启动初始化（新建）：仓库尚无 AGENTS.md 时，扫描项目生成一份。
2. 更新优化（已有）：基于当前仓库信号做增量更新——修正过期命令、补全缺失 section、删除失真项，绝不整份覆盖、不丢弃用户手写内容。

何时使用本技能（判定表）

检查点：判定为「不适用」→ 告知用户当前目标不在本技能范围，建议退出或调整诉求。

能力与参考路由

流程（两条路径，共用扫描与落盘）

通用前置：探测信号

按 01-scan-signals.md 扫描构建文件、测试、CI、linter、已有上下文（含已有 AGENTS.md / CLAUDE.md 的实际内容）。 全程遵守 01 §0 Token 经济学铁律（限定范围、元数据优先、懒加载、Bash 聚合、Git 增量），避免 Token 浪费与上下文污染。 扫描若未命中任何构建元数据（纯脚本 / 无构建步骤前端 / 零散源文件），按 01 §1「无构建 fallback」处理，不臆造命令。

Path A · 冷启动初始化（仓库无 AGENTS.md）

1. 探测信号（前置）。
2. 读取 README / CONTRIBUTING 等辅助上下文。
3. 按 02 模板草拟草稿：标准模式目标 ≤150 行、推荐上限 ≤200 行（实际可超，超长建议说明原因）；小项目无信号 section 直接省略（见强约束 8），自然落短。命令必须可验证准确。
4. 关键节点询问（克制）：是否嵌套子 AGENTS.md？项目特有硬约束？
5. 落盘 + 提交建议，不自动 commit。

Path B · 更新优化（仓库已有 AGENTS.md）

1. 探测信号（前置）——Git 增量优先（01 §0 铁律 6）：先 git diff / git log 看变更面，只重扫变更文件；未变文件复用上一版信号。比对更新信号：依赖升级 / 包管理器切换（package-lock → pnpm-lock）、架构调整（新增子包）→ 缺嵌套或描述过时、CI 规则变更（新增强制 lint / test / 覆盖率）、命令执行报错 / 约束已废除、出现 CLAUDE.md 等工具专属记忆 → 迁移并降 stub（见 05）。
2. 读取现有 AGENTS.md 全文，逐 section 与现状信号比对，产出三类标注：
   • 🔴 过期/失真：命令失效（如 npm 实为 pnpm）、路径变更、约束已废除
   • 🟡 缺失：官方 5 section 中未覆盖的项（如缺 Security considerations）、新子包未嵌套
   • 🟢 仍准确：保留，不改动用户手写内容
3. 生成更新建议（diff 式）：给出"新增 / 修订 / 删除"清单 + 修订后完整草稿，保留用户原有有效内容。
4. 关键节点询问（克制）：过期项是否确认删除？缺失 section 是否补齐？是否需嵌套？
5. 应用更新 + 提交建议，不自动 commit；绝整份覆盖。

关键决策检查点

检查点：任一检查点触发且无法自动判断 → 在对应节点向用户给选项，不擅自替用户决策。

强约束（生成 / 更新前必须满足）

1. 内容唯一载体 = AGENTS.md：允许子目录嵌套（见 04）；禁止生成任何实质内容的工具专属记忆文件 （CLAUDE.md / .cursorrules / .windsurfrules / .clinerules / .workbuddy 记忆等）。 例外（适配指针）：可将 CLAUDE.md 降为零内容适配指针（仅一行 @AGENTS.md + 可选 Claude 专属小节）， 判据：指针文件不得含任何项目事实副本，一旦出现重复即退化为第二份记忆 → 违规（见 05）。
2. 已有则增量更新：检测到已有 AGENTS.md → 走 Path B，合并/补充/修正 + 保留用户有效内容， 绝不覆盖、不整份重写、不生成第二份。
3. 锚定官方核心标准：section 覆盖以官方 5 个推荐 section 为骨架（Project overview / Setup commands / Code style / Testing / Security considerations）；"≤200 行"是信息密度推荐上限（Claude Code 实践参考，非官方强制），实际可超（模板见 02）。
4. 工具无关：只描述项目事实（命令/约定/架构/硬约束/陷阱）；禁止在 AGENTS.md 写任何 agent 专属指令或工具 hack（适配指针见 05）。
5. 命令可验证：安装/构建/测试命令必须从构建文件或脚本实际提取；误写构建命令比不写更糟。 无法确认时显式标注「需核实」或询问，不臆造。
6. 不自动 commit：给出落盘 + 提交建议，由用户决定。
7. 无状态 / must-know-only：禁止把待办 / 未决 / 任务执行进度 / 本次会话状态写进 AGENTS.md； 只放"每次对话都必须得知"的稳定上下文与约定，写入门槛 = "不知道这条是否会在本次对话出错"。
8. 无信号不写空段：无对应信号（无 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）