iamfakeguru/agent-md

Production-grade agent directives for autonomous coding agents: Claude Code, Codex, Cursor, Windsurf, Aider.

agent-md – 用于编码代理的便携式合约

它是什么 – agent-md 是一个微型、语言无关的框架，让您可以在代码库中嵌入正式且可强制执行的合约，以便 AI 编码助手（Claude Code、Codex、Cursor、Windsurf 等）能够受到引导、验证并承担责任。它通过安装一组规则文件、git-hooks 和辅助脚本，将通常自由形式的提示词转变为可重现、可审计的工作流程。

为什么重要 – 随着基于 LLM 的结对程序员变得普遍，开发人员失去了对模型实际操作的能见度。agent-md 为代理的指令提供了单一事实来源 (AGENT.md)，并结合了硬性强制检查（类型检查、linting、测试执行、视觉截图），在提供必要证据前，可阻止模型完成任务。

核心概念

概念	角色	如何强制执行
规则文件 (`AGENT.md`, `AGENTS.md`, `CLAUDE.md`)	人类编写的关于风格、规划、安全等的指导。	咨询性质 – 模型必须阅读，但不会自动阻挡。
Hooks / 工件	具体检查（类型检查、lint、测试、视觉证据、状态更新）	由代理特定的 hook 脚本（例如 `.claude/hooks/block-destructive.sh`）或后备 git pre-commit hooks 强制执行。
记忆文件 (`memory/*.md`)	会话间的持久传递 – 计划、进度、验证标准、注意事项。	Hooks 验证这些文件是否已更新；缺少更新会导致硬性阻挡。
辅助脚本 (`.agent-md/bin/*`)	任何代理皆可调用的小型 shell 工具（发现辅助工具、执行 Playwright 截图、诊断）。	由模型直接执行；它们返回确定性结果供后续 hooks 使用。

安装后的内容

your-project/
├─ AGENT.md               # 代理的单一事实来源
├─ AGENTS.md              # Codex / Cursor / Windsurf 的副本
├─ CLAUDE.md              # 为 Claude Code 导入 AGENT.md 的包装器
├─ agent-md.toml.example  # 确定性验证配置模板
├─ .claude/               # Claude 特定的设置与 hooks
├─ .codex/                # Codex 特定的 hooks 与配置
├─ .agents/skills/        # 原生 Codex 技能 (verify, visual-evidence)
├─ .cursor/… .windsurf/…  # 这些代理的规则文件
├─ .agent-md/bin/         # 辅助脚本 (discover_helpers.sh, doctor.sh, …)
├─ memory/                # 持久状态文件 (plan.md, progress.md, …)
└─ .githooks/pre-commit   # 可选的通用后备 hook

所有这些都可以通过单一 curl … | bash 指令或提供的 install.sh 脚本安装。

验证运作方式

配置检查 – 将 agent-md.toml.example 复制为 agent-md.toml 并填入 typecheck、lint、test 和视觉工件要求的指令。
执行代理 – 模型照常编写代码。
触发 Hooks – 当模型表示完成时，适当的 hook 会执行配置的指令。
阻挡或允许 – 如果任何指令失败，或所需的视觉证据缺失/过时，hook 会中止模型的完成步骤并返回错误信息。只有在所有检查通过后，模型的输出才会被接受。

典型工作流程

# 1. 安装到新仓库
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bash

# 2. 使用项目特定的准则编辑 AGENT.md
vim AGENT.md

# 3. 定义验证指令
cp agent-md.toml.example agent-md.toml
# 编辑 toml 以指向您的测试执行器、linter 等。

# 4. 开始使用 Claude Code (或 Codex, Cursor, …) 进行编码
#    代理将看到规则，并在完成时执行 hooks。

# 5. 如果涉及 UI 工作，请截取屏幕截图
./.agent-md/bin/playwright-capture.sh http://localhost:3000 .agent/visual/home.png
# 写下描述视觉检查的 markdown 笔记

如果任何步骤失败，hook 会打印清晰的信息，模型必须重做工作。

适用对象

依赖基于 LLM 的代码生成且需要可重现、可审计输出的团队。
注重安全的开发人员，希望阻挡破坏性的 Bash 指令或确保状态文件已更新。
构建 UI 的产品团队，除了单元测试外还需要视觉回归证据。
开源维护者，希望以轻量级、语言无关的方式为 AI 贡献者嵌入“合约”。

限制（如文件所述）

规则 (AGENT.md) 是咨询性质的；只有 hooks 可以强制执行。
强制执行仅限于主机代理公开的事件 – 例如，Cursor 和 Windsurf 仅获得可选的 git-hook 后备。
Pre-commit hooks 可以通过 git commit --no-verify 绕过。
Bash 安全 hooks 是护栏，而非完整的沙盒。

开发与 CI

测试使用 Bats (Bash Automated Testing System) 编写。
使用 ShellCheck 进行 linting，并对 hook 文件进行 JSON 验证。
CI 执行测试套件、ShellCheck、别名同步检查和安装程序冒烟测试。

授权

MIT – 可自由使用、修改和重新分发。

总结 – agent-md 是一个实用、低依赖的工具包，将与 AI 编码助手通常非结构化的交互转变为合约驱动的流程，让团队在模型工作被视为完成之前，能够要求类型检查、测试、视觉证明和状态更新。