はじめに
この記事は、新人プログラマのみなさんに向けた「Claude Codeのノウハウをサンプルコードで学ぶ」シリーズの入門編です。シリーズは全4本で、ゆるやかにステップアップしていく構成になっています。
- 入門編（本記事） — Claude Codeの全体像・使い方・拡張機能の地図までを一冊で理解する
- 中級編 — エージェント設計の考え方を概念レベルで解説する
- ハーネス設計8パターン編 — 設計パターンを動くTypeScriptで再現する
- エージェント実装深掘り編 — 統合エージェントの実装詳細を読み解く
本記事はその1本目、いわば地図を広げる段階です。AI時代に初めてプログラミングの世界に足を踏み入れる方、あるいは「Claude Codeという言葉は聞くけれど、どこから手をつけたらいいのかわからない」という方に読んでいただければ嬉しいです。
新人のうちに製品の全体像を掴んでおくと、あとで個別の機能を学ぶときの吸収スピードが変わります。本記事では、インストール・基本操作・内蔵ツール・拡張機能（MCP／フック／スキル／サブエージェント）・コスト感・他ツール比較までを、手を動かしながら追いかけられる構成でお届けします。
AI時代だからこそ、仕組みを読み解きたい理由
AIコーディングツールを使って「動くものを作る」までは、今やとても早くできるようになりました。数行のプロンプトで関数ができあがり、テストも生成され、READMEまで書いてくれます。
一方で、こんな経験はないでしょうか。
- コードは動いたけれど、なぜ動くのか自分では説明できない
- AIが提案してきた方法が本当に安全なのか、判断がつかない
- 同じ質問をしているのに、日によって精度が違う気がする
これは、AIの「中で何が起きているか」が見えていないことが原因の多くを占めます。料理の腕前がある人は、冷蔵庫の中を見ただけで献立が組み立てられます。同じように、AIエージェントの中身を少し覗いておくと、指示の出し方・結果の読み方・壊れた時の直し方が一段上手になります。
本シリーズは、そんな「仕組みを読み解く力」を、新人のみなさんと一緒に育てていくことを目標にしています。
Claude Codeとは何か
まず「Claude」と「Claude Code」の違いを整理します
本記事には「Claude」と「Claude Code」という似た単語が並んで出てくるので、最初に意味を分けておきます。
-
Claude（クロード） — Anthropic社が開発している**LLM（大規模言語モデル）**の名称です。用途や性能帯ごとに以下のモデルファミリーがあり、本記事執筆時点（2026年4月）の最新世代は以下のようになっています。
- Claude Opus 4.7（高性能・複雑な推論向け・最大1Mトークンのコンテキスト）
- Claude Sonnet 4.6（性能と速度のバランス型・日常的なコーディング用途の主役）
- Claude Haiku 4.5（軽量・高速・低コスト・サブエージェントや軽作業向け）
- Claude Code（クロード コード） — そのClaudeをターミナル上のコーディングエージェントとして使うためのツールです。Anthropic社が公式に提供しています。
例えるなら、Claudeが「脳」で、Claude Codeが「その脳を使って実際に手を動かす体」のようなイメージです。以下の本文では、両者を意識的に使い分けて書いていきます。
モデル別の用途イメージ
3モデルのざっくりした使い分け表です。プロジェクトやタスクによっては切り替えながら使うのが実務的です。
| モデル | 得意 | 典型的な用途 | 相対コスト |
|---|---|---|---|
| Opus 4.7 | 深い推論・大規模な設計 | アーキテクチャ設計・難しいバグの根本原因調査 | 高 |
| Sonnet 4.6 | 日常的なコーディング | 機能実装・リファクタリング・レビュー | 中 |
| Haiku 4.5 | 高速処理・単純作業 | 短いQ&A・ログ要約・サブエージェントの並列処理 | 低 |
Claude CodeではデフォルトでSonnetが選ばれ、/model コマンドで随時切り替えられます。最初はSonnetでよく、重いタスクで必要を感じたときにOpusに持ち替える、くらいのイメージで十分です。
Claude Codeの位置づけ
Claude Code は、Anthropic社が提供するターミナル上で動くAIコーディングエージェントです。2024年後半から広く使われはじめ、2026年現在では数多くのエンジニアが日々の開発に取り入れています。
ざっくりしたイメージは以下のような流れです。
ここで注目してほしいのは、「Claude Code」と「Claude」は別のレイヤだということです。Claude（LLM）はあくまで「考える部分」で、Claude Codeはその周りを包んでファイルを読んだり・コマンドを実行したり・あなたに確認をとったりする役割を担っています。
この「考える部分」と「実行する部分」が分かれている構造こそが、本シリーズで繰り返し登場する**ハーネス（harness）**という概念の原型です。
他のAIコーディングツールとの違い
Claude Codeの特徴を掴むには、同じジャンルの他ツールと比較するのが早いです。2026年4月時点での代表的なツールを簡単に並べてみます。
| ツール | 形態 | 特徴 | Claude Codeとの違い |
|---|---|---|---|
| GitHub Copilot | エディタ内補完＋Agent Mode | リアルタイム補完が主軸 | Copilotはコード補完寄り、Claude Codeは対話エージェント寄り |
| Cursor | AI特化型エディタ | 独自エディタ全体がAI中心設計 | Cursorはエディタ統合、Claude Codeはターミナル＋任意エディタ |
| Cline | VSCode拡張エージェント | OSSで拡張自由度が高い | ClineはVSCode内で完結、Claude Codeはシェル文化に溶け込む |
| Aider | CLIエージェント（OSS） | Git統合に特化 | 思想は近い。Claude Codeはツール群と拡張機能が豊富 |
| Claude Code | CLIエージェント（公式） | ハーネス設計とMCP/フック/スキルで拡張可能 | 後述の通り拡張機能の体系が整備されている |
どのツールが「正解」ということはなく、プロジェクトや好みに応じて使い分ける時代です。本記事ではClaude Codeに絞って掘り下げますが、ここで紹介するハーネスやTool Useの概念は他ツールでも共通なので、学びがそのまま応用できます。
セットアップと認証
インストール
Claude Codeは公式に以下の3系統のインストール方法が用意されています（2026年4月時点）。環境に合わせて選んでください。
macOS / Linux（公式インストーラ）
curl -fsSL https://claude.ai/install.sh | bash
実行後、シェルを再起動して claude --version が動けば成功です。
npm経由（クロスプラットフォーム）
Node.js v18以上が入っていれば、以下でもインストールできます。
npm install -g @anthropic-ai/claude-code
Windows（WSL2 推奨）
Windowsで使う場合は、WSL2上のUbuntuなどLinux環境へインストールするのが公式推奨です。ネイティブWindowsにも拡張サポートが増えつつありますが、まずはWSL2が無難です。
認証方式の選び方
Claude Codeには4つの認証経路があり、組織やコスト構造に応じて選べます。
簡単な対応表を挙げます。
| 認証方式 | 設定 | 向いている人 |
|---|---|---|
| Claude Pro / Max |
claude login でブラウザ認証 |
個人利用・月額定額で使いたい |
| Anthropic API Key |
ANTHROPIC_API_KEY 環境変数 |
従量課金・スクリプト組み込み |
| Amazon Bedrock |
CLAUDE_CODE_USE_BEDROCK=1 + AWS認証 |
AWSのガバナンスに統合したい |
| Google Vertex AI |
CLAUDE_CODE_USE_VERTEX=1 + GCP認証 |
GCPのガバナンスに統合したい |
新人のうちは、個人でClaude Pro/Maxが最も手軽です。社内環境で使うときは上司・情シスに認証方式を確認してから進めてください。
起動と終了
インストールが済んだら、Gitリポジトリのディレクトリに移動して以下を実行します。
cd ~/dev/my-project
claude
対話プロンプトが開きます。終了するときは Ctrl+D（または /exit スラッシュコマンド）です。
最初の1セッション（ハンズオン）
ここで実際に1セッション動かしてみます。以下は手元の小さなリポジトリで「READMEを3行に要約してもらう」という流れです。対話ログを引用しつつ、何が起きているかを解説していきます。
ステップ1: 起動
$ claude
Welcome to Claude Code!
/help for help, /status for your current setup
>
起動直後は、何も知らないまっさらなClaude（Sonnet）が待機している状態です。ディレクトリの内容はまだ読んでいません。
ステップ2: 依頼を出す
> このリポジトリの README.md を読んで、3行で要約してください。
Claude Codeは、この依頼を裏側で以下の手順で処理します。
- ユーザーのメッセージをClaudeに送る
- Claudeが「READMEを読む必要がある」と判断し、
Readツールの呼び出しをJSONで返す - Claude Code側で
README.mdの中身をディスクから取得する - 取得内容をClaudeに戻す
- Claudeが3行の要約を生成してユーザーに表示する
画面上はこのように見えます（具体的な応答はモデル・バージョンで変わります）。
● Read(README.md)
⎿ Read 124 lines
要約です:
1. このプロジェクトは〜
2. 主な機能は〜
3. セットアップは〜
行頭の ● が付いた行はツール実行を意味します。Claude Codeは何をしたかを画面に必ず残す設計になっています。
ステップ3: 続けて指示する
続きで「英訳してREADME.en.mdに保存して」と頼んだとしましょう。今度はReadに加えWriteツールが呼ばれます。
> 英訳して README.en.md に保存してください。
● Read(README.md)
● Write(README.en.md)
Do you want to create README.en.md?
> 1. Yes
2. Yes, and don't ask again for this tool
3. No, and tell Claude what to do differently
ファイル作成・書き換え・コマンド実行など副作用のある操作は、デフォルトで毎回ユーザーに確認されます。このガード機構こそが「ハーネス」の本質です。
ステップ4: 振り返り
/status や /cost で、このセッションで使ったトークンやコストの目安が見られます。
> /cost
Total cost: $0.0042 (2,340 input + 560 output tokens)
Cache read: 1,820 tokens
初回は高く見えますが、続けてやり取りするとプロンプトキャッシュが効いて後半のコストは下がっていきます。キャッシュの詳細は中級編で扱います。
Claude Codeが備える内蔵ツール
Claude Codeは、Readのようなツールを15種類以上標準で備えています。Claude自身はこれらの存在をツール定義として受け取り、必要に応じて呼び分けます。主要なものを一覧でご紹介します。
| ツール | 役割 | 典型的な使い道 |
|---|---|---|
Read |
ファイル読み取り | ソース・README・設定の確認 |
Write |
ファイル新規作成 | 新しいファイルの生成 |
Edit |
部分書き換え | 既存ファイルのピンポイント修正 |
Bash |
シェルコマンド実行 | テスト実行・git操作・ビルド |
Grep |
ripgrep検索 | コード内のキーワード検索 |
Glob |
ファイル名パターン検索 |
**/*.ts のような探索 |
WebFetch |
URLから内容取得 | 公式ドキュメント参照 |
WebSearch |
Web検索 | 最新の技術情報収集 |
Task |
サブエージェント起動 | 並列リサーチ・大きなタスクの委譲 |
TodoWrite |
TODO管理 | 複数ステップのタスク追跡 |
ExitPlanMode |
プランモード終了 | 計画→実装への移行 |
これらはClaude自身が呼び分けるため、ユーザーが「Readを使って」と明示する必要はありません。自然言語で「READMEを読んで」と言えば、適切なツールが自動で選ばれます。
「AIに全部任せる」と言っても、結局は使えるツールがあらかじめ用意されている範囲でしかAIは動けません。この「利用可能なツールを把握しておく」感覚は、AIエージェント時代の基礎スキルです。
最小限の「動くイメージ」を作ってみる
概念だけだとふわっとしてしまうので、TypeScriptで10行程度のミニマムサンプルを書いてみます。実行しなくても、読むだけで雰囲気がつかめると思います。
// 1. 「考える部分」を模した関数（実際のLLMに置き換わります）
function think(userRequest: string): { action: string; target?: string } {
if (userRequest.includes('読んで')) return { action: 'read', target: 'README.md' }
return { action: 'reply' }
}
// 2. 「実行する部分」
function execute(plan: { action: string; target?: string }): string {
if (plan.action === 'read') return `[FILE CONTENT of ${plan.target}]`
return '了解しました'
}
// 3. 流れをつなぐ
const plan = think('READMEを読んでほしい')
const result = execute(plan)
console.log(result) // [FILE CONTENT of README.md]
たったこれだけですが、AIエージェントの心臓部は同じ構造です。違うのは、think の中身が本物のClaudeに差し変わること、そしてexecute が扱えるアクション（ツール）の種類が豊富なこと、の2点です。
この「考える」「実行する」を分けて書いておくと、あとで考える部分を賢いモデルに差し替えても実行部分に手を入れる必要がありません。この「関心の分離」はAIエージェントに限らず、ソフトウェア設計の基本原則の一つです。新人のうちに触れておくと、あとで効いてきます。
スラッシュコマンドと便利機能
Claude Codeには、対話中に / で始まるスラッシュコマンドが用意されています。何度も使う操作をキーワードで呼び出せる仕組みです。よく使うものを押さえておくと作業効率が劇的に変わります。
| コマンド | 機能 |
|---|---|
/help |
ヘルプ一覧表示 |
/clear |
会話履歴を完全リセット |
/compact |
会話履歴を要約して圧縮 |
/model |
モデル切り替え（Sonnet ⇄ Opus ⇄ Haiku） |
/status |
現在のモデル・認証・プロジェクト情報 |
/cost |
累積トークン・コスト表示 |
/config |
設定を開く |
/init |
プロジェクトにCLAUDE.mdを新規作成 |
/exit |
終了 |
プランモードという「一呼吸」
特に新人に強くおすすめしたいのが Shift+Tab を1〜2回押したときに切り替わるプランモード です。このモードでは、Claude Codeはファイルの編集を一切行わず、計画だけを提示します（調査のためのファイル読み取りやシェルコマンド実行は行われます）。
- 「この機能を実装したいけれど、まずどう進めるか見たい」
- 「大きなリファクタリングの前に全体像を掴みたい」
こういう場面でプランモードを使うと、Claudeが手を動かす前に計画書を見せてくれます。そこに修正要望を伝えれば、計画段階で軌道修正でき、手戻りが減らせます。
新人のうちは「3ステップ以上のタスクは必ずプランモードから」くらいの習慣が丁度よいと思います。
拡張機能の地図 ── MCP・フック・スキル・サブエージェント
Claude Codeは内蔵ツールだけでも十分強力ですが、それだけで終わらないのが特徴です。以下の4種類の拡張機構が用意されていて、それぞれ異なる目的を担っています。
MCP（Model Context Protocol）
用途: 外部サービス・APIと連携するツールを追加する仕組み
MCPは2024年末にAnthropicが公開した、AIエージェントに外部データソースをつなぐ標準プロトコルです。たとえば以下のようなMCPサーバーが存在します。
- Supabase / PostgreSQL MCP — データベースに直接クエリを投げられる
- GitHub MCP — PR・Issue・コードを直接操作できる
- Slack MCP — メッセージ投稿・取得
- Notion MCP — ページ読み書き
接続すると、Claude Codeから自然言語で「Slackの#devチャンネルの最新10件を要約して」と依頼できるようになります。新人のうちは「こういう世界があるんだな」と知っておくだけで十分です。具体的な設計は中級編で扱います。
フック（Hooks）
用途: ツール実行の前後に自動で走るスクリプトを差し込む仕組み
.claude/settings.json にシェルコマンドを登録すると、以下のようなイベントで自動実行されます。
| イベント名 | 発火タイミング | ユースケース |
|---|---|---|
PreToolUse |
ツール実行直前 | 危険コマンド事前ブロック・入力検証 |
PostToolUse |
ツール実行直後 | ログ記録・フォーマッタ実行 |
UserPromptSubmit |
ユーザー入力直後 | プロンプトに追加情報を注入 |
Stop |
メインエージェントの応答終了時 | 完了通知・サマリー |
SessionStart |
セッション開始時 | 前回の続きを復元 |
SessionEnd |
セッション終了時 | 終了時の後片付け・保存 |
たとえば「TypeScriptファイルが保存されるたびにprettierを自動実行する」「rm -rfを含むBash呼び出しをブロックする」といった運用ポリシーをコードで表現できます。
スキル（Skills）
用途: プロジェクト固有の振る舞い・ノウハウをMarkdownファイルで拡張する仕組み
.claude/skills/<スキル名>/SKILL.md というファイルを作ると、その内容をClaudeが必要時に自動で読み込みます。
---
name: qiita-writing
description: Qiita記事を執筆する際のスタイルガイドとワークフロー
---
## 文体規則
- です/ます調で統一する
- 1文は60文字以内
...
本記事もQiita記事執筆のスキル（qiita-writing）を使って書いています。Markdownだけで振る舞いを拡張できるのがスキルの大きな特徴で、プログラミング経験が浅い人でもカスタマイズしやすい仕組みになっています。
サブエージェント（Subagents）
用途: 別のClaudeインスタンスを子プロセス的に呼び出して並列処理する仕組み
大きな調査タスクを複数に分けたいときや、メインのコンテキストを綺麗に保ちたいときに使います。たとえば「このリポジトリの認証まわりとAPIまわりを同時に調査して」と依頼すると、Claude Codeは2つのサブエージェントを並列起動し、それぞれの結果をまとめてくれます。
サブエージェントは並列で動くため、リサーチ系タスクのレイテンシが大きく下がるのが利点です。
CLAUDE.mdでプロジェクトをカスタマイズ
Claude Codeの最大の「伝える道具」が、プロジェクトルートに置く CLAUDE.md ファイルです。
Claude Codeを起動するたびに、このファイルの内容が自動的にシステムプロンプトへ追加されます。つまりここにプロジェクト固有の知識やルールを書いておけば、毎回説明しなくてもClaudeが把握してくれる、という仕組みです。
典型的な構成例
# プロジェクト概要
TypeScript製のタスク管理アプリ。Next.js + Prisma + PostgreSQL構成。
## ディレクトリ構成
- `src/` — アプリケーション本体
- `prisma/` — スキーマとマイグレーション
- `tests/` — Vitestによるテスト
## コーディング規約
- インデントはスペース2つ
- `any`型の使用禁止、代わりに`unknown`を使う
- 新しい関数にはJSDocコメント必須
## テスト・ビルドコマンド
- `npm run dev` — 開発サーバー起動
- `npm test` — テスト実行
- `npm run build` — プロダクションビルド
## 禁止事項
- `.env` を直接参照せず、必ず`src/config.ts`経由で読む
- `prisma migrate` は必ず `migrate dev` を使う
このファイルがあるとないとでは、Claudeの振る舞いが別物になります。「新人が先輩からもらうオンボーディング資料」をClaudeにも渡してあげるくらいのイメージです。
/init スラッシュコマンドを実行すると、Claude自身がディレクトリを調査してCLAUDE.mdのたたき台を生成してくれます。まずはこれから始めるのがおすすめです。
階層構造
CLAUDE.mdは以下の3階層で重ね合わせて使えます。
| 階層 | 置き場所 | 用途 |
|---|---|---|
| ユーザー | ~/.claude/CLAUDE.md |
個人の好み・全プロジェクト共通ルール |
| プロジェクト | <repo>/CLAUDE.md |
プロジェクトメンバー共有のルール |
| ディレクトリ | <repo>/<subdir>/CLAUDE.md |
特定ディレクトリ限定のルール |
個人の好みはユーザーレベルに、チームのルールはプロジェクトレベルに、と役割を分けると綺麗に運用できます。
権限と実行モード
Claude Codeを使っていると、「この操作を実行してよいですか？」と確認されることがあります。たとえば以下のような状況です。
- ファイルを新しく作成する
- 既存のファイルを書き換える
- シェルコマンドを実行する
- npm install のような外部ネットワーク通信を伴う操作をする
「便利なツールなんだから、全部任せてしまえばいいじゃないか」と感じるかもしれません。ただ、ここで少し立ち止まる必要があります。
LLMは間違える
Claudeは非常に賢いモデルですが、間違った判断をすることがあります。たとえば、以下のようなケースを想像してみてください。
- 「不要なログファイルを消しておいて」と伝えたつもりが、重要な設定ファイルまで消されてしまう
- プロンプトに混入した悪意のある指示によって、秘密情報が外部に送信される
- 誤って
rm -rf /に相当する操作が提案される
こうした事故を防ぐために、Claude Codeはモデルの提案をそのまま実行しません。いったんハーネス層で受け止めて、危険な操作は止める・ユーザーに確認する、という流れになっています。
ハーネスは「セーフティネット」
「ハーネス（harness）」とは、元々は乗馬や登山で使われる装具のことです。乗り手や登山者を支え、落下や暴走を防ぐ役割があります。
AIエージェントのハーネスも同じ発想です。モデルが何を提案しようと、実行前に安全チェックを挟む。これによって、モデルがどれだけ賢くなっても（あるいはたまたま暴走しても）、システム全体としての安全性が保たれます。
実行モードの種類
Claude Codeには、対話の性質に応じて複数の実行モードがあり、起動時または途中で切り替えられます。代表的なものは以下のとおりです（詳細は公式ドキュメントを参照）。
| モード | 挙動 | 使いどころ |
|---|---|---|
default |
破壊的操作は毎回確認 | 日常作業 |
acceptEdits |
ファイル編集は自動承認、シェル・削除は確認 | コード編集に集中したい時 |
plan |
計画提示のみ、編集はしない（読み取りやシェル実行は可） | 設計段階 |
bypassPermissions |
権限プロンプトと安全チェックをスキップ（保護パス書き込みは例外的に確認） | 隔離コンテナ・完全自動化 |
Shift+Tab を押すと default → acceptEdits → plan の順でサイクルします（bypassPermissions は起動フラグ等で有効化した場合のみサイクルに入ります）。新人のうちはdefaultとplanの2つだけで十分です。bypassPermissionsは事故のリスクが高いため、CI環境や使い捨ての隔離環境など、失敗しても安全な場面に限定するのが無難です。
保護パスという最終ガード
どの実行モードであっても、以下のパスへの書き込みは必ず確認を求められます。これは「壊滅的操作の最終ガード」として設計されています。
-
.git/配下 -
.claude/配下 - シェル設定（
.bashrc,.zshrcなど） - 認証情報系ファイル
この仕組みは公式ドキュメントで定義されています。bypassPermissions は権限プロンプトや通常の安全チェックを広くスキップしますが、上記のような保護パスへの書き込みだけは例外的に確認を求めます。「bypassPermissions = なんでも通る」ではなく、「致命的な事故は最後まで止める」という設計思想です。
コストとトークンの感覚
AIエージェントは便利な反面、使った分だけお金がかかるツールでもあります。新人のうちから感覚を掴んでおきましょう。
トークンとは何か
LLMは文章をトークンという単位で処理します。ざっくりの目安は以下のとおりです。
- 英語: 1トークン ≈ 4文字
- 日本語: 1トークン ≈ 1〜2文字
- コード: 1トークン ≈ 3〜4文字
Claudeの料金は入力トークンと出力トークンで課金され、モデル別に単価が異なります。価格は改訂されることがあるため、具体的な数字は必ずAnthropic公式価格ページで確認してください。
相対的な位置づけは次のようなイメージです。
| モデル | 単価の傾向 | 備考 |
|---|---|---|
| Opus 4.7 | 最も高い | 複雑な推論で真価を発揮 |
| Sonnet 4.6 | 中程度 | 日常業務のバランス型 |
| Haiku 4.5 | 最も安い | 大量処理・サブエージェント向け |
出力トークンは入力トークンより数倍高いモデルが多いです。長大な応答を求めるよりも、要点を絞ってもらう方がコスト効率が良くなります。
プロンプトキャッシュで大幅削減
Anthropic APIにはプロンプトキャッシュ機能があり、同じプレフィックスを繰り返し送る場合、**通常料金の10%（0.1倍）**に抑えられます。
Claude Codeは内部でこの仕組みを積極的に使っており、長い会話になるほどキャッシュヒット率が上がって相対コストが下がります。/cost で「Cache read」の数字を見ると、どれだけキャッシュが効いているかわかります。
月額目安（参考）
個人利用の感覚値を挙げます（実際の消費は使い方次第です）。
- Claude Pro サブスクリプション: $20/月 ─ 軽〜中程度のコーディング利用
- Claude Max サブスクリプション: $100/月 ─ 日常的にClaude Codeを使う
- APIキー従量課金: 日に数時間〜使う人で $50〜200/月が目安
組織導入時はBedrock/Vertex経由が主流で、既存クラウド請求に統合できます。
新人が陥りやすい5つの失敗と対処
新人がClaude Codeを使い始めてよく踏む落とし穴と、その対処法をまとめました。
失敗1: 長すぎる依頼で精度が下がる
「このプロジェクト全体を見て、全機能をリファクタリングし、テストも追加して、READMEも更新して、デプロイまで」のような一息に全部詰め込んだ依頼は、ほぼ確実にどこかが抜けます。
対処: タスクを区切って、1ステップごとにレビューする。プランモードで全体構想を先に確定させる。
失敗2: AIの提案をノーレビューでコミット
「動いたからOK」でそのままコミットすると、後日セキュリティホールや規約違反が発覚することがあります。
対処: 1行ずつ目を通し、意味を自分で説明できる状態にしてからコミット。AIレビューを組み合わせるのも有効ですが、最終判断は人間です。
失敗3: 無限ループで高コストに
Claudeがエラーを直そうとして、同じファイルの編集と再実行を延々繰り返すことがあります。気づかずに離席すると、数十ドル消費していることも。
対処: maxTurns の制限を意識する、異常に長い時間レスポンスが返ってこないときは一度キャンセル、/cost で頻繁にチェック。
失敗4: 機密情報の漏洩
.env を誤って開いて内容をClaudeに送信してしまう、あるいはAWS認証情報を含むファイルをリポジトリにコミットしてしまう、という事故はAI時代に増えています。
対処: CLAUDE.md に「.envは読まない」「*.key系ファイルは触らない」と明示。フックで防御も可。日常的に git diff でコミット内容を確認する習慣。
失敗5: AIに任せきりでスキルが伸びない
「エラーが出たらAIに聞く」「分からないコードはAIに説明させる」だけを繰り返していると、自分で調べる力が育ちません。
対処: 最低でもエラーメッセージ・スタックトレース・差分は自分で読む。AIに聞く前に5分は自分で考える。ログとドキュメントを読む筋肉は、10年先も陳腐化しません。
使い始めの人によくある疑問
Q1. AIが書いたコードをそのままコミットしてよいですか
結論は「読んでから」です。AIの提案は7〜9割は妥当ですが、残りには微妙な間違いが含まれます。
- エッジケースの考慮が抜けている
- 既存のコーディング規約と合っていない
- セキュリティ的に問題があるパターンを使っている
1行ずつ目を通して、自分で意味を説明できる状態にしてからコミットする習慣をつけるのがおすすめです。これはレビュー文化の第一歩でもあります。
そもそもコードレビューはAIが書いたかどうかに関係なく必要です。人が書いたコードであっても、他人の目（あるいは一晩おいた自分の目）を通すことで、設計の歪みや見落としが発見されます。AIの登場で「レビューが不要になった」わけではなく、むしろレビューの相対的な価値が高まっていると捉えるのが正確です。
そのうえで、最近はエージェント自身に別インスタンスでレビューさせる（いわゆるAIレビュー）という方法も一般的になってきました。ただし、プログラムの重要度によっては人が必ず介在すべきケースとAIレビューで十分なケースが分かれます。目安としては、以下のような切り分けをおすすめします。
- 人が必ず介在: 本番DBに触れる処理、認証・認可、決済、外部APIへの書き込み、セキュリティ上の境界になるコード
- AIレビューで十分なことが多い: 使い捨てスクリプト、ドキュメント修正、ローカル検証用のツール、テストコードの初版
なお、この切り分けは開発の規模やチーム体制によっても変わります。たとえば一人で開発している個人プロジェクトであれば、AIレビューを主として人のレビューは節目だけで済むケースもあります。一方、複数人で開発する業務システムや、監査・コンプライアンスの対象となるプロダクトでは、ドキュメント修正であっても人の目が要求される場合があります。所属チームのレビュー規約・プルリクエストのポリシーに合わせて、自分の中の基準をチューニングしていくのがよいと思います。
新人のうちは「重要度が判断できないから全部目を通す」で構いません。経験を積むなかで、自分なりの切り分け基準が育っていきます。
Q2. プロンプトが長くなるほど精度が上がりますか
一概にそうとは言えません。LLMにはコンテキストウィンドウという「一度に読める情報の上限」があります。Claude Sonnet 4.6は最大1Mトークンのコンテキストをサポートしています。
長くなりすぎると、以下のような問題が起きます。
- 大事な指示が後半に埋もれて効かない（lost-in-the-middle現象）
- 応答が遅くなり、コストも上がる
- 古い会話履歴が優先されて新しい要件が反映されない
「長く詳しく書く」よりも「必要な情報を構造化して渡す」ほうが効果的です。
Q3. 失敗したときはどうすればいいですか
まず落ち着いて、以下を確認してみてください。
- エラーメッセージを読む（AIに頼らず、自分で読むことが大事です）
- 最後に実行されたコマンドやファイル変更を
git status/git diffで確認する - 一度作業を止めて、Claude Codeに「何が起きたか要約して」と聞いてみる
- どうにもならなければ
/clearで会話を一度リセットして、違う切り口で再依頼する
AIを使うからこそ、基礎的な調査スキル（ログを読む、差分を見る、再現する）が一段大事になります。このスキルは10年先も腐りません。
Q4. 複数の人で同じリポジトリを使うときの注意点は？
-
CLAUDE.mdはチームで共有できる（コミット推奨） -
.claude/settings.jsonは共有用と個人用で分ける（個人用は.gitignore） - MCPサーバーの認証情報は絶対にコミットしない（環境変数か
.claude/settings.local.json）
チーム導入時のガイドとして、最初にレビュー担当が運用ルールを文書化しておくと事故が減ります。
Q5. 情報が古くなるのが心配です
Claude Codeは頻繁にアップデートされ、MCPなどの拡張機構も活発に進化しています。以下を押さえておくと最新を追いやすいです。
- 公式ドキュメント — 一次情報
- Anthropic社公式ブログ — 大きな更新の告知
-
claude --version— 手元のバージョン確認 - QiitaやZennの「ClaudeCode」タグ — コミュニティの生の運用例
一度に全部覚える必要はありません。「どこを見れば最新がわかるか」のブックマークを持つことのほうが、新人にとっては大事な財産です。
Q6. モデルはいつ切り替えればいいですか
次のような感覚値がおすすめです。
- 普段はSonnet 4.6
- 大きなアーキテクチャ設計・難しいバグ調査はOpus 4.7
- サブエージェントや並列リサーチはHaiku 4.5
/model でいつでも切り替えられるので、「このタスクは思ったより重い」と感じた瞬間にOpusに持ち上げる運用が現実的です。
サンプルコードの置き場
本シリーズの後半で扱うサンプルコードは、すべて以下のGitHubリポジトリにまとめています。入門段階では中身を読む必要はありません。「いつか自分でいじってみたい」と感じたときのブックマーク先として、頭の片隅に置いておいていただければ十分です。
- リポジトリ: nogataka/ts-claude-code-patterns-tutorial
- 基本パターン集:
examples/harness-patterns/ - 統合エージェント:
examples/mini-agent/
- 基本パターン集:
次のステップ
ここまで読めたら、新人プログラマとしての最初の一歩は十分です。次の 中級編 では、以下のテーマを一段深く掘り下げます。
- エージェントが会話を続ける「ループ」の中身
- ツール呼び出しが実際どう行われているか（JSONベースのプロトコル）
- プロンプトキャッシュやメモリ階層など、本番運用で出てくる話題
- エージェントが「コンテキスト溢れ」を起こしたときの対処方法
- MCP・フック・スキル・サブエージェントの設計指針
中級編を読み終えれば、ハーネス設計8パターン編 と エージェント実装深掘り編 に書かれている動くサンプルコードを、自分の言葉で理解できるようになります。
まとめ
本記事でお伝えしたかったのは、以下の7点です。
- AIコーディングツールは「動かす」だけでなく「中身を少し覗く」ことで格段に使いこなせる
- Claude Codeは「Claude（LLM）」と「ハーネス（制御層）」の2層構造
- モデル（Opus/Sonnet/Haiku）は用途で使い分ける、日常はSonnetで十分
- 内蔵ツール15種類＋4つの拡張機構（MCP・フック・スキル・サブエージェント）が豊富に用意されている
-
CLAUDE.mdにプロジェクト固有のルールを書くと、毎回説明しなくて済む - プランモードと4つの実行モードの違いを理解し、場面で使い分ける
- 権限確認はうるさいのではなく、あなたの作業を守るための仕組み
新人プログラマとしての第一歩は、目の前のタスクを終わらせるだけではなく、「道具の仕組み」を自分の武器にしていくことだと思っています。焦らず、一歩ずつ。シリーズの続きでお会いしましょう。
参考リンク
- Claude Code公式サイト
- Claude Code公式ドキュメント
- Anthropic公式ドキュメント
- Anthropic公式価格ページ
- Model Context Protocol公式
- 本シリーズのサンプルコード（GitHub）
- Qiita新人プログラマ応援イベント