# Stepwise Executor

> 任意の作業目標を自動的に中間目標（サブゴール）に分解し、段階的に実行するスキル。 複雑なプロジェクト、大規模な実装タスク、長期的な作業を段階的に進めたい場合に使用する。 「Webアプリを作りたい」「データ分析レポートを作成したい」「リファクタリングを実施したい」 などの大きな目標を、実行可能な中間目標に分解して、進捗を追跡しながら確実に完了させる。

- Skill: `majiayu000/stepwise-executor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/stepwise-executor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/stepwise-executor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/stepwise-executor

---


# Stepwise Executor

## Overview

Stepwise Executorは、任意の作業目標を中間目標（サブゴール）に自動分解し、段階的に実行するための汎用スキルです。
AIが最適な分解を提案し、各ステップの実行状況を追跡しながら、最終目標の達成まで確実にガイドします。

**主な機能**:
- 🎯 AI による自動的な目標分解（Claude API使用）
- 📊 リアルタイムの進捗追跡
- 🔄 ステップ間の依存関係管理
- 📝 実行履歴とメモの記録
- 📄 詳細なレポート生成

**適用場面**:
- ソフトウェア開発プロジェクト（新機能実装、リファクタリング等）
- データ分析・機械学習プロジェクト
- ドキュメント作成・技術執筆
- インフラ構築・クラウド移行
- 学習計画・スキル習得

## Quick Start

最も典型的な使用フローを示します。

### 1. 目標を分解する

```bash
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. ステップを実行する

```bash
python scripts/execute_steps.py decomposed_goal.json
```

各ステップの実行指示が表示されるので、その指示に従って作業を進めます。
実行が完了したら、進捗が自動的に記録されます。

### 3. 進捗を確認する

```bash
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: 目標分解

#### 基本的な使い方

```bash
python scripts/decompose_goal.py "作業目標の説明"
```

#### オプション

- `-o, --output FILE`: 出力ファイルパス（デフォルト: `decomposed_goal.json`）
- `--show-only`: 結果を表示するのみで保存しない（プレビュー用）

#### 例

```bash
# 基本的な分解
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`が必要です:

```bash
# .envファイルに設定（推奨）
ANTHROPIC_API_KEY=sk-ant-...

# または環境変数として設定
export ANTHROPIC_API_KEY=sk-ant-...
```

#### 分解の品質を高めるコツ

1. **具体的な目標を記述**:
   - ❌ 「アプリを作る」
   - ✅ 「ユーザー認証機能付きのTodoリストWebアプリを作成する」

2. **制約や要件を含める**:
   - ✅ 「Pythonでデータ分析レポートを作成し、PDF形式で出力する」

3. **最終成果物を明確に**:
   - ✅ 「新しいREST APIの包括的なドキュメントを作成し、開発者が簡単に利用できるようにする」

### ステップ2: ステップ実行

#### 基本的な使い方

```bash
python scripts/execute_steps.py decomposed_goal.json
```

#### オプション

- `-p, --progress FILE`: 進捗ファイルのパス（デフォルト: `progress.json`）
- `-i, --interactive`: インタラクティブモード（各ステップで入力を求める）
- `--resume`: 既存の進捗ファイルから再開する

#### 実行モード

**1. 標準モード（非インタラクティブ）**

```bash
python scripts/execute_steps.py decomposed_goal.json
```

各ステップの実行指示が表示されます。Claude Code に指示を送信して作業を進め、
完了したら次のステップに進みます。

**2. インタラクティブモード**

```bash
python scripts/execute_steps.py -i decomposed_goal.json
```

各ステップで以下の操作が可能:
- 実行結果のメモを記録
- ステップ完了の確認
- ステップのスキップ
- 再試行

**3. 再開モード**

```bash
python scripts/execute_steps.py --resume decomposed_goal.json
```

中断した作業を既存の進捗ファイルから再開します。

#### 実行の流れ

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

2. **実行指示の表示**:
   ```
   🤖 Claude Code に以下の指示を送信してください:
   ------------------------------------------------------------
   次のステップを実行してください:

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

   このステップを完了させるために必要な作業を実行してください。
   完了したら、実行内容をまとめて報告してください。
   ------------------------------------------------------------
   ```

3. **Claude Code で作業を実行**

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

### ステップ3: 進捗追跡

#### 基本的な使い方

```bash
python scripts/track_progress.py progress.json
```

#### オプション

- `-f, --filter STATUS`: 特定のステータスのステップのみ表示
  - `pending`: 未着手
  - `in_progress`: 実行中
  - `completed`: 完了
  - `skipped`: スキップ
- `-s, --summary-only`: サマリーのみ表示（詳細を省略）
- `-e, --export FILE`: レポートをMarkdown形式で出力

#### 例

```bash
# 全体の進捗を表示
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を直接編集することで、分解結果をカスタマイズできます:

```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`オプションで再開

```bash
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`ファイルがプロジェクトルートにあることを確認。共通ライブラリが自動的に探索します