Claude Codeを導入するときは、最初から大きな自動化を作るより、CLAUDE.md、Skills、MCP、hooksの役割を分けて小さく始める方が失敗しにくいです。この記事では、既存リポジトリにClaude Codeを入れる前提で、どのファイルを作り、何を書き、どこを人間が確認するかを手順で説明します。（出典: Anthropic）
ゴールは、Claude Codeに「何でも任せる」状態ではありません。ゴールは、任せてよい作業、止める作業、レビューする観点をリポジトリ内に明示し、差分とログを人間が確認できる状態にすることです。
完成形を先に決める
まず、最小構成はこの形にします。最初から全部を埋める必要はありません。CLAUDE.mdに共通ルール、.claude/skills/に繰り返し手順、.mcp.jsonに外部ツール接続、.claude/settings.jsonにhooks設定を置きます。
project-root/
├── CLAUDE.md
├── .mcp.json
└── .claude/
├── settings.json
├── hooks/
│ └── block-dangerous-commands.sh
└── skills/
└── release-check/
└── SKILL.md
役割は次のように分けます。
| ファイル | 置く内容 | 置かない内容 |
|---|---|---|
CLAUDE.md |
プロジェクト全体の前提、開発コマンド、禁止事項 | 毎回変わる作業手順 |
.claude/skills/*/SKILL.md |
繰り返す作業の手順、入力、出力形式 | プロジェクト全体の長い説明 |
.mcp.json |
外部ツールの接続設定 | 秘密情報の実値 |
.claude/settings.json |
hooksや権限設定 | 作業依頼そのもの |
Step 1：CLAUDE.mdを小さく作る
CLAUDE.mdはClaude Codeがプロジェクトの前提を理解するためのファイルです。ここには、常に必要な情報だけを書きます。長く書きすぎると、重要なルールが埋もれます。（出典: Claude Code）
最初はこの程度で十分です。
# Project Guide
## 概要
このリポジトリはNext.jsで作られた記事サイトです。
## よく使うコマンド
- npm run lint
- npm run build
## 作業ルール
- 既存の変更を勝手に戻さない。
- 秘密情報をコードやログに出さない。
- 大きな変更の前に差分を確認する。
## レビュー観点
- 表示崩れがないか。
- 生成物に不要なファイルが混ざっていないか。
- 本番データを壊す操作が含まれていないか。
判断基準は単純です。毎回Claude Codeに読ませたい内容はCLAUDE.mdに置きます。特定の作業でしか使わない手順は、次のStepでSkillに分けます。
Step 2：繰り返す作業をSkillに切り出す
Skillは、Claude Codeに再利用させる作業手順です。たとえば、リリース前確認、PRレビュー、ログ調査、記事公開前チェックなど、何度も同じ観点で依頼する作業に向いています。
まずは.claude/skills/release-check/SKILL.mdを作ります。
---
name: release-check
description: リリース前に差分、テスト、影響範囲を確認するSkill
---
# リリース確認Skill
## 目的
リリース前に、差分、テスト、設定、公開影響を同じ観点で確認する。
## 入力
- 対象ブランチ
- 変更の目的
- 確認してほしいファイル
## 手順
1. 差分を読み、変更範囲を3行で要約する。
2. テスト、設定、公開手順に漏れがないか確認する。
3. 本番影響がある変更を分けて列挙する。
4. 反映前に人間が確認すべき点を出す。
## 制約
- APIキー、接続文字列、社内URLの実値を書かない。
- 破壊的な操作は実行せず、提案に留める。
- 不明点は推測で断定しない。
## 出力形式
- 変更概要
- リスク
- 確認コマンド
- 人間の判断が必要な点
Skillを作るときのポイントは、抽象的な文章ではなく、入力、手順、制約、出力形式を分けることです。Claude Codeに「いい感じに確認して」ではなく、「どの順番で、何を、どの形で返すか」を渡します。
Step 3：Claude Codeへの依頼文を固定する
Skillを作ったら、依頼文も型にします。毎回ゼロから文章を考えると、確認観点がぶれます。
release-check Skillを使って、今回の変更を確認してください。
対象ブランチ: feature/update-article-layout
変更目的: 記事詳細ページの表示崩れを修正する
確認してほしいファイル:
- src/app/posts/[slug]/page.tsx
- src/app/globals.css
制約:
- 既存のユーザー変更は戻さない
- 本番データに触る操作はしない
- 問題があれば、ファイル名と確認方法をセットで出す
依頼文に入れるべき項目は、対象、目的、確認ファイル、制約、期待する出力です。この5つがあると、Claude Codeの作業範囲が狭まり、人間もレビューしやすくなります。
Step 4：MCPは最小権限から始める
MCPは、Claude Codeが外部ツールと連携するための入口です。便利ですが、最初から広い権限を渡すと、何が起きたか追いにくくなります。最初は読み取り中心、対象ディレクトリ限定、ログ確認可能な状態から始めます。（出典: Connect Claude Code to tools via MCP）
人間がMCPの範囲を定義・設定する
↓
Claude Codeに対象ファイルと制約を渡す
↓
Claude Codeが外部ツールを使い、差分とログを作る
↓
人間が差分、ログ、権限範囲を確認する
↓
問題なければ反映する
MCPを使う前に、次の3点を決めます。
- どのツールに接続するか。
- どのディレクトリやデータに触れてよいか。
- 失敗時にどのログを見ればよいか。
たとえばGitHub、Slack、ブラウザ、ファイルシステムなどを使う場合でも、最初は「読み取りだけ」「特定リポジトリだけ」「特定ワークスペースだけ」のように範囲を狭くします。
Step 5：hooksで危険操作を止める
hooksは、Claude Codeの操作前後に処理を挟む仕組みです。まず使いやすいのは、危険なBashコマンドを止めるPreToolUseと、編集後に整形やログ保存を行うPostToolUseです。（出典: Best practices for Claude Code）
最初に入れるなら、危険コマンドを止めるhookが実用的です。
.claude/
├── settings.json
└── hooks/
└── block-dangerous-commands.sh
確認する観点は次の通りです。
| hook | 使いどころ | 人間の確認 |
|---|---|---|
PreToolUse |
危険なBashや不要な外部アクセスを止める | ブロック条件が広すぎないか |
PostToolUse |
編集後にformatやlintを走らせる | 失敗時に作業ファイルを壊さないか |
Stop |
完了前の最終確認を入れる | 長時間処理にならないか |
最初から複雑な自動化を入れる必要はありません。git reset --hard、git push --force、広すぎる削除コマンドなど、明確に止めたい操作だけから始めます。
Step 6：人間のレビュー手順を固定する
Claude Codeを使う運用では、最後に人間が見る場所を決めておくことが重要です。ここを曖昧にすると、AIが作った差分を何となく信じて反映する流れになります。
最低限、次を確認します。
git diffで変更範囲が依頼どおりか。- 生成されたファイルに一時ファイルやログが混ざっていないか。
- 秘密情報、接続文字列、個人情報が含まれていないか。
- MCPやhooksの権限が広がりすぎていないか。
- テストやビルドの結果が残っているか。
レビュー依頼も型にできます。
今回の差分をレビューしてください。
観点:
- 依頼範囲外の変更がないか
- 本番影響がある変更が混ざっていないか
- 一時ファイルやログが含まれていないか
- テスト不足がないか
出力:
- 問題あり/なし
- 問題がある場合はファイル名と理由
- 反映前に人間が判断すべき点
よくある失敗と対処
Claude Codeの導入でよくある失敗は、設定を増やしすぎることです。最初から巨大なCLAUDE.md、大量のSkills、広いMCP権限、複雑なhooksを入れると、どの設定が効いているのか分かりにくくなります。
| 失敗 | 原因 | 対処 |
|---|---|---|
CLAUDE.mdが長くなりすぎる |
手順まで全部書いている | 繰り返し手順はSkillへ移す |
| Skillが使われない | descriptionが曖昧 |
いつ使うかを具体的に書く |
| MCPが怖くて使えない | 権限範囲が広い | 読み取り、対象限定から始める |
| hooksで作業が止まりすぎる | ブロック条件が広すぎる | まず危険コマンドだけ止める |
| レビューが属人的になる | 確認観点が毎回違う | レビュー依頼文を固定する |
最小構成で始めるチェックリスト
最後に、今日やるならこの順番です。
CLAUDE.mdにプロジェクト概要、コマンド、禁止事項だけを書く。- 繰り返し作業を1つ選び、
.claude/skills/<name>/SKILL.mdに切り出す。 - 依頼文テンプレートを1つ作る。
- MCPを使う場合は、読み取り中心・対象限定で始める。
- hooksを使う場合は、危険コマンドのブロックから始める。
- 最後に人間が見る差分、ログ、テスト結果を決める。
この順番なら、Claude Codeを「便利だけれど挙動が読みにくいツール」ではなく、「差分とログを確認しながら使える開発補助」として導入できます。まずは1つのリポジトリで、CLAUDE.mdと1つのSkillだけを作り、実際の小さな修正依頼で試すのが現実的です。
参考文献
anthropic.com Anthropic Claude Code medium.com reddit.com reddit.com Connect Claude Code to tools via MCP Best practices for Claude Code