Claude Code チーム導入の最初の2週間｜リポジトリ整備とAGENTS.mdの書き方ガイド
目次 クリックで開く
Anthropic がリリースした Claude Code は、単なるチャット AI ではありません。それは、私たちの開発リポジトリの中に常駐し、自らファイルを読み、テストを実行し、コードを修正してコミットまで行う「24時間稼働のエージェント」です。しかし、多くのチームが導入初日に直面するのは、「思うように動いてくれない」という壁です。
Claude Code の真価を引き出すには、人間が指示を出すだけでなく、リポジトリ側に「Claude Code が自律的に動くためのインフラ」を整備しなければなりません。導入の最初の 2 週間で最も重要なのは、コードを書くことではなく、CLAUDE.md や AGENTS.md を通じて、エージェントに「この現場のルール」を教え込むことです。
Claude Code チーム導入の「最初の2週間」にやるべきこと
Claude Code を導入してからの最初の 2 週間は、技術的なセットアップ以上に「文化の同期」が求められます。CLI 上で claude コマンドを叩けば、Claude は即座にカレントディレクトリの情報をスキャンし始めますが、何も設定がなければ、彼は「一般的な正論」でコードを書き始めます。それがあなたのプロジェクトのコーディング規約に沿っているかは別問題です。
なぜ導入直後の「リポジトリ整備」が命運を分けるのか
Claude Code は、リポジトリ内のファイルをコンテキストとして読み取ります。以下の 3 点が不透明だと、Claude は誤った判断を繰り返します。
- ビルド・テストコマンドが不明：コードを書き換えた後、どうやって動作確認をすべきかわからない。
- ディレクトリ構造の意図が不明：どこに新しいロジックを追加し、どこに型定義を置くべきか迷う。
- 優先すべき規約が不明：チーム独自の ESLint ルールや、命名規則を無視してしまう。
これらを解決するのが、プロジェクトルートに配置する CLAUDE.md です。これは Claude Code 専用の「取り扱い説明書」であり、これがあるだけで開発効率は劇的に向上します。
もし、この段階でデータ基盤の整備や自動化の全体像を見直したい場合は、【図解】SFA・CRM・MA・Webの違いを解説。高額ツールに依存しない『データ連携の全体設計図』のようなアーキテクチャの視点が、リポジトリ構成のヒントになるはずです。
リポジトリの「脳」を作る：CLAUDE.md と AGENTS.md の概念設計
Claude Code を運用する上で、最も重要な 2 つのファイルについて整理しましょう。これらは、人間向けの README.md とは別に、AI エージェントが読むことを前提としたドキュメントです。
CLAUDE.md：プロジェクトの憲法
CLAUDE.md は、Claude Code が起動時に必ず参照する「ガイドライン」です。公式ドキュメント（Anthropic 公式）でも推奨されており、以下の内容を含めます。
- Build/Test Commands：
npm run devやpytestなど、即座に実行可能なコマンド。 - Coding Guidelines：使用するライブラリ、インデント、非同期処理の書き方。
- Architecture Context：なぜこの技術スタックを採用しているのか、過去の大きな技術決定。
AGENTS.md：役割と権限の定義
一方で、AGENTS.md はより「振る舞い」にフォーカスした概念です。Claude Code に複数の「人格（Skills）」を持たせる場合や、特定のタスク（例：脆弱性診断のみ、ドキュメント生成のみ）に限定した動きをさせたい場合に、その定義を記述します。
例えば、経理データのスクリプト作成を依頼する場合、楽楽精算×freee会計の「CSV手作業」を滅ぼすような自動化プロジェクトでは、Claude Code に「CSV変換職人」としての役割を与え、読み込むべきカラム定義やバリデーションルールを AGENTS.md に集約させるのが有効です。
【実践】AGENTS.md の書き方と Skills 構成の具体例
具体的に AGENTS.md をどう構成すべきか、実務的なテンプレートを紹介します。このファイルは、Claude Code に対して「お前は誰で、何ができて、何をすべきではないか」を伝えるためのものです。
AGENTS.md の構成要素
基本的には以下の 4 セクションで構成します。
- Agent Identity：役割名（例：Reliability Engineer, Documentation Specialist）。
- Core Responsibilities：担当するファイルパスやディレクトリの範囲。
- Skills & Tools：Claude Code が実行を許可されている外部スクリプトやツール。
- Constraints：禁止事項（例：「テストコードがない PR は作成しない」「外部 API を直接叩かない」）。
記述例：
“You are an Integration Specialist. Your mission is to maintain the data mapping between the ERP system and the cloud accounting software. Before proposing any changes to the mapping scripts in
/src/mappings/, you must run the local validation toolnpm run validate-csv.”
このように、「特定のディレクトリ」と「特定の確認コマンド」を紐付けることで、Claude Code は迷いなく実務をこなせるようになります。
既存ツールとの比較：Claude Code が選ばれる理由
なぜ GitHub Copilot や Cursor がある中で、あえて Claude Code をリポジトリに導入し、整備する手間をかけるのでしょうか。その違いを比較表でまとめました。
| 機能・特性 | GitHub Copilot | Cursor (IDE) | Claude Code (CLI) |
|---|---|---|---|
| 形態 | エディタ拡張機能 | VS Code ベースの IDE | CLI エージェント |
| 自律実行能力 | 低い（提案のみ） | 中（複数ファイル修正） | 高い（コマンド実行、テスト、修正のループ） |
| コンテキスト理解 | 開いているファイル中心 | リポジトリ全体（インデックス） | リポジトリ全体 ＋ 実行結果のフィードバック |
| 適した用途 | コード記述の高速化 | AI 中心の開発体験 | タスク完遂、自動化、リファクタリング |
| 料金体系 | 個人 $10/月〜 | 個人 $20/月〜 | Anthropic API 使用量に応じた従量課金 |
Claude Code の最大の特徴は、「ターミナルを操作できる」という点です。例えば、claude "全てのテストが通るまで、src/lib/auth.ts のエラーを修正して" と指示すれば、彼は「修正 → テスト実行 → エラー確認 → 再修正」を自律的に繰り返します。これは既存のチャット型 AI にはできない芸当です。
企業の基幹システムや、【完全版】勘定奉行からfreee会計への移行ガイドで扱うような複雑なデータ移行スクリプトを開発する場合、この「自律的なデバッグ能力」が工数を大幅に削減します。
運用フェーズの設計：プルリクエストと承認フローの自動化
導入から 2 週間が経つ頃には、Claude Code が作成したコードをどうやってメインブランチに統合するか、というルールが決まっている必要があります。
claude commit による品質管理
Claude Code には claude commit というコマンドがあります。これを使うと、Claude は直前の変更内容を解析し、Conventional Commits などの規約に沿ったコミットメッセージを自動生成します。チーム導入時は、以下の手順を CLAUDE.md に明記しましょう。
- Claude がコードを修正する。
- 人間が
claude testで結果を確認する。 - 問題なければ
claude commitでメッセージを作成・保存する。 claude pr create（Skill 等で拡張可能）でプルリクエストを投げる。
特に非エンジニアと連携する DX プロジェクトでは、Google Workspace × AppSheet 業務DX完全ガイドで述べているような「使いやすさ」と「ガバナンス」の両立が不可欠です。Claude Code を使うエンジニアが、非エンジニア向けの説明ドキュメントを自動生成させる際も、この承認フローを通すことで品質を担保できます。
Claude Codeのリスクレベル別 × ガードレール設計の方針 × 承認フローの設計パターン 早見表
前のセクションでPRと承認フローの自動化設計を説明しましたが、チームでClaude Codeを使う際に「どの操作を自動実行させて良いか」「どの操作は人間の承認が必要か」という判断基準を明確にしておかないと、意図しないコードのコミットや本番環境への影響が発生するリスクがあります。Claude Codeが実行できる操作はテキスト編集からシェルコマンド実行・外部API呼び出しまで幅広く、すべてを自動承認にしても問題のある操作まで通ってしまいます。操作のリスクレベルを定義して、それに応じたガードレールと承認フローを設計することがチーム導入の安全基盤になります。
| 操作のリスクレベル | 代表的な操作の例 | Claude Codeのガードレール設計 | 承認フローの設計パターン |
|---|---|---|---|
| 低リスク （自動実行可・承認不要） |
①ファイルの読み取り・テキスト検索（grep等）②コードの静的解析・型チェック（TypeScript型チェック・ESLint）③テストの実行（ユニットテスト・スナップショットテスト）④Gitのdiff確認・log閲覧（読み取り専用のgitコマンド）⑤ドキュメント生成の下書き作成 | CLAUDE.mdの「許可コマンドリスト」にread-onlyな操作を明示的に記載してClaude Codeが確認なしで実行できる範囲を定義する。「–allowedTools」設定で許可するツールを明示することで意図しないツール使用を防ぐ。低リスク操作はClaude Codeの実行ログをGit Commitのコメントに自動記録する設計が後からの追跡に有効 | 承認不要（自動実行）。ただし自動実行の操作内容はすべてターミナルのログとしてチームが確認できる形で残す設計を徹底する。定期的なログレビュー（週次）でClaude Codeが期待通りの操作のみを行っているか確認する運用サイクルを設ける |
| 中リスク （要確認・担当者の目視承認） |
①ファイルの作成・編集・削除（新規ファイル作成・既存ファイルへの変更）②依存ライブラリの追加・更新（npm install・pip install等）③Gitコミットの作成・PRの自動作成④内部APIへのPOSTリクエスト（テスト環境・ステージング環境への操作）⑤設定ファイルの変更（.env・config.yaml等） | CLAUDE.mdに「変更を加える操作は担当者の確認後に実行する」ルールを記載して、Claude Codeがインタラクティブモードで実行前に確認を求める設定（–interactive）にする。「–permission-prompt-tool」設定でファイル変更・シェル実行の都度に確認ダイアログを表示する設計が中リスク操作の誤実行防止になる | 担当者の目視承認（Y/Nの確認）。Claude Codeがターミナルに「実行内容の要約（どのファイルを・どう変更するか）」を表示してから実行する設計にすることで、担当者が判断しやすくなる。Slack/Teamsへの確認通知送信→承認後に実行するフローまで自動化する設計も選択肢（工数と厳格さのトレードオフ） |
| 高リスク （複数承認・管理者確認必須） |
①本番環境へのデプロイ（CI/CDパイプラインのトリガー）②本番データベースへの直接操作（スキーマ変更・データ更新・削除）③外部サービスへのコスト発生操作（クラウドリソース作成・APIの有料呼び出し）④認証情報・APIキーの設定ファイルへの書き込み⑤ブランチの強制プッシュ・タグの作成・削除 | CLAUDE.mdの「禁止コマンドリスト（forbiddenTools）」に本番デプロイコマンド・DBの破壊的操作を明示して、Claude Codeが単独では実行できない設計にする。高リスク操作はClaude Codeが「この操作は自動実行できません。手動で実行してください」とターミナルに出力して処理を停止するプロンプト設計が安全な境界線を形成する | 複数人承認（担当者+リードエンジニアまたは管理者の2名承認）。GitHub Actionsのrequired reviewers設定で本番ブランチへのマージに特定人数の承認を必須にする。本番デプロイは承認後のCI/CDパイプラインのみが実行権限を持つ設計（Claude Codeから直接デプロイコマンドを実行させない）が最も安全なアーキテクチャ |
| 禁止操作 （いかなる状況でも自動実行させない） |
①本番DB・顧客データの削除・トランケート操作②機密情報・個人情報を含むファイルの外部送信（Slack/メール/外部URL等への転送）③APIシークレット・パスワードのログへの出力・ファイルへの平文書き込み④本番環境の認証設定変更（IAMポリシー・SSO設定等）⑤利用規約・ライセンスに抵触するコードの生成・使用 | CLAUDE.mdに「絶対禁止操作（dangerousPatterns）」を明示して、これらのパターンに一致するコマンドをClaude Codeが実行しようとした際に即座にセッションを停止してアラートを出す設計を実装する。–dangerously-skip-permissionsフラグは禁止操作の除外設定であっても使用しないルールをチーム全員に周知する | 実行不可（自動拒否）。禁止操作の実行試行があった場合はClaude Codeのログに記録してシステム管理者に通知する設計が、インシデント発生時の原因調査と再発防止につながる。定期的な禁止操作リストの見直し（四半期ごと）でビジネス要件の変化に対応した設計の更新を行う |
この表でClaude Codeのチーム導入において最重要のガバナンス設計が「リスクレベル別の操作分類と承認フローをCLAUDE.mdに明示して、チーム全員が同じ基準で判断できるようにすること」です。「高速化のためにすべて自動承認」にすると本番インシデントのリスクが上がり、「すべて手動確認」にすると開発速度が低下してClaude Code導入の意義が薄れます。上記の4段階のリスクレベル分類を自社の開発環境・チーム規模・セキュリティ要件に合わせてカスタマイズして、CLAUDE.mdに記載することが「暴走しないClaude Code」をチームに定着させるための基盤設計です。
セキュリティとガバナンス：暴走を防ぐガードレール設置
Claude Code は強力な権限（シェル実行、ファイル削除、ネットワークアクセス）を持ちうるため、チーム導入時には必ずガードレールを設計してください。
.claudignore の活用
.gitignore と同様に、Claude Code に読み取らせたくないファイルを指定する .claudignore を作成します。
.envファイル（API キー、DB パスワード）- 巨大なバイナリデータ
- 機密情報が含まれる
/docs/private/フォルダ
これらを明示的に除外することで、トークンの節約とセキュリティリスクの低減を同時に行えます。
承認設定の義務化
Claude Code はデフォルトで、破壊的な可能性のあるコマンド（rm, git push 等）の実行前にユーザーの承認を求めますが、これをスキップするオプション（-y）をチームで安易に使わないよう運用ルールを徹底してください。特に本番環境に近いディレクトリでの操作は、常に「Human-in-the-loop」の原則を守るべきです。
まとめ：Claude Code を「使い捨ての道具」から「自走するチームメンバー」へ
Claude Code 導入の最初の 2 週間は、単なるツールのセットアップ期間ではありません。それは、AI があなたのチームの一員として振る舞うための「教育期間」です。CLAUDE.md でプロジェクトの知識を与え、AGENTS.md でその役割を限定し、リポジトリ全体を AIフレンドリーな構造に整えること。この投資こそが、半年後の生産性を数倍に変える決定打となります。
まずは小さな自動化スクリプトや、ドキュメントの整備から Claude Code に任せてみてください。彼が「正しく失敗」し、それをあなたが CLAUDE.md の更新で修正していくプロセスを繰り返すことで、Claude Code はあなたのチームにとって唯一無二の、最強のエンジニアリングエージェントへと進化していくはずです。
CLAUDE.mdとAGENTS.mdを整備してチームで運用し始めると、「どの操作を自動承認にするか」「禁止コマンドをどう定義するか」という承認フローと実行境界の設計が次の課題になります。自社のリポジトリ構成に合わせた最初の2週間の設計は、Claude Code 導入支援で一緒に進められます。
生成AIの法人導入・セキュリティ設計のご相談
ChatGPTやClaudeなど生成AIのプラン選定・セキュアな全社導入・権限／ログ設計を、貴社の体制に合わせて整理します。すでに導入済みの環境について『この設計で問題ないか』を確認したい、という導入前後のセカンドオピニオンにも対応しています。
AI・業務自動化
ChatGPT・Claude APIを活用したAIエージェント開発、n8n・Difyによるワークフロー自動化で繰り返し業務を削減します。まずはどの業務をAI化できるか診断します。