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 セクションで構成します。

1. Agent Identity：役割名（例：Reliability Engineer, Documentation Specialist）。
2. Core Responsibilities：担当するファイルパスやディレクトリの範囲。
3. Skills & Tools：Claude Code が実行を許可されている外部スクリプトやツール。
4. 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 tool npm run validate-csv.”

このように、「特定のディレクトリ」と「特定の確認コマンド」を紐付けることで、Claude Code は迷いなく実務をこなせるようになります。

既存ツールとの比較：Claude Code が選ばれる理由

なぜ GitHub Copilot や Cursor がある中で、あえて Claude Code をリポジトリに導入し、整備する手間をかけるのでしょうか。その違いを比較表でまとめました。

Claude Code の最大の特徴は、「ターミナルを操作できる」という点です。例えば、claude "全てのテストが通るまで、src/lib/auth.ts のエラーを修正して" と指示すれば、彼は「修正 → テスト実行 → エラー確認 → 再修正」を自律的に繰り返します。これは既存のチャット型 AI にはできない芸当です。

企業の基幹システムや、【完全版】勘定奉行からfreee会計への移行ガイドで扱うような複雑なデータ移行スクリプトを開発する場合、この「自律的なデバッグ能力」が工数を大幅に削減します。

運用フェーズの設計：プルリクエストと承認フローの自動化

導入から 2 週間が経つ頃には、Claude Code が作成したコードをどうやってメインブランチに統合するか、というルールが決まっている必要があります。

claude commit による品質管理

Claude Code には claude commit というコマンドがあります。これを使うと、Claude は直前の変更内容を解析し、Conventional Commits などの規約に沿ったコミットメッセージを自動生成します。チーム導入時は、以下の手順を CLAUDE.md に明記しましょう。

1. Claude がコードを修正する。
2. 人間が claude test で結果を確認する。
3. 問題なければ claude commit でメッセージを作成・保存する。
4. claude pr create（Skill 等で拡張可能）でプルリクエストを投げる。

特に非エンジニアと連携する DX プロジェクトでは、Google Workspace × AppSheet 業務DX完全ガイドで述べているような「使いやすさ」と「ガバナンス」の両立が不可欠です。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 はあなたのチームにとって唯一無二の、最強のエンジニアリングエージェントへと進化していくはずです。