まくろぐ
更新: / 作成:

Claude Code のノウハウが溜まってきたので様々なノウハウをメモしていきます。 Agent といかに共同作業するかのコツのようなものです。

Claude Code を使い始めてすぐの頃は、「指示を出す → 動作が終わるまで見守る → 新しい指示を出す」という感じで使っていました。 ただ、このやり方だと「自分が」ツールを使っている感覚に近く、自分の時間は拘束されたままです。 Agent にもっとうまく働いてもらうには、人に仕事を委託している感覚 で使うのがよいことに気づきました。 下記のような使い方を知っていると、単なる壁打ちから脱却した一歩進んだ使い方 ができます。

  • 作業中に割り込んで、方向性を修正する(ESC 割り込み)
  • 先に詳細なプランを立ててもらう (Shift + TAB で Plan mode へ)
  • 作業が終わったら知らせてもらう(hooks)
  • Agent と並行して別の作業をする(git worktree など)

作業中に割り込む (ESC)

/p/qj9wydo/img-matta.png

この ESC キーによる「待った」 機能は超重要です。 Claude Code にある程度複雑な作業を任せると、作業中に「やっぱりこうしてほしい」ということが出てきます。 例えば、下記はビルド構成の最適化をしてもらっているところですが、Claude が想定外のファイルまで解析しようとしていることに気づいたとします。 そんなときは、ESC キーを押して作業に割り込み、そのファイルは対象外だと教えてあげます。

/p/qj9wydo/img-interrupt-1.png
図: ESC で割り込み指示

そうすると、新しく指示した方針に従って作業を続けてくれます。 上記のように Claude が考えている最中に割り込むだけでなく、Claude から追加の情報を求められたとき(ユーザーからの入力待ちのとき)にも割り込むことができます。 間違った方向に進んでいることに気づいたら、すぐに ESC キーで割り込むことで、トークンも時間も無駄にしなくて済みます。

先に詳細なプランを立ててもらう (Plan mode)

仕事で部下や協力会社の人へ複雑な作業をお願いする場合は、いきなり作業を始めるのではなく、まずは「作業プラン」を立ててもらって確認すると思います。 同様に、Claude Code にも最初に詳細なプランを立ててもらい、それを確認してから作業を始めてもらうと後戻りが少なくなります。 Claude Code はデフォルトではいきなり作業を始めてしまうので、Shift + TAB キーを 2 回押して Plan mode に切り替えます。

/p/qj9wydo/img-plan-mode-1.png
図: plan mode へ切り替え

上記のように、入力エリアの下に plan mode on と表示されていることを確認してください。 この状態で、やってもらいたいことを指示すると、最初に詳細なプランを立ててくれます。

/p/qj9wydo/img-plan-mode-2.png
図: 詳細なプランを立ててもらう

提示されたプランでよければ、そのまま作業を開始してもらえば OK です。 少し修正してほしいところがあれば、先ほど説明したように ESC キーで割り込んで修正指示を出します。 ここでは、難しいオプション機能は必要ないことを伝えてみます。

/p/qj9wydo/img-plan-mode-3.png
図: プランの修正指示

そうすると、次のような感じで修正されたプランを提示してくれます。

/p/qj9wydo/img-plan-mode-4.png
図: 修正された実装プラン

プランを立てずにいきなりコードを作成してもらうというやり方もありますが、複雑な作業の場合は、できあがったコードをレビューするより実装プランをレビューする方がずっと楽です。 全体のプランに納得できたら、安心して作業を任せることができます。

作業が終わったら知らせてもらう (hooks)

時間のかかりそうな作業を Claude Code(Agent)に依頼した後は、自分は別の作業をしていたいですよね。 例えば、それは物理的な机の上での作業かもしれません。 そうなると、Agent の作業が終わったタイミングで知らせてもらう手段が必要です。

幸いなことに Claude Code には hooks という仕組みがあり、Agent が入力待ちになったときや、作業が完了したタイミングで、任意のコマンドを実行できるようになっています。 ここでは、次のように通知してもらうように設定します。

  • Agent が入力待ちになったときに「Waiting」と音声で知らせる。できれば OS の通知も出す。
  • Agent の作業が完了したときに「Completed」と音声で知らせる。できれば OS の通知も出す。

OS ごとにコマンドを書き分けるのは面倒なので、めもらばさんccnoti というツールを使わせてもらいました。 Node がインストールされている環境であれば、npx コマンドだけで実行できます(npm install -g ccnoti でグローバルインストールしてもよいです)。 Claude Code の設定ファイル (~/.claude/settings.json) で下記のように設定します。

~/.claude/settings.json
{
  // ...
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx ccnoti@0.2.0 -v -d -m Waiting"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx ccnoti@0.2.0 -v -d -m Completed"
          }
        ]
      }
    ]
  }
}

これで、Agent の作業が完了したときに通知してもらえるようになります。 ちょうど、同僚から「作業が終わったよ」と声をかけてもらうような感覚です。

Agent と並行して別の作業をする

Agent へうまく作業を任せられるようになると、自分は別の作業をしたくなります。 あるいは、複数の Agent を並行して動かしたくなるかもしれません。 同じコードベースに対して異なる作業を並行して行う場合、作業内容が競合しないようにする必要があります。 そのためのツールの使い方を学びましょう。

例えば、その作業が Git リポジトリに関するものであれば、git worktree コマンドを使うと便利です。 通常 Git ではチェックアウト可能なブランチは 1 つだけですが、git worktree を使うと、別のブランチを別の作業ディレクトリにチェックアウトして作業できます。

feature1 ブランチ用の作業ディレクトリを作る
# プロジェクトのディレクトリへ移動
$ cd myproject

# feature1 ブランチとそれ専用の作業ディレクトリを作成
$ git worktree add ../myproject-feature1 -b feature1

その他

下記は、Agent ツールの進化によって変わっていくかもしれないので簡潔に記載しておきますが、いずれも現時点では有効な方法です。

LLM が苦手な定型作業は MCP 化しておく

例えば、「ランダムな ID を生成する」みたいな依頼をすると、Claude Code は毎回シェルスクリプトや Python スクリプトを作ろうとします。 これはトークンを無駄に消費するし、余計なコード確認の手間も増えます。 同様の処理を頻繁に行う場合は、独自の MCP サーバーを作ってツールとして提供 してしまうのがよいです。 Python の fastmcp ライブラリを使えば、関数を定義するくらいの感覚で MCP サーバーを簡単に作れます。

main.py
#!/usr/bin/env python3
"""
MCP Maku Tools - A Model Context Protocol server with useful tools
"""

import random

from fastmcp import FastMCP


def create_server() -> FastMCP:
    """MCPサーバーを生成します"""
    server = FastMCP("mcp-maku-tools")

    @server.tool()
    def generate_random_id(length: int = 7) -> str:
        """指定された文字数のランダムID生成ツールです

        Args:
            length: 生成するIDの長さ(デフォルト: 7)

        Returns:
            生成されたランダムID
        """
        chars = "23456789abcdefghijkmnopqrstuvwxyz"
        return "".join(random.choice(chars) for _ in range(length))

    return server


if __name__ == "__main__":
    # MCPサーバーを起動
    mcp = create_server()
    mcp.run(transport="stdio")
~/.claude.json
{
  // ...
  "mcpServers": {
    "mcp-maku-tools": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/maku/gitwork/maku77/mcp-maku-tools",
        "main.py"
      ],
      "env": {}
    }
  },
  // ...
}

自分用の MCP サーバーを 1 つ作ってしまえば、あとはそこに関数を追加していくだけで Claude Code から使えるツールが増えていきます。 MCP サーバー自体をたくさん作る必要はありません。

複数の解決方法を提案してもらう

Agent は一つの解決方法しか提示しないことが多く、それをそのまま受け入れてしまいがちです。 もしかすると他にもっとよい方法があるかもしれません。 例えば、ある問題を解決するためのコードを作成してもらうときに、次のような感じで 複数のアプローチを提示してもらうように指示 することを試してみてください。

複数の解決方法を提案してください。

テストにパスするまで修正を繰り返してとお願いする

Agent がコードを一発で完璧に書けることは稀です。 例えば、テストコードも一緒に作成してもらい、テストにパスするまで 修正を繰り返してもらうように指示 します。

テストコードも一緒に作成し、テストにパスするまで修正を繰り返してください。

簡単なテストに関しては、多くの場合は成功するまで修正を繰り返してくれるようになりましたが、途中で諦めてしまうような作業があったら、明示的に繰り返し修正するようにお願いするとよいです。

think harder で深く考えてもらう

Claude Code の隠しコマンド(正確には Sonnet モデルの機能)に think hardthink harder というのがあります。 プロンプト内にこれらの文字列を含めておくと、より深く考えてもらえるようになるので、ここぞというときに使うとよいです。 カスタムスラッシュコマンドでも使うことができます(例: /maku:analyze-project think harder)。

汎用的なカスタムスラッシュコマンドは GitHub で管理する

ユーザーディレクトリ以下に配置した汎用的なカスタムスラッシュコマンド (~/.claude/commands/*.md) も、GitHub リポジトリで管理 するようにしましょう。 PC 故障などで紛失するのを防げますし、複数の PC やユーザー間で共有したい場合にも便利です。 下記ページでは、Windows のジャンクション機能や、macOS/Linux のシンボリックリンクを使って、Git リポジトリや Dropbox と連携する方法を紹介しています。

(2025-08) Claude Code の新しい仕組みとして、~/.claude/plugins/ ディレクトリを使って、GitHub リポジトリと自動連携する仕組みが検討されているようです。

関連記事

まくろぐ
サイトマップまくへのメッセージ