Codex と Claude Code が適切に従えるディレクトリ規約とコードスタイルとは？

Codex と Claude Code は、本質的に特定のプログラミング言語、フレームワーク、インデント幅、フォルダーレイアウトを好むわけではありません。比較的確実に従える環境は、既存のリポジトリ規約が一貫しており、必要なルールの適用範囲が明確で、変更を自動的に検証できる環境です。したがって目標は、AI が好みそうな構造を考案することではなく、人や新しいコントリビューターが理解でき、簡潔で検証可能なプロジェクト規約にすることです。openai.com↗code.claude.com↗

ここでいう Codex と Claude Code とは、リポジトリ内のファイルを読み、指示を参照し、コードを変更したりコマンドを実行したりできるコーディングエージェントツールを指します。このようなツールはコード自体から多くの手がかりを得られますが、プロダクトのドメイン用語、禁止されている変更、デプロイ前のチェック、特定フォルダーの例外ルールを常に正確に推論できるとは限りません。リポジトリ構造、指示ファイル、実行可能な検証手順がその不足を補います。cdn.openai.com↗

「正しいフォルダー構造」より一貫性が重要なのはなぜですか？

たとえば、あるチームは機能ごとに src/payments/ と src/users/ を整理し、別のチームはレイヤーごとに src/controllers/、src/services/、src/repositories/ を整理するかもしれません。どちらの方法が Codex や Claude Code にとって自動的に優れていると断定できる根拠はありません。重要なのは、同種の責務がリポジトリ内の似た場所にあり、新規ファイルが同じ基準で配置され、テストと import のスタイルが既存パターンに従っていることです。

エージェントが新しい決済機能を追加する場合も同様です。既存の決済モジュールがリクエスト検証、エラー処理、データアクセス、テストの配置方法を示していれば、そのパターンを続けるほうが安全です。反対に、新機能のたびに新しいファイル名やレイヤーが導入されたり、1 つのフォルダーにドメインコード、ビルド成果物、一時ファイルが混在したりすると、エージェントにも人にも、どこを変更すべきか、その変更が何に影響するかを判断しにくくなります。

したがって、ディレクトリ規約は単なる見た目のルールではありません。コードをどこで見つけるか、何を一緒に変更するか、どの検証を実行するかを示すナビゲーションシステムです。名前と境界が安定しているほど、指示ファイルで長い説明を繰り返す必要は少なくなります。

リポジトリの基本ガイダンスはどこに置くべきですか？

Codex では、一般に AGENTS.md がプロジェクトの指示ファイルとして機能します。このファイルに記載したコードスタイル、構造、命名、テストの指示は、それを含むディレクトリとその配下に適用されます。また、より深い場所にある指示は、競合時により具体的なガイダンスとして機能します。個人環境向けの指示や AGENTS.override.md によるオーバーライドもサポートされています。openai.com↗

Claude Code では、CLAUDE.md または .claude/CLAUDE.md をプロジェクトのメモリとガイダンスの中心として使用できます。親パスにある CLAUDE.md は起動時にコンテキストとして提供され、サブディレクトリ内のファイルは、そのパスのファイルを扱う際に必要に応じて読み込まれます。ユーザーごとの設定には CLAUDE.local.md を使用でき、ホームディレクトリレベルのファイルも利用できます。code.claude.com↗

2 つのファイルは名前が似ていますが、自動検出の動作は同じではありません。特に、Claude Code が共有指示として AGENTS.md を自動的に読むとは想定しないでください。両方のツールを使う場合は、CLAUDE.md から @AGENTS.md を使って共有ファイルをインポートするか、チームの運用モデルに合う接続を明示的に定義してください。code.claude.com↗

ルートのガイダンスファイルは、リポジトリ全体を長々と説明する百科事典ではなく、入口となる地図に近いものにするのが最適です。新しいコントリビューターが最初に必要とするコマンド、トップレベルの構造、主要な不変条件、詳細ドキュメントの場所を示せば十分です。長大な単一の指示ファイルは、実際のコードやタスク要件に使うべきコンテキストを消費し、重要な制約を見つけにくくするおそれがあります。OpenAI Codex 関連の例でも、約 100 行の短い地図のようなファイルと、別ドキュメントを組み合わせる方法が示されています。openai.com↗

AGENTS.md と CLAUDE.md には何を含めるべきですか？

良い指示は、コードからすでに明らかな事実を大量に重複させません。代わりに、コードだけでは学びにくい情報や、誤って推論した場合のコストが大きい情報を優先します。Codex 関連の資料では、命名規約、ドメイン用語、既知の制約と依存関係、ビルドおよびテスト手順は、AGENTS.md に置く価値のある情報として挙げられています。cdn.openai.com↗

ルート指示では、次のような質問に簡潔に答えられます。

• 最初の変更後に、フォーマット、静的解析、型チェック、テストを実行するコマンドは何か？
• ソースコード、テスト、設計ドキュメント、運用ドキュメントはどこにあるか？
• 既存モジュールを拡張する際、どのファイル命名、import、エラー処理、テストの規約に従うべきか？
• 生成ファイル、ビルド成果物、ロックファイル、シークレットを変更またはリポジトリに含めてもよいか？
• 高リスク領域では、計画、追加レビュー、特定のテストが必要か？
• 詳細な設計および運用手順は、どのドキュメントにあるか？

対照的に、「きれいなコードを書く」「セキュリティを優先する」「最善を尽くす」といった広範な文言は、実行可能なルールに変換しにくいものです。「外部入力には既存の検証モジュールを使い、新しい API ルートごとに対応する統合テストを追加する」という文言のほうが、観察・検証できるため有用です。Claude Code のガイダンスでも、プロジェクト固有のルールを具体的に書き、増えてきた指示を定期的にレビューして整理することが重視されています。code.claude.com↗

指示は、実装の細部すべてを規定する文書ではなく、意思決定基準を圧縮した記録であるべきです。特定ライブラリの使い方、API 契約、インシデント対応の順序など、長くなりやすく変更の可能性が高い知識は、docs/ 配下の適切な文書に移し、ルート指示ではその場所と利用条件を示すほうが保守しやすくなります。

個別サブディレクトリのルールはいつ必要ですか？

サブディレクトリのルールは、すべてのフォルダーに機械的に追加するファイルではありません。共有のルートルールで十分な場合、個別ファイルはナビゲーションの負担や競合の可能性を増やすだけになり得ます。一般ルールから明確に逸脱する境界、またはミスの影響が大きい領域に限定するのが適切です。

たとえば、src/payments/ には金額計算の表現方法、外部決済プロバイダー用モックの使用方法、実行すべき特定の統合テストコマンドを記載できます。infra/ では変更前の計画、適用前のチェック、変更可能な環境固有ファイルの制限を必須にできます。generated/ では直接編集を禁止し、ソースと生成コマンドを特定できます。これらのルールの目的はフォルダーを特別に見せることではなく、その領域の実際の制約を作業コンテキスト内で正確に提供することです。

Codex では、ネストした AGENTS.md がそのディレクトリ配下に適用され、より深いファイルがより具体的なルールを提供できます。Claude Code も同様に複数の CLAUDE.md をコンテキストとして蓄積できるため、ネストしたファイルでは親ファイルを曖昧に覆す宣言をするのではなく、その領域でのみ必要な具体的条件を追加するほうが安全です。openai.com↗code.claude.com↗

たとえば、ルートには「変更したパッケージのテストを実行する」と書き、決済フォルダーには「決済契約を変更した場合は、ユニットテストと統合テストの両方を実行する」と書けます。一方、ルートに「テストは常に実行する」、サブフォルダーに「テストを実行しない」と書くと、ツールだけでなく人もどのルールに従うべきか分からなくなります。

Claude Code の .claude/rules/ はどのように分割すべきですか？

Claude Code では、常に必要なグローバルルールを CLAUDE.md に置き、話題が異なるルールやパスに依存する動作を .claude/rules/ 配下の小さなファイルに分割できます。ルールファイルは再帰的に整理でき、パス条件により特定のファイルや領域にだけルールを適用できます。code.claude.com↗

分割の基準はファイル数ではなく、一緒に変更されるルールの凝集性です。たとえば、テストコマンドとテストデータの原則は testing.md に、import・命名・フォーマットの例外は code-style.md に、シークレット・外部リクエスト・権限に関する制約は security.md に置けます。各ファイルは 1 つの話題を扱い、タイトルからいつ読む必要があるのか分かるようにするべきです。

この方法の利点は、不要な指示を常に全文読む必要がないことです。たとえば、ドキュメントだけを編集する作業に完全なデータベースマイグレーションのルールが混在していると、重要な指示を見えにくくする可能性があります。ただし、ルールを細かく分割しすぎると場所を見つけにくくなります。バランスの取れた方法は、ルートの CLAUDE.md で主要なルールグループと目的を簡潔に紹介し、実際の内容はトピック別ファイルに保持することです。

ルールを分離した後は、同じ義務を複数のファイルにコピーすることを避けてください。コピーは時間とともに容易に乖離します。共有原則は 1 か所に保ち、パス固有のファイルには例外と追加条件だけを記録すると、競合を減らせます。

コードスタイルはどのように指定すべきですか？

「AI フレンドリーなコードスタイル」とは、タブかスペースか、関数型かオブジェクト指向かといった普遍的な選択を意味するものではありません。より重要な基準は、リポジトリのローカルな規約を再現できるかどうかです。新しいモジュールが既存モジュールのファイル命名パターン、export スタイル、import 順序、エラー処理経路、テスト構造に従うと、レビューと保守が容易になります。

プロジェクトが言語の一般的な規約と異なる選択をしている場合は、特に文書化する価値があります。Claude Code のドキュメントでは、ES modules や名前付き import の分割代入など、プロジェクト固有のコードスタイルが例として使われています。つまり、言語のデフォルトルールをすべて書き直すのではなく、「このプロジェクトがデフォルトと異なる点」を説明するほうが効率的です。code.claude.com↗

次の表は、スタイルガイダンスを判断するための簡単な基準です。

フォーマッター、リンター、型チェッカーにより、スタイルは文章で強制するのではなく、機械的にテスト可能になります。したがって、指示では「きれいにフォーマットする」と言うよりも、実際に実行するコマンドと失敗時に期待される対応を指定するほうがよいでしょう。Claude Code のベストプラクティスでも、明確なプロジェクト指示と検証可能な開発ワークフローが推奨されています。code.claude.com↗

どのようなディレクトリ構造から始められますか？

以下は、Codex と Claude Code を併用する際に検討できる例です。必須の標準ではありませんが、共有指示、詳細ドキュメント、領域固有の例外を分離するための出発点の 1 つです。

repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│   ├── design-docs/
│   ├── product-specs/
│   ├── runbooks/
│   └── generated/
├── src/
│   ├── feature-a/
│   └── feature-b/
├── tests/
└── .claude/
    ├── rules/
    │   ├── testing.md
    │   ├── code-style.md
    │   └── security.md
    └── settings.json

ここでは、README.md にリポジトリを使い始めるために人が必要とする情報を記載し、ARCHITECTURE.md でシステムの主要な境界と構造を説明し、docs/ には長く詳細な設計、プロダクト、運用に関する知識を置けます。src/ と tests/ の実際のレイアウトは、主としてプロジェクトの既存構造に従うべきです。.claude/rules/ は Claude Code 向けのトピック固有またはパス固有のルールを置く場所です。code.claude.com↗

ルートに多数のファイルを置くことが気になる場合、重要なのはファイル名の数ではなく、責務の分離です。1 つのファイルがプロジェクト紹介、システム設計、運用対応、詳細な API 規約、スタイルルールをすべて同時に担うと、現在のタスクにどの情報が不可欠なのか判断しにくくなります。反対に、必要な詳細ドキュメントを指す短いルートガイドがあれば、コントリビューターは必要な深さまでだけ探索できます。

同じ原則は、機能固有のフォルダーに指示ファイルを置く場合にも当てはまります。その機能に専用ルールがない限り追加せず、機密データの取り扱いや自動生成プロセスなど、明確な理由がある場合にだけ追加してください。ルールファイルを頻繁に増殖させると、構造を説明するどころか構造自体を複雑にする可能性があります。

両方のツールを使う場合、重複ルールをどう減らせますか？

1 つの選択肢は、正本となる共有開発規約を AGENTS.md に置き、ルートの CLAUDE.md からそれをインポートし、Claude Code が必要とする内容だけを追記することです。たとえば次のようにします。

@AGENTS.md

## Claude Code のみ
- `src/payments/` を変更する前に計画を提示する。
- `.claude/rules/` のパス固有ルールに従う。

この設定により、テストコマンド、共通の命名ルール、生成ファイルの原則を両方のファイルで繰り返し管理する必要が減ります。同時に、Claude Code 固有のルールと .claude/rules/ ベースの設定も維持できます。ただし前述のとおり、Claude Code は共有指示として AGENTS.md を自動的には読まないため、実際に import または同等の接続を設定する必要があります。code.claude.com↗

共有ファイルをどこに置くかは、チームにおけるツールの利用比率や既存のリポジトリ規約に左右されることがあります。Codex の利用頻度が高ければ、AGENTS.md を正本にするのは容易です。運用が Claude Code のルールシステムを中心とするなら、代わりに CLAUDE.md を正本にできます。どちらを選ぶ場合でも、重要なのは各ルールについて唯一の権威ある原本を指定し、もう一方のファイルには参照またはツール固有の追記だけを残すことです。

個人の好みとチームの規約は分けるのが最適です。個人環境のコマンドエイリアス、ローカルツールの選択、個人の作業習慣は、個人用のオーバーライドファイルに属する場合があります。対照的に、リポジトリをクローンする全員が知る必要のあるテスト手順、セキュリティ制約、コード構造は、バージョン管理されたプロジェクト指示に残すべきです。Codex と Claude Code はどちらも、プロジェクトレベルと個人レベルの指示設定をサポートしています。openai.com↗code.claude.com↗

検証コマンドを指示の中心にすべきなのはなぜですか？

コーディングエージェントによる提案や変更はもっともらしく見える場合がありますが、正確性、互換性、セキュリティを自動的に保証するものではありません。Codex 関連のガイダンスでも、出力には人によるレビューと検証が依然として必要であると説明されています。openai.com↗

そのため、優れたリポジトリ指示は「どのようにコーディングするか」だけでなく、「どのように確認するか」も説明します。可能な場合は、フォーマット、lint、型チェック、ユニットテスト、統合テスト、ビルドのコマンドを、実際に実行できる形式で列挙してください。大規模リポジトリで、すべてのタスクに完全な検証を求めることが現実的でない場合は、変更箇所ごとの最小検証と完全検証を必要とする条件を区別できます。

たとえば、ドキュメント更新ではリンクチェックまたはドキュメントビルドだけが必要かもしれません。一方、公開 API 契約の変更では、ユニットテストと統合テストの両方が必要になる場合があります。データベーススキーマやインフラ設定のように元に戻しにくい変更には、追加のレビューステージが必要になることがあります。重要なのは、ツールがリスクを魔法のように評価すると期待することではなく、チームがすでに把握している検証経路をリポジトリに明示的に記録することです。

生成コードとビルド成果物も、検証の観点から明確に区別すべきです。直接編集してはならないファイルがある場合は、そのソースの場所と生成手順を文書化してください。成果物の編集が許可されている場合は、どのコマンドがそれを更新するかを明記します。また、シークレットや環境固有の個人設定はリポジトリに含めないという原則、サンプルファイルの場所、必要な検証手順を明確にするほうが安全です。

よくある誤解と失敗パターンは何ですか？

1 つ目の誤解は、「指示が多いほど遵守度が高くなる」というものです。実際には、長い文書は最も重要なルールを埋もれさせる場合があります。指示が長くなりすぎた場合は、重複した説明、すでに自動化されているルール、もはや有効でない例外を削除し、詳細な知識を別ドキュメントへ移してください。code.claude.com↗openai.com↗

2 つ目は、「すべてのフォルダーに指示ファイルが必要だ」という誤解です。ネストした指示が有用なのは、特別な制約がある場合だけです。具体性のないネストファイルは、読むべきファイルを 1 つ増やすだけで、親ルールとの関係を不明確にする可能性があります。

3 つ目は、「スタイルルールに一致すれば十分だ」という誤解です。フォーマットが一貫していても、テストが実行されていない、ドメインルールに違反している、生成ファイルを直接編集している場合、その変更が必ずしも良いとはいえません。スタイルの自動化、テスト、レビュー手順は代替関係ではなく、組み合わせて機能する安全策です。

4 つ目は、「ツールが文書内の矛盾を自力で解決する」という誤解です。親と子の指示、または共有指示とツール固有指示が衝突すると、結果は予測しにくくなります。同じルールは 1 か所に置き、子ルールの適用範囲と追加条件を明確にしてください。Claude Code のメモリ設定も階層的な指示を扱うため、競合を避けるようルールを設計することが重要です。code.claude.com↗

最後に、指示ファイルを品質保証として扱うことは避けてください。指示はエージェントと人の判断を支えるコンテキストを提供するものであり、生成コードの正確性、セキュリティ、テスト成功を保証する仕組みではありません。変更のレビューと必要な検証は引き続き不可欠です。openai.com↗

自分たちのリポジトリには何から適用すべきですか？

最初からフォルダー構造全体を再設計する必要はありません。現在のリポジトリで繰り返し発生している混乱に基づき、小さな改善から始めるほうが現実的です。たとえば、新しいコントリビューターがテストコマンドを見つけられないなら、ルート指示に追加します。決済モジュールで同じミスが繰り返されるなら、そのパスにだけ具体的なルールを追加します。設計ドキュメントとコードが混在してナビゲーションしにくいなら、まず docs/ 内で文書の種類を区別します。

次のような評価手順を利用できます。

1. 現在のコードベースで実際に繰り返されているファイル配置、命名、テストの規約を特定する。
2. フォーマッター、リンター、型チェック、テストのコマンドと失敗条件を整理する。
3. コードだけでは理解しにくいドメイン制約、編集禁止領域、生成手順を特定する。
4. 最も重要な内容だけを、ルートの AGENTS.md または CLAUDE.md に簡潔に記述する。
5. 一般ルールでは説明できない機密性の高い領域にだけ、ネストした指示またはパス固有ルールを追加する。
6. 共有ルールの原本を 1 つ指定し、もう一方のツール向けファイルには参照とツール固有ルールだけを残す。
7. 指示が実際の作業で役立ったか、不必要または矛盾する記述がないかを定期的にレビューする。

このプロセスでは、「ツールに理解しやすいこと」と「人にとって保守しやすいこと」を対立する目標として扱う必要はありません。短く正確なドキュメント、予測可能なモジュール境界、自動実行可能な検証は、どちらにも役立ちます。反対に、人にとってさえ説明しにくい構造を指示ファイルだけで補おうとすると、ドキュメントが扱いにくくなる可能性が高いでしょう。

結論：どの規約を選ぶべきですか？

Codex と Claude Code に適したディレクトリ規約とコードスタイルの要点は、流行している特定の構造を採用することではありません。実用的な方法は、既存コードベースの規約を一貫して維持し、ルートに短いガイドを置き、詳細な知識を適切なドキュメントに分離し、必要な箇所にだけ適用範囲の狭いルールを追加することです。

Codex には AGENTS.md、Claude Code には CLAUDE.md と、必要に応じて .claude/rules/ を使用できます。両方のツールを使う場合は、共有ルールの単一のソースを指定し、重複を減らすために Claude Code で共有ファイルを明示的に接続してください。何よりも、指示をフォーマッター、リンター、型チェック、テスト、人によるレビューと組み合わせてください。プロダクト固有の指示解釈はバージョンによって変わる可能性があるため、実際に運用するツールの公式ドキュメントを確認しながら、ルールを小さく明確に保つことをお勧めします。openai.com↗code.claude.com↗