← 返回博客

    CLAUDE.md 到 AGENTS.md 迁移指南

    大多数团队不是从 AGENTS.md 开始的。他们先用 Claude Code，写一份 CLAUDE.md，经过几次痛苦 session 后慢慢调出有用的东西。然后 toolchain 变了。Codex 进入 repo。Cursor 读另一个 rule file。Copilot 有自己的 instructions。旧 CLAUDE.md 仍然有价值，但已经不够了。

    从 CLAUDE.md 迁到 AGENTS.md，不是 search-and-replace。它是 source-of-truth decision。CLAUDE.md 里有些规则是 project rules，应该移进 AGENTS.md。有些是 Claude Code mechanics，应该留在 Claude-specific files。有些是很长的 workflow procedures，应该搬到 skills 或 docs。有些已经过期，应该删掉。

    这份 guide 是我给 Claude-only 团队迁到 multi-tool setup 时用的路径。目标是不把 repo 变成 split-brain harness。

    Step one: audit the existing CLAUDE.md

    先读文件，再动它。不要盲目复制。

    做一张简单表：

    Rule or section | Type | Keep, move, or delete

    把每个 section 分成四类。

    Project facts：repo 是什么、stack、layout、commands、process、architecture、security rules。这些通常移到 AGENTS.md。

    Claude Code mechanics：hooks、slash commands、skills、MCP permissions、Claude-specific settings、Claude 怎样加载 global 和 project files。这些通常留在 CLAUDE.md 或 .claude/。

    Workflow procedures：release process、handoff format、review checklist、incident drill。这些通常移到 docs 或 skills，再让 AGENTS.md 链过去。

    Stale or generic material：已经删掉的 commands、旧 paths、“write clean code”、复制来的聊天记录、过期 tool preferences。这些应该删除。

    audit 是你回收价值的地方。一份乱的 CLAUDE.md 通常不是全坏。它包含踩坑换来的知识。但这些知识混着 tool habits、old scars、stale references。migration 正好可以把它们分开。

    Step two: identify cross-agent rules

    Cross-agent rules 是不管哪个 coding agent 碰 repo，都应该适用的规则。

    例子：

    - Use npm. package-lock.json is canonical.
- Run npm run build before opening a PR.
- Do not edit generated dist/ output by hand.
- Never print secret values.
- Public API changes require docs and tests.
- Blog slugs are derived from markdown filenames.
- New dependencies require approval.

    这些属于 AGENTS.md，因为它们描述项目，不描述 Claude Code。如果 Codex 应该遵守规则，它就不能只活在 CLAUDE.md。如果 Cursor 应该遵守规则，它也不能只活在 AGENTS.md，除非 Cursor 被配置成读取它，或者有 pointer。

    一个实用测试：把句子里的 “Claude” 换成 “agent”。如果句子仍然成立，而且应该约束每个 tool，它就是 cross-agent rule。

    Step three: separate Claude-specific rules

    现在收集只对 Claude Code 有意义的规则。

    例子：

    - SessionStart hooks live in .claude/settings.json.
- Use /handoff when the user asks to wrap up a session.
- Project skills live under .claude/skills/.
- Claude Code MCP permissions are configured in settings.json.
- Hook output is injected as system-reminder messages.

    这些不属于 shared AGENTS.md，最多只留一行 reference。Codex 不需要一大段 Claude Code hook semantics。Cursor 不需要知道 Claude skill frontmatter field 怎样触发。Tool-specific detail 应该靠近 tool。

    很多 migration 会在这里错。团队把整份 CLAUDE.md 复制进 AGENTS.md，结果 Codex 读到 slash commands 或 hooks 的说明，而它的 harness 并没有这些东西。这不是无害的。它会教 agent 一个错误环境。

    Step four: create AGENTS.md as canonical

    从分类后的规则写 AGENTS.md，不要照搬旧文件结构。

    一个强的一版可以这样：

    # AGENTS.md

## Project facts
One paragraph describing the product, stack, and repo layout.

## Commands
- Install: npm ci
- Build: npm run build
- Lint: npm run lint
- Test: npm test

## Working rules
- Branch from main and open a PR. No direct pushes to main.
- Use npm only. Do not add other lockfiles.
- Do not edit generated dist/ output by hand.
- Never print secret values. Refer to environment variable names only.

## Architecture and boundaries
- Route metadata lives in src/lib/seo.ts.
- Static route generation lives in scripts/generate-sitemap.ts.
- Blog content lives in src/content/blog/.

## References
- package.json is the source of truth for commands.
- docs/release.md covers release procedure.
- .github/workflows/ci.yml is the source of truth for CI.

    如果旧 section order 很糟，不要保留。AGENTS.md 应该为 agent 开 session 优化，而不是为 CLAUDE.md 的生长历史优化。

    保持短。如果一个 section 需要很多 bullet，要么它太模糊，要么它应该在被 reference 的 document 里。

    Step five: replace CLAUDE.md with a thin pointer

    一旦 AGENTS.md canonical，CLAUDE.md 就不该继续做 parallel source of project truth。让它变成 adapter。

    例子：

    # CLAUDE.md

AGENTS.md is the canonical project instruction file.
Read AGENTS.md before making changes.

## Claude Code-specific behavior
- Hooks are configured in .claude/settings.json.
- Workflow-specific instructions live in .claude/skills/.
- If AGENTS.md and this file conflict, AGENTS.md wins for project rules.
- This file only owns Claude Code harness behavior.

    这故意很无聊。无聊是好事。薄 pointer 会让 drift 变明显。如果有人把 package-manager rule 加进 CLAUDE.md，review 问题马上出现：为什么 project rule 被加到 adapter，而不是 AGENTS.md？

    如果团队还没准备让 AGENTS.md canonical，可以临时反过来：

    # AGENTS.md

Generated from CLAUDE.md. Do not edit by hand.
Shared project rules follow.

    这可以当桥，但必须显式。沉默的 dual ownership 才是失败模式。

    Step six: verify each agent reads correctly

    不要假设 discovery 会工作。要测试。

    对 Codex，从 repo root 跑一个 harmless prompt：

    codex --ask-for-approval never "Summarize the project instructions you loaded."

    预期：它提到 AGENTS.md、project commands、working rules。如果没有，检查 current directory、CODEX_HOME、override files，以及文件是不是空的。Codex 在 session start 构建 instruction chain，所以改完 instruction files 后要重启 session。

    对 Claude Code，开新 session，让它 summarize active project guidance。预期：它读 CLAUDE.md，跟随 pointer，并把 AGENTS.md 当 project rules 的 canonical。

    对 Cursor 或 Copilot，要么在支持的地方配置它们读 AGENTS.md，要么加一个薄 adapter file 指过去：

    Project rules live in AGENTS.md. Treat that file as canonical.
Tool-specific instructions in this file only cover editor behavior.

    verification 很重要，因为 repo 看起来可能没问题，但某个 tool 还在读旧文件。harness bug 经常看起来像 model behavior，直到你检查真正加载的 instructions。

    Step seven: catch contradictions

    迁移后，搜索重复名词：

    package manager
test
build
lint
main
PR
secret
lockfile
generated

    如果 AGENTS.md 说 npm，而 CLAUDE.md 说 pnpm，决定哪个是真的。如果 AGENTS.md 说 PR required，而 Cursor rule 说 direct commits allowed，决定哪个是真的。不要两个都留着，然后希望 agent 推断你的 intent。

    每个 intentional override 都要说自己是 intentional：

    - Use npm in this repo; overrides global pnpm preference because CI uses npm.

    这句话做两件事。它告诉 agent 哪条规则赢，也告诉 human reviewer 为什么这个冲突存在。

    Step eight: move long procedures out of always-loaded files

    Migration 也是瘦身的时机。常见 CLAUDE.md 里会有 70 行 release procedure、50 行 handoff format、40 行 review checklist。这些都有用。但它们不属于 always-loaded AGENTS.md。

    搬出去：

    docs/release.md
.claude/skills/handoff/SKILL.md
docs/review-checklist.md

    然后只留下 pointers：

    - Release procedure: docs/release.md.
- Session handoff in Claude Code: use /handoff.
- Review checklist: docs/review-checklist.md.

    这样 AGENTS.md 保持小，知识也还在。agent 只有在 task 需要时才打开更深文件。

    A migration checklist

    PR checklist 可以用这个：

    - [ ] Existing CLAUDE.md audited and classified.
- [ ] Cross-agent project rules moved to AGENTS.md.
- [ ] Claude-specific rules kept in CLAUDE.md or .claude/.
- [ ] Long workflow procedures moved to docs or skills.
- [ ] CLAUDE.md now points at AGENTS.md as canonical.
- [ ] Each agent was tested in a fresh session.
- [ ] Contradictions and stale references were removed or declared.
- [ ] CI, hooks, or review gates enforce the rules that matter.

    最后一行最容易被跳过。prose 不是 enforcement。如果一条规则重要到能挡 release，就在它下面放 check。

    What good looks like after migration

    迁移后，新 contributor 应该知道要在哪里改 project rule。Codex session 和 Claude Code session 应该在 package manager、commands、branch policy、generated files、security basics 上一致。Tool-specific files 应该薄，而且 scope 明显。长 procedures 应该住在可以维护的地方，而不是塞爆每个 session。

    真正结果不是“我们加了 AGENTS.md”，而是“我们从 harness 里移除了 ambiguity”。AgentLint 适合放在 migration 末尾，因为它会在新结构开始 drift 之前，检查新的 AGENTS.md 和剩下的 instruction files 是否有模糊规则、过期引用、冲突、缺少 enforcement。

    相关文章

    AGENTS.md vs CLAUDE.md

    AGENTS.md 作为 single source of truth

    Claude Code Skills 和 CLAUDE.md：它们怎么配合