ほとんどのチュートリアルは、Claude Codeがシンプルで独立した例題を解く様子を示します。依存関係のない関数。小さなクラス。自己完結型のファイル。
しかしあなたのコードベースはそうではありません。
あなたのコードベースには2018年に作られた共通認証サービスがあります。誰も触りたがらない支払いモジュールもあります。当時は意味のあった命名規則は今や部族的な知識が必要です。カバレッジ40％のテストスイートと、チーム拡大により4つの異なるテストフレームワークが混在しています。
Claude Codeをこれらと一緒に機能させることは、多くのドキュメントが教える内容とは異なるスキルです。やり方を解説します。
コンテキストの問題
Claude Codeはあなたのコードベースを自動的に理解しません。見せたものだけを理解します。
「この関数にエラーハンドリングを追加して」と依頼すると、現在のコンテキストウィンドウ内の情報で動いています。チームがカスタムのAppErrorクラスを使っていることを知らなければ、一般的なErrorを生成します。集中ロギングサービスの利用を知らなければconsole.logを追加します。非同期処理のパターンを知らなければ、慣用的だと思われる方法を使います。
結果は技術的には正しいですが、あなたのコードではありません。
解決策は、タスク開始前にClaude Codeに適切なコンテキストを与えることを学ぶことです。
コンテキストに必ず含めるべき3つの要素
1. チームの慣習ファイル（または関連部分）
AGENTS.md、CONTRIBUTING.md、CONVENTIONS.mdなどがあれば、該当部分をコピーして貼り付けます。なければ、作る良い機会です。
例：「当チームは全てのエラーにAppError(message, code)を使用します。ログは共通の/lib/loggerモジュールのlogger.error(context, message)を使います。非同期関数は常にasync/awaitで書き、.then()は使いません。」
30秒のコンテキスト設定が10分の後処理を省きます。
2. 操作対象となる関連ファイル
作業中の関数だけを見せず、その関数が利用するファイル一式も示します。実装しているインターフェース、使用する型定義、呼び出すサービスなどです。
特に型安全なコードベースでは重要です。TypeScriptのインターフェースを見せなければ、使用から型推論し誤った推論になることが多いです。
3. 「完成」の具体例
コードベース内の完成しレビュー済みのコード例を示して、望むパターンをClaude Codeにわかりやすく伝えます。「これが我々の良い関数の例です。これに沿ってください。」
口頭で説明するより速く確実です。
内部ドキュメントの問題
ConfluenceページやNotionドキュメント、アーキテクチャ決定記録、数年触っていないREADMEなど。
Claude Codeは内部ドキュメントを直接読むことはできませんが、関連部分をコピー＆ペーストすれば推論は可能です。
繰り返しのタスク—「新しいAPIエンドポイントを書くたびに内部のAPI設計ドキュメントに従う必要がある」—には短いリファレンスの要約を作り、コンテキストに貼り付けるスニペットとして保管しましょう。キーとなる慣習を30～50行程度にまとめ、慣習変更時に更新します。
一部チームはリポジトリのルートにCLAUDE.mdを置き、該当コードベースセッションの開始時に必ず貼り付ける習慣にしています。
実際の運用例
効果的なワークフローパターンの例です：
セッション開始:
1. CLAUDE.mdまたは慣習スニペットを貼り付ける
2. 作業中の関連ファイル（または関連セクション）を貼り付ける
3. タスクを明確に伝える：「[service]に[X]エンドポイントを追加します。[example file]の既存パターンに従います。」
複雑なタスクの場合：
4. 書く前にClaude Codeに計画を説明させる
5. 計画をレビューし、200行の出力前に問題を取り除く
6. 一度に全部書かせず、段階的に実行する
この計画・実行パターンで、「技術的には正しいが我々の方法ではない」という問題の80％を未然に防げます。
共有コードベースの課題
5人以上のエンジニアでの開発では別の問題があります。異なるエンジニアが異なる使い方をし、生成されるコードが異なるチームから来たように見えることです—実際その通りなのです。
解決策は人間のチームの不一致を解消する方法と同じ：共通基準を持つこと。
チームレベルのClaude Codeコンテキストファイルを作り、従うべき慣習を合意し、AI支援プルリクも手書きのものと同様にレビューし合います。こうして徐々にAIの使い方が統一されていきます。
これは自動では起きません。誰かがファイルを作り、合意を取得し、更新し続ける必要があります。普通はテックリードかAIツールに熱心なメンバーが担当し、個人からチームへの導入を促進します。
ベンチマーク
慣習ファイルや文書を午後1回整備したチームは、2週間以内にAI支援コード品質の有意な改善を確認しています。具体的には「技術的には正しいが我々のコードではない」というレビューコメントの減少です。
魔法の解決策ではありませんが、Claude Codeが「使えるチームメンバー」と感じられるか、「毎日同じ確認をしてくるインターン」のままかの差を生みます。
私たちはエンジニアリングチームがチュートリアル例ではなく実際のコードベースに合ったClaude CodeやCopilotのワークフロー構築を支援します。まずは無料のClaude Codeクイックスタートプレイブックまたはチームの現状測定ツールから始めてください。
