Claude Code サブエージェントで開発を7倍速にする実践ガイド

タスクが順番待ちで止まる、コンテキスト切り替えで無駄が増える――そんな「逐次作業」の停滞感が痛いあなたへ。Claude Code のサブエージェントを使えば、並列に仕事を走らせて待ち時間を有効活用できる。本稿では、実際に使える設計パターン、プロンプトとテンプレート、エージェント間の責務分離、失敗時の回復戦略まで、ステップバイステップで解説します。CI、コードレビュー、テスト自動化など身近な開発タスクを例に取り、導入の手順と監視・デバッグのコツを提示。実例では7倍に近いスループット改善を達成したケースも紹介するので、今すぐ試して待ち時間を実働時間に変えてください。

そもそもどう動くのか

家のPCの前にいないと背景で回していた処理が止まってしまう、そんな「長期実行が不安」な状況をまず刺す。

サブエージェントは「目的を限定した小さなエージェント（決められた役割＋記憶）」を並列で動かし、オーケストレーターが各出力を収集してマージする仕組みだ。生成AIが単発の生成物を返すのに対し、エージェントは状態（メモリ）と役割を持って継続的にタスクを進められる。Claude Code の長期セッションはログイン期限で中断され得るので、2.1.203で追加された期限警告を活用して再認証の運用を組むのが実務パターンである。基本は「プロンプト設計／ワークスペース分離／ベクトルDBでの情報共有」。

役割を明確化する

例: summarizer（要約）、extractor（構造抽出）、qa（質問応答）。
定義例（YAML）:

- id: summarizer
  role: "ドキュメントを3文で要約"
  memory: "vectordb://project/shared"

ワークスペースを分離する

featureごとにワークスペースを作成してコンテキスト漏れを防ぐ。
例: workspace new feature-x; export CLAUDE_WS=feature-x

プロンプトテンプレを固める

各エージェントに守らせる行動ルールを先にテンプレ化する。
例: "Always cite memory-id when using past context. Max tokens: 400."

メモリはベクトルDBで共有

アップサート例（擬似API）:

vectordb.upsert(namespace="shared", id="doc-123", vector=embed(text), metadata={"source":"spec"})

細かいメタを入れて検索精度を保つ。

並列実行して短周期で同期

実行例（擬似CLI）: agent run --parallel summarizer,extractor,qa --ws feature-x
各エージェントは自分のメモリ名空間だけ書き、共有はvectorDB経由にする。

オーケストレーターで合成・矛盾解消

収集例:

orchestrator.collect --from summarizer,extractor --merge=rule_based

マージはルール優先（例: extractorの構造化データを優先）→ 人間レビューを最後に挟む。

セッション監視と再認証運用

長期セッションはログイン期限で中断するため定期チェックを入れる。2.1.203では期限警告が追加されているので、それをトリガに再認証する運用を。
例（cron擬似）:

*/59 * * * * /opt/infra/claude-auth refresh || /opt/infra/notify "Re-auth required"

まとめ：サブエージェントは「分割された役割＋共有ベクトルDB」でスケールする。まずは1つだけ（例：summarizer）をワークスペース分離して作り、ベクトルDBにアップサート→オーケストレーターで収集する流れを試してみてください。

① サブエージェントの役割をまず定義する

誰が何をやるか曖昧だとサブエージェントはゴミ出力を量産する。

そもそもどう動くのか：サブエージェントは「与えられた役割（systemプロンプト）＋入力」を受けて決まった仕事だけを返す小さなワーカーである。役割を明確にすると期待する変更範囲・出力形式・拒否ルールが固定され、チェーン化や自動化が容易になる。

役割を書き出す（誰が何をするか）

例: 開発者＝最終判断、Refactor Agent＝関数名改名とテスト修正、Doc Agent＝変更点の要約。
ファイル: roles.md に短く箇条書きで保存。

systemプロンプトのテンプレを作る（最低限の必須項目）

必須: role名、目的、拒否ルール、出力フォーマット。
まずは1ファイルで試す。例（コマンドそのまま）:

echo '{"role":"system","content":"You are a refactor agent: focus on improving function names and tests."}' > agent-refactor.json

検証: jq があればjq . agent-refactor.jsonでJSON整形確認。

出力仕様を明確にする（マシンで検証できる形に）

formatフィールドを追加: JSON schema で返すよう指示する。例:

jq '. + {format:"{\"changes\":[{\"file\":\"\",\"line\":0,\"before\":\"\",\"after\":\"\"}]"}' agent-refactor.json > tmp && mv tmp agent-refactor.json

実行ラッパーを作る（手で呼べる最小単位）

スクリプト: scripts/run_agent.sh を作り、agentファイルと task.json を渡すだけにする。例:

cat > scripts/run_agent.sh <<'SH'
#!/bin/sh
agent="$1"; task="$2"; out="$3"
# runner.py は任意のローカル実行ラッパー
python3 runner.py --agent "$agent" --task "$task" --out "$out"
SH
chmod +x scripts/run_agent.sh

タスクテンプレを用意して小さく回す

例タスク:

echo '{"task":"rename function foo->bar","files":["src/foo.py"]}' > task.json
./scripts/run_agent.sh agent-refactor.json task.json out.json

out.json が期待フォーマットかjq . out.jsonで確認。

リポジトリとの接続ルールを決める

自動コミット可否、PR作成者、タグ付け規則を roles.md に記載。
例: agents/ 配下は CI でのみ main にマージ可。ファイル配置:

mkdir -p agents && mv agent-refactor.json agents/
git add agents/ && git commit -m "add refactor agent"

監査と人の承認フローを組み込む

出力は自動で直接コミットしない。out.json を diff 用に保存し、レビューワークフローへ通知する。
ローカルでのチェック例:

git checkout -b agent-proposal
# 手動で out.json の差分を適用
git add -p
git commit -m "apply agent suggestions"

まとめ：まずは「役割（role）」「出力フォーマット」「実行ラッパー」の3点を固めるだけで、サブエージェントは使えるツールになる。まずは提示した echo コマンドで agent-refactor.json を作って、scripts/run_agent.sh を実行してみてください。

② リポジトリとワークスペースを分ける（ブランチ運用）

AIキャリア相談＆実務AI活用はこちらから無料相談AIキャリア相談＆実務AI活用は
こちらから無料相談

家のPCの前にいないとサブエージェントの作業がめちゃくちゃになる、そんな経験はないだろうか。

そもそもどう動くのか：エージェントごとに「ブランチ＋専用フォルダ」を切ると、変更点が明確になりマージ／CIのトリガーが簡単になる。ブランチで履歴を隔離し、フォルダでワークスペースを分ければ並行開発が安全だ。

7ステップ

リポジトリをクローンしてエージェント用ブランチとフォルダを作る（最初の一手）

git clone <repo>
cd <repo>
git checkout -b agent/refactor
mkdir -p agents/refactor
git add .
git commit -m "add refactor agent workspace"

命名規則を決める

ブランチ: agent/<agent-name>
フォルダ: agents/<agent-name>例: agent/payment → agents/payment。これで差分が一目瞭然。

ワークスペースのアーティファクトを除外する

echo "agents/*/.cache" >> .gitignore
echo "agents/*/state.json" >> .gitignore
git add .gitignore && git commit -m "ignore agent runtime files"

プルリクでレビューを回す

git push -u origin agent/refactor
# GitHub等で PR を作成。タイトル例: [agent/refactor] add workspace

CIをパスフィルタで最適化（例: GitHub Actions）

workflow の paths を使い、該当エージェント配下のみでジョブを走らせる。

on:
  push:
    paths:
      - 'agents/refactor/**'

ローカル運用をスクリプト化する

scripts/start-agent.sh を用意してチェックアウト→起動まで1コマンドで済ませる。

#!/bin/bash
git fetch origin
git checkout agent/refactor
cd agents/refactor || exit 1
# 例えば ./run.sh があれば実行
./run.sh || echo "run.sh not found"

マージとクリーンアップ

git checkout main
git fetch origin
git merge --no-ff agent/refactor
git push origin main
git push origin --delete agent/refactor
rm -rf agents/refactor

まとめ：ブランチ＋フォルダでエージェント単位に作業を分離すれば衝突と無駄なCI実行を減らせる。まずは一つ、上のコマンドで agent/refactor を作って実際にワークフローを回してみてください。

③ 並列セッションを立ててエージェントを並走させる

家のPCの前にいないとエージェントが止まる──そんな非効率、もうやめましょう。

そもそもどう動くのかサブエージェントは「独立したプロセス」として並列実行させるのがポイント。各プロセスが独自のメモリ・ログ・状態を持つため、1つがブロックしても他は回り続ける。注意点として、長時間のバックグラウンド実行は認証切れで中断される可能性があるため、ログイン有効期限に関する警告（Claude Code 2.1.203で導入）を見かけたら再認証しておく。

7ステップ（具体手順）

tmuxで素早く立てる例:

tmux new -d -s agent-refactor 'python agent_runner.py --agent refactor --prompt agent-refactor.json'
tmux attach -t agent-refactor

単純なバックグラウンド（nohup）ログを分けるとデバッグが楽:

nohup python agent_runner.py --agent lint > logs/lint.log 2>&1 &

systemdで永続化（プロダクション向け） /etc/systemd/system/agent-refactor.service の例:

[Unit]
Description=agent-refactor

[Service]
ExecStart=/usr/bin/python /opt/agents/agent_runner.py --agent refactor
Restart=on-failure
User=deploy

作成後: sudo systemctl daemon-reload && sudo systemctl enable --now agent-refactor

Dockerで環境分離

docker run -d --name agent-refactor -e AGENT=refactor my-agent-image

ボリュームでログを吐く / ローカル設定を渡す。

環境変数とPID管理プロセス識別用に環境変数を渡し、PIDファイルを作る:

AGENT=refactor nohup python agent_runner.py --agent refactor > logs/refactor.log 2>&1 & echo $! > run/refactor.pid

ログとローテーション簡易的に日別ログを残すか、logrotateでローテート設定を作る。logs/*.log を対象にし、ディスク肥大化を防ぐ。
監視と自動再起動（ヘルスチェック）シンプルな監視コマンド例:

pgrep -f "agent_runner.py --agent refactor" >/dev/null || tmux new -d -s agent-refactor 'python agent_runner.py --agent refactor --prompt agent-refactor.json'

systemdを使っているなら systemctl restart を利用。

まとめ各サブエージェントは独立プロセスで運用するのが安定と高速化の肝。まずはtmuxで1つ立ててログ確認→systemd化、という流れで作業を進めてください。次の一歩: まず「tmuxで1セッション」を立てて動作ログを確認してみましょう。

④ 知識共有はベクトルDBで行う（履歴・検索用）

家のPCの前じゃないと過去の設計判断やリファクタ履歴が参照できず、同じバグを何度も追いかけていないか。

そもそもどう動くのか：短期のやり取りや生ログはファイルで保存し、検索性と類似検索はベクトルDBに任せる。要点は「テキスト→分割→埋め込み→インデックス→メタデータを紐付けて検索→サブエージェントに渡す」だけ。仕組みが分かれば、既存ログをどんどん流し込める。

保存ポリシーを決める
- 短期: 作業ログは時系列ファイルに追記（例: echo "2026-07-08: リファクタ" >> work.log）
- 検索用: 定期的にファイルをバッチ処理してベクトル化する。
必要ライブラリを入れて最初の動作確認
- コマンド: pip install faiss-cpu sentence-transformers
- 簡単な導入例:

pip install faiss-cpu sentence-transformers && python - <<'PY'
from sentence_transformers import SentenceTransformer
import faiss
m=SentenceTransformer('all-MiniLM-L6-v2')
emb=m.encode(['関数Aをリファクタリングしました'])
idx=faiss.IndexFlatL2(emb.shape[1])
idx.add(emb)
print('indexed')
PY

テキストのチャンク化
- 手順: 長文は一定サイズで切る（例: 512文字ごと）
- サンプルPython:

def chunk(text, size=512):
    return [text[i:i+size] for i in range(0, len(text), size)]

埋め込みとインデックス作成
- コード: model.encode(chunks, show_progress_bar=True)
- FAISSへ追加後に永続化: faiss.write_index(idx, 'index.faiss'); np.save('emb_meta.npy', metadata_list)
メタデータ管理（必須）
- FAISSはメタを持たないのでSQLite等で紐付ける
- 例: sqlite3を使う（Python）

import sqlite3
c=sqlite3.connect('meta.db'); cur=c.cursor()
cur.execute("CREATE TABLE IF NOT EXISTS docs(id INTEGER PRIMARY KEY, filename TEXT, start INT, note TEXT)")
cur.execute("INSERT INTO docs(id, filename, start, note) VALUES(?,?,?,?)", (doc_id, fn, pos, note))
c.commit()

検索フロー（実行例）
- クエリを埋め込み、kNN検索: D, I = idx.search(q_emb, k=5)
- 返ってきたインデックスIを元にSQLiteからメタを引き、最適な断片を抽出してサブエージェントに渡す。
サブエージェント統合の実務的注意
- 常に「context window」に入るサイズを意識して返却をトリミング
- 新規ログを定期バッチ（cron等）で差分インデックス化する: 例 crontab -e に週次バッチを登録

まとめ：短期はファイル、検索はベクトルDB。まずは上の導入例をローカルで実行して、手持ちのログを1回だけインデックスしてみてください — そこから検索→サブエージェントに渡す流れが見えてきます。

⑤ タスク分割・プロンプト設計をテンプレ化する

家のPCの前にいないと作業が進まない、というボトルネックに飽き飽きしていませんか。

そもそもどう動くのか：サブエージェントにやらせるべき作業を「小さなテンプレ化された指示」に落とし込み、必要な変数だけ与えて呼び出す。テンプレートは役割（System）、やること（Task）、制約（Constraints）を明文化するだけ。仕組みが分かれば、あとは変数を差し替えて再利用するだけで手が動く。

7ステップ（テンプレ化して運用するための実践手順）

作業単位を定義する

1作業＝テスト追加1件、関数1つのリネーム、1コミット分の変更と決める。
例: 「関数Xのテスト追加と命名改善」を単位にする。

テンプレートファイルを作る（必須）

実際のテンプレートをファイル化。例：

cat > templates/refactor.tpl <<'T'
System: あなたはリファクタリング専門家です。
Task: {{task_description}}
Constraints: 小さなコミットで動作保証を残す
T

ファイルはGit管理して差分を追えるようにする：git add templates/refactor.tpl && git commit -m "add refactor template"

変数化して呼び出す

JSONで変数を渡すことで同じテンプレを流用。
呼び出し例：

agent_runner --template templates/refactor.tpl --vars '{"task_description":"関数Xのテスト追加と命名改善"}'

出力の自動検証を組み込む

生成物はCIで自動テストする。ローカルなら:

git checkout -b tmp/refactor && applypatch.sh && pytest tests/test_x.py

テスト通らなければテンプレのConstraintsに「必ずテストを通す手順を書く」を追加。

小さなコミット単位で履歴を残す

生成内容をそのまま大コミットにしない。例:

git add path/to/changed && git commit -m "refactor: rename X; add test for X"

変更が複数ファイルなら分割コミットを指示するテンプレ変数を使う。

生成物の差分取得とレビューフロー

生成前後のdiffを作ってレビュワークフローへ流す:

git diff --staged > /tmp/patch.diff
# attach /tmp/patch.diff to PR or code review tool

テンプレに「出力はpatchで返せ」と明記すると再利用しやすい。

テンプレのバリエーションを作る＆バージョン管理

小さな派生テンプレ（bugfix.tpl, feature.tpl）を作る。
バージョンはGitタグで管理：git tag templates/v1.0 refactor-template

まとめ：テンプレート化は「小さく明確に」「変数で差し替え」「必ず自動検証」の3点を守れば即実用化できる。まずは上のrefactor.tplを作って、例のagent_runnerコマンドを1回実行してみてください。次はその出力をテストにかけるところまで進めましょう。

⑥ セッション維持とエラー対処（ログイン期限・再認証）

家を離れているときにバックグラウンド処理が「知らないうちに止まってた」ほど痛いものはない。

そもそもどう動くのか：Claude Code は長時間のバックグラウンドセッションで認証切れや手動許可モードに入ることがある（検証済み：Claude Code 2.1.203 はログイン期限が近づくと警告を出す）。つまり「定期的に認証状態を確認して、切れそうなら再認証をトリガーする」仕組みを入れれば中断を防げる。

定期再認証の基本スクリプトを置く

/usr/local/bin/refresh_auth.sh を作り、実際の再認証コマンドを呼ぶ。

例：

#!/bin/sh
# ここに実際の再認証コマンドを入れる（例: CLIのトークン更新）
YOUR_REAUTH_COMMAND || exit 1

chmod +x /usr/local/bin/refresh_auth.sh

cronで定期実行（推奨：1時間毎）

例：毎時0分に実行

echo '0 * * * * /usr/local/bin/refresh_auth.sh' | crontab -

UIの警告をヘッドレスで監視（ログイン期限警告検出）

puppeteerで「login is about to expire」やフッターの⏸を探す例:

npm i puppeteer
node check_session.js  # check_session.js はページを開いて警告テキストを検索

systemdで常駐プロセスを再起動させる

unitファイル例（/etc/systemd/system/claude-agent.service）を作成し自動再起動を有効化：
```
Restart=on-failure
ExecStart=/usr/local/bin/run_agent.sh
```
sudo systemctl daemon-reload sudo systemctl enable --now claude-agent.service

ネット切断や一時エラーはリトライで耐える（指数バックオフ）

bashの簡易リトライ例：

for i in 1 2 4 8; do YOUR_API_CALL && break || sleep $i; done

トークンはファイルでなく安全に渡す（systemd EnvironmentFile の例）

/etc/claude_env を作り権限を限定：

echo 'CLAUDE_TOKEN=xxxxx' > /etc/claude_env
chmod 600 /etc/claude_env
# unitファイル内に: EnvironmentFile=/etc/claude_env

失敗時のログとアラートを残す（フォールトトレース）

失敗時に syslog と外部通知（Webhook 環境変数使用）を呼ぶ例：

logger "claude auth refresh failed"
curl -X POST -H 'Content-Type: application/json' -d '{"text":"auth failed"}' $ALERT_WEBHOOK || true

まとめ：まずは /usr/local/bin/refresh_auth.sh を作って cron に登録し、1時間ごとに再認証を試してみてください。UI警告（ログイン期限）を監視するヘッドレスチェックを1つ追加するだけで、セッション切れによる中断の多くを防げます。次はcronスクリプトを実際に置いて動作ログを確認してみましょう。

⑦ CIと自動レビューで成果をマージする

家のPCの前にいないとサブエージェントの成果が放置されがち、という痛みをまず消します。

そもそもどう動くのか：各サブエージェントは「変更を作るエンティティ」です。その成果物を直接マージせず、必ずプルリク（PR）で受け取り、CIで自動チェック→レビュー→マージの流れに乗せると作業が止まらない。CIは自動的にリンタ・ユニットテスト・静的解析を走らせ、失敗したものはマージ不可にします。

7ステップ

サブエージェントは必ずPRを作らせる
- コマンド例（エージェントが実行）: git checkout -b agent/feature-x git add . git commit -m "agent: implement X" git push origin agent/feature-x gh pr create --title "agent: implement X" --body "自動生成PR"
ワークフロー追加（GitHub Actions）
- ファイル: .github/workflows/agent-check.yml に jobs.agent-test.steps を追加:

jobs:
  agent-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run agent lint and tests
        run: bash scripts/agent_lint_and_unit_tests.sh

スクリプトは一発で失敗コードを返す（例）

#!/usr/bin/env bash
set -e
npm ci
npm run lint
npm test

必須チェックをブランチ保護で設定する
- リポジトリ設定 > Branch protection rules で "Require status checks to pass before merging" を有効に。CIジョブ名（agent-test）を指定する。
自動レビュー補助を走らせる
- PR作成時に自動で差分を要約するBot（またはエージェント）をコメント。例: gh pr comment<num>--body "$(agent summarize-diff)"。
マージポリシーを決める（自動マージ、手動承認）
- 自動マージするなら合格時に gh pr merge<num>--merge または GitHub の Auto-merge を使用。手動ならレビューワークフローを明確化する。
失敗時のフィードバックループを作る
- CIが失敗したらエージェントに通知して修正PRを投げさせる。例: workflowで失敗を検知し /scripts/retry_agent_fix.sh をトリガー。

まとめ：サブエージェントは「PR作成→CI合格→マージ」というパイプラインに必ず乗せると、自動化の恩恵が回り始める。まずは .github/workflows/agent-check.yml を置いて scripts/agent_lint_and_unit_tests.sh を作ることから試してください。

まとめ

まずは1つの小さなサブエージェントを作り、ブランチ＋tmuxで並列実行して素早く試行→ベクトルDBで履歴を共有し文脈を維持→CIでデプロイとテストを自動化、という一連の流れを一度通してみてください。これだけで開発速度と品質が格段に上がります。次の一歩は、agent-refactor を1ブランチで立ち上げることです — 気軽に始めてみましょう。

目次