agent-md多Agent支持矩阵:一份规则集如何在Claude Code、Codex、Cursor、Windsurf复用

原创2026-10-22 11:07:161,844 阅读

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 支持矩阵的核心价值。✨

登录后查看全文
agent-md