技能は読み込まれたのに子Agentが動かない、または作業結果が主タスクへ戻りませんか？
今週は再インストールを繰り返す前に、コーディングハーネスの起動時読み込み、ツール、権限、タスクの受け渡しを順に確認してください。必要な機能がなければ、対応する環境へ切り替えるか、手動で直列実行します。
この記事は、Superpowersを導入済みなのに技能が起動しない人、複数のコーディングハーネスを使い分ける人向けです。
リモート開発環境を管理し、障害を再現できる形で記録したいチームにも役立ちます。
SuperpowersのマルチAgent障害は、止まった段階から切り分けます
最初に記録するのは「失敗した」という結論ではなく、どの処理で初めて期待と違ったかです。会話開始、技能の呼び出し、ツール実行、子タスクの返却、検証結果のいずれかを特定できれば、調べる場所を絞れます。
| 見えている症状 | 最初に確認するもの | 判定の目安 |
|---|---|---|
| 技能に沿った応答にならない | プラグインの有効状態、会話開始時の読み込み | 技能ファイルが存在するだけでなく、現在の会話に読み込まれているか |
| 子タスクが始まらない | タスク委譲機能、実行許可、呼び出しログ | ハーネスに機能がないのか、許可で止められたのか |
| 子タスクの結果が見えない | タスクの指示、実行状態、結果の返却先 | 子タスクが未実行なのか、実行後の受け渡しで途切れたのか |
| 完了報告に根拠がない | テスト命令、実出力、終了状態、レビュー記録 | 検証失敗・未実行・ツール利用不可を区別できているか |
まず、ファイルを読むなど、結果を目で確認できる小さな作業を一つだけ依頼します。同じ条件で再現するかも記録してください。複数の変更をまとめて試すと、直った理由も失敗した場所も分からなくなります。
ハーネスの機能不足と設定ミスを分けます
Superpowersの公式資料では、プロジェクトのREADMEや技能の説明に加え、新しいハーネスへ移植するための案内が公開されています。つまり、技能の設置だけでなく、実行環境側が必要な仕組みを備えているかの確認が欠かせません。公式READMEと新しいハーネスへの移植ガイドを照らし合わせ、公式に説明されている方法と、独自に行った適応を混同しないでください。
| 確認項目 | 利用できる状態 | 不足している場合の対応 |
|---|---|---|
| 技能の読み込み | 会話開始時に技能が認識され、呼び出し可能 | 有効化と起動時の読み込み設定を見直す |
| ファイル操作 | 対象の作成・編集・読み取りが許可される | 対象パスと書き込み権限を確認する |
| シェル実行 | 必要な命令を起動でき、実行結果を確認できる | 実行ポリシーや承認待ちの状態を調べる |
| タスク委譲 | 子タスクの開始、状態確認、結果の取得ができる | 未対応なら手動で直列実行する |
| 承認・制限 | 必要な操作が許可され、拒否理由が追える | 許可設定と拒否ログを確認する |
using-superpowers技能の公式説明を参照し、現在の会話で技能が扱われているかを確認します。技能名を入力しても動かないときは、名前の表記だけを何度も変えるのではなく、プラグインの有効状態と読み込み経路を先に調べます。
会話のログに技能の読み込みが見当たらない場合、子Agentの問題と決めつけないでください。技能が会話へ渡る前の段階で止まっている可能性があります。
権限による停止と、ツール自体がない状態を見分けます
タスク委譲が止まったように見えても、実際にはファイル書き込みやシェル命令の承認待ち、あるいは実行拒否で止まっていることがあります。実行ログに許可要求、拒否理由、失敗した命令が残っていないかを見ます。承認が必要な操作と、ハーネスが提供していない機能は別の問題です。
子Agent駆動開発の公式技能で想定される作業と、実環境にあるツールを照合してください。実行環境の承認仕様については、ツールの権限と承認に関する説明や実行時の承認状態に関する説明も確認できます。機能の有無や承認方法は環境によって異なるため、資料の説明をそのまま別のハーネスへ当てはめないでください。
条件に合わせて復旧方法を選びます
- 会話開始時に技能が読み込まれ、必要なツールも使える場合： プラグインの有効状態と権限を直して、最小タスクをもう一度実行します。
- ツールはあるが承認や拒否で止まる場合： どの操作が拒否されたかをログで確認し、必要な操作だけ許可して再試行します。
- ファイル操作やシェルが使えない場合： その環境で実行できる範囲にタスクを変更します。権限を変更できないなら、作業者が手動で補います。
- 子タスクの委譲機能がない場合： ツール名を推測して呼び出すのをやめ、作業を小さく分割して手動で直列実行します。自動のマルチAgent処理が必要なら、必要機能を備えたハーネスへ切り替えます。
子タスクの消失と未実施の検証を混同しません
子Agentへ渡す内容が曖昧だと、開始したかどうかも、何を返すべきかも判断しにくくなります。対象ファイル、変更内容、完了条件、返却する結果を指示に含め、主タスクへ結果を書き戻す場所も決めておきます。
長い会話の後や、セッションを再起動した後に問題が出たなら、以前の会話内容が引き継がれたと仮定せず、現在のタスク状態とログを確認してください。内部で何が起きたかを推測するのではなく、子タスクが開始された記録、完了状態、返却された内容を順に追います。
完了報告も、実施した検証と分けて記録します。「テストが失敗した」「テスト用ツールが使えなかった」「テストを実行していない」は異なる状態です。命令、実際の出力、終了状態、レビュー結果を分けて残せば、根拠のない「完了」を成功扱いするのを防げます。
同じ条件で再確認できる記録を残します
次の項目を障害記録に残してください。設定を変えた後も同じ最小タスクを試し、どの変更が結果に影響したかを追います。
- [ ] 使用したコーディングハーネスと確認時のバージョン
- [ ] Superpowersのプラグインが有効か、技能が読み込まれたか
- [ ] ファイル操作、シェル、タスク委譲が利用できたか
- [ ] 発生した段階と、再現に使った最小の指示
- [ ] 実行ログ、承認・拒否の状態、子タスクの状態
- [ ] テスト命令と実出力、または未実施・利用不可の理由
- [ ] 変更した設定と、変更後に同じ条件で確認した結果
リモート環境のセッションや作業場所まで確認が必要なら、Hashvpsのヘルプセンターを参照し、プラグイン、権限、実行セッションのどこで問題が起きたかを整理してください。環境を替えた場合は、技能の設置状態だけでなく、利用できるツールと起動時の読み込みも再確認します。
よくある疑問
技能が会話で使われない場合は、何から確認しますか？
プラグインの有効状態と、会話開始時に技能が読み込まれる仕組みを確認します。技能ファイルがあることと、現在の会話で利用できることは同じではありません。ログで読み込みを確認できないなら、子Agentの呼び出しを調べる前に、ハーネス側の読み込み設定を見直してください。
子Agentが始まらないとき、何を切り分けますか？
タスク委譲機能が存在するか、実行が許可されているか、タスクの指示が独立して実行できるかを順に確認します。呼び出し機能がない環境では、ツール名の推測で解決しようとしないでください。タスクを分割し、結果を主作業へ戻す手動の直列フローに切り替えます。
ハーネスを変更した後、設定のどこを見直しますか？
技能の読み込み時点、ファイルの読み書き、シェルの利用、子タスクの委譲、承認・拒否の記録を確認します。以前の環境で動いた設定が新しい環境でも使えるとは限りません。公式の移植資料と実際の機能を照合し、同一の最小タスクで動作を確かめます。
子Agent用のツールがない場合も使えますか？
技能の説明を参考にできても、自動的なタスク委譲が可能とは限りません。ハーネスにある機能だけで作業できるようタスクを組み替え、結果を手動で主作業へ統合します。並行処理が必須なら、必要な機能を備えた環境を選んでください。
現在の開発環境で続ける方法は、すでにあるツールを使う手動実行、対応機能のある環境への切り替え、Macを含む別環境での検証に分かれます。既存環境での作業には、権限の制約、セッション切断後の復旧、必要機能の不足が残ることがあります。一方、常時稼働する重い処理や物理接続が必須なら、レンタルより自前の環境が適する場合もあります。
一時的な検証環境が必要なら、HashvpsのMacレンタルを候補に加え、プラン詳細で利用条件を確認してください。現在のハーネスで問題が解決できるかを先に見極め、必要な期間だけ別環境で同じ再現タスクを試す使い方が適しています。
開発環境を整えるなら、HashvpsのクラウドMac
ネイティブmacOSを備えたMac miniをクラウドで利用し、開発やビルドの作業環境を整えられます。
SSHとVNCに対応しているため、ターミナル操作と画面操作を用途に合わせて使い分けられます。