はじめてのClaude Code

claude-code 101

Ryo Nakagami

2026年04月13日

コーディングエージェント概論

  • コーディングエージェント概論

  • 標準ワークフローと活用

  • プロンプトエンジニアリング基礎

  • Context Management

  • Pricing

コーディングエージェントとは何か？

  • コーディングエージェントとは，LLMが自律的にコードの読み書き・コマンド実行・検証を行うAIエージェント1のこと
  • ユーザーの指示を受けて「計画 → 実行 → 検証 → 修正」のループを自走し，タスク完了まで反復する
    • 従来ソフトウェア: 人間が アルゴリズム・分岐・例外処理を事前にすべて設計し，その手順に従う
    • コーディングエージェント: 手順そのものを動的に生成・修正

コーディングエージェントの進化2

pipeline:
  title: "LLM登場前"
  content:
    - 'バッチ処理やワークフローによる処理自動化'
    - '処理は自動化されるがロジックは固定'
  opposite: "2010年代後半"
  color: "#B4D7FF"

copilot:
  title: "LLMコーディング支援"
  content:
    - 'コード補完・生成（Copilot, ChatGPTなど）'
    - 'コード補完や関数の生成'
    - '試行錯誤は人間が実施'
  opposite: "2020年代前半"
  color: "#0E3666"

agent_v1:
  title: "対話型エージェント"
  content:
    - 'IDE + AIモデル(Cursorが代表例)'
    - 'レポジトリ内容を踏まえて，コード生成と実行を自動化'
    - 対話的な開発フロー中心
  opposite: "2023〜2024"
  color: "#0E3666"

agent_v2:
  title: "自律型エージェント"
  content:
    - 'Devin, Claude Code'
    - '計画→実行→検証→修正のループを確立'
    - 'バックグラウンド実行，非同期・並列実行'
  opposite: "2024〜"
  color: "#428CE6"

コーディングエージェントの特徴

「計画 → 実行 → 検証 → 修正」の自律ループ1で動く

指示・ゴール

  • ユーザー要件
  • 成功条件の把握

計画立案

  • タスク分解・要件具体化
  • 手順の動的設計

実行

  • Read/Edit/Bash
  • 環境への作用

検証

  • 出力・エラー確認
  • テスト結果検証

修正・再計画

  • 誤り訂正
  • 方針転換
フィードバックループ：完了条件を満たすまで自走反復

コーディングエージェントの中核機能

regmonkey_abstract_summary:
  title_fontsize: 1em
  bullet_fontsize: 0.8em
  keystat_fontsize: 0.8em
  children:
    - title: 目的駆動
      description:
        - 操作ではなく「やりたいこと（Goal）」を与える
        - 完了条件・成功基準をもとに自走
      width: [25,75]

    - title: 動的生成
      description:
        - 手順・コード・コマンドを状況に応じて生成
        - 固定ロジックではなく都度設計・変更
      width: [25,75]
regmonkey_abstract_summary:
  title_fontsize: 1em
  bullet_fontsize: 0.8em
  keystat_fontsize: 0.8em
  children:
    - title: ツール実行
      description:
        - Git，APIなどのツールを自律的に操作
        - ファイル操作・シェル実行・検索を使い分け
      width: [25,75]

    - title: 自己修正
      description:
        - 実行結果を確認し，エラーに応じて修正
        - 完了条件を満たすまで反復
      width: [25,75]

Bare LLM vs Coding Assistant

ファイル読込など環境作用が必要な質問は、LLM単体では完結せずアシスタント層が必須

Bare LLM：ファイルにアクセスできない

sequenceDiagram
    participant U as User
    participant L as LLM

    U->>L: what's written in main.go?
    L-->>U: テキストの入出力しか扱えず<br/>外部システムと直接やり取りすることはできない<br>=ファイル参照手段を持たない

  • コーディングアシスタントは，リクエストにツール利用指示(ReadFile)を付加
  • Claude 系モデル（Opus / Sonnet / Haiku）は，ツールの役割の充実という強みがある
  • 新しいツールを容易に追加できるという意味で，拡張可能性もある

Coding Assistant：ツール経由でファイルを読む

sequenceDiagram
    participant U as User
    participant CA as Coding Assistant
    participant L as LLM

    U->>CA: what's written in main.go?
    CA->>L: what's written in main.go?<br/>If you want to read a file,<br/>respond with "ReadFile: name"
    L-->>CA: ReadFile: main.go
    Note over CA: read main.go
    CA->>L: <Contents of main.go>
    L-->>CA: ファイル内容に基づく回答
    CA-->>U: 回答を表示

標準ワークフローと活用

  • コーディングエージェント概論

  • 標準ワークフローと活用

  • プロンプトエンジニアリング基礎

  • Context Management

  • Pricing

Explore → Plan → Code → Commit Workflow

いきなり実装ではなく，Plan Modeで設計を固めてから実装・レビューに進める4段の標準フロー

  • いきなり実装依頼に進むと後工程の軌道修正コストが大きくなる：先に Explore / Plan で固める
  • Plan の段階で確定した方針が，Code 以降のClaudeの判断軸として効き続ける
record1:
  category: Explore
  rule:
    - 関連ファイル・依存関係を<span class="regmonkey-bold">読み取り専用</span>で網羅させる
  actions:
    - 「実装場所・依存追加要否・アプローチ」をまとめて指示
    - 計画前提でなくてもexploreサブエージェント単体で起動可

record2:
  category: Plan
  rule:
    - <span class="regmonkey-bold">コードを書く前</span>に方針をレビュー・修正する
    - <code>Shift</code> + <code>Enter</code>でPlanモードに切り替え
  actions:
    - 提案された計画を読み，妥当性を確認
    - 不足箇所は「ここを直して」と指摘して再提案させる
    - approve / 個別修正 / 質問 を選んで進行を制御

record3:
  category: Code
  rule:
    - <span class="regmonkey-bold">「正しい」の定義</span>を渡し，検証可能な状態を保つ
  actions:
    - 成功条件を明示：何をもって完了とするか定義
    - 信頼できるテストスイートを継続検証の拠り所に

record4:
  category: Commit
  rule:
    - <span class="regmonkey-bold">第三者視点</span>で差分を確認してからpushする
  actions:
    - <code>code-reviewer</code> サブエージェントに新コンテキストでレビュー
    - スタイルを指定してClaudeにcommit messageを生成

コーディングエージェントを使いこなすには？

仕様書駆動（Spec-Driven）でエージェントのコンテキストを整える

  • エージェントはコンテキストの質で精度が決まる ⇔ 曖昧な指示は動的生成を暴走させる
  • コードではなく仕様書を「正」として扱い，仕様 → 実装の方向性を固定することでズレを抑える
  • 小さく切った仕様に沿わせることで自律ループの予測可能性が高まる

📋 仕様書を先に書く

  • REQUIREMENTS → DESIGN → TASKS1 の順で書く
  • コードより仕様書を「正」として扱う
  • 実装詳細ではなく意図と制約を明文化

🤖 仕様書をコンテキストとして渡す

  • 会話のたびに仕様書を参照させる(CLAUD.mdで制御)
  • エージェントの外部記憶として機能させる
  • セッション間での一貫性を担保

🔄 変更は仕様書から

  • 要件変更があれば仕様書を先に更新
  • コードへの直接パッチは仕様との乖離を生む
  • 仕様 ↔︎ 実装の整合性を維持

📏 タスクを細かく切る

  • 小さなタスク = 高い予測可能性
  • エージェントが迷わず実装できる粒度に分解
  • 検証・修正ループを短く保つ

プロンプトエンジニアリング基礎

  • コーディングエージェント概論

  • 標準ワークフローと活用

  • プロンプトエンジニアリング基礎

  • Context Management

  • Pricing

プロンプトとはAIへの効果的な指示設計

人間への指示と同じ原則にAI固有の留意点を組み合わせる

  • プロンプトエンジニアリング = AIから望ましい応答を引き出すための指示文を設計する実践
  • 出力の質は プロンプトの具体性・構造・前提情報の与え方 に強く依存する
  • 人間への依頼と通じる原則(背景・例・制約)に，AI固有の考慮(役割設定・思考時間・反復改善)を重ねる

AI Fluency 4D Framework における位置づけ1

  • プロンプティングは Description（AIとの効果的な意思疎通） に該当する技能
  • Delegation で何を任せるか決め，Description で伝え方を設計し，Discernment で出力を評価する
  • 一連のサイクルで初めてAIを使いこなせる ⇔ プロンプト単独では完結しない

人間への依頼との共通点と相違点を理解する

文脈・例示・制約は共通．役割設定・思考時間はAI固有の考慮

人間への依頼と共通する原則

  • 背景・目的の説明：何のために何が欲しいかを冒頭で示す
  • 望ましい出力の例示：完成イメージのサンプルを添える
  • 要件・制約の明文化：フォーマット・分量・口調を指定する
  • 複雑な依頼の分解：手順や中間成果物を順序づけて渡す

AI固有の考慮事項

  • 役割・トーンの定義：「あなたは〜の専門家」と立場を与える
  • 推論時間の確保：結論前に思考過程を書かせる(Think step-by-step)
  • 反復改善が前提：初稿を見て指示を調整する協働プロセス
  • AI自身に改善依頼：プロンプトの不足点をAIに指摘させる

6つの基本テクで指示の質を上げる

文脈・例示・制約・分解・思考・役割を組み合わせて使う

record1:
  category: Give context
  rule:
    - 何を・なぜ・どんな背景でかを<span class="regmonkey-bold">冒頭で明示</span>する
  actions:
    - 目的・前提・対象データ・成功条件を最初に書く
    - 関連ファイル・既知の制約・想定読者を添える

record2:
  category: Show examples
  rule:
    - 望ましい出力の<span class="regmonkey-bold">形を具体例で見せる</span>
  actions:
    - Few-shot examples（入出力ペアを2〜3組）
    - 完成サンプル・参考フォーマットを添付

record3:
  category: Specify constraints
  rule:
    - フォーマット・長さ・口調を<span class="regmonkey-bold">数値や形式で固定</span>する
  actions:
    - JSON形式・箇条書き・xx語以内など出力形式を指定
    - 含めるもの・含めないものを明記

record4:
  category: Break complex tasks into steps
  rule:
    - 複雑な依頼を<span class="regmonkey-bold">段階的なサブタスクに分ける</span>
  actions:
    - Step 1・Step 2 ... と順序を明示
    - 中間成果物の確認ポイントを置く

record5:
  category: Ask the AI to think first
  rule:
    - 結論前に<span class="regmonkey-bold">推論プロセスを書かせる</span>余地を与える
  actions:
    - 「Think step-by-step」「まず計画を立ててから」と指示
    - チェーン・オブ・ソートで途中経過を出させる

record6:
  category: Define the AI's role
  rule:
    - AIの<span class="regmonkey-bold">立場・専門性・トーン</span>を定義する
  actions:
    - 「あなたは〜の専門家として回答してください」
    - 想定読者に合わせた説明の粒度を指定

Context Management

  • コーディングエージェント概論

  • 標準ワークフローと活用

  • プロンプトエンジニアリング基礎

  • Context Management

  • Pricing

Context Windowは入出力が共有する作業メモリ

エージェントの「作業メモリ」として，あらゆる入出力が同じ有限リソースを共有する

  • Context Window = エージェントが 一度の会話で参照できるトークンの上限
  • ユーザー入力・ツール結果・読込ファイル・MCPツール定義が同じリソースを共有する
  • 容量に限りがあるため，何を入れ・何を残すかを能動的に設計する必要がある

Context Windowを消費する代表的な要素

  • ユーザープロンプト・アシスタント応答
  • Read / Bash / Grep などツール実行結果
  • システムプロンプト・組み込みツール定義
  • MCPサーバーが提供するツール一覧
  • Skill / Subagent の読み込み内容
  • 自動Compactionバッファ領域

上限到達時は自動Compactionで要約圧縮される

会話は途切れず継続できるが，要約により細部の情報が落ちるリスクがある

Compactionの仕組み

  • 上限に近づくと Claude Code は 重要情報を要約し，古いツール結果を捨てる
  • 圧縮後の要約が新しい文脈として保持され，会話を中断せずに作業を継続できる
  • 画面上には Compacting conversation... と表示され，要約結果が直後に展開される

詳細喪失のリスク

  • 要約は 固有値・コードの細部・微妙なやり取りを取りこぼすことがある
  • 重要な仕様・前提条件は Compaction前に CLAUDE.md やファイルへ書き出すべき
  • 自動任せにせず，区切りで /compact か /clear を能動的に呼ぶ方が安全

3つのスラッシュコマンドで容量を能動管理

/context で現状把握 → 状況に応じて /compact か /clear を使い分ける

record1:
  category: /context
  rule:
    - 現在のコンテキスト使用量を<span class="regmonkey-bold">カテゴリ別に可視化</span>する
  actions:
    - System prompt / Tools / Messages / Free space の内訳をバーで確認
    - どのカテゴリが圧迫しているかを特定し，対策の起点にする

record2:
  category: /compact
  rule:
    - その時点までの会話を<span class="regmonkey-bold">手動で要約・圧縮</span>する
  actions:
    - 同一feature内で作業を続けたい時に空き容量を確保
    - 自動Compactionより制御性が高く，区切りを意図的に置ける

record3:
  category: /clear
  rule:
    - 会話を<span class="regmonkey-bold">完全にリセット</span>し，記憶を持ち越さない
  actions:
    - 別タスクへ切り替える時に前文脈のバイアスを断つ
    - 永続化したい知識は <code>CLAUDE.md</code> に書き出してから実行

feature継続なら/compact，切替なら/clear

作業が続くか切り替わるかでコマンドを選び，永続記憶は CLAUDE.md に逃がす

同じfeatureを継続したい

  • /compact を使う：直近の作業文脈を要約として残す
  • 同じ実装タスクの途中で容量が逼迫してきた時に有効
  • 設計判断・既読ファイル・進捗の文脈が引き継がれる
  • 自動Compactionを待たず，キリの良いタイミングで自分で発火するのが安全

別タスク・別featureへ切り替える

  • /clear を使う：過去の文脈を一切持ち越さない
  • 前タスクの想定や思い込みが新タスクに混入しない
  • セッション間で覚えていてほしい知識は CLAUDE.md に書く
    • 起動時に自動読み込みされ，毎回の再発見コストを削減
  • プロジェクト共通のコマンド・規約・アーキテクチャを集約

コンテキスト節約は具体性・MCP整理・委譲

曖昧な指示・不要なMCP・本体での雑用がコンテキストを最も食う

具体的に書く

  • 曖昧プロンプトはClaudeが探索・推論で逆に消費
  • ファイル名・関数名・成功条件を明示
  • 詳細プロンプトの方が結果として節約

MCPサーバーを管理

  • MCPは全ツール定義を起動時にロード
  • 不要なサーバーは無効化する
  • Skillsはon-demandで読み込まれ常駐しない

サブエージェントに委譲

  • 別コンテキストで実行し要約だけ親に返す
  • 「認証エンドポイントの場所」など探索系で有効
  • 親コンテキストを汚さずに調査結果を取得

Pricing

  • コーディングエージェント概論

  • 標準ワークフローと活用

  • プロンプトエンジニアリング基礎

  • Context Management

  • Pricing

Claude Code Tokenコストの目安

1 MTok = 100万トークン；Input・Cache Write・Cache Hit・Output それぞれの消費量に課金される

モデル別コストテーブル(単位はすべてMTok)

record1:
  モデル: Claude Opus 4.7
  Input: $5 
  "Cache (5m)": $6.25 
  "Cache (1h)": $10 
  "Cache Hit": $0.50 
  Output: $25 

record2:
  モデル: Claude Opus 4.6
  Input: $5 
  "Cache (5m)": $6.25 
  "Cache (1h)": $10 
  "Cache Hit": $0.50 
  Output: $25 

record3:
  モデル: Claude Opus 4.5
  Input: $5 
  "Cache (5m)": $6.25 
  "Cache (1h)": $10 
  "Cache Hit": $0.50 
  Output: $25 

record6:
  モデル: Claude Sonnet 4.6
  Input: $3 
  "Cache (5m)": $3.75 
  "Cache (1h)": $6 
  "Cache Hit": $0.30 
  Output: $15 

record7:
  モデル: Claude Sonnet 4.5
  Input: $3 
  "Cache (5m)": $3.75 
  "Cache (1h)": $6 
  "Cache Hit": $0.30 
  Output: $15 

record9:
  モデル: Claude Haiku 4.5
  Input: $1 
  "Cache (5m)": $1.25 
  "Cache (1h)": $2 
  "Cache Hit": $0.10 
  Output: $5

プロンプトキャッシュでAPI コストを約74%削減できる

Claude Sonnet 4.6：入力10万tokens・出力2,000tokensの場合；キャッシュ比率90%で合計コストが$0.330 → $0.087

キャッシュなし（全量を新規入力）

  • Input 100,000 tokens
    • $3 per MTok × 100,000 = $0.300
  • Output 2,000 tokens
    • $15 per MTok × 2,000 = $0.030

合計：$0.330 / リクエスト

キャッシュ活用（90%がキャッシュヒット）

  • Base Input 10,000 tokens（新規）
    • $3 per MTok × 10,000 = $0.030
  • Cache Hit 90,000 tokens（ヒット）
    • $0.30 per MTok × 90,000 = $0.027
  • Output 2,000 tokens
    • $15 per MTok × 2,000 = $0.030

合計：$0.087 / リクエスト（約74%削減）

Appendix

プロンプトトラブルシューティング

Claudeの返答が期待と外れた時に，原因と対処を症状別に切り分ける早見表

record1:
  category: 返答が<br>抽象的すぎる
  rule:
    - プロンプトに<span class="regmonkey-bold">具体的状況の文脈</span>が不足している
  actions:
    - 対象読者・役割・制約条件などの詳細を追加する
    - 例：「遅延メールを書いて」→「ソフト統合が2週間遅れる旨を伝える，2回目の遅延，謝意を含むプロフェッショナルなトーン」と具体化

record2:
  category: 返答が<br>長すぎる/短すぎる
  rule:
    - Claudeが<span class="regmonkey-bold">適切な長さを推測</span>するしかない状態
  actions:
    - 「2段落で要約して」「100語以内」など長さを具体的に明示する
    - 詳細解析が必要なら「長さは気にせず包括的に」と逆方向にも指定

record3:
  category: 指定フォーマットに<br>従わない
  rule:
    - 「何を」は理解したが「<span class="regmonkey-bold">どう提示するか</span>」が伝わっていない
  actions:
    - フォーマット例を直接見せるか，構造を明示する
    - 例：「各セクションに太字見出しを付けた箇条書きで書いて」

record4:
  category: 自信ありげに<br>誤情報を出す
  rule:
    - 専門領域や具体事実で<span class="regmonkey-bold">もっともらしい誤答</span>を生成しうる
  actions:
    - 重要用途では重要事実を独立に検証する
    - <code>出典提示</code>や<code>確信度表示</code>を要求する
    - Web検索を有効化して最新情報に基づかせる

record5:
  category: トーンが<br>合わない
  rule:
    - デフォルトの<span class="regmonkey-bold">親切でプロフェッショナル</span>な口調が目的と合わない
  actions:
    - 「もっと会話的に」「権威的でフォーマルに」と自然言語でトーンを説明
    - 望む文体の例を与える

AI Fluencyの4D Framework1

Delegation・Description・Discernment・Diligence の4つでAI協働の能力を分解する

regmonkey_abstract_summary:
  title_fontsize: 1.3em
  bullet_fontsize: 0.95em
  children:
    - title: Delegation
      description:
        - 何を人，何をAI，どう分担するかを<strong>戦略的に決める</strong>
        - 自分のゴール・AIの能力・タスクの性質を踏まえて配分
        - 例：下書き・要約はAI，最終レビューと意思決定は人で切り分ける
      width: [25, 75]
    - title: Description
      description:
        - AIシステムと<strong>効果的に意思疎通</strong>する技能
        - 出力の定義・プロセスの誘導・望ましい挙動の指定
        - 例：制約条件・フォーマット・トーンを明示して精度を高める
      width: [25, 75]
    - title: Discernment
      description:
        - AIの出力・プロセス・挙動を<strong>批判的に評価</strong>する
        - 品質・正確性・適切性を見極め，改善点を特定
        - 例：ハルシネーションや論理破綻を検知して修正する
      width: [25, 75]
    - title: Diligence
      description:
        - AIを<strong>責任を持って倫理的に使う</strong>
        - 透明性・説明責任・人による最終確認を維持
        - 例：機密情報・著作権・バイアスへの配慮を行う
      width: [25, 75]

REQUIREMENTS → DESIGN → TASKS

  • コードを書く前に機械が読める以下の仕様書を作ることで，仕様書をエージェントの「外部記憶」として機能させる
  • 一義的には，人間のためのドキュメントではなく，エージェントのためのコンテキストとして設計
  • 変更が起きたらコードより仕様書を先に更新すること

WHATの明確化

# REQUIREMENTS.md

## ゴール

CSV をアップロードし
グラフを生成・DLできるアプリ

## 機能要件

- [ ] ドラッグ&ドロップでCSV読込
- [ ] X/Y 軸を選択できる
- [ ] 折れ線・棒・散布図に対応
- [ ] PNG/SVG でダウンロード

## 非機能要件

- 1,000行以下は 300ms 以内
- サーバーレス（フロントのみ）

## 制約

- 外部APIへのデータ送信禁止

## 完了の定義（DoD）

- 全要件の [ ] が ✅ になること

HOWの明確化

# DESIGN.md

## アーキテクチャ

単一HTML + Vanilla JS + d3.js

## コンポーネント構成

┌────────────────────┐
│ DropZone     │ CSV受け取り
├────────────────────┤
│ AxisSelector │ 列選択UI
├────────────────────┤
│ ChartRenderer│ d3で描画
├────────────────────┤
│ ExportButton │ PNG/SVG出力
└────────────────────┘

## データフロー

CSV → Papa.parse → rawData[]
→ { xCol, yCol, chartType }
→ d3.select('#chart') → SVG

TODOの明確化

# TASKS.md

## Phase 1: 基盤構築

- [x] index.html 骨格作成
- [x] d3.js CDN 動作確認
- [ ] CSS Grid レイアウト

## Phase 2: CSV処理

- [ ] DropZone 実装
  - [ ] drag/drop イベント
  - [ ] File API 読み込み
  - [ ] Papa.parse で変換
- [ ] 数値列の自動検出

## Phase 3: 可視化

- [ ] 折れ線グラフ（d3.line）
- [ ] 棒グラフ（d3.scaleBand）
- [ ] 散布図（d3.scaleLinear）