このリポジトリの AGENTS.md を改めて読み直して、何を制御しているのか・何が足りないのかを整理した。
##AGENTS.mdとは
OpenAI Codexなどのエージェントがリポジトリで作業するとき、最初に読み込む指示書。CLAUDE.mdがClaude Code向けなのに対して、AGENTS.mdは主にCodex向けのルールを定義している。
現状66行。短いファイルだが、エージェントの行動をかなり絞り込んでいる。
##構造の全体像
現状のAGENTS.mdは、大きく5つのブロックで構成されている。
- Purpose — Discord通知の義務化宣言
- Agent Guidelines — 設計哲学（YAGNI/KISS/DRY）
- Mandatory Completion Step —
codex:finishコマンドの実行義務 - Mandatory Memo Blog Step — memo記事の作成義務
- Git Completion Step — commit/pushの手順
##設計思想を読み解く
###「完了の可視化」が最優先
AGENTS.mdの中心にあるのは「Codexが仕事を終えたことを人間が確実に把握できるようにする」という思想。Discord通知、memo記事、gitコミットの3つを必須にすることで、エージェントの作業が闇に消えるのを防いでいる。
bun run codex:finish -- --summary "<short completion summary>" --memo "src/_memo/content/YYYY/MM/<slug>.mdx"
このコマンドが全ての起点。通知とログを1つのコマンドに集約しているのは運用として正しい。
###失敗時のガードレール
通知失敗時のルールが明文化されている点は地味に重要。
- Retry once.
- If it still fails, report the failure reason in the final response.
- Do not claim completion notification was sent when it was not.
3番目の「送ってないのに送ったと言うな」は、LLMのハルシネーション対策として的確。エージェントは成功を装う傾向があるので、こういう明示的な禁止は効く。
###一次情報の強制
memo記事に「参照した一次情報」セクションを必須にしている。ローカルパスではなく公開URLを求めるルールにすることで、記事が外部から検証可能になる。
- Required section heading: `## 参照した一次情報`
- List only publicly accessible primary-source URLs
- Do not list local files or local paths
AIが適当なURLを出すリスクはあるが、「一次情報を明示しろ」というルール自体は正しい方向。
##現状の課題
###1. Claude CodeとCodexでルールが分散している
CLAUDE.mdとAGENTS.mdの二重管理になっている。両方に書くべきルール（memo記事のスタイル、一次情報ポリシーなど）がどちらか一方にしかない。CLAUDE.mdには Read ./AGENTS.md と書いてあるが、逆方向の参照はない。
###2. Agent Guidelinesが1行しかない
Always prefer simplicity over pathological correctness. YAGNI, KISS, DRY.
方向性としては正しいが、これだけでは具体的な判断基準にならない。例えば「エラーハンドリングをどこまで入れるか」「型定義はどこまで厳密にするか」などの判断がエージェント任せになっている。
###3. テストに関する言及がゼロ
コード変更を伴うタスクが前提なのに、テスト実行や型チェックへの言及がない。codex:finish:build はオプション扱いで、通常の codex:finish にはビルド検証が含まれない。壊れたコードがpushされるリスクがある。
###4. ブランチ戦略が未定義
Git Completion Stepでは git push としか書いていない。ブランチ名の規則、mainへの直pushの可否、PRを作るべきかの判断基準がない。現状はCodexがmainに直pushする運用のようだが、それが意図的なのか未整備なのか、ファイルからは読み取れない。
###5. スコープの制限がない
「どのディレクトリを触っていいか」「どのファイルは変更禁止か」といったスコープ制限がない。エージェントが .env や CLAUDE.md 自体を書き換えるリスクを考えると、明示的な制限があったほうが安全。
##CLAUDE.mdとの比較
| 観点 | AGENTS.md | CLAUDE.md |
|---|---|---|
| 対象 | Codex | Claude Code |
| 行数 | 66行 | 97行 |
| 設計哲学 | YAGNI/KISS/DRY（1行） | スキル体系で詳細定義 |
| memo記事 | 構造のみ指定 | 文体・トーンまで指定 |
| 品質チェック | オプション | quality-gateスキルあり |
| テスト | 言及なし | testing-strategyスキルあり |
CLAUDE.mdのほうがスキルシステムを通じて体系化が進んでいる。AGENTS.mdは「最低限これだけは守れ」という防衛線の設計。
##どう改善するか
短期的にできること:
codex:finishにtypecheckを組み込む（壊れたコードのpush防止）- 触っていいディレクトリのホワイトリストを追加
- CLAUDE.mdのmemo記事スタイルルールをAGENTS.mdにも反映
中長期:
- CLAUDE.mdとAGENTS.mdの共通ルールを別ファイルに切り出し、両方から参照する構成にする
- エージェントごとの権限レベル（読み取り専用、特定ディレクトリのみ変更可、など）を定義する
##まとめ
AGENTS.mdは「完了の可視化」と「ハルシネーション防止」に絞った実用的なファイルになっている。ただ、コード品質のガードレール（テスト・型チェック・スコープ制限）が弱い。CLAUDE.mdのスキル体系が充実してきた今、AGENTS.md側も同じレベルまで引き上げるタイミングに来ている。