Claude Code完全ガイド：AIと「協働」するエンジニアの新常識
📖 本記事について
本記事の内容は、書籍「ストーリーで覚えるClaude Code開発ガイド 物語で学ぶAI駆動開発（ネクストステージ出版）」を参考・引用しています。詳細や実際のストーリー展開に興味のある方はぜひ書籍をご覧ください。
■ この記事はこんな人におすすめ
- CursorやCopilotは触ったが、CLIエージェントは未体験の方
- 既存の開発フローにAIをどう組み込むか悩んでいる方
- レガシーコードのリファクタリングにAIを活用したい方
- AI時代のエンジニアの価値に不安を感じている方
- チームにAI駆動開発を導入したい方
■ この記事で得られること
- Claude Codeのインストールから基本操作まで理解できます
-
CLAUDE.mdとSkillsを使ったチーム活用法がわかります - 既存コード（10万行規模）へのAI活用アプローチが身につきます
- AI時代に求められるエンジニアの価値・役割が整理できます
- チームへのAI駆動開発導入に必要なセキュリティ観点が得られます
■ 参考書籍
1. 結論：AIは「任せる」のではなく「協働」するもの
📖 本章の内容は参考書籍の第1〜8章を参考にしています。
AIに仕事を奪われるのか——そんな不安を抱えているエンジニアは少なくないはずです。しかし、現実はもう少し繊細です。
AIは「協働」することで、初めて本領を発揮します。
AIが得意なこと：
- 一緒に設計を考える
- 実装部分を担当する
エンジニアが担うべきこと：
- 設計方針を決める
- バリデーションの条件を決定する
- レスポンス形式を統一する
- AIの出力をレビューし、品質に責任を持つ
この役割分担を理解することが、Claude Codeを使いこなす第一歩です。
2. 具体的にやること
■ ① インストールして起動する
前提条件： Node.js（v18以上）がインストールされていること
# インストール
npm install -g @anthropic-ai/claude-code
# 起動（プロジェクトディレクトリに移動してから）
cd your-project-directory
claude
■ ② CLAUDE.md でチームのルールを共有する
NG： チームのルールが口頭や暗黙の了解にとどまっている
OK： CLAUDE.md にルールを明文化し、AIと人間の両方に共有する
■ ③ Skills（カスタムスラッシュコマンド）で作業を定型化する
NG： 毎回同じ指示を手入力する
OK： コードレビューやテスト生成などを /review /test などのコマンドで即呼び出す
■ ④ Plan mode で変更前に計画をレビューする
NG： いきなりコードを変更させて、後から影響範囲を確認する
OK： Shift+Tab でPlan modeに切り替え → 計画確認 → 承認 → 実行のフローを守る
■ ⑤ 既存コードの全体構造をAIに説明させる
NG： 10万行のコードをエンジニアが1から読み解こうとする
OK： 「このリポジトリの全体構造を説明して」とClaude Codeに尋ね、地図を生成させてから自分で検証する
■ ⑥ テストの「8割」をAIに任せ、「2割」に集中する
NG： AIが生成したテストをそのままコミットする
OK： 業務固有ロジックや暗黙の前提条件が絡む2割は、エンジニアが責任を持って修正する
■ ⑦ Subagent と git worktree で並列作業を活用する
NG： 影響分析・テスト追加・コード書き換えを1つずつ順番に進める
OK： 複数のSubagentを立ち上げ、git worktree で別ブランチを同時並行で作業する
■ ⑧ hooks で品質ゲートを自動化する
NG： AIが生成したコードを手動でフォーマットし、テストを手動で走らせる
OK： コミット前のテスト実行・ファイル書き込み後の自動フォーマットをhooksに設定する
■ ⑨ MCP で他サービスとの連携を一元化する
NG： JiraやGitHubをブラウザで開きながら、Claude Codeに情報を手動コピペする
OK： MCP経由でClaude Codeがターミナルから直接情報を取得できるようにする
■ ⑩ チーム導入はセキュリティガイドラインとセットで進める
NG： AIツールの便利さだけを強調して強制導入する
OK： 禁止事項・フロー・インシデント対応を明文化したガイドラインを整備してから展開する
3. 各項目の詳細説明
■ CLAUDE.md の仕組みと書き方のコツ
📖 本節の内容は参考書籍の第2章を参考にしています。
CLAUDE.md は、チームのルールをClaude Codeに共有するためのファイルです。プロジェクトのコーディング規約、アーキテクチャ方針、禁止事項などを記載することで、AIの出力にチームのルールが反映されます。
また、暗黙知を言語化するという副産物もあります。 「なんとなくこうしてきた」をCLAUDE.mdに書き出す作業自体が、チームのドキュメント整備にもなります。
配置場所と読み込みの優先順位
-
チーム共有用： リポジトリルートの
CLAUDE.md（Gitで管理・共有） -
ローカル用： リポジトリルートの
CLAUDE.local.md（個人設定、Gitには含めない）
効果的な書き方のコツ
以下は書籍で紹介されているポイントをまとめたものです。
-
具体例を必ず添える
「lowerCamelCaseを使う」だけでなく、良い例・悪い例を併記する -
禁止事項には理由を書く
「RuntimeException禁止」だけでなく「HTTPステータスコードの自動マッピングのため」と理由を書く -
プロジェクトの文脈を最初に書く
技術スタック、全体構成、依存関係など、プロジェクトの前提情報があるとAIの出力精度が上がる -
短く保つ
CLAUDE.mdが長すぎると、重要なルールが埋もれる。A4で1〜2ページ程度が目安
【参考】CLAUDE.md の具体例
📖 具体的なサンプルは参考書籍に詳しく掲載されています。実際のプロジェクトへの適用イメージをつかみたい方はぜひ書籍をご参照ください。
■ Skills（カスタムスラッシュコマンド）の仕組み
📖 本節の内容は参考書籍の第2章を参考にしています。
Skillsを使うと、繰り返し行う作業をコマンド1つで呼び出せるようになります。
-
チーム共有用：
.claude/commands/ディレクトリ（Gitで管理・共有） -
個人用：
~/.claude/commands/（個人設定）
$ARGUMENTS は、コマンド実行時に引数で置き換わるプレースホルダーです。
例：/review TimeEntryService.java
→ $ARGUMENTS が TimeEntryService.java に置き換わって実行
【参考】Skills の具体例
📖 コードレビューやテスト生成の具体的なコマンドサンプルは参考書籍に詳しく掲載されています。実際の運用イメージをつかみたい方はぜひ書籍をご参照ください。
CLAUDE.mdとSkillsを使うことで、「規約を理解し、定型作業をこなせるチームメンバー」として機能するようになります。
■ Plan mode の使い方
📖 本節の内容は参考書籍の第3章を参考にしています。
Plan modeは、コードを変更せずに「分析と計画立案のみ」を行うモードです。大規模な変更の前に全体像を把握し、エンジニアが承認してから実行するワークフローに最適です。
Plan modeが有効な場面：
- 大規模リファクタリングの前
- 影響範囲が広い機能追加
- 「何から手をつけるか」が不明瞭なとき
ワークフロー：
ステップ1: Plan modeで計画を立てる
Shift+Tab でPlan modeに切り替え → 指示を入力 → Claude Codeが計画を提案
ステップ2: 計画をレビューし、承認する
人間が計画を確認 → 必要に応じて修正を依頼
ステップ3: 承認した計画に沿って実行する
計画の各項目を順番に実行 → 1つ完了するごとに確認
■ 既存コード（10万行規模）でのAI活用
📖 本節の内容は参考書籍の第4章を参考にしています。
レガシーコードにAIを活用する際は、以下の手順が効果的です。
① まず全体構造を把握させる
「このリポジトリの全体構造を説明して」
パッケージ構成、主要なクラス、データフロー、依存関係が整理された地図が生成されます。AIが出力した地図を使って、自分の目で検証しましょう。
② 既存コードから CLAUDE.md を逆引きさせる
「このコードから読み取れるコーディング規約をCLAUDE.mdとして出力して」
暗黙のルールがコードから明文化されます。生成されたCLAUDE.mdはエンジニアがレビューし、補足があれば追記しましょう。
大事なのは、エンジニアがレビューすることを怠らないこと！
■ コラム：AI生成テストの「8割/2割」法則
📖 本コラムの内容は参考書籍に掲載されているものです。
（１）8割：そのまま使えるテスト
- 基本的なCRUD操作の正常系・異常系
- バリデーションのチェック（null、空文字、型不一致）
- 明示的な境界値テスト（0、最大値、リストの空）
- フレームワーク固有のパターン（Mockitoのセットアップ、JUnit5のアサーション）
（２）2割：修正が必要なテスト
- 業務固有のロジック（「工数の最小単位は0.5時間」など、コードに明示されていないルール）
- 暗黙の前提条件（「このメソッドは必ずトランザクション内で呼ばれる」など）
- 複数の条件が組み合わさるエッジケース
8割をAIに任せて、2割の判断に集中する。 ー AI協働テストの基本戦略
■ Subagent と git worktree の使い方
📖 本節の内容は参考書籍の第5章を参考にしています。
Subagent（Task tool）
「段階的にやって」「複数の観点で分析して」と指示するだけで、Claude Codeが自律的にTask toolを使い、複数のSubagentを立ち上げます。
並列で実行できる作業例：
- 影響範囲の分析
- テストの追加
- コードの書き換え
必ずレビューとセットで使うことが重要です。任せきりにしない。
git worktree
git worktree を使うと、同じリポジトリの別ブランチを、別ディレクトリとして同時に開けます。stash で退避したり、コミットしてブランチを切り替えるような手間がなくなります。
# worktreeの追加（新しいブランチを別ディレクトリに展開）
git worktree add <path> <branch>
# 例: リファクタリング用ブランチを別ディレクトリに展開
git worktree add ../project-refactor feature/refactor-order
# worktreeの一覧表示
git worktree list
# worktreeの削除（作業完了後）
git worktree remove <path>
■ コラム：AI出力のレビューチェックリスト
📖 本コラムの内容は参考書籍に掲載されているものです。
AIが生成したコードをコミットする前に、以下を確認しましょう。
-
変更範囲は指示通りか（スコープの確認）
指示した範囲だけが変更されているか。意図しないファイルが含まれていないか -
意図しないシグネチャ変更はないか
メソッドの引数型、戻り値型、アクセス修飾子が勝手に変わっていないか -
テスト対象外のモジュールへの影響は？
変更したモジュールを参照している他のモジュールに影響はないか（grepで呼び出し箇所を確認） -
コミット単位は適切か（1コミット=1変更）
複数の変更が1つのコミットに混ざっていないか。後から切り戻しやすい粒度になっているか -
CLAUDE.mdの規約に沿っているか
命名規則、例外処理のルール、アーキテクチャ方針など、プロジェクト固有のルールが守られているか
■ hooks の仕組みと設定
📖 本節の内容は参考書籍の第6章を参考にしています。
hooksは、Claude Codeの動作の前後に自動で処理を挟む仕組みです。いわば、CI/CDのローカル版です。
主なフックポイント：
- コミットする前にテストを実行
- ファイルを書き込んだ後に自動フォーマット
設定場所： .claude/settings.json（Gitで管理することでチーム全員に適用可能）
設定の構造：
{
"hooks": {
"フック名": [
{
"matcher": "対象ツール名のパターン",
"hooks": [
{
"type": "command",
"command": "実行するスクリプトのパス"
}
]
}
]
}
}
| パラメータ | 説明 |
|---|---|
matcher |
対象ツールを正規表現で指定。主なツール名：Bash（シェルコマンド実行）、Write（ファイル作成）、Edit（ファイル編集）など |
command |
実行するシェルスクリプトのパス。stdin経由でJSON形式の入力データを受け取る |
PreToolUseでスクリプトが終了コード2を返すと、ツールの実行がブロックされます。
■ MCP の仕組みと使い方
📖 本節の内容は参考書籍の第6章を参考にしています。
MCPは、JiraやGitHubなどの情報をClaude Codeがターミナルから直接取得できる仕組みです。ブラウザで他サービスを開く必要がなくなります。
MCPサーバーの登録：
claude mcp add <サーバー名> -- <起動コマンド>
管理コマンド：
claude mcp list # 登録済みMCPサーバーの一覧
claude mcp remove # MCPサーバーの削除
主なMCPサーバーの例：
| サービス | 用途 |
|---|---|
| GitHub MCP | PRの確認、Issue管理 |
| Jira MCP | チケットの参照・更新 |
| Slack MCP | 通知やメッセージ確認 |
■ チームへのAI駆動開発導入のポイント
📖 本節の内容は参考書籍の第7章を参考にしています。
導入の3原則
- 強制しない — 便利さを体験させ、自発的に使いたくなる環境を整える
- 成果を示す — 「このPRはClaude Codeで30分で実装できた」など、具体的な効果を共有する
- セキュリティガイドラインの策定 — ガイドラインを先に整備してから全体展開する
セキュリティガイドラインの一例
📖 禁止事項・確認フロー・インシデント対応を網羅した具体的なガイドラインのサンプルは参考書籍に掲載されています。チーム導入を検討されている方はぜひ書籍をご参照ください。
コラム：チーム導入で避けるべき3つのアンチパターン
📖 本コラムの内容は参考書籍に掲載されているものです。
- 強制導入 — 押し付けは反発を生む。まず有志から始める
- ツール信仰 — 「AIが書いたから大丈夫」は禁物。レビューは必須
- セキュリティ無視 — 便利さに引っ張られてルールを後回しにしない
■ AI時代に求められるエンジニアの価値
📖 本節の内容は参考書籍の第8章を参考にしています。
価値が下がること
- 「コードを書く」という価値は、間違いなく下がる
- 「コードを読む」ことの価値も、小さくなる可能性が高い
価値が高まること
- システム全体を立体的に組み立てられる力 は求められ続ける
- デバッグの8割（手を動かす作業）はAIに任せ、「この修正で本当に正しいのか」「他に影響はないか」を判断することがエンジニアの役割
AIが進化しても変わらないもの
- 何を作るかを決める力
- それが本当に必要かを判断する力
- 品質に責任を持つ覚悟
「AI」と「自分の役割」を理解することがAIと協働するための鍵である。
まとめ
| テーマ | ポイント |
|---|---|
| AIの役割 | 実装を担当、設計のパートナー |
| エンジニアの役割 | 設計決定、レビュー、品質責任 |
| CLAUDE.md | チームルールをAIと人間の両方に共有 |
| Skills | 定型作業をコマンド化 |
| Plan mode | 変更前に計画をレビュー・承認 |
| テスト | 8割はAIに任せ、2割に集中 |
| Subagent | 並列作業で生産性向上 |
| git worktree | ブランチ切り替えのコスト削減 |
| hooks | 品質ゲートを自動化 |
| MCP | 外部サービス連携を一元化 |
| チーム導入 | 強制せず・成果を示す・セキュリティ先行 |
結局何をすればいいの❓
-
今すぐ：
npm install -g @anthropic-ai/claude-codeでインストールし、個人プロジェクトで試す -
今週中： プロジェクトに
CLAUDE.mdを1枚作成する（A4一枚でOK） - 今月中： コードレビュー・テスト生成のSkillsを1つ作る
- チーム展開前： セキュリティガイドラインを作成し、レビューフローを整備する
- 継続的に： AI出力のレビューを習慣化する（任せきりにしない）
「自分はこの方向に伸びていけばいい」という方向性を信じて努力しよう！
株式会社シンシア
株式会社xincereでは、実務未経験のエンジニアの方や学生エンジニアインターンを採用し一緒に働いています。
※ シンシアにおける働き方の様子はこちら
シンシアでは、年間100人程度の実務未経験の方が応募し技術面接を受けます。
その経験を通し、実務未経験者の方にぜひ身につけて欲しい技術力（文法）をここでは紹介していきます。