agent-md

用于编码 Agent 的生产级指令集，支持：Claude Code, Codex, Cursor, Windsurf, Aider。

agent-md 提供了一套统一的规则文件（Source-of-truth）、仓库本地钩子（Repo-local hooks）、持久化任务状态以及若干辅助脚本，让 Agent 不再盲目猜测，而是通过证据证明其工作成果。

原则说明：

• Markdown 规则：属于建议性质，需要 Agent 自行阅读并遵循。
• 钩子（Hooks）与 Git Hooks：在宿主 Agent 支持的情况下强制执行。
• 测试、类型检查、截图及证据记录：比模型自身的自我评估更具说服力。

快速开始

# 在您的项目目录内运行
curl -sL https://raw.githubusercontent.com/iamfakeguru/agent-md/main/install.sh | bash

默认安装对 Claude Code、Codex、Cursor 和 Windsurf 的支持。

您将获得什么

your-project/
  AGENT.md                         # 事实来源 (source of truth)
  AGENTS.md                        # Codex / Cursor / Windsurf 适用
  CLAUDE.md                        # Claude Code 适用
  agent-md.toml.example            # 确定性验证配置

  .claude/
    settings.json
    hooks/                         # Claude Code 强制执行钩子

  .codex/
    hooks.json
    hooks/                         # Codex 钩子封装

  .agents/skills/                  # 原生 Codex 技能
    agent-md-verify/
    visual-evidence/

  .cursor/rules/agent-md.mdc       # Cursor 项目规则
  .windsurf/rules/agent-md.md      # Windsurf 工作区规则

  .agent-md/
    bin/
      discover_helpers.sh
      doctor.sh
      playwright-capture.sh

  memory/
    agents.md
    plan.md
    progress.md
    verify.md
    gotchas.md

  .githooks/pre-commit             # 适用于任何 Agent 的可选兜底方案

核心理念

Agent 指导分为两个层级：

层级	目的	可靠性
规则文件	判断、规划、风格、流程	建议性
钩子/制品	类型检查、测试、Lint、状态更新、视觉证据	支持环境下强制执行

如果某件事可能被遗忘或被模型“合理化”掩盖，请将其从文字描述中移出，转变为可校验的制品。

运行时经验应用

本仓库将生产级 Agent 的最佳实践以“契约”而非重复的 API 样板代码形式应用：

• 成本/上下文纪律 — 简洁的指令、辅助工具发现机制，以及持久化的 memory/ 文件，避免臃肿重复的 Prompt。
• 可靠性 — 结构化的 Hook JSON、确定性检查、高风险命令拦截块，以及明确的“未验证状态”警告。
• 性能 — 受限的工作切片、选择性加载上下文、安全的并行工具调用，以及截断警告。
• 工具使用 — 结构化的工具结果指导、执行前验证，以及清晰的辅助工具边界。
• 输出质量 — 测试、运行时证据、视觉制品，以及独立的对抗性验证。

Prompt 缓存、流式显示、提供商重试、幂等键、Temperature 调节和批处理等 API 特性属于应用程序或宿主运行时的职责。agent-md 指导编码 Agent 在项目使用这些特性时进行记录和验证，而不是试图通过规则文件强制要求提供商行为。

执行矩阵

检查项	Claude Code	Codex	Cursor / Windsurf / 其他
Bash 安全性	通过 .claude/hooks/block-destructive.sh 硬拦截	通过 .codex/hooks/pre-tool-use.sh 硬拦截	不支持
结束时的类型检查/Lint/测试	通过 stop-verify.sh 硬拦截	通过 .codex/hooks/stop.sh 继续执行	可选 .githooks/pre-commit
更新 memory/progress.md	通过 state-enforcement.sh 硬拦截	通过 .codex/hooks/stop.sh 继续执行	可选 .githooks/pre-commit
UI 视觉证据	默认建议，当 [visual].required = true 时硬拦截	通过 Codex Stop 封装实现相同效果	通过规则建议
新导出函数无配套测试	建议	通过规则/技能建议	通过规则建议
Bash 输出被截断	建议	通过 Codex PostToolUse 建议	不支持
规划、上下文、编辑安全	建议	建议	建议

Codex 钩子处于实验阶段，需要：

[features]
codex_hooks = true

在 ~/.codex/config.toml 中配置。

安装选项

# 安装所有支持的 Agent
./install.sh .

# 安装指定 Agent
./install.sh --agent=claude .
./install.sh --agent=codex,cursor .

# Git 钩子兜底
./install.sh --githooks .
./install.sh --no-githooks .

# Claude 设置处理方式
./install.sh --claude-settings=skip .
./install.sh --claude-settings=merge .
./install.sh --claude-settings=replace .

安装程序会在替换现有顶级规则文件前进行备份。现有的 memory/*.md 文件永远不会被覆盖。.claude/settings.json 默认会被跳过，除非您选择 merge 或 replace。

确定性验证

启发式方法很有用，但明确的命令更好。复制示例配置并声明您的项目检查：

cp agent-md.toml.example agent-md.toml

[verify]
typecheck = "npx --no-install ts