repo-initlisted

# 通用项目上下文初始化与更新优化（AGENTS.md） ## 核心理念 AGENTS.md 是**单一事实源**：一份跨工具通用的项目简报，所有主流 AI 编码 agent 自动读取，无需为每个工具各建一份实质内容记忆（工具专属文件最多留适配指针 stub，见 `05`）。它是一份**无状态、低频更新**的稳定文档——只存放每次对话 agent 都必须得知的上下文与约定，**禁止**写入待办/未决/任务进度/本次会话状态（详见 `03` §3（changelog/wiki/进度日志））。两个一等能力： 1. **冷启动初始化**（新建）：仓库尚无 AGENTS.md 时，扫描项目生成一份。 2. **更新优化**（已有）：基于当前仓库信号做**增量更新**——修正过期命令、补全缺失 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」处理，不臆造命令。 ### P