用 agents-md-writer 优化你的 AGENTS.md

最近我写了一个 agent skill：agents-md-writer。

它做的事情很简单：让 agent 写 AGENTS.md 的时候，先去仓库里探测，只写验证过的东西，写完自己跑一遍检查。

GitHub：https://github.com/RUIIIOVO/agents-md-writer

为什么写这个

起因是我发现，让 AI「给这个项目写一份 AGENTS.md」，产出基本都很差。差得还挺有规律：

• 写没跑过的命令。仓库里 package.json 根本没有 test script，它照样写「运行 npm test」。
• 写不存在的路径。它抄 README，不看文件系统，README 一旧它就跟着错。
• 写死开发机路径，/Users/alice/dev/project 直接进文件，换台机器就废了。
• 写三百行「编写清晰、可维护的高质量代码」这种话。

前三条是错误，能一眼看出来。第四条最麻烦，因为它看起来「没毛病」。

AGENTS.md 是每次会话开始时被完整注入上下文的。你往里塞的指令越多，所有指令的遵循率一起往下掉，不只是新加的那条。所以一份塞满套话的 AGENTS.md，不光浪费 token，还会把你真正在意的那几条规则稀释掉。

左边这份，每次会话都要花预算注入一遍，但里面没有一句是可执行的。「Code is well written」这种验收项，agent 想怎么解释都行，等于没写。

第二个原因更私人一点：我自己攒了几条给 agent 的规矩，想把它们固定下来，不用每个项目重新交代一遍。比如这两条，是我现在全局配置里最有用的：

- 本轮改动了文件就在回复末尾列出全部改动文件的**完整路径**，标注新增/修改/删除，
  不要只说「已更新」。
- 需要我拍板的事项一律收在回复最末尾的「待你确认」块，编号列出。
  每条写成：一句话说清问题 → 列 A/B/C 选项及各自代价 → 标出你推荐哪个并说明理由。

第一条治「它到底改了什么我得自己翻」，第二条治「它自作主张选了一条路还不告诉我有别的选项」。

但这两条属于个人偏好，换个仓库依然成立，所以它们该待在全局配置里，不该复制进每个项目的 AGENTS.md。这个区分我也写进了 skill：它会主动把这类规则往全局挪，把「本仓库的提交格式是 feat(scope):」这类事实留在项目里。

支持哪些 agent

skill 本身遵循 Agent Skills 规范，任何加载 skill 的工具都能用。安装脚本目前覆盖：Claude Code、Codex、pi、omp、Hermes、ZCode、WorkBuddy。

它写出来的 AGENTS.md，这些工具会直接读：Codex、pi、omp、OpenCode、Grok CLI、Kimi Code、OpenClaw、DeepSeek Harness、Hermes、GitHub Copilot。Claude Code 和 Gemini CLI 需要一个入口文件指过去。逐个 agent 的路径矩阵和证据在仓库的 references/agent-registry.md 里。

Gemini CLI 没有 skill 机制，装的时候会退化成往 ~/.gemini/GEMINI.md 追加一个带标记的引用块。它只是叫模型去读那个文件，没有 progressive disclosure，可靠性比真 skill 差一截。

安装

最省事的办法：把这句话直接贴给你正在用的 agent。

安装这个 skill：https://github.com/RUIIIOVO/agents-md-writer

自己动手就两条命令：

git clone https://github.com/RUIIIOVO/agents-md-writer.git ~/.agents/skills/agents-md-writer
~/.agents/skills/agents-md-writer/scripts/install.sh

第一条把 skill 放到 ~/.agents/skills/ 这个共享位置，第二条只链到你当前用的那个 agent，其他的不碰。

安装脚本怎么知道装到哪：你在终端里手动跑，它列出本机的 agent 让你选；由 agent、管道或 CI 调用，它自己认出调用者，不弹提示。重复跑不会出错。

几个常用参数：

./scripts/install.sh --all          # 本机所有 agent 都链上
./scripts/install.sh --agent codex  # 指定一个
./scripts/install.sh --dry-run      # 只看计划，不改东西
./scripts/install.sh --where        # 输出 agent 和路径两行就退出

实体只有一份，各 agent 各链一条软链过去。git pull 一次，所有链上的 agent 都是新的，不会分裂成好几份副本。

Windows 用 scripts/install.ps1，建的是目录联接（junction），不需要管理员权限，也不用开发者模式。

装完问一句「你现在有哪些 skill」就能确认。

三种用法

装完之后不用再跑任何命令，也不用记 slash command。走哪一条，看你怎么说。

一、给项目写一份

在项目目录里打开 agent，直接说：

给这个项目写一份 AGENTS.md

这一条就一句话：先探测，绝不猜。

skill 会要求 agent 先跑一遍 ls -A、读 package.json / pyproject.toml / Cargo.toml、find 找 Makefile、git log --format=%s -20 看提交风格，然后才动笔。README 里写了但仓库里不存在的命令，直接不写进去，或者标成「已知缺口」。

写完它会自己跑一遍 lint，再按 12 项自检清单过一遍。如果你用的是 Claude Code，它还会建一个只有一行 @AGENTS.md 的 CLAUDE.md 当入口，而不是复制两份内容出来各自跑偏。

二、检查现有的

检查一下我的 AGENTS.md

这一条只读不改。它给你一句结论（能用 / 要修 / 建议重写），加一张 位置 → 问题 → 建议 的清单。你没点名要改哪个，它一个字都不动。

也可以直接盘点整台机器：

检查一下我电脑上所有的 AGENTS.md

这里有个细节我写进 skill 了：定位文件必须走 Spotlight 索引（macOS 的 mdfind、Linux 的 plocate），禁止在 home 目录上做无限制递归扫描。不写死这条，agent 很容易一个 find ~ -name AGENTS.md 下去，然后卡在那里。实在没有索引，也要求限定目录和 -maxdepth。

三、整理已经写臃肿的

这个 CLAUDE.md 四百行了，整理一下

这一条会先 cp CLAUDE.md CLAUDE.md.bak 备份并告诉你备份在哪，然后把每一段分类，先给你一张表：

去处	什么内容
留在项目	项目事实：目录结构、命令、边界、约定
上提到全局	个人偏好：语言、输出风格、本机环境
下沉到子目录	只跟某一个模块相关的规则
移到 skill	多步骤流程、低频的专门知识
删除	过期内容、元规则、手填日期、一次性需求

你过目确认之后它才动手。这一步我特意做成两段式的，因为「整理」这个动作删起来没有边界，让 AI 自己决定删什么太危险。

lint 脚本

12 项自检里有 5 项是纯机械的，所以单独做成了脚本，不依赖 AI 判断：

检查项	级别
存在 YAML frontmatter	error
写死开发机路径（/Users/x/、/home/x/、C:\）	error
手填日期（YYYY-MM-DD）	warning
反引号里的路径在磁盘上不存在	warning
行数超过 200	warning

./scripts/lint-agents-md.sh                     # 默认检查 ./AGENTS.md
./scripts/lint-agents-md.sh AGENTS.md docs/sub/AGENTS.md
pwsh -File scripts/lint-agents-md.ps1 AGENTS.md # Windows

退出码 0 表示没有 error，1 表示至少有一个，可以直接挂到 CI 上。NO_COLOR=1 关彩色输出。

脚本只依赖 bash 3.2+（macOS 自带的那个版本）、zsh 或 PowerShell 5.1+，没有外部依赖，不用装 node 也不用装 python。

两个注意点：

• lint 按被检查文件所在目录解析路径，所以要在真实仓库里跑。
• 别拿它检查 SKILL.md，skill 文件本来就该有 frontmatter。

写出来的东西长什么样

摘一段仓库里的样例（examples/after.md）：

## Environment & commands

Prerequisites: Node 20+, pnpm 9+, Docker (for Postgres).

- **Install**: `pnpm install`
- **Dev server**: `pnpm dev` (port 3000)
- **Reset database**: `pnpm db:reset` (drops, recreates, re-runs `migrations/`)

## Boundaries

- `src/routes/` must not import from `src/repos/`. Routes call services; services call repos.
- `migrations/` is append-only. To change a migration, add a new one.

## Review checklist

- [ ] `pnpm typecheck` passes
- [ ] `pnpm lint` passes with zero warnings
- [ ] The changed endpoint was actually called — compiling is not verification

**A human verifies these. AI must not claim they are done**: staging smoke test, dashboard visuals.

最后那行是我比较满意的一个设计。有些验收项 AI 根本没法验——预发环境冒烟、看板视觉——那就明确标出来「这条由人验证，AI 不许声称已完成」，免得它在回复里给你打个勾糊弄过去。

这些规则的依据

章节骨架不是我随手定的，是数了 agents.md 官方 showcase 里三个真实项目的章节：apache/airflow（522 行）、openai/codex（322 行）、temporalio/sdk-java（59 行）。

「指令要可验证」「规则不能互相矛盾」来自 Anthropic 的 memory 文档。「指令预算」的说法来自 HumanLayer 的 Writing a Good CLAUDE.md：前沿模型能可靠遵循的指令大约在 150–200 条，超出之后所有指令的遵循率一起下降。

有两条主张是我自己加的，超出了官方文档：

• 不设固定行数上限。 判断标准是「能不能删掉一行而不损失信息」。根文件超过 200 行，第一反应应该是把内容下沉到子目录的 AGENTS.md，而不是把句子压短。
• 测试和编码规范不是必备章节。 showcase 的统计里它们出现频率很高，但在一个没有测试框架、没有格式化工具的项目里，这两节只会变成套话。

不同意的话欢迎去仓库开 issue。

入口文件别用软链

项目级的入口文件（CLAUDE.md、GEMINI.md）不要用软链。提交进 git 的软链，在 Windows 和一部分 CI runner 上会退化成一个内容是路径字符串的普通文本文件。老老实实建一个只有一行 @AGENTS.md 的实体文件。

用户级配置（~/.claude/、~/.codex/）用软链没问题，install.sh 用的就是软链。

另外 Cursor、Cline、Windsurf 的规则文件格式跟 AGENTS.md 不兼容（.mdc 带 frontmatter、.clinerules、global_rules.md），千万别软链过去。

仓库信息

MIT 协议。CI 在 Linux、macOS、Windows 上跑，断言 examples/before.md 退出码为 1、examples/after.md 为 0。改 lint 规则的话 bash 和 PowerShell 两个脚本都要改。

如果你机器上不止一个 agent，装一份就够，不用每个工具复制一遍。