開発方針を相談する

Claude Code / Codex を開発現場で使うときの設計原則

AI コーディングツールは、使い方より "環境設計" で成果が変わる。

この記事の結論

「Cursor を導入したけど、人によって使い方がバラバラで効果が出ない」「Claude Code、個人では使えるけどチームで使うと PR レビューが追いつかない」

AI コーディングツールを導入した組織から、こうした相談が増えています。問題は ツールではなく、環境設計 にあることがほとんどです。

この記事では、Claude Code / Codex / Cursor をチームで使うときの設計原則を、ツール選定、ドキュメント、テスト、レビューの 4 観点で整理します。

ツール選定: Cursor / Claude Code / Codex の住み分け

AI コーディングツールはどれも進化が早く、機能差はすぐ追い付きます。ただし、得意な使い方が違う ので、チームでは複数を併用するのが現実的です。

ツール得意な使い方苦手
CursorIDE での対話編集、ファイル間の小さな変更、ペアプログラミング感覚大規模変更、ターミナル操作中心の作業
Claude Codeターミナルでの大規模変更、CLAUDE.md による文脈付与、コードベース横断の調査IDE 内のリアルタイム補完
Codexクラウドでの並列タスク、PR 作成までの自動化、サンドボックスでのテスト実行ローカル IDE での対話的編集

OpenAI のドキュメントによれば、Codex は独立したクラウドサンドボックスでテストやリンタを実行できる設計とされています (Introducing Codex / OpenAI)。Claude Code は、ローカルのファイルシステムを直接たどってコードベースを理解する設計で、CLAUDE.md などのハーネス (CLAUDE.md / hooks / skills / plugins / MCP servers) がモデル本体より成果を左右する、と整理されています (Claude Code docs / Anthropic)。

min's での使い分け例

「全部を 1 つのツールでやろう」とすると、どこかに無理が出ます。チーム内でツールを統一する必要はなく、得意な使い方で住み分ける のが現実的です。

AI コーディングツールを個人利用で終わらせない

個人で使うときの強みは、自分が触っているコードベースの文脈を全部頭に入れた状態で AI に指示できることです。チームで使うとそうはいかない。人によって AI に渡す前提が違う ので、生成されるコードの品質もバラバラになります。

これを解消するために、AI に渡す前提を コードベース側に置いておく のが基本姿勢です。

具体的には、リポジトリのルートに以下のようなファイル群を置きます。

/CLAUDE.md           ← Claude Code 用のプロジェクト文脈
/AGENTS.md           ← Codex 用のプロジェクト文脈 (内容は CLAUDE.md と共通化可)
/.claude/            ← Claude Code 固有の設定、スキル、フック
/.codex/             ← Codex 固有の設定、サブエージェント定義
/docs/architecture/  ← アーキテクチャ判断の記録
/docs/runbook/       ← 障害対応・運用手順

ここまで揃っていれば、誰が AI に指示しても、同じ前提のコードが出やすくなります。

CLAUDE.md / AGENTS.md の役割

Anthropic の Claude Code には CLAUDE.md という設定ファイルの仕組みがあり、Claude の system prompt に自動的に含められます。プロジェクトの構造、規約、ワークフローを記述し、毎回の対話で読み込ませる用途で使われます (Using CLAUDE.md files / Anthropic)。OpenAI の Codex にも AGENTS.md という同じ役割のファイルがあり、グローバル / プロジェクト / サブディレクトリの 3 階層で重なる設計です (Custom instructions with AGENTS.md / OpenAI Developers)。

書くべき項目 (最低限)

書きすぎてはいけないもの

OpenAI の Codex ベストプラクティスでも、AGENTS.md は 「肥大化したらタスク別ドキュメントへ分ける」 ことが推奨されています (Codex Best Practices / OpenAI Developers)。プロジェクト全体に効く規約だけを残し、特定タスクの詳細は別ファイルへ分割します。

具体的に書かない方がいいもの:

詳しい書き方とテンプレートは CLAUDE.md / AGENTS.md に何を書くべきか で展開しています。

テスト・lint・型チェックを先に整える

AI に書かせる前に、コードベースが「機械的に検証できる状態」 になっている必要があります。

最低限揃える CI のチェック

# 例: GitHub Actions のチェック項目
- pnpm install --frozen-lockfile
- pnpm typecheck    # 型チェック
- pnpm lint         # ESLint / Biome
- pnpm test         # 単体テスト (Vitest / Jest)
- pnpm e2e          # E2E テスト (Playwright)

これらが揃っていれば、AI が書いたコードを 「動いているように見えるが、壊れている」状態でマージ することを防げます。

逆に揃っていれば、AI に「型エラーを直して」「テストを追加して」と指示するだけで、品質ゲートを通る形でコードが出てきます。Codex のドキュメントでも、テスト出力やターミナルログを通じて作業の検証可能性を提供する設計が説明されています (Introducing Codex / OpenAI)。AI と CI は補完関係です。

既存プロジェクトに後から入れるときの順序

既存のリポジトリでこれらが整っていない場合、以下の順で入れていきます。

  1. 型チェック (TypeScript なら tsc --noEmit を CI で実行)
  2. lint + formatter (ESLint / Biome / Prettier)
  3. 単体テスト (まずはドメインロジックだけ)
  4. CI で必須化 (PR が通らない設定)
  5. E2E テスト (主要フローだけ)

全部一気にやらず、1〜2 週間ずつかけて段階的に 入れます。

AI に任せるタスク単位を定義する

AI に任せるタスクは、完了基準と検証方法が明確 なものに絞ります。

任せやすいタスク

タスク検証方法
単独機能の実装 (CRUD、フォーム)自動テストで動作確認
既存関数のリファクタリングテスト通過 + 差分レビュー
テストケースの追加カバレッジ計測 + 観点レビュー
ドキュメント更新内容レビュー
バグの原因調査再現コードによる検証
ライブラリ移行 (例: Moment.js → date-fns)テスト通過 + 差分レビュー

任せにくいタスク

タスク理由
認証・テナント分離の設計整合性判断は人間
データモデルの根本変更既存データへの影響判断が必要
セキュリティ判断業界・法令の文脈が必要
リリース判断事業判断が必要
価格・契約に関わるロジック法務判断が絡む

「コードベースをまたぐ大きな変更」は、Claude Code が複数ファイルを横断して扱える設計とされていますが、それでも 人間がスコープを切ってから渡す のが現実的です。

Codex Subagents での並列実行

OpenAI のドキュメントでは、複雑な調査や実装で specialized agents を並列に走らせる Subagents の仕組みが提供されています (Codex Subagents / OpenAI Developers)。

典型的な使い方:

ただし、最終 PR は 1 つに集約して、人間がレビューする という設計が破綻を防ぎます。

レビューと承認フローを設計する

AI が書いたコードを、CI 通過だけでマージするのは危険です。最低限以下のレビューフローを組みます。

PR テンプレートに AI 区分を入れる

## このPRの種類
- [ ] 100% 手書き
- [ ] AI 生成 + 人間レビュー済み
- [ ] AI 生成 + 軽微な修正
- [ ] AI と対話しながら共同で書いた

これがあると、レビュアーは「AI 生成部分は特に注意して見る」という心構えで読めます。

必須レビュー領域

以下の変更は、必ず人間 2 人以上でレビューする運用にします。

これらは AI 任せにせず、設計段階で人間が方針を決めて、AI は実装補助 に使います。

「AI レビュアー」を補助に使う

レビュー側も AI を使えます。

これらを AI に依頼すると、人間は「事業判断」「例外許容」「リスク受容」「UX 判断」に時間を集中できます。

ここまでで「自社のコードベースに、AI を本格導入したい」と感じたら、まずは現状診断と CLAUDE.md / AGENTS.md の整備から始めるのが現実的です。

AI 開発環境のセットアップ支援を相談する →

失敗をルールに反映する習慣

AI コーディングを運用していると、必ず「AI が同じミスを繰り返す」状況が出てきます。コーディング規約に書いていない暗黙の前提を AI が知らないと、何度プロンプトを工夫しても同じ間違いが起きます。

そのときの対処は、プロンプトを工夫する ではなく、CLAUDE.md / AGENTS.md に追記する が正解です。

典型的な追記パターン

OpenAI の Codex ベストプラクティスでも、失敗が起きたら振り返って AGENTS.md に反映する運用が推奨されています。「失敗 → ルール化 → 再発防止」 が、AI 時代の改善サイクルです。

これを徹底すると、AI を使うほどに コードベースの一貫性が上がっていく ようになります。

min's の運用例

min's では、CLAUDE.md / AGENTS.md は 「2 週間に 1 回見直し、月に 1 回チームで読み合わせ」 という運用にしています。同じ指摘がレビューで 2 回出たら、その場でファイルに追記します。

四半期に 1 回は全文をレビューし、陳腐化した項目 (使わなくなったライブラリの注意事項など) を整理します。CLAUDE.md / AGENTS.md は 長くなりすぎると AI のコンテキストを圧迫する ので、適切なサイズを保つ意識が重要です。

ハーネス全体で考える

Claude Code のドキュメントでは、CLAUDE.md だけでなく、hooks、skills、plugins、MCP servers といった ハーネス全体 が成果を左右する、とされています。これは Codex も同じで、AGENTS.md だけでなく、Subagents、Skills、CLI 設定、IDE 統合まで含めて「環境」を作ります。

ハーネスを構成する要素:

これらを 一度に全部揃える必要はありません。プロジェクトで使うものから少しずつ整え、運用の中で増やしていくのが現実的です。

AI 開発環境のセットアップを依頼したい方へ

min's では、Claude Code / Codex / Cursor のチーム導入、CLAUDE.md / AGENTS.md の整備、AI 活用前提の CI 整備を支援しています。

以下のような状態であれば、ご相談ください。

次に読む記事

参考

動くデモで終わらせず
本番まで持っていく開発を

AI で作りかけたもの、止まりかけている開発、新しいプロダクトの構想。 まずは現状を整理するところから、ご相談ください。

開発方針を相談する概算見積もりを依頼する