feature-dev-loop

Feature Dev Loop

ローカルの開発スキルを書き直すのではなく組み合わせて、要件のベースライン作成、計画の分解、多角的な計画レビュー、安全な逐次実装、動的な受け入れレビュー、HTML 形式の PR サマリー作成まで、ソフトウェア機能開発の一連のループをオーケストレーションします。

これはコントローラースキルです。ステージ間をいつ移行するか、フィードバックをどう分類するか、ループをいつ終了するか、何をディスクに書き込むか、ユーザーをいつ関与させるかを判断します。低レベルの作業では、利用可能な場合、特に以下の既存のローカルスキルを呼び出すか、それらに従ってください。

• superpowers:writing-plans で実装計画を作成します
• superpowers:subagent-driven-development で実装エージェントとレビュアーエージェントを使ってタスクを実行します
• superpowers:test-driven-development で機能とバグ修正を実装します
• superpowers:requesting-code-review でコードレビューを依頼します
• 完了を宣言する前に superpowers:verification-before-completion を使います
• UI の動作を変更する場合は、フロントエンド／ブラウザー検証スキルを使います

運用時のデフォルト

• 複雑な機能作業、複数ステップの変更、PR 規模のタスク、または計画レビュー、サブエージェントレビュー、受け入れテスト、コードレビュー、PR サマリー作成を明示的に求められた場合に使用します。
• 小規模な編集には、ユーザーがフルループを明示的に求めない限り、簡易版を使用します。
• 安全な逐次実装をデフォルトとします。実装ワーカーの並列実行は、ファイル／モジュールの担当範囲が重複せず、共有する契約がすでに確定している場合に限ります。
• 計画レビューの終了時と最終リリース前に、人による確認を挟むことをデフォルトとします。ユーザーが完全自動モードを求めた場合は、終了基準を満たした時点で自動的に進め、すべての前提を記録します。
• プロセスの成果物は、対象リポジトリの docs/dev-loop-runs/YYYY-MM-DD-feature-slug/ に保存します。
• Git の状態を確認しますが、ユーザーから明示的に依頼されない限り、コミット、プッシュ、PR の作成は行いません。
• 無限にループしないでください。各レビューループのデフォルト上限は 3 ラウンドです。
• サブエージェントに関する有効なツールポリシーを守ってください。ユーザーがサブエージェント、委任、エージェントによる計画レビュー、フル機能開発ループ、またはこのスキルを名指しで明示的に求めた場合は、利用可能であればサブエージェントに作業を割り当てます。それ以外の場合は、最初のサブエージェントへの割り当て前に確認するか、レビューをインラインで行い、その制約を記録してください。

依存関係の確認

フルループを開始する前に、現在のセッションで必要なローカルスキルが利用可能か確認します。このスキルは Superpowers 形式の開発ワークフローに依存しています。必要なスキルがない場合に、場当たり的なプロセスへ黙って切り替えてはいけません。

利用可能な場合は、有効なスキル一覧から依存関係を確認します。有効なスキル一覧がない場合は、.agents/skills/superpowers、.codex/superpowers/skills などのローカルスキル／プラグインの場所や、ハーネスのプラグイン一覧を確認します。このスキルで言及されているという理由だけで、依存関係が存在すると想定してはいけません。

必須スキル

以下は、意図されたワークフローに必須です。

• superpowers:writing-plans - 実装計画の分解
• superpowers:subagent-driven-development - 実装エージェントとレビュアーエージェントによる逐次タスク実行
• superpowers:test-driven-development - 挙動の変更におけるレッド／グリーン／リファクタリングの規律
• superpowers:requesting-code-review - 構造化されたコードレビューの依頼
• superpowers:verification-before-completion - 完了を宣言する前のエビデンス確認

推奨スキル

以下は常に必須ではありませんが、関連する場合は使用してください。

• superpowers:brainstorming - 依頼がまだ曖昧な場合や、製品／デザインの意図が明確でない場合
• superpowers:systematic-debugging - 実装やテストでバグが見つかった場合
• superpowers:receiving-code-review - レビュアーのフィードバックを適用する場合
• superpowers:finishing-a-development-branch - ユーザーがマージ、PR、ブランチのクリーンアップに関する案内を求めている場合
• superpowers:using-git-worktrees - ユーザーが分離されたブランチ／ワークツリーでの実行を求めている場合
• フロントエンド／ブラウザー自動化スキル - UI の動作を視覚的に検証する必要がある場合

依存関係が不足している場合の動作

必須スキルが不足している場合：

1. 完全な実行ディレクトリを作成したり、実装を開始したりする前に停止します。
2. 不足している前提スキルを正確にユーザーに伝えます。
3. これらの必須スキルは Superpowers ワークフローで提供されるため、Superpowers のインストールを勧めます。
4. 現在のハーネスで Superpowers 用のプラグインインストールツールを利用できる場合は、使用するか、有効なツールポリシーに従ってユーザーに承認を求めます。利用できない場合は、判明しているハーネスに応じた適切なインストール方法を案内します。
   • Codex App：サイドバーで「Plugins」を開き、「Coding」セクションから Superpowers を見つけて + をクリックし、表示される手順に従います。
   • Codex CLI：/plugins を実行し、superpowers を検索して Install Plugin を選択します。
   • Claude Code：/plugin install superpowers@claude-plugins-official を実行するか、/plugin marketplace add obra/superpowers-marketplace で Superpowers マーケットプレイスを登録してから、/plugin install superpowers@superpowers-marketplace を実行します。
5. ユーザーがインストールした後、依存関係の確認を最初からやり直してから次に進みます。

現在のハーネスでインストールできない場合は、その制約を明確にしたうえでのみ、縮小インラインモードを提案します。縮小インラインモードでも実行成果物を作成し、サブエージェント／Superpowers の依存関係を利用できなかったことを記録する必要があります。

インストール方法とワークフロー名の参照先：https://github.com/obra/superpowers

フィードバックの重要度

レビュアーのすべてのコメントには、次の重要度を使用する必要があります。

• BLOCKER：ループを終了する前に解決する必要があります。
• IMPORTANT：終了前に解決することが望まれます。コントローラーは、根拠を書面で示した場合に限り、裁定して終了できます。
• QUESTION：終了前に回答するか、具体的な変更に置き換える必要があります。
• NIT：進行を妨げない改善です。記録しますが、進行をブロックしないでください。

未解決の BLOCKER、IMPORTANT、QUESTION がない場合に限り、フェーズを終了できます。残った NIT はフォローアップ項目とします。

実行ディレクトリ

実行の開始時に：

1. 利用できる場合は git rev-parse --show-toplevel でリポジトリのルートを特定します。
2. git status -sb を確認します。
3. base_sha、現在のブランチ、変更状態の概要、ユーザーの依頼、モードを記録します。
4. 次を作成します。

docs/dev-loop-runs/YYYY-MM-DD-feature-slug/
  00-requirements.md
  01-plan.md
  02-plan-review-rounds.md
  03-implementation-log.md
  04-acceptance-report.md
  05-pr-summary.html
  artifacts/
    screenshots/
    test-outputs/

作業ツリーに変更がある場合は、元に戻さないでください。既存の変更が依頼されたタスクに関連するかどうかを判断します。判断が難しく、リスクがある場合は、編集する前にユーザーに確認します。

フェーズ 1：要件のベースライン

計画を立てる前に 00-requirements.md を作成します。

次の構成を使用します。

# Requirements Baseline

## Goal
## Non-goals
## User-visible Behavior
## Acceptance Criteria
## Constraints
## Assumptions
## Open Questions
## Source Request
## Repo Context

アーキテクチャ、データモデル、セキュリティ、ユーザーエクスペリエンス、互換性、テスト戦略に重大な影響を与える未解決の質問に限って、ユーザーに尋ねます。通常の実装上の詳細はリポジトリの慣例から推測し、前提として記録します。

解決を妨げる未解決の質問が残っている間は、計画の分解に進まないでください。

フェーズ 2：計画の分解

計画を書く前にコードベースを調査します。rg と既存のプロジェクト文書／テストを優先します。リポジトリを手本に、実装スタイルを把握します。

01-plan.md を作成します。利用できる場合は、superpowers:writing-plans に従います。

計画には次を含める必要があります。

• 正確な目標とアーキテクチャの概要
• 変更が見込まれるファイル／モジュール
• タスクの順序と依存関係
• テスト戦略と正確な検証コマンド
• 作業者となるサブエージェントの担当範囲
• 00-requirements.md に対応付けた受け入れ基準
• 既知のリスクと前提

タスクは、個別に実装およびレビューできる程度に小さくします。共有コントラクトが必要な場合は、依存するタスクより前に配置します。

フェーズ 3：複数の視点による計画レビューの反復

サブエージェントを利用でき、許可されている場合は、異なる視点を持つ複数の計画レビュアー用サブエージェントを起動します。各レビュアーには、要件ファイル、計画ファイル、関連するリポジトリの規約、要求する出力スキーマなど、正確なコンテキストを提供します。会話履歴全体を渡してはいけません。

デフォルトのレビュアーの視点：

• アーキテクチャレビュアー：分割、境界、依存関係の順序、拡張性、統合リスク
• テスト戦略レビュアー：受け入れ基準、回帰テストの網羅性、失敗時の経路、検証コマンド
• プロダクト／仕様レビュアー：ユーザーから見える動作、要件の抜け、対象外事項、曖昧な意味
• リスク／複雑性レビュアー：隠れた複雑性、移行リスク、段階的な展開に関する懸念、保守性を損なう落とし穴

各レビュアーは次を返す必要があります：

## Verdict
APPROVED | COMMENTS

## Comments
- id:
  severity: BLOCKER | IMPORTANT | QUESTION | NIT
  area:
  target:
  comment:
  required_change:

## Approval Conditions

すべてのフィードバックを 02-plan-review-rounds.md に集約します。

各ラウンドでは：

1. 有効な BLOCKER、IMPORTANT、QUESTION のフィードバックすべてに対応できるよう、計画を修正します。
2. コメントを却下する場合は、裁定とその根拠を記録します。
3. 差分だけでなく、改訂後の計画全体をレビュアーに再レビューしてもらいます。
4. 3 ラウンドで終了し、未解決の阻害要因となる意見の相違があれば、具体的な推奨事項とともにユーザーにエスカレーションします。

すべてのレビュアーが承認するか、NIT の項目だけが残った場合、計画レビューを終了します。

計画ゲート

ユーザーが自動モードを指定していない限り、実装の前に簡潔な計画の概要を示し、承認を求めます：

• 目標
• 主なファイル／モジュール
• タスクの順序
• 主なリスク
• 検証戦略

フェーズ 4：安全な逐次実装

計画の順序に従い、一度に 1 つのタスクを実装します。計画が十分に明確で、ワーカーサブエージェントが適切な場合は superpowers:subagent-driven-development を使用します。動作を変更する場合は superpowers:test-driven-development を使用します。

各タスクでは：

1. ファイル／モジュールの担当範囲を明確に割り当てます。
2. ワーカーには、コードベースで作業しているのは自分たちだけではないこと、他者の編集を取り消してはならないこと、既存の変更に合わせて作業することを伝えます。
3. 可能な場合は TDD を優先し、実装前に失敗するテストを作成して検証します。
4. タスク固有の検証コマンドを実行します。
5. 変更内容、コマンド、結果、懸念事項を 03-implementation-log.md に記録します。
6. タスクに重要な動作やリスクがある場合は、タスクレベルで仕様準拠とコード品質をレビューします。
7. 共通の重大度ルールに従って、レビューで見つかった問題を解決します。

デフォルトでは逐次実装とします。並行実装は、次の条件をすべて満たす場合にのみ許可されます：

• タスクが互いに異なるファイル／モジュールを対象としている
• 共通の契約がすでにコミットされているか、または他の方法で安定している
• 各ワーカーの担当範囲が明確である
• コントローラーが出力を安全に統合してレビューできる

ユーザーがコミットまたは PR モードを明示的に要求していない限り、チェックポイントコミットを作成してはいけません。

フェーズ 5：動的受け入れマトリクス

実装後、実際の変更範囲に基づいてレビュアーを選びます。

必ず実施します：

• 要件受け入れレビュアー：00-requirements.md および 01-plan.md に照らして、実装された動作を確認します
• テストカバレッジレビュアー：テスト、不足しているケース、回帰リスク、検証コマンドが信頼できるかを確認します
• コード品質レビュアー：正確性、保守性、統合、エッジケース、潜在的な回帰を確認します

条件に応じて実施します：

• フロントエンド UX レビュアー：UI、操作性、レイアウト、アクセシビリティ、または視覚的な変更がある場合。ブラウザーまたはスクリーンショットによる証拠が必要です
• セキュリティレビュアー：認証、権限、シークレット、アップロード、外部入力、支払い、またはデータ露出がある場合
• パフォーマンスレビュアー：クエリ、レンダリングループ、並行処理、キャッシュ、バッチ処理、または大規模データの処理経路に関わる場合
• ドキュメント／移行レビュアー：設定、移行、API の動作、セットアップ手順、またはユーザー向けの動作に変更がある場合
• 互換性レビュアー：公開 API、スキーマ、シリアル化データ、プラグイン、または統合コントラクトに関わる場合

各受け入れレビュアーに次の情報を渡します：

• 要件の基準
• 最終計画
• 実装ログ
• base_sha と現在の HEAD または作業ツリーの差分
• 関連するテスト出力とスクリーンショット
• 各レビュアー固有のレビュー指示

各レビュアーは次を返します：

## Verdict
PASS | PASS_WITH_NOTES | FAIL

## Scope Checked
## Evidence
## Findings
- id:
  severity: BLOCKER | IMPORTANT | MINOR
  target:
  finding:
  suggested_fix:
  evidence:

## Residual Risks

結果を 04-acceptance-report.md に集約します：

# Acceptance Report

## Verdict
PASS | PASS_WITH_NOTES | FAIL

## Scope Checked
## Reviewers Run
## Tests Run
## Requirement Coverage
## Findings
## Fixes Applied
## Residual Risks
## Follow-ups

次の条件をすべて満たした場合にのみ、受け入れを完了します：

• BLOCKER が残っていない
• 未解決の IMPORTANT が残っていない
• 検証コマンドが成功しているか、利用できないコマンドについて明確な説明がある
• コントローラーが正直に PASS または PASS_WITH_NOTES を割り当てられる

受け入れに失敗した場合は、問題を修正し、関連するレビュアーに再レビューを依頼します。3 ラウンドで停止し、ブロッカーレポートとともにエスカレーションします。

フェーズ 6：HTML PR サマリー

自己完結型で、要約を最初に示す HTML レポートとして 05-pr-summary.html を生成します。PR レビュアーが変更をすばやく理解できるようにしつつ、展開可能な監査詳細も保持します。

最初の画面で次の内容が分かるようにします：

• この PR が解決する問題
• 変更内容
• ユーザーから見える動作の変更
• 検証結果と受け入れ判定
• 残存リスクとフォローアップ項目

次の項目について、展開可能な詳細セクションを含めます：

• 要件の基準
• 計画レビューの概要
• 実装ログ
• 受け入れマトリクス
• 実行したテストと主要な出力
• コードレビューの指摘事項
• 該当する場合はスクリーンショットまたは成果物
• 主な差分または変更ファイルの概要

外部ネットワークへの依存がない、シンプルで読みやすい HTML と CSS を使用します。可能な場合は、相対パスでローカルの成果物にリンクします。

Git ポリシー

• 現在のブランチと base_sha を必ず確認し、記録します。
• 破壊的な git コマンドは実行しません。
• ユーザーから明示的に依頼されない限り、ユーザーの変更を元に戻しません。
• ユーザーから明示的に依頼されない限り、コミット、プッシュ、PR の作成は行いません。
• コミットを依頼された場合は、非対話型の git コマンドを使用し、完了して検証済みの単位ごとにコミットを分けます。
• コミットがない場合は、git diff と git status から概要を生成します。

ユーザーへのエスカレーションルール

次の場合にのみ、ユーザーに確認します：

• 要件の曖昧さによって、アーキテクチャ、UX、データモデル、セキュリティ、互換性、または受け入れ基準が変わる場合
• 既存のワークスペースの変更により、安全な編集方法が明確でない場合
• レビューループが 3 ラウンドに達し、ブロッカーに関する意見の相違が未解決の場合
• 依頼された動作がリポジトリの制約または安全要件に反する場合

確認する際は、一度に具体的な質問を 1 つだけ行い、推奨する回答も提示します。

完了チェックリスト

最終回答の前に、次を確認します：

• 00-requirements.md が存在する
• 01-plan.md が存在し、計画レビューに合格しているか、裁定内容が記録されている
• 03-implementation-log.md にタスク、変更ファイル、検証の証拠が記録されている
• 04-acceptance-report.md に明確な判定がある
• 05-pr-summary.html が存在する
• 必須のテストまたはチェックが実行済みであるか、実行できなかった理由が記録されている
• 未解決の BLOCKER、IMPORTANT、QUESTION が残っていない

その後、レポートのパスと検証状況を含め、結果を簡潔にユーザーへ報告します。