agents-md-setup 是做什么的？
将 AGENTS.md 设为代理/项目指令的唯一真相来源，
并通过符号链接将所有工具的文件指向它。一个文件被所有代理读取——无重复，无偏差。
为什么这样布局
AGENTS.md正在成为跨工具的标准（Cursor、Codex 等其他工具都会读取它）。- Claude Code 读取
CLAUDE.md。你无法通过提示或技能让 harness 直接读取AGENTS.md——但一个符号链接CLAUDE.md → AGENTS.md意味着 Claude 打开CLAUDE.md得到的是AGENTS.md的内容。这就是机制；不需要其他任何东西。 - 结果：仅编辑
AGENTS.md；每个代理保持同步。
决策：已经存在什么？
- 两个文件都不存在 → 从下面的模板创建
AGENTS.md。 - 只有
CLAUDE.md（一个真实文件） → 将其设为主要来源：git mv CLAUDE.md AGENTS.md # 保留历史记录（或者：如果未跟踪则用 mv） - 只有
AGENTS.md→ 保持原样（很好）。 - 两个文件都存在且都是真实文件 → 不要盲目覆盖。比较它们，合并到
AGENTS.md（它作为规范文件胜出），如果内容不同则与用户确认，然后删除单独的CLAUDE.md。 CLAUDE.md已是指向AGENTS.md的符号链接 → 已完成；停止。
创建符号链接
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md # git 将其存储为真正的符号链接（模式 120000）
验证它是以符号链接而非副本提交的：
git ls-files -s CLAUDE.md # 模式应为 120000
也可以选择将其他工具指向同一个文件：
ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
Monorepo（Turborepo / 工作区）
保留一个根目录下的 AGENTS.md 用于仓库范围的约定（上面的 CLAUDE.md 符号链接也一样），然后为每个需要自己规则的工作区添加一个作用域内的 AGENTS.md——如 apps/<app>/AGENTS.md、packages/<pkg>/AGENTS.md——每个都有自己的同级符号链接，创建时从该目录内部，使目标为相对路径：
cd apps/web && ln -s AGENTS.md CLAUDE.md # CLAUDE.md -> ./AGENTS.md（同一目录）
- Claude Code 会读取它正在处理的文件最近的
CLAUDE.md，因此嵌套文件补充而不是替换根目录的文件。将仓库范围的内容放在根目录；仅在工作区中放置该包特有的增量——不要重复根目录的内容。 - 始终使每个符号链接相对于其自己的文件夹（在
cd进入工作区后执行ln -s AGENTS.md CLAUDE.md），永远不要指向根目录——相对的同级目录链接在检出/移动后仍然有效。 - Turborepo 本身不读取这些文件（它们是为代理准备的），所以不需要修改
turbo.json。如果你想让它们暴露出来，仍然可以在根目录的AGENTS.md中注明该约定。
README
如果没有 README.md，则搭建一个最小化的模板（项目名称、一行描述、设置/运行命令）。将面向人类的文档保留在 README.md 中，将代理指令放在 AGENTS.md 中——不要将两者合并。
Windows / CI 注意事项（重要）
Git 符号链接需要 core.symlinks=true，并且在 Windows 签出或某些 CI 运行器上可能会失效（符号链接会变成一个包含 AGENTS.md 的文本文件）。如果项目面向 Windows，首选回退方案：一个真正的小型 CLAUDE.md，其全部内容是一个指向：
请参见 [AGENTS.md](./AGENTS.md) 了解项目和代理指令。
——接受这需要手动同步（或通过检查）的事实。在符号链接可靠的地方，符号链接更好。
以后不要撤销它
如果你看到 CLAUDE.md 是指向 AGENTS.md 的符号链接，那是故意的——编辑 AGENTS.md，永远不要用副本替换符号链接。
AGENTS.md 模板
# AGENTS.md
针对在此仓库中工作的 AI 代理和人类的指令。
`CLAUDE.md` 是指向此文件的符号链接；此文件是唯一真相来源。
## 项目概览
<这是什么，1–3 句话>
## 命令
- 安装: `…`
- 开发: `…`
- 构建: `…`
- 测试 / 代码检查 / 格式化: `…`
## 约定
- <代码风格、语言/运行时、格式化>
- 提交信息: <例如 Conventional Commits>
- <代理必须不做或始终做的事情>
## 布局
<关键目录以及各自存放的内容>