autonomous-skill

自律型スキル — 複数セッションでのタスク実行

自動継続、進捗追跡、2 つの完了メカニズム（promise タグとチェックボックスのカウント）を使って、 複雑なタスクを複数の Claude Code セッションにまたがって実行します。

2 つの実行モード

ヘッドレスモード（デフォルト）

bash ループで claude -p の子セッションを起動します。バックグラウンドまたは無人での作業に最適です。

bash <skill-dir>/scripts/run-session.sh "Build a REST API" --max-sessions 10

フックモード（セッション内）

Stop フックを使ってセッションの終了を検知し、プロンプトを再度入力します。現在の対話型セッション内で実行されるため、 ネストに関する問題は発生しません。

bash <skill-dir>/scripts/setup-loop.sh "Build a REST API" --max-iterations 10

2 つのタスク戦略

構造化（デフォルト）

タスクを完全に分解します。イニシャライザーがフェーズ別のサブタスクを含む task_list.md を作成し、 エグゼキューターがタスクを 1 つずつ実行して完了します。複雑な複数フェーズのプロジェクトに最適です。

bash <skill-dir>/scripts/run-session.sh "Build a REST API for todo app"

軽量（--lightweight）

Ralph 形式の反復です。各セッションで同じプロンプトを繰り返し、タスクを分解しません。 成功条件が明確な反復タスク（TDD、バグ修正、リファクタリング）に最適です。

bash <skill-dir>/scripts/run-session.sh "Fix all failing tests in src/" --lightweight

完了の検出

相互に補完する 2 つのメカニズムがあり、先に条件を満たした方が適用されます。

1. Promise タグ（両モード）：作業が本当に完了すると、エージェントは <promise>DONE</promise> を出力します。 デフォルトの promise は DONE です。--completion-promise で変更できます。エージェントには、 ループを抜けるためではなく、作業が本当に完了した場合にのみ promise を出力するよう指示されます。

2. チェックボックスのカウント（構造化モードのみ）：task_list.md 内のすべての [ ] 項目が [x] にマークされます。

ディレクトリ構成

project-root/
├── .autonomous/
│   └── <task-name>/
│       ├── task_list.md      # Master checklist (structured mode)
│       ├── progress.md       # Per-session progress log
│       ├── .mode             # "structured" or "lightweight"
│       ├── sessions/         # Transcript logs per session
│       │   ├── session-001.log
│       │   └── session-002.log
│       └── run.lock          # Prevents concurrent runs
└── .claude/
    └── autonomous-loop.local.md  # Hook mode state (when active)

ヘッドレスモード — CLI リファレンス

bash <skill-dir>/scripts/run-session.sh "task description" [OPTIONS]

フラグ	説明	デフォルト
--lightweight	Ralph 形式の反復（タスクの分解なし）	構造化
--task-name <name>	タスク名を明示的に指定	自動生成
--continue, -c	最新のタスクまたは指定したタスクを続行	—
--list, -l	すべてのタスクと進捗を一覧表示	—
--completion-promise TEXT	完了を示す promise の文言	DONE
--max-sessions N	N セッション後に停止	無制限
--max-budget N.NN	セッションごとの予算（ドル）	5.00
--model <model>	モデルのエイリアスまたは正式名称	sonnet
--fallback-model <m>	プライマリモデルが過負荷の場合のフォールバック	—
--effort <level>	思考の強度（low/medium/high）	high
--no-auto-continue	セッションを 1 回だけ実行	—
--permission-mode <m>	権限モード	auto
--add-dir <dirs>	許可する追加ディレクトリ	—

フックモード — セットアップ

セッション内のループ（子プロセスを起動しない場合）：

bash <skill-dir>/scripts/setup-loop.sh "task description" [OPTIONS]

フラグ	説明	デフォルト
--mode structured|lightweight	タスク戦略	構造化
--max-iterations N	ループの最大反復回数	無制限
--completion-promise TEXT	promise の文言	DONE
--task-name NAME	タスク名を明示的に指定	自動生成

フックは hooks/hooks.json に登録されます。有効な場合、Stop フックは .claude/autonomous-loop.local.md を読み込み、promise が検出されるか最大反復回数に達するまで 終了をブロックします。

フックモードで実行中のループをキャンセルするには、rm .claude/autonomous-loop.local.md を実行します。

ワークフローの詳細

構造化モード

1. イニシャライザーエージェント — タスクを分析し、フェーズ別の task_list.md を作成して作業を開始します
2. エグゼキューターエージェント — タスクリストと進捗を読み込み、前回の作業を確認して次のタスクを完了します
3. 自動継続 — promise タグとチェックボックスを確認し、未完了の場合は次のセッションを起動します

軽量モード

1. 各反復で同じプロンプトを入力します
2. エージェントはファイルと git 履歴から前回の作業を確認します
3. 作業が完了し、promise タグが出力されるまで反復します
4. task_list.md は作成せず、完了は promise のみに基づいて判定します

モードの選び方

シナリオ	戦略	モード
アプリケーション全体を構築する	構造化	ヘッドレス
失敗しているすべてのテストを修正する	軽量	どちらでも可
モジュールをリファクタリングする	軽量	どちらでも可
複数フェーズのプロジェクト	構造化	ヘッドレス
すばやく反復的に修正する	軽量	フック
夜間に一括処理を実行する	構造化	ヘッドレス

重要な制約

1. task_list.md への完了記録は追記のみです：[ ] → [x] の変更のみ行います
2. タスクごとに実行ランナーは 1 つです：ロックファイルにより、同じタスクでの同時セッションを防ぎます
3. プロジェクトファイルはプロジェクトのルートに置きます：.autonomous/ は追跡専用です
4. 完了の宣言を適切に行います：エージェントは、実際に完了するまで <promise>DONE</promise> を出力してはなりません
5. コストを意識します：セッションごとのデフォルト予算は $5 です。--max-budget で調整してください

トラブルシューティング

問題	解決方法
「ロックファイルが存在します」	前回の実行がクラッシュしました。.autonomous/<task>/run.lock を削除してください
セッションが何度も失敗する	sessions/session-NNN.log でエラーを確認してください
ネストされたセッションのエラー	スクリプトは CLAUDECODE を自動的に解除します。代替手段としてフックモードを使用してください
フックのループが停止しない	.claude/autonomous-loop.local.md を削除してください
タスクが見つからない	--list を実行して、利用可能なタスクを確認してください
再起動したい	タスクディレクトリを削除して、最初から開始してください
コストが高すぎる	--max-budget の値を下げるか、--model sonnet を使用してください