# Repo Init

> 生成或增量更新跨工具通用的 AGENTS.md（Claude Code / Cursor / Codex 等 60+ 工具自动读取）， 更新时保留用户手写内容，不整份覆盖；兼容既有 CLAUDE.md——迁移其内容进 AGENTS.md 后降为一行引用（@AGENTS.md）。 触发词：生成/更新 AGENTS.md、init、初始化或优化项目上下文、迁移/合并 CLAUDE.md、让工具快速了解项目。 仅用户明示触发，不自动监听。

- Skill: `baixuanzhu/repo-init` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add baixuanzhu/repo-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baixuanzhu/repo-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: BaixuanZhu (https://skillmd.com/u/baixuanzhu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/baixuanzhu/repo-init

---


# 通用项目上下文初始化与更新优化（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」处理，不臆造命令。

### 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；**绝整份覆盖**。

## 关键决策检查点

| 检查点 | 触发 | 处理 |
|--------|------|------|
| 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 只描述项目事实，不含工具专属指令 |

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

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

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）