AGENTS.mdの知見を次に
活かす
（Codex CLI）

by

OpenAI CodexやClaude Code、Cursorといったコーディングエージェントを使っていると、プロジェクトごとにAGENTS.mdというファイルが生成されます1。
このファイルには、AIとの対話を通じて生まれた作業の進め方や設計の判断、つまずいたポイントとその解決策が記録されています。

新しいプロジェクトを始めるとき、過去のプロジェクトでのやり方を何度も言い聞かせているときがあります。
そこで、複数のプロジェクトで蓄積されたAGENTS.mdを一箇所に集め、新しいプロジェクトでの立ち上げ時に参照するようにしました。

#!/bin/bash

# 保存先ディレクトリの作成
mkdir -p agents-references

# 各プロジェクトからAGENTS.mdを収集
for project in */; do
    if [ -f "${project}AGENTS.md" ]; then
        project_name="${project%/}"
        cp "${project}AGENTS.md" "agents-references/AGENTS_${project_name}.md"
        echo "Copied: ${project_name}"
    fi
done

echo "Collection complete. Files saved in agents-references/"Code language: PHP (php)

関連記事

1. 収集スクリプトの実装

agents-referencesという専用フォルダを作り、各プロジェクトのAGENTS.mdをプロジェクト名付きでコピーします。

プロジェクトの知見を蓄積する Project A Project B Project C agents- references 新規 プロジェクト AGENTS.mdを集めて次に活かす

スクリプトをcollect_agents.shとして保存し、プロジェクトフォルダが集まっている親ディレクトリで実行すれば、agents-referencesに一度にすべてのAGENTS.mdが収集されます。

sh collect_agents.shCode language: CSS (css)

このスクリプトは現在のディレクトリにあるすべてのサブフォルダを走査します2。
AGENTS.mdが存在すれば、プロジェクト名を接頭辞として付けた形でコピーします。

例えばmy-web-appというプロジェクトにAGENTS.mdがあれば、agents-references/AGENTS_my-web-app.mdとして保存されます。

2. AGENTS.mdとは何か

AGENTS.mdは、AIコーディングアシスタントが作業履歴や設計判断を記録するファイルです3。

AGENTS.mdとは何か AGENTS .md 記録される内容 技術スタック・フレームワーク 設計上の制約・判断理由 エラーと解決策 テスト・デプロイ手順 試行錯誤の過程を記録 = 生きた知見

具体的には次のような情報が含まれます。

  • プロジェクトの技術スタック（使用言語、フレームワーク、主要ライブラリ）
  • 設計上の制約や方針（なぜこの実装を選んだのか）
  • つまずいたポイントと解決策（エラーメッセージとその対処）
  • 作業の進め方のパターン（テストの書き方、デプロイ手順）

これは人間が書くREADMEやドキュメントとは異なり、実際の試行錯誤の過程が記録されています4。
失敗も含めた生々しい情報があるからこそ、同じような状況に直面したときに役立ちます。

3. 実際の運用例

新しいプロジェクトを作るときには、agents-referencesを作成し、プロジェクト内の参照資料として配置します。
これを元に、Codex CLIでそのプロジェクト用のAGENTS.mdを作るのが恒例です。

また、LLMを使って収集したAGENTS.mdを要約し、インデックスを作ることも有用かもしれません5。

各プロジェクトで得た知見は、そのプロジェクトだけのものではありません。
試行錯誤の記録を蓄積し、横断的に参照できるようにすることで、開発速度が上がります。

  1. AGENTS.mdはOpenAI、Google、Anthropicなど複数企業が協力して策定したオープン標準で、現在はLinux Foundation傘下のAgentic AI Foundationが管理しています – AGENTS.md — a simple, open format for guiding coding agents
  2. for project in */はサブディレクトリを順番に処理するループです。${project%/}はシェルのパラメータ展開で、末尾のスラッシュを削除します – Bash Parameter Expansion
  3. AGENTS.mdはOpenAI Codex、Claude Code、Cursor、Windsurf、Zed、GitHub Copilot、VS Code、JetBrains IDEなど20以上のツールで対応されています – AGENTS.md
  4. AGENTS.mdはプロジェクトルートだけでなく、サブディレクトリにも配置できます。最も近いAGENTS.mdが優先的に読み込まれる階層構造により、モジュール固有の知見も記録可能です – How I Made Cursor Autonomous: AGENTS.md and the Art of AI Instruction
  5. Builder.ioのようなツールでは、AGENTS.mdを活用して非エンジニアでもコード生成時に適切なガイドラインを適用できます。LLMによる要約や検索も将来的に実装される可能性があります – Improve your AI code output with AGENTS.md