Agent Skills: do — 汎用実行スキル（オーケストレーター型）

do — 汎用実行スキル（オーケストレーター型）

このスキルの目的

依頼を受けてすぐ手を動かすと、解釈違い・対象範囲のズレ・検証漏れが起きやすい。このスキルは、あらゆる依頼に一貫した実行の型を与えることで、その種の事故を防ぐ。要は「速さ」より「外さないこと」を担保するための型である。

それと同時に、本スキルはメインの文脈を軽く保つことを重視する。調査・検索・大量のファイル読込・検証ログなどでメインコンテキストが膨らむと、後半の判断精度が落ち、長いタスクが途中で頭打ちになる。そこで本スキルは、メインループをオーケストレーター（指揮役）と位置づけ、トークンを食う実作業はサブエージェントに出して、メインには結論だけを戻させる。

型は手段であって目的ではない。ceremony（儀式的な手間）と委譲はタスクの規模に合わせて伸縮させること。一行の修正に重い手順やサブエージェントを被せれば、かえって遅く・高くつく。各フェーズは「何のためにあるか」を理解した上で、必要な分だけ使う。

中核方針: メインは指揮、実作業は委譲

メインループが自分で全部やると、読んだ内容・検索結果・ログがすべて文脈に積み上がる。これを避けるため、「コンテキストを消費するが結論は短い」作業はサブエージェント（Agent ツール）に委譲するのが本スキルの背骨である。

| メインループが担う（委譲しない） | サブエージェントへ委譲する | |------|------| | 依頼の理解・成功条件の定義 | コードベースの調査・横断検索・命名規約の探索 | | ユーザーへの確認（推奨案を含む複数の選択肢の提示） | 多数ファイルの読込・要点抽出・該当箇所の特定 | | 計画立案・委譲の設計・意思決定 | 独立しスコープの明確な実装/修正 | | サブエージェント結果の統括・最終判断 | ビルド・テスト・型チェック等の検証実行 | | ユーザーへの最終報告 | 外部ドキュメント/Webの下調べ |

委譲の判断軸:

• 読み取り中心で出力がかさむ作業は迷わず委譲。調査・検索・横断読込は、読み取り専用の探索エージェント（例: Explore）に任せ、メインには「結論＋根拠の file:line」だけ戻させる。
• 編集は性質で振り分ける。独立してスコープが明確な実装はサブエージェントへ。逆に、密な対話・段階的な合意・進化する共有文脈が必要な編集はメインで行う（サブエージェントはユーザーに質問できないため）。
• 確認はメイン専任。推奨案を含む複数の選択肢の提示による確認はサブエージェントから行えない。曖昧点・リスクの確認は必ずメインに引き取る。
• 並列で投げる。独立した調査・検証は1メッセージ内で複数のサブエージェントを同時に起動し、待ちを作らない。

委譲しても丸投げにはしない。指示は具体的に、戻り値は構造化を要求する（後述「サブエージェントの使い方」）。これが守れないと、結局メインに大量のテキストが返って文脈節約の意味が消える。

適用範囲と前提

• 明示呼び出し専用。「do スキル」や「doで」と明示された時のみ動く。汎用名ゆえ、暗黙に発火させると専門スキルと競合する。
• 専門スキルが優先。依頼に対応する専門スキル（commiter / pr-reviewer / pr-description / task-performer など）があれば、そちらに委ねる。本スキルはその隙間を埋める。
• プロジェクト規約に従う。作業対象に CLAUDE.md 等の規約があれば最優先で尊重する。言語・命名・コーディング規約・ディレクトリ慣習を勝手に逸脱しない。委譲するサブエージェントにも、従うべき規約を明示的に渡す（サブエージェントはメインの会話文脈を引き継がない）。
• 言語は日本語。報告・確認・コメントはすべて日本語で行う。サブエージェントへの指示も日本語の出力を求める。

規模に手順を合わせる

着手前に、依頼がどの規模かを見積もり、かける手間と委譲の度合いを決める。迷ったら一段重い側に倒す。

| 規模 | 例 | かける手順 | 委譲の目安 | |------|-----|-----------|-----------| | 軽量 | 1ファイルの小修正、明確な単発コマンド、事実確認 | 理解と実行が中心。確認・計画は省略可、報告は1〜2行 | メインで直接。委譲はかえって割高 | | 標準 | 機能追加、複数ファイル変更、調査+まとめ | 6フェーズを一通り。TodoWrite で段取りを可視化 | 調査・検証は委譲。実装は独立性で判断 | | 重量 | 設計を伴う実装、広範な改修、不可逆操作を含む | 各フェーズを丁寧に。計画は明示合意、検証は厳格 | 調査・検証・独立実装を積極委譲。メインは指揮に専念 |

標準手順

1. 理解（Understand）— 調査はサブエージェントへ

依頼のゴール・成功条件・制約を自分の言葉で捉える。何が「完了」かを先に決める。

前提を埋めるための事実集め（コードベース調査・横断検索・関連ファイルの把握）は、読み取り専用の探索エージェントに委譲する。メインで何十ファイルも開くと文脈が一気に膨らむ。サブエージェントには「何を知りたいか」を具体的に渡し、戻り値は結論＋該当箇所の file:line＋短い根拠に絞らせる。複数の観点があるなら、観点ごとに並列で投げる。

軽量タスクや、すでに対象が1ファイルに特定済みなら、委譲せずメインで直接読んでよい。

2. 確認（Confirm）— 曖昧な点のみ、ただし必ず（メイン専任）

曖昧さやリスクが残る点は、着手前に必ずメインループで推奨案を含む複数の選択肢を提示してユーザーに確認する。 サブエージェントはユーザーに質問できないため、このフェーズは委譲できない。調査をサブエージェントに出していた場合は、その結論を受け取ってから、確認すべき点を一度にまとめて聞く。

確認する（聞く）べき場面:

• 妥当な解釈が複数ある（出力形式・対象範囲・対象ファイル/環境が特定できない）
• 後戻りが困難・破壊的（削除・上書き・force push・本番影響・課金・外部公開・認証情報の扱い）
• 前提が検証できない（対象が存在するか不明、依存関係や権限が不確か）
• コストと品質のトレードオフが大きい（簡易実装 vs 本格実装など、どちらも妥当）

確認しない（即実行してよい）場面:

• 依頼が一義的に明確で、解釈の余地がない
• 合理的なデフォルトで進められ、結果を容易に元へ戻せる
• 確認が形式的なだけで、回答が作業内容を変えない

複数の選択肢を提示してユーザーに確認するときは、選択肢を具体的にし、推奨案があれば先頭に置いて「(推奨)」と明示する。聞くべきことは一度にまとめ、何度も小刻みに割り込まない。

3. 計画（Plan）— 段取りと「委譲の設計」

標準〜重量タスクでは段取りを立てる。多段なら TodoWrite で手順を可視化し、依存関係と検証方法を含める。

このフェーズでは委譲の設計も行う。どの作業を独立したサブエージェントに切り出せるかを見極める。独立した作業が並ぶなら並列起動を計画する。並列で同じファイルを編集するおそれがあるなら、競合を避けるため直列化するか、isolation: "worktree" で隔離して走らせる。Plan mode が有効なときは、計画を提示して承認を得てから実行に移る。軽量タスクでは本フェーズは省略してよい。

4. 実行（Execute）— 独立タスクは委譲、対話的作業はメイン

計画に沿って進める。実装は性質で振り分ける。

• 独立・スコープ明確な実装はサブエージェントへ: 「このモジュールにこの関数を追加」「この設定ファイルをこう直す」のように、入出力と完了条件が一文で言える作業は委譲する。指示に対象・期待結果・従うべき規約・戻すべきサマリ形式を含める。
• 対話的・共有文脈が要る編集はメインで: 段階的な合意や、直前の判断を踏まえて進む編集はメインが担う。
• 既存コードに馴染ませる: 周囲の命名・スタイル・イディオムに合わせる。新しい流儀を持ち込まない。委譲時も同じ要求をサブエージェントに渡す。
• 編集前に読む: ファイルを変更する前に必ず現状を読む（メインで編集するなら同一セッションで読込。サブエージェントに委譲するならそのエージェント内で読ませる）。前提と食い違えば、上書きせず一旦立ち止まって共有する。
• 独立作業は並列に: 依存の無い委譲・ツール呼び出しはまとめて発行し、無駄な待ちを作らない。
• 不可逆操作は慎重に: 削除・上書き・push・外部送信は、フェーズ2で確認済みの範囲を超えないこと。これらは原則メインで実行し、サブエージェントに丸投げしない（確認に戻れないため）。途中で新たな曖昧点・リスクに気づいたら、勝手に進めず確認に戻る。
• ツール実行が詰まったら: Edit・Bash・MCP 等のツール呼び出し自体が同種エラーで3回連続失敗し進行がブロックされたら、盲目的にリトライせず「エージェント内部のツール実行エラーで詰まったときの対処」フローに入る。

5. 検証（Verify）— 検証実行はサブエージェントへ

「やった」と「できた」は別物。完了を宣言する前に、成功条件を満たしたかを実際に確かめる。

ビルド・テスト・型チェック・lint など出力が大量になりうる検証は、サブエージェントに実行させ、メインには「合否＋失敗時の要点（落ちたテスト名・主要エラー）」だけを戻させる。これでログ全文がメイン文脈を埋めるのを防ぐ。

• コードならビルド/テスト/型チェック等を可能な範囲で実行し、結果を事実として確認する
• 設定・ドキュメントなら、対象が意図通りに反映/参照されるかを確認する
• 検証できなかった項目があれば、それを正直に「未検証」として残す（できたふりをしない）
• テストが落ちた・スキップした手順があるなら、その出力とともに率直に報告する

6. 報告（Report）— サブエージェントのサマリを統括して締める

完了したら、簡潔なサマリで締める。冗長なテンプレートは避け、要点だけを残す。各サブエージェントから戻った構造化サマリをメインが統括し、ユーザー向けに一本化する（個々のエージェントの生ログを貼り付けない）。

## 実施内容
- <やったことを箇条書きで。委譲した作業も含め、結果として何を達成したか>

## 結果 / 検証
- <成功条件を満たしたか。検証方法と結果。未検証があれば明記>

## 残課題・次の一手（あれば）
- <フォローが要る点、推奨する次のアクション>

軽量タスクなら、この型に縛られず1〜2行で十分。残課題が無ければ「残課題」節は省く。

エージェント内部のツール実行エラーで詰まったときの対処（エラーハンドリング・フロー）

ここで扱うのは、AIエージェント自身のツール呼び出しが繰り返し失敗して作業が前に進まない状況だ。たとえば Edit が old_string のマッチに失敗し続ける、Bash が権限モードやサンドボックスに阻まれて実行できない、MCP/ツール呼び出しがエラーを返す、入力検証エラーやタイムアウトが繰り返す、といったツール/ハーネス層（tool_use レベル）の失敗である。

これはユーザーの目線ではブラックボックスにあたる。ユーザーには「なぜそのツールが失敗し続けるのか」が見えない。だからこそ、ここで詰まったら黙って粘らず、内部で何が起きていて、どう回避しようとしているのかを言語化してユーザーに諮ることに価値がある。最も避けたいのは、原因を変えないまま同じ呼び出しを投げ続ける盲目的なリトライだ。時間とトークンを浪費し、文脈をエラーで埋め、問題は解決しない。

このフローは標準手順のどのフェーズでも、ツール実行が繰り返し詰まった瞬間に割り込んで発動する。

区別: ユーザーのプロジェクト側の結果（ビルド失敗・テストレッド・lint 指摘など）は、ツールが正常に動いた上で得られたドメインの結果であり、検証(5)で事実として扱い普通に報告する。本フローの対象は、その手前でツール呼び出し自体が成立しないケースである。たとえば「npm test を流したらテストが落ちた」は検証(5)の領域、「npm test を実行する Bash 呼び出しが権限拒否・サンドボックスで動かせない」は本フローの領域。

発動条件 — 同種エラーが3回連続

単発のツールエラーは正常系の一部であり、いちいちユーザーに上げない。1回目はエラー内容を正確に読み、原因を特定して的を絞った修正を試みる（例: Edit が落ちたらファイルを読み直して old_string を取り直す、replace_all や Write に切り替える）。それでも同種のエラーが3回連続し、進行が実質ブロックされたら、リトライを止めて本フローに入る。「同種」とは、対象や文言が多少違っても根本原因が同じと見られる失敗を指す（同じ権限拒否・同じサンドボックス制限・同じツールの不調が形を変えて出る等）。原因の異なる別エラーは、それぞれ独立に1からカウントする。

手順

1. リトライを止める: 同じ呼び出しの反復をやめる。ここで粘っても解決しないと割り切る。

2. 原因と回避策を見極める（委譲可）: 何が・なぜ失敗しているのかを突き止め、回避策の候補を挙げる。ツール層の典型的な回避策は次のような形になる。

   • 別ツール・別手段への切替: Edit が通らないなら Write で書き直す、あるテンプレ的処理を別アプローチに変える等。
   • ユーザーに権限付与を依頼: Bash が権限モードで拒否される場合、許可をもらう。
   • ユーザー自身に実行を依頼: サンドボックスや対話的ログイン等でエージェントから実行できない操作は、ユーザーに ! <command> でその場実行してもらい、出力を会話に取り込む。
   • ツール定義の読込・前提整備: 遅延ロードのツールやMCPがエラーになるなら、スキーマを読み込む／前提条件を満たす。
   • スコープ・パラメータ調整: タイムアウトなら範囲を小さくする・バックグラウンド実行にする等。

   仕様確認やドキュメント調査が要るなら、読み取り中心で出力がかさむためサブエージェントに委譲してよい。メインには**原因の要点＋回避策の選択肢＋各案のトレードオフ（影響・副作用・可逆性）**だけを構造化して戻させる。

3. ユーザーに報告し、承認を得る（メイン専任）: 推奨案を含む複数の選択肢の提示で次を提示する。サブエージェントは質問できないため、このステップは必ずメインが担う。ユーザーには内部エラーが見えていない前提で、過不足なく説明する。

   • 何が・なぜ失敗しているか: どのツール呼び出しが、どんなエラーで、なぜ詰まっているのかを簡潔に。ユーザーから見えない情報なので、ここを省かない。
   • 回避策の選択肢: 実行可能な案を具体的に。推奨案は先頭に置き「(推奨)」と明示する。
   • 各案の影響・トレードオフ: 副作用・可逆性・残るリスクを添え、ユーザーが判断できるようにする。

4. 承認された回避策のみ実施: ユーザーが選んだ案だけを実行する。承認なしに回避策を実施しない（権限の付与、別手段への切替、スコープ変更などは影響が波及しやすい）。回避策自体が不可逆・破壊的なら、通常どおりメインで慎重に行う。実施後は、本来やりたかった作業が進められるようになったかを確かめてから先へ進む。

5. 回避もできない場合は正直に報告: 妥当な回避策が無い、またはどれもユーザーの許容範囲外なら、無理に進めない。試したこと・失敗の要点・ブロッカーの正体を率直に共有し、判断を仰ぐ。動けないことを「できた」と取り繕わない。

軽さを保つ

このフローは「ツール実行で詰まったとき」専用の保険であって、エラーのたびに重く回すものではない。1〜2回で自力で抜けられる失敗は黙って直してよい。3回連続という線引きは、自力で直せる範囲は自力で片付け、本当に詰まったときだけユーザーの手を借りるための目安である。

サブエージェントの使い方（委譲のコツ）

委譲は「投げ方」で価値が決まる。雑に投げると、結局メインに大量のテキストが返り文脈節約が消える。次を守る。

• 指示は自己完結に: サブエージェントはメインの会話文脈を引き継がない。目的・対象・制約（CLAUDE.md等の規約）・完了条件・戻すべき形式を指示文に明記する。
• 戻り値を絞らせる: 「結論を3〜5点」「該当箇所は file:line で」「生ログではなく要約を」と、返す形を指定する。これが文脈節約の肝。
• 適切なエージェント種別を選ぶ: 読み取り中心の調査・横断検索は読み取り専用の探索エージェント（例: Explore）。実装や多段の作業を伴うなら汎用エージェント（general-purpose）。プロジェクトに専用エージェントがあればそれを優先。
• 並列で投げる: 独立した委譲は1メッセージ内で複数同時に起動する。
• 編集競合を避ける: 複数エージェントが同じファイルに触れうるなら、直列化するか isolation: "worktree" で隔離する。
• 丸投げ禁止の領域: ユーザー確認（推奨案を含む複数の選択肢の提示）と、不可逆・破壊的操作はメインに残す。

やってはいけないこと

• 理解前の着手: ゴールが曖昧なまま手を動かさない。
• 過剰な確認: 明白な依頼に形式的な質問を重ねて進行を止めない。
• 検証なしの完了宣言: 確かめずに「できました」と言わない。
• 規約の無視: プロジェクトの CLAUDE.md・既存スタイルを勝手に逸脱しない。委譲先にも規約を渡し忘れない。
• 専門領域への越境: 該当する専門スキルがある依頼を、本スキルで巻き取らない。
• 沈黙の取りこぼし: 範囲を絞った・スキップした・未検証で残した点を黙って隠さない。
• 過剰委譲・丸投げ: 軽量作業にまでサブエージェントを噛ませて遅く高くしない。確認・不可逆操作をサブエージェントに丸投げしない。戻り値を絞らせず生ログでメイン文脈を埋めない。
• 盲目的なリトライ: 同種のツールエラーで詰まっているのに、原因を変えないまま同じ呼び出しを繰り返さない。3回連続したらエラーハンドリング・フローに入る。
• 無断での回避策実施: ツール実行エラーの回避策（権限付与・別手段への切替・スコープ変更など）を、ユーザーに内部エラーと回避策を報告し承認を得る前に勝手に実行しない。