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-...

分解の品質を高めるコツ

1. 具体的な目標を記述:

   • ❌ 「アプリを作る」
   • ✅ 「ユーザー認証機能付きのTodoリストWebアプリを作成する」

2. 制約や要件を含める:

   • ✅ 「Pythonでデータ分析レポートを作成し、PDF形式で出力する」

3. 最終成果物を明確に:

   • ✅ 「新しい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. ステップ表示:

   ============================================================
   📍 ステップ 1: 要件定義と技術選定
   ============================================================
   説明: 機能要件を明確化し、使用する技術スタック（フレームワーク、データベース等）を決定する
   推定作業量: small
   

2. 実行指示の表示:

   🤖 Claude Code に以下の指示を送信してください:
   ------------------------------------------------------------
   次のステップを実行してください:
   
   タイトル: 要件定義と技術選定
   説明: 機能要件を明確化し、使用する技術スタック（フレームワーク、データベース等）を決定する
   推定作業量: small
   
   このステップを完了させるために必要な作業を実行してください。
   完了したら、実行内容をまとめて報告してください。
   ------------------------------------------------------------
   

3. Claude Code で作業を実行

4. 進捗が自動保存され、次のステップへ

ステップ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で詳細なパターンを確認してください。

エラーハンドリング

実行中にエラーが発生した場合:

1. 即座に停止: 進捗ファイルに状態が保存される
2. 問題を解決: エラーの原因を修正
3. 再開: --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

効果的な目標設定

1. 具体的に: 最終成果物が明確に想像できる目標を設定
2. 範囲を限定: 大きすぎる目標は複数に分割
3. 制約を明示: 使用技術、期限、リソースなどの制約を含める

ステップ実行のコツ

1. 依存関係を尊重: 依存するステップが完了してから次へ
2. こまめに進捗保存: 長時間の作業は定期的に進捗を確認
3. エラーを記録: 問題が発生したらメモに残す

進捗管理

1. 定期的に確認: track_progress.pyで現在地を把握
2. レポート生成: マイルストーンごとにMarkdownレポートを作成
3. 振り返り: 完了後、所要時間と見積もりを比較して改善

よくある問題と対処法

Q: AI分解が期待と異なる

• A: 目標をより具体的に記述するか、出力JSONを手動編集

Q: ステップが多すぎる/少なすぎる

• A: 目標の粒度を調整するか、references/decomposition_strategies.mdの指針を参照

Q: 途中で中断した作業を再開したい

• A: --resumeオプションで既存の進捗から再開可能

Q: 環境変数が読み込まれない

• A: .envファイルがプロジェクトルートにあることを確認。共通ライブラリが自動的に探索します