sparv

SPARV

5 フェーズのワークフロー：Specify → Plan → Act → Review → Vault.

目標：「要件 → 検証可能な成果物」を 1 回の作業で完了し、推測に頼るのではなく、重要な決定を外部メモリに記録します。

コアルール（必須）

• 10 点の Specify ゲート：仕様スコアは 0-10。Plan に進むには >=9 が必要です。
• 2 アクションごとの保存：ツール呼び出しを 2 回行うごとに .sparv/journal.md にエントリーを追記します。
• 3 回失敗プロトコル：失敗が 3 回連続したら停止し、ユーザーにエスカレーションします。
• EHRB：高リスク（本番環境／機密データ／破壊的操作／課金 API／セキュリティ上重要）が検出された場合は、ユーザーの明示的な確認を求めます。
• 固定フェーズ名：specify|plan|act|review|vault（.sparv/state.yaml:current_phase に保存）。

拡張ルール（v1.1）

不確実性の宣言（G3）

Specify のいずれかの項目のスコアが 2 未満の場合：

• 次のように宣言します：UNCERTAIN: <what> | ASSUMPTION: <fallback>
• Plan に進む前に、すべての仮定をジャーナルに記載します。
• 要件が曖昧な場合は、2～3 個の選択肢を提示します。

例：

UNCERTAIN: deployment target | ASSUMPTION: Docker container
UNCERTAIN: auth method | OPTIONS: JWT / OAuth2 / Session

要件の振り分け

モード	条件	フロー
Quick	スコア >= 9、ファイル数 <= 3、かつ EHRB なし	Specify → Act → Review
Full	それ以外	Specify → Plan → Act → Review → Vault

Quick モードでは正式な Plan フェーズを省略しますが、次の要件は引き続き適用されます：

• 完了の約束をジャーナルに記載する
• 2 アクションごとの保存ルールを適用する
• Review フェーズは必須

コンテキストの取得（任意）

Specify のスコア付けの前に：

1. .sparv/kb.md を確認し、既存のパターンや決定事項を調べます。
2. 不十分な場合は、関連ファイルを探すためにコードベースをスキャンします。
3. 調査結果を ## Context としてジャーナルに記録します。

ユーザーが完全なコンテキストを明示的に提供している場合は省略します。

ナレッジベースのメンテナンス

Vault フェーズ中に .sparv/kb.md を更新します：

• パターン：発見した再利用可能なコードパターン
• 決定事項：アーキテクチャ上の選択とその根拠
• 注意点：よくある落とし穴と解決策

CHANGELOG の更新

重要な変更の場合、Review または Vault フェーズで使用します：

~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."

外部メモリ（2 ファイル）

初期化（プロジェクトのルートで実行）：

~/.claude/skills/sparv/scripts/init-session.sh --force

ファイルの規約：

• .sparv/state.yaml：状態マシン（最低限必要なフィールド：session_id/current_phase/action_count/consecutive_failures）
• .sparv/journal.md：統合ログ（Plan／Progress／Findings をすべてここに記録）
• .sparv/history/<session_id>/：アーカイブディレクトリ

フェーズ 1：Specify（10 点満点）

各項目を 0／1／2 点で採点し、合計 0～10 点とします：

1. 価値：実施する理由、メリットや指標が検証可能か
2. 範囲：MVP と対象外の内容
3. 受け入れ条件：テスト可能な受け入れ基準
4. 境界条件：エラー／パフォーマンス／互換性／セキュリティに関する重要な境界条件
5. リスク：EHRB／依存関係／不明点と、その対処方法

score < 9：質問を続け、Plan に進まないでください。 score >= 9：明確な completion_promise（検証可能な完了の約束）を記述してから、Plan に進みます。

フェーズ 2：Plan

• タスクを 2～5 分単位の小さな作業に分解し、それぞれに検証可能な成果物またはテストポイントを設定します。
• 計画を .sparv/journal.md に記述します（Plan セクション、または末尾に追記）。

フェーズ 3：Act

• TDD ルール：失敗するテストがなければ、本番コードを書きません。
• 2 アクションごとにジャーナルを自動的に書き込みます（PostToolUse フック）。
• 失敗のカウント（3 回失敗プロトコル）：

~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short blocker"
~/.claude/skills/sparv/scripts/failure-tracker.sh reset

フェーズ 4：Review

• 2 段階で確認します：仕様への準拠 → コード品質（正確性／パフォーマンス／セキュリティ／テスト）。
• 修正は最大 3 回までです。超過した場合はユーザーにエスカレーションします。

セッション終了前に 3 つの質問による再起動テストを実行します：

~/.claude/skills/sparv/scripts/reboot-test.sh --strict

フェーズ 5：Vault

現在のセッションをアーカイブします：

~/.claude/skills/sparv/scripts/archive-session.sh

スクリプトツール

スクリプト	目的
scripts/init-session.sh	.sparv/ を初期化し、state.yaml と journal.md を生成します
scripts/save-progress.sh	action_count を管理し、2アクションごとに journal.md に追記します
scripts/check-ehrb.sh	差分／テキストをスキャンし、ehrb_flags を出力します（任意で書き込み可能）
scripts/failure-tracker.sh	consecutive_failures を管理し、3回に達すると終了コード 3 を返します
scripts/reboot-test.sh	3つの質問によるセルフチェック（任意の厳格モード）
scripts/archive-session.sh	journal.md と state.yaml を history/ にアーカイブします

自動フック

hooks/hooks.json:

• PostToolUse：save-progress.sh（2アクションごとに保存）
• PreToolUse：check-ehrb.sh --diff --dry-run（プロンプトのみ、状態は書き込みません）
• Stop：reboot-test.sh --strict（3つの質問によるセルフチェック）

---

速度より品質を重視し、本当に完了するまで反復してください。