agent-md多Agent支持矩阵:一份规则集如何在Claude Code、Codex、Cursor、Windsurf复用
agent-md多Agent支持矩阵:一份规则集如何在Claude Code、Codex、Cursor、Windsurf复用
agent-md 是一套面向自主编码 Agent 的生产级规则集与钩子方案:以单一事实源 AGENT.md 为核心,通过 install.sh 安装器把同一份指令自动分发到 Claude Code、Codex、Cursor、Windsurf 四大主流编码助手,并结合原生 hooks 与 git 钩子兜底,实现"规则写一次、多 Agent 复用"。🎯
🧩 为什么"多 Agent 复用"是第一难题
如果你同时用 Claude Code 写后端、Cursor 改前端,很容易遇到这样的窘境:
- 每个工具的规则入口不同(
CLAUDE.md、AGENTS.md、.cursor/rules/、.windsurf/rules/); - 手动维护多份规则,时间一长必然漂移——A 工具改了约定,B 工具还是旧版;
- 规则文件本质是"建议"(advisory),Agent 不读不执行就形同虚设。
agent-md 的思路是把 Agent 引导分成两层(见 README.md):
| 层 | 作用 | 可靠性 |
|---|---|---|
| 规则文件 | 判断、规划、风格、流程 | 建议性,靠 Agent 自觉 |
| Hooks / 工件 | 类型检查、测试、状态更新、视觉证据 | 宿主支持时可强制 |
一句话原则:凡是"可能被遗忘或被找借口绕过"的事,就从散文挪到可检查的工件里去。
📦 支持矩阵核心:1 个主规则,4 个入口
AGENT.md 是全项目唯一的指令源。安装器会按目标 Agent 把同一份内容复制或包装到各工具的专属位置,矩阵如下(源自 AGENT.md 第 15 节):
| Agent | 安装的文件 | 是否装原生 hooks |
|---|---|---|
| Claude Code | CLAUDE.md、.claude/settings.json、.claude/hooks/ |
✅ |
| Codex | AGENTS.md、.codex/hooks.json、.codex/hooks/、.agents/skills/ |
✅(实验性) |
| Cursor | AGENTS.md、.cursor/rules/agent-md.mdc |
❌ |
| Windsurf | AGENTS.md、.windsurf/rules/agent-md.md |
❌ |
| 其他工具 | 手动指向 AGENT.md 即可 |
❌ |
包装逻辑很巧妙:Cursor 和 Windsurf 的规则文件由 install.sh 自动生成,头部带上各自的 frontmatter(alwaysApply: true 或 trigger: always_on),正文直接就是 AGENT.md 全文——改一处,处处生效。📌
🚀 一键安装步骤:最快接入方法
clone 仓库后,在项目里执行安装器即可:
git clone https://gitcode.com/gh_mirrors/cla/agent-md
cd agent-md
./install.sh /path/to/your-project
常用参数:
./install.sh --agent=codex,cursor . # 只给指定 Agent 安装
./install.sh --dry-run . # 预演,不改动任何文件
./install.sh --no-overwrite . # 不覆盖已存在文件
./install.sh --githooks . # 启用 git 钩子兜底
安装器的默认行为以"安全"为先:
- 覆盖顶层规则文件前,自动备份为
*.bak; memory/下的 5 个状态文件永不覆盖(那是你的工作状态);- 已有
.claude/settings.json默认跳过,可用--claude-settings=merge合并钩子。
⚖️ 强制力差异矩阵:哪些能"硬拦",哪些只是提醒
这是多 Agent 场景最关键的一节——不同宿主能暴露的钩子事件不同,强制力度自然有差异(来自 README.md 的 Enforcement Matrix):
| 检查项 | Claude Code | Codex | Cursor / Windsurf |
|---|---|---|---|
| Bash 危险命令拦截 | 硬拦截(block-destructive.sh) |
硬拦截(pre-tool-use.sh) |
未覆盖 |
| 收尾时 type-check / lint / 测试 | 硬拦截(stop-verify.sh) |
继续执行提示(stop.sh) |
可选 .githooks/pre-commit |
强制更新 memory/progress.md |
硬拦截(state-enforcement.sh) |
继续执行提示(stop.sh) |
可选 .githooks/pre-commit |
| UI 视觉证据 | 默认建议;[visual].required = true 时硬拦 |
同左(经 Stop 包装) | 建议性 |
| Bash 输出截断提醒 | 建议性 | 建议性(PostToolUse) | 未覆盖 |
| 规划 / 上下文 / 编辑安全 | 建议性 | 建议性 | 建议性 |
两点注意:
- Claude Code 的钩子注册在 .claude/settings.json,覆盖
PreToolUse/PostToolUse/Stop三类事件; - Codex 钩子是实验性的,需要先在
~/.codex/config.toml开启:
[features]
codex_hooks = true
🛡️ 不支持原生钩子的 Agent 如何兜底
Cursor 和 Windsurf 拿不到原生钩子,agent-md 给了通用兜底:.githooks/pre-commit。它随安装器写入仓库但默认不激活,需要手动一行命令启用:
git config core.hooksPath .githooks
诚实的边界也要知道:pre-commit 可以被 git commit --no-verify 绕过;Bash 安全钩子是护栏,不是沙箱。所以建议"规则 + 钩子 + 测试"三层并用,而不是只押注某一层。🛡️
⚙️ agent-md.toml:把"启发式猜测"变成显式声明
默认情况下,钩子靠启发式猜检查命令(tsconfig.json → tsc、pyproject.toml → pytest/ruff 等)。想要确定性验证,复制一份示例配置并声明即可:
cp agent-md.toml.example agent-md.toml
[verify]
typecheck = "npx --no-install tsc --noEmit"
lint = "npx --no-install eslint ."
test = "pnpm test"
lint_file = "npx --no-install eslint {file}"
[visual]
required = true
artifacts_dir = ".agent/visual"
freshness_seconds = 3600
字段说明可参考 agent-md.toml.example。特别注意 [visual].required = true 时,"光截个图"不算数——必须有一份结构化 Markdown 证据(改动文件、路由、视口、截图文件名、观察结果),这才是"视觉验证"的完整契约。若项目没配置任何检查,钩子会放行但明确警告:工作处于未验证状态。
🧠 memory/ 五文件:所有 Agent 共享的持久记忆
聊天历史不是持久记忆。agent-md 在 memory/ 下维护 5 个文件,作为跨会话、跨 Agent 的交接面:
| 文件 | 职责 |
|---|---|
| memory/agents.md | 活跃 Agent、MCP、技术栈 |
| memory/plan.md | 宏观设计与垂直切片 |
| memory/progress.md | 原子任务清单与当前状态 |
| memory/verify.md | 完成定义(Definition of Done) |
| memory/gotchas.md | 已被人工纠正过的错误模式 |
其中 state-enforcement.sh 会硬拦截:源文件改了但 progress.md 没更新,Agent 无法宣布完成。这一招让四个工具共享同一份"任务账本",换工具接手也不丢上下文。
🧪 这套规则集自身也被测试保护
agent-md 的所有钩子脚本都有对应的 Bats 测试(如 tests/stop-verify.bats、tests/block-destructive.bats),CI 会跑 Bats、ShellCheck、JSON 校验与安装器冒烟测试,配置见 .github/workflows/ci.yml:
bats tests/
✅ 总结
- 单一事实源:
AGENT.md写一次,安装器分发到CLAUDE.md、AGENTS.md及各工具规则目录; - 双层契约:建议性规则管"怎么做",可执行钩子管"必须做";
- 优雅降级:不支持原生钩子的 Cursor / Windsurf 用
.githooks/pre-commit兜底; - 确定性验证:
agent-md.toml显式声明检查命令,拒绝靠猜; - 共享记忆:
memory/五文件让不同 Agent 之间可无缝交接。
工具可以随技术栈随时切换,但规则和验证契约只维护一份——这就是 agent-md 多 Agent 支持矩阵的核心价值。✨