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) を提供し、それを厳格なチェック（型チェック、lint、テスト実行、視覚的スクリーンショット）と組み合わせることで、必要な証拠が揃うまでモデルのタスク完了をブロックします。

コアコンセプト

コンセプト	役割	強制方法
ルールファイル (`AGENT.md`, `AGENTS.md`, `CLAUDE.md`)	スタイル、計画、安全性などに関する人間が書いたガイドライン。	アドバイザリー – モデルは読み込む必要があるが、自動的にはブロックされない。
Hooks / アーティファクト	具体的なチェック（型チェック、lint、テスト、視覚的証拠、状態更新）	エージェント固有のフックスクリプト（例: `.claude/hooks/block-destructive.sh`）またはフォールバックの git pre-commit フックによって強制される。
メモリファイル (`memory/*.md`)	セッション間の永続的な引き継ぎ – 計画、進捗、検証基準、注意点。	フックがこれらのファイルの更新を検証。更新がない場合はハードブロックされる。
ヘルパースクリプト (`.agent-md/bin/*`)	エージェントが呼び出せる小さなシェルユーティリティ（ヘルパーの検出、Playwrightスクリーンショットの実行、診断など）。	モデルによって直接実行され、後続のフックで使用される決定論的な結果を返す。

インストール後の構成

your-project/
├─ AGENT.md               # エージェントの単一の信頼できる情報源
├─ AGENTS.md              # Codex / Cursor / Windsurf 用のコピー
├─ CLAUDE.md              # Claude Code 用に AGENT.md をインポートするラッパー
├─ agent-md.toml.example  # 決定論的検証設定のテンプレート
├─ .claude/               # Claude 固有の設定とフック
├─ .codex/                # Codex 固有のフックと設定
├─ .agents/skills/        # ネイティブ Codex スキル (verify, visual-evidence)
├─ .cursor/… .windsurf/…  # 各エージェント用のルールファイル
├─ .agent-md/bin/         # ヘルパースクリプト (discover_helpers.sh, doctor.sh, …)
├─ memory/                # 永続的な状態ファイル (plan.md, progress.md, …)
└─ .githooks/pre-commit   # オプションの汎用フォールバックフック

これらはすべて、単一の curl … | bash コマンドまたは提供されている install.sh スクリプトでインストールされます。

検証の仕組み

チェックの設定 – agent-md.toml.example を agent-md.toml にコピーし、typecheck、lint、test、および視覚的アーティファクトの要件に対するコマンドを入力します。
エージェントの実行 – モデルは通常通りコードを書きます。
フックの起動 – モデルが完了を通知すると、適切なフックが設定されたコマンドを実行します。
ブロックまたは許可 – コマンドが失敗したり、必要な視覚的証拠が欠落・古い場合、フックはモデルの完了ステップを中断し、エラーメッセージを返します。すべてのチェックが通過した場合のみ、モデルの出力が受け入れられます。

標準的なワークフロー

# 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 を編集。

# 4. Claude Code (または Codex, Cursor, …) でコーディングを開始
#    エージェントはルールを確認し、終了時にフックが実行されます。

# 5. UI 作業が含まれる場合はスクリーンショットをキャプチャ
./.agent-md/bin/playwright-capture.sh http://localhost:3000 .agent/visual/home.png
# 視覚的チェックを説明するマークダウンメモを作成

ステップが失敗すると、フックが明確なメッセージを表示し、モデルは作業をやり直す必要があります。

推奨されるユーザー

LLMベースのコード生成に依存し、再現可能で監査可能な出力を必要とするチーム。
セキュリティを重視する開発者で、破壊的な Bash コマンドをブロックしたり、状態ファイルが更新されていることを確認したい場合。
UI を構築するプロダクトチームで、単体テストに加えて視覚的な回帰テストの証拠が必要な場合。
オープンソースのメンテナーで、AI 貢献者向けに「コントラクト」を埋め込む軽量で言語に依存しない方法を探している場合。

制限事項（ドキュメント通り）

ルール (AGENT.md) はアドバイザリーであり、フックのみが強制力を持つ。
強制力はホストエージェントによって公開されるイベントに限定される（例: Cursor や Windsurf はオプションの git-hook フォールバックのみ）。
Pre-commit フックは git commit --no-verify でバイパス可能。
Bash セキュリティフックはガードレールであり、完全なサンドボックスではない。

開発と CI

テストは Bats (Bash Automated Testing System) で記述。
ShellCheck による linting と、フックファイルの JSON 検証を実施。
CI はテストスイート、ShellCheck、エイリアス同期チェック、インストーラーのスモークテストを実行。

ライセンス

MIT – 自由に使用、変更、再配布が可能。

結論 – agent-md は、AIコーディングアシスタントとの非構造化なやり取りをコントラクト駆動型のプロセスに変える、実用的で依存関係の少ないツールキットです。チームはモデルの作業が完了と見なされる前に、型チェック、テスト、視覚的証明、状態更新を要求できるようになります。