tomevault-io Stepwise Executor
Overview
Stepwise Executorは、任意の作業目標を中間目標（サブゴール）に自動分解し、段階的に実行するための汎用スキルです。 AIが最適な分解を提案し、各ステップの実行状況を追跡しながら、最終目標の達成まで確実にガイドします。
主な機能:
- 🎯 AI による自動的な目標分解（Claude API使用）
- 📊 リアルタイムの進捗追跡
- 🔄 ステップ間の依存関係管理
- 📝 実行履歴とメモの記録
- 📄 詳細なレポート生成
適用場面:
- ソフトウェア開発プロジェクト（新機能実装、リファクタリング等）
- データ分析・機械学習プロジェクト
- ドキュメント作成・技術執筆
- インフラ構築・クラウド移行
- 学習計画・スキル習得
Quick Start
最も典型的な使用フローを示します。
1. 目標を分解する
python scripts/decompose_goal.py "ユーザー認証機能付きのTodoアプリを作成する"
出力例:
🎯 目標を分解中: ユーザー認証機能付きのTodoアプリを作成する
📋 目標分解サマリー
============================================================
元の目標: ユーザー認証機能付きのTodoアプリを作成する
中間目標数: 7
中間目標:
1. 要件定義と技術選定 [small]
機能要件を明確化し、使用する技術スタック（フレームワーク、データベース等）を決定する
2. データベーススキーマ設計 [small] (依存: 1)
ユーザーテーブルとTodoテーブルのスキーマを設計し、マイグレーションファイルを作成する
3. 認証APIの実装 [medium] (依存: 2)
ユーザー登録、ログイン、ログアウトのAPIエンドポイントを実装する
...
✅ 分解結果を保存しました: decomposed_goal.json
次のステップ: execute_steps.py decomposed_goal.json
2. ステップを実行する
python scripts/execute_steps.py decomposed_goal.json
各ステップの実行指示が表示されるので、その指示に従って作業を進めます。 実行が完了したら、進捗が自動的に記録されます。
3. 進捗を確認する
python scripts/track_progress.py progress.json
出力例:
======================================================================
📊 実行進捗サマリー
======================================================================
目標: ユーザー認証機能付きのTodoアプリを作成する
ステータス: 🔄 in_progress
開始時刻: 2025-01-15T10:00:00
経過時間: 2時間 30分
進捗: 3/7 ステップ完了 (42.9%)
[████████████████░░░░░░░░░░░░░░░░░░░░░░░░]
----------------------------------------------------------------------
📋 ステップ詳細
----------------------------------------------------------------------
✅ ステップ 1: 要件定義と技術選定
ステータス: completed
開始: 2025-01-15T10:00:00
完了: 2025-01-15T10:45:00
所要時間: 45分
✅ ステップ 2: データベーススキーマ設計
ステータス: completed
...
🔄 ステップ 3: 認証APIの実装
ステータス: in_progress
開始: 2025-01-15T11:30:00
...
Workflow
ワークフロー全体像
1. 目標設定
↓
2. AI分解（decompose_goal.py）
↓
3. 分解結果の確認・調整（必要に応じて）
↓
4. ステップ実行（execute_steps.py）
├─→ 各ステップの実行
├─→ 進捗記録
└─→ エラー時の対処
↓
5. 進捗追跡（track_progress.py）
↓
6. 完了・レポート生成
ステップ1: 目標分解
基本的な使い方
python scripts/decompose_goal.py "作業目標の説明"
オプション
-o, --output FILE: 出力ファイルパス（デフォルト:decomposed_goal.json）--show-only: 結果を表示するのみで保存しない（プレビュー用）
例
# 基本的な分解
python scripts/decompose_goal.py "データ分析レポートを作成する"
# 出力先を指定
python scripts/decompose_goal.py "APIドキュメントを作成する" -o api_doc_plan.json
# プレビューのみ（保存しない）
python scripts/decompose_goal.py "レガシーコードをリファクタリングする" --show-only
環境変数の設定
このスクリプトはClaude APIを使用するため、ANTHROPIC_API_KEYが必要です:
# .envファイルに設定（推奨）
ANTHROPIC_API_KEY=sk-ant-...
# または環境変数として設定
export ANTHROPIC_API_KEY=sk-ant-...
分解の品質を高めるコツ
具体的な目標を記述:
- ❌ 「アプリを作る」
- ✅ 「ユーザー認証機能付きのTodoリストWebアプリを作成する」
制約や要件を含める:
- ✅ 「Pythonでデータ分析レポートを作成し、PDF形式で出力する」
最終成果物を明確に:
- ✅ 「新しいREST APIの包括的なドキュメントを作成し、開発者が簡単に利用できるようにする」
ステップ2: ステップ実行
基本的な使い方
python scripts/execute_steps.py decomposed_goal.json
オプション
-p, --progress FILE: 進捗ファイルのパス（デフォルト:progress.json）-i, --interactive: インタラクティブモード（各ステップで入力を求める）--resume: 既存の進捗ファイルから再開する
実行モード
1. 標準モード（非インタラクティブ）
python scripts/execute_steps.py decomposed_goal.json
各ステップの実行指示が表示されます。Claude Code に指示を送信して作業を進め、 完了したら次のステップに進みます。
2. インタラクティブモード
python scripts/execute_steps.py -i decomposed_goal.json
各ステップで以下の操作が可能:
- 実行結果のメモを記録
- ステップ完了の確認
- ステップのスキップ
- 再試行
3. 再開モード
python scripts/execute_steps.py --resume decomposed_goal.json
中断した作業を既存の進捗ファイルから再開します。
実行の流れ
ステップ表示:
============================================================ 📍 ステップ 1: 要件定義と技術選定 ============================================================ 説明: 機能要件を明確化し、使用する技術スタック（フレームワーク、データベース等）を決定する 推定作業量: small実行指示の表示:
🤖 Claude Code に以下の指示を送信してください: ------------------------------------------------------------ 次のステップを実行してください: タイトル: 要件定義と技術選定 説明: 機能要件を明確化し、使用する技術スタック（フレームワーク、データベース等）を決定する 推定作業量: small このステップを完了させるために必要な作業を実行してください。 完了したら、実行内容をまとめて報告してください。 ------------------------------------------------------------Claude Code で作業を実行
進捗が自動保存され、次のステップへ
ステップ3: 進捗追跡
基本的な使い方
python scripts/track_progress.py progress.json
オプション
-f, --filter STATUS: 特定のステータスのステップのみ表示pending: 未着手in_progress: 実行中completed: 完了skipped: スキップ
-s, --summary-only: サマリーのみ表示（詳細を省略）-e, --export FILE: レポートをMarkdown形式で出力
例
# 全体の進捗を表示
python scripts/track_progress.py progress.json
# 完了したステップのみ表示
python scripts/track_progress.py -f completed progress.json
# サマリーのみ表示
python scripts/track_progress.py -s progress.json
# Markdownレポートを生成
python scripts/track_progress.py -e report.md progress.json
Advanced Usage
カスタム分解戦略
AI分解の結果が期待に沿わない場合、references/decomposition_strategies.mdを参照して、
分解の方針を調整できます:
- トップダウンアプローチ: 最終目標から逆算
- ボトムアップアプローチ: タスクをリストアップして整理
- マイルストーンアプローチ: 重要なマイルストーンを設定
詳細は references/decomposition_strategies.md を参照してください。
手動での分解結果編集
decompose_goal.pyの出力JSONを直接編集することで、分解結果をカスタマイズできます:
{
"original_goal": "...",
"steps": [
{
"step": 1,
"title": "ステップタイトル",
"description": "詳細説明",
"estimated_effort": "small/medium/large",
"dependencies": [2, 3] // このステップが依存する他のステップ
}
]
}
並列実行パターン
依存関係のないステップは、複数のClaude Codeインスタンスや 複数の作業者で並列実行できます。
references/execution_patterns.mdで詳細なパターンを確認してください。
エラーハンドリング
実行中にエラーが発生した場合:
- 即座に停止: 進捗ファイルに状態が保存される
- 問題を解決: エラーの原因を修正
- 再開:
--resumeオプションで再開
python scripts/execute_steps.py --resume decomposed_goal.json
分解例の参照
references/examples.mdに、様々な作業領域での分解例があります:
- Webアプリケーション開発
- レガシーコードのリファクタリング
- データ分析レポート作成
- 機械学習モデル開発
- 技術ドキュメント作成
- クラウド移行プロジェクト
- 学習計画
これらの例を参考に、自分のプロジェクトに適した分解を行えます。
Resources
このスキルには、効果的な目標分解と実行をサポートするリソースが含まれています。
scripts/
実行可能なPythonスクリプトです。すべてMiyabi共通ライブラリを使用しています。
decompose_goal.py: 作業目標をAIで中間目標に自動分解
- Claude API（claude-sonnet-4-20250514）を使用
- ANTHROPIC_API_KEY環境変数が必要
- JSON形式で分解結果を出力
execute_steps.py: 中間目標を順次実行
- インタラクティブモードと非インタラクティブモードをサポート
- 進捗をリアルタイムで記録
- 再開機能（
--resume）をサポート
track_progress.py: 実行進捗の追跡と表示
- プログレスバー付きサマリー表示
- ステップ詳細表示
- Markdownレポート生成
references/
Claude が参照するドキュメントです。
decomposition_strategies.md: 目標分解の戦略とベストプラクティス
- SMART原則
- トップダウン/ボトムアップ/マイルストーンアプローチ
- 分解の品質チェックリスト
execution_patterns.md: 実行パターンとベストプラクティス
- 完全自動実行/インタラクティブ/ハイブリッドモード
- エラーハンドリング戦略
- 並列実行パターン
- モニタリングとロギング
examples.md: 様々な作業領域での分解例
- ソフトウェア開発（Webアプリ、リファクタリング）
- データ分析（レポート作成、機械学習）
- ドキュメント作成
- インフラ・運用（クラウド移行）
- 学習計画
assets/
テンプレートとパターン例です。
progress_template.json: 進捗記録用テンプレート
- 進捗ファイルの構造を示す
- カスタマイズの参考に
goal_patterns/: 典型的な目標パターン例
software_development.json: ソフトウェア開発プロジェクトのパターンdata_analysis.json: データ分析プロジェクトのパターンdocumentation.json: ドキュメント作成プロジェクトのパターン
Tips & Best Practices
効果的な目標設定
- 具体的に: 最終成果物が明確に想像できる目標を設定
- 範囲を限定: 大きすぎる目標は複数に分割
- 制約を明示: 使用技術、期限、リソースなどの制約を含める
ステップ実行のコツ
- 依存関係を尊重: 依存するステップが完了してから次へ
- こまめに進捗保存: 長時間の作業は定期的に進捗を確認
- エラーを記録: 問題が発生したらメモに残す
進捗管理
- 定期的に確認:
track_progress.pyで現在地を把握 - レポート生成: マイルストーンごとにMarkdownレポートを作成
- 振り返り: 完了後、所要時間と見積もりを比較して改善
よくある問題と対処法
Q: AI分解が期待と異なる
- A: 目標をより具体的に記述するか、出力JSONを手動編集
Q: ステップが多すぎる/少なすぎる
- A: 目標の粒度を調整するか、
references/decomposition_strategies.mdの指針を参照
Q: 途中で中断した作業を再開したい
- A:
--resumeオプションで既存の進捗から再開可能
Q: 環境変数が読み込まれない
- A:
.envファイルがプロジェクトルートにあることを確認。共通ライブラリが自動的に探索します
Converted and distributed by TomeVault — claim your Tome and manage your conversions.