「ClaudeCode」はコード補完じゃなくて、ターミナル常駐の相棒だった話

hirokaji

2025年11月29日 15:26

ある日、いつものようにターミナルの前で「うーん」と唸っていました。

既存サービスに小さな機能を足したい
でも型エラーが雪崩のように出ている
ついでにテストもだいぶ怪しい

「このレガシー周りを、ちゃんと整理しないとダメだよなあ」と思いながらも、一つ一つファイルを開いて、検索して、影響範囲を洗い出して…を手作業でやる気力が、正直あまり残っていませんでした。

そのとき、頭の片隅にずっと置きっぱなしにしていた名前が浮かびました。

「そういえば、ClaudeCode ってやつがあったな」

ちょうど Xでも「CLI からまるっと開発補助してくれるらしい」という話題を何度か見かけていて、「そのうちちゃんと触ろう」とブックマークだけして放置していたツールです。

「どうせ今日もそんなに進まないし、一回ちゃんと試してみるか」と思って入れてみたのが、私にとってのスタートでした。

少し前までの私は、わりと本気でこう思っていました。

「AIエディタに、仕事の大半を任せる未来なんて、そう簡単には来ないだろう」

ところが、実際に ClaudeCode を触ってみて、
何度か「助かった…」という場面を経験していくうちに、

型エラーの調査
影響範囲の洗い出し
テストの追加
README のたたき台作り

みたいな「地味だけど時間のかかる仕事」を、かなりの割合で任せるようになってきました。

ターミナルで claude と打つだけで、

プロジェクト全体を読み込み、
必要なファイルを探し出し、
コードを書き、
テストを回し、
バグを見つけて、修正案まで出してくれる

ここまで来ると、もはや「賢い補完」ではなくターミナルに常駐している、気の利く後輩エンジニアくらいの存在感があります。

この記事では、私なりの視点で ClaudeCode を

ざっくり何者として捉えているか
どんな“道具”があって、どう使い分けているか
どこまで任せて、どこからは人間が握るべきか

をまとめてみます。

※この記事は、私が実際に試してみた範囲での整理です。
環境やバージョンによって細部は変わる可能性があります。

1. ClaudeCodeって結局なにものか

ClaudeCode は、Anthropic 社が提供している 公式の CLI ツール です。

使い方はとてもシンプルで、Node.js が入っている環境なら、まずは：

npm install -g @anthropic-ai/claude-code

インストール後、プロジェクトルートでこう打てば起動します。

cd my-project
claude "このプロジェクトの概要を教えて"

すると内部では、

ファイルを読む
ファイルを編集する
コードベースを検索する
シェルコマンドを実行する
Web上のドキュメントを読む
サブエージェントを起動する

といった 十数種類のツール が、状況に応じて自動的に組み合わされます。

人間側は、「いま cat すべきか grep すべきか」といったレベルの判断をしなくても、

「このエラーの原因を探して、必要ならテストも追加して」

のように、タスク寄りの指示ができます。
ここが、いわゆる「コード補完ツール」との大きな違いだと感じています。

2. まず押さえたい“道具箱”の中身

全部を暗記する必要はありません。
私自身も、最初は 「よく使うものだけ押さえる」 ところから始めました。

2-1. ファイルを見る・書く・直す

Read：まずはここから

役割：ファイルの中身を見る
特徴：テキストだけでなく PDF やノートブックなども読める
便利ポイント：行番号や範囲指定で「このあたりだけ見て」と頼める

私は、cat 代わりにほぼ Read 一択になりました。

claude "src/index.ts の 50 行目から 80 行目までを読んで、ざっくり説明して"

Write：新規ファイル・全置き換え用

役割：新規ファイル作成、既存ファイルの全書き換え
注意：部分修正には使わない方が安全（全部上書きされる）

たとえば、「この構成で README のたたき台を作って」と頼むときなど、
“ゼロから生成” のときに限定して使うイメージです。

Edit：部分修正の主力

役割：既存ファイルの一部だけを置き換える
条件：置換対象テキストが 空白やインデントを含めて完全一致 している必要がある

なので、自分ルールとしては

「必ず Read で現物を確認 → Edit で置き換え」

という 2 ステップにしています。

2-2. コードベースを“歩き回る”道具

Glob：どこに何のファイルがあるか

役割：*.ts, src/**/**.tsx などのパターンでファイルを探す
用途：大規模リポジトリで「対象範囲を絞る」最初の一手

例：

claude "src ディレクトリ以下の TypeScript ファイル一覧を出して、役割ごとにざっくりグループ分けして"

Grep：中身の検索担当

役割：TODO, FIXME, 特定の関数名などを高速検索
オプション：行番号付き、前後何行表示、などが指定できる

私がよくやるのは、この流れです。

claude "プロジェクト全体から TODO を含む行を検索して、重要そうな順に整理して"

このとき、内部では Glob + Grep + Read がいい感じに組み合わさって動いているイメージです。

2-3. Bash や Web とのつきあい方

Bash：ビルドやテストを任せる

役割：git, npm, docker, pytest などのコマンド実行
コツ：中身を読むための cat や grep は Bash 経由ではなく Read / Grep に任せる

私の感覚では、

環境操作系（ビルド・テスト・lint） → Bash
中身を見る・探す系 → 専用ツールに寄せる

という分担にしておくと、トラブルが減ります。

WebFetch / WebSearch：ドキュメント読み係

WebFetch：指定 URL のコンテンツを Markdown に整形して読み込む
WebSearch：検索エンジン的に調べる（地域によって制限あり）

例えば、Next.js の公式ドキュメントを読み込んで要約させるときは、

claude "この URL を読んで、このプロジェクトに関係する部分だけを抜き出して要約して:
https://nextjs.org/docs/app/building-your-application/routing"

のように、URL を素直に渡してしまう方が楽です。

3. 4つの“役割”を持つエージェントたち

ClaudeCode のおもしろいところは、
「モデルが1体いて、全部それに投げる」わけではない点です。

私は、ざっくり次の4つの役割で整理しています。

3-1. General-Purpose：本番実装担当

高性能モデル（Sonnet 系）を前提とした“何でも屋”
実装・修正・テストなど、重めのタスクはここに投げる
何も指定しないと基本これが動く

「このサービスのエンドポイントを追加して、テストも書いて」といった
“実際に手を動かす系” は、ここに任せるイメージです。

3-2. Explore：調査専門アシスタント

軽量モデル（Haiku 系）で、読み取り中心
コードベースの探索や検索に特化
呼び出しはメンションで：

claude "@explore このエラーの原因になりそうなファイルと箇所を洗い出して"

「とりあえず状況を把握したいだけ」のときに General を呼ぶのは、
軽い質問で CTO を会議室に呼ぶようなものなので（笑）、
私はまず Explore を使うようにしています。

3-3. Plan：いきなり工事しないための設計担当

実装はせず「計画だけ」を立てる役割
起動方法は：

claude --plan "この認証周りのコードを整理する計画を立てて"

大きめのリファクタリングやアーキテクチャ変更は、

Plan で計画 → 人間がレビュー → 実装

という流れにしてから、手戻りが一気に減りました。

3-4. Claude-Code-Guide：使い方のガイド係

ClaudeCode 自体の機能や設定について質問する専用の役割
呼び出し例：

claude "@claude-code-guide Plan モードのオプション一覧を教えて"

「フックってどこに設定するんだっけ？」みたいな話は、
General に聞くより Guide に聞いた方が安くて正確です。

4. コストを溶かさないための“マイルール”

経験から、次のルールだけ守るようにしたら、だいぶ楽になりました。

調査・検索 → Explore
計画立案（大きめのタスク） → Plan
実装・修正 → General-Purpose
使い方・設定 → Claude-Code-Guide

これを守るだけで、

「とりあえず全部 General に投げていた頃」と比べて、
モデルコストも待ち時間も、体感でかなり変わります。

5. スラッシュコマンドで「よくやる作業」を一発にする

ここからは、私が「これがあると一気にラクになる」と感じた機能の話です。それが カスタムスラッシュコマンド です。

5-1. 仕組みのイメージ

/security-review のように、自分専用のコマンドを定義できる
実体は .claude/commands/（プロジェクト単位）か
~/.claude/commands/（ユーザー共通）に置く Markdown ファイル
ファイルの先頭に YAML、後ろにプロンプト本文を書く

たとえば、軽めのセキュリティチェック用コマンドは、こんなイメージです。

---
description: 指定ファイルのセキュリティざっくりレビュー
allowed-tools:
  - Read
  - Grep
argument-hint: "[ファイルパス]"
---

セキュリティ簡易レビュー

対象ファイル: $ARGUMENTS

次の観点で気になる点を洗い出してください。

- 認証・認可
- 入力値のバリデーション
- 外部サービスとのやりとり
- ログ出力に機密情報が含まれていないか

それぞれについて、

- 気になった箇所
- なぜ問題になりうるか
- 具体的な修正案（コード例があればなお良い）

を整理してください。

ここまで書いておくと、あとはターミナルから：

claude "/security-review src/api/auth.ts"

と打つだけで、毎回同じ観点でレビューが走ります。

5-2. 差分解説コマンドのサンプル

「PR の説明文を書く前に、変更の全体像を整理してほしい」というときは、こんなコマンドを用意しておくと便利です。

---
description: 現在の Git 差分を要約してもらう
allowed-tools:
  - Bash(git status:*)
  - Bash(git diff:*)
---

Git差分の要約

1. 次のコマンドを実行して、結果を埋め込んでください。
   - `git status`
   - `git diff HEAD`

2. 結果をもとに、以下を日本語で整理してください。
   - どのファイルが変更されたか
   - 主な変更内容
   - 影響がありそうな機能やモジュール
   - レビュー時に特に注意して見てほしいポイント

使い方はシンプルで：

claude "/explain-diff"

と打つだけです。これをベースに、PR の本文を少し手直しする、という流れがかなり楽になりました。

6. フックで「やってはいけない操作」を自動ブロックする

もうひとつ、私が重宝しているのが フック です。

ツール実行前後
セッション開始・終了
プロンプト送信時

などのタイミングで、スクリプトを自動実行できます。

6-1. .env を守るための PreToolUse フック（イメージ）

たとえば「.env や本番設定ファイルは絶対に編集させたくない」という場合。
~/.claude/settings.json に、ざっくりこんなイメージで書きます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/deny_env_edit.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

deny_env_edit.sh 側も、概念としてはこんな感じです（実装は環境に合わせて調整）。

#!/usr/bin/env bash
# 標準入力にツールの入力情報（JSON）が渡ってくる想定

read -r json_input

# jq などでパスを取り出す（実際のスキーマは公式ドキュメントを要確認）
file_path=$(echo "$json_input" | jq -r '.toolInput.path // empty')

if [[ "$file_path" == *".env"* ]]; then
  echo "セキュリティポリシー: .env ファイルの編集は禁止です" >&2
  exit 2  # 非0でツール実行をブロック
fi

exit 0

これを入れてからは、「うっかり .env を書き換えてしまう」系の事故を、かなり防げています。

7. 実務で使ってみたミニケース

ここからは、私が実際の作業の中で「これは ClaudeCode に助けられたな」と感じた場面を、雰囲気が伝わる範囲で 2 つほど挙げてみます。

7-1. ミニケース1：バリデーション地獄からの脱出

あるフォーム画面で、バリデーションまわりがだいぶ混沌としていました。

画面側でのチェック
カスタムフック内でのチェック
API サーバー側でのチェック

がバラバラに書かれていて、「どこで何を担保しているのか」が、もはや自分でも追いきれない状態でした。

ここでやったのは、次のような流れです。

1.Explore に現状把握を丸投げ

claude "@explore ユーザー登録周りでバリデーションしている箇所を全部洗い出して、『何を』『どこで』チェックしているか一覧にして"

2.出てきた一覧を見ながら、Plan で整理方針を相談

claude --plan "このバリデーションを『フロント共通』『サーバー共通』『画面固有』くらいに整理したい。移行ステップを提案して"

3.計画の中から「ここまでは今日やる」と決めて、General に実装を依頼

claude "Plan で出してくれたステップ1と2だけ実装して。 
差分が分かるように、変更したファイルと内容を最後にまとめて"

4.最後に /explain-diff で変更の全体像を再確認

結果として、「どこを触れば何が壊れるか」がだいぶ見通しやすくなり、
自分一人でやるよりも、だいぶ短い時間で“整理された状態”に持っていけた感覚がありました。

7-2. ミニケース2：README をサボらないための仕組み化

もうひとつは、個人でちょっとしたツールを作ったときの話です。

小さなプロジェクトだと、つい README を後回しにして、そのまま書かれないまま…ということがよくあります。
そこで、最初から「README を自動でたたき台生成する」前提で進めてみました。

やったことはシンプルで、

1.開発の最初期に /generate-readme 的なコマンドを用意しておく
2.プロジェクト構造がある程度固まったタイミングで一度実行する

claude "/generate-readme web-tool"

3.出てきた README（セットアップ手順・使い方・技術スタックなど）を、自分の言葉に整える

というだけです。

「ゼロから書く」と「たたき台を直す」の間には、かなり大きな心理的ハードルの差があるので、
このパターンにしてからは README 周りの後悔がだいぶ減りました。

8. 典型的なワークフロー 3 本

ここまでの話を、「実際にどう使うか」という流れでまとめてみます。

8-1. 型エラーを一気に潰すワークフロー

1.Bash でビルド／テスト実行を依頼

claude "Bash で型チェックを実行して、エラーの一覧を出して。使っているコマンドも教えて"

2.Explore に原因箇所を洗い出してもらう

claude "@explore さっき出た型エラーのうち、影響範囲が広そうなものを上位3つ教えて"

3.General に修正とテスト追加を依頼

claude "影響範囲が広そうなエラーから順に直して、必要ならテストも追加して。変更内容は要約して"

4.最後に /generate-test のようなコマンドでテストを補強

8-2. レガシーコードの段階的リファクタリング

1.まず Plan で計画を立てる

claude --plan "このレガシーなユーザー管理モジュールを、責務ごとに分割する計画を立てて"

2.計画を読んで、人間が「この順番ならいけそう」と判断
3.General に「計画通りに 1〜2 ステップ目だけ進めて」と依頼
4.変更内容と影響範囲を /explain-diff で整理
5.問題なければ、次のステップに進む

8-3. 新規プロジェクト立ち上げ

1.要件だけざっくり伝える

claude "React + TypeScript + Jest で、小さめの CRUD アプリを作るためのプロジェクト雛形を作って。 npm スクリプトとディレクトリ構成も提案して"

2.生成された構成を一度眺めて、気になる点を修正依頼

3../generate-readme で README のたたき台を作る/
4.CLAUDE.md に「このプロジェクトのルール」を書いておく

# このプロジェクトでのルール
- TypeScript を必須とする（.js ではなく .ts / .tsx） 
- テストは Jest + Testing Library 
- UI ライブラリは基本的に Chakra UI 
- コミットメッセージは Conventional Commits に従う

こうしておくと、ClaudeCode が今後の提案や実装で、この前提を理解して動いてくれるようになります。

9. 私自身の「失敗リスト」とそこからの学び

最後に、私が実際にやらかした失敗と、その反省から決めたルールを書いておきます。

何でもかんでも General に投げて、コストが爆増した
→ 調査は Explore、計画は Plan に分ける
Bash で cat や grep を使い続けて、権限周りでハマった
→ 中身を見る／探す系は専用ツールに寄せる
大きな改修を Plan なしでやらせて、手戻りが大量発生した
→ 「設計が要りそう」と感じたら、まず Plan に投げる
毎回ほぼ同じプロンプトを手入力していて、微妙にニュアンスがブレた
→ よくやる作業は /xxx コマンドにしてしまう
本番系設定ファイルをうっかり触らせてヒヤッとした
→ フックでガードレールを敷く

10. これから試してみるなら、この2つだけでも

もしまだ ClaudeCode を本格的には触っていないなら、
個人的には、次の 2 ステップから始めるのがおすすめです。

既存プロジェクトで claude を起動し、
@explore に「このプロジェクトの構造を案内して」と頼んでみる
手を付けたい改善タスクをひとつ選んで、
claude --plan に「計画だけ立てて」とお願いしてみる

この 2 つを経験すると、

「AIエディタは補完だけしてくれれば十分」

という感覚から、

「設計や調査も含めて、かなり任せてもよさそうだ」

というところまで、認識が一段上がるはずです。

そのうえで、

自分ならどんな /xxx コマンドを 3 つ定義したいか
どのファイルはフックで絶対に守りたいか

をメモに書き出してみると、
「ClaudeCode をどう自分の相棒に育てるか」 のイメージが、かなり具体になってきます。