Propose Implementation Plan Skill (実装計画提案スキル)
目的
implement-commitスキルを駆動するTOML実装計画を作成します。
計画は機械がパース可能でなければなりません。オーケストレーターが機械的に読み取ります。
使用タイミング
- 機能設計ドキュメントが存在し、承認されている
- 実装を開始する準備ができている
- 作業を調整したり、進捗を追跡する必要がある
前提条件
- 機能設計が
docs/features/NNNN-feature-name/design.mdに存在する - テスト計画が
docs/features/NNNN-feature-name/test-plan.mdに存在する
出力形式
docs/features/NNNN-feature-name/implementation-plan.toml を作成します。
[meta]
feature = "feature-name"
feature_dir = "docs/features/NNNN-feature-name"
workspace = "./path/to/workspace"
[dependencies]
1 = []
2 = []
3 = [1, 2]
[[commits]]
id = 1
title = "短い説明"
message = "feat(scope): conventional commit message"
files = ["path/to/file.rs"] # ワークスペースからの相対パス
acceptance = ["CCテーブルからの基準 (CC-N)"]
anti_patterns = ["やってはいけないこと"]
tests = ["test_name_from_test_plan"] # 必須: test-plan.md にマッピング
手順
1. 設計ドキュメントを調査する
design.md をよく読み、以下に注意します。
- モジュール構造と影響を受けるファイル
- コンポーネント間の依存関係
- 重要制約テーブル (CC-1, CC-2, ...)
2. テスト計画を調査する (重要)
test-plan.md を読み、マッピングを作成します。
- 要件カバレッジテーブルからすべてのテスト名をリストアップする
- 各テストは必ず1つのコミットに割り当てる
- テストは受け入れ基準の真実の情報源です
3. 機能境界を特定する
コード成果物の境界ではなく、機能境界を探します。
良い境界の例:
- 新しいモジュール（型、実装、テストをまとめて）
- ユーザーが認識できる機能 (例: 新しいCLIコマンド)
- エンドツーエンドで満たされる要件
アンチパターン: 成果物ごとに分割する (型を1つのコミット、実装を別のコミット、テストをさらに別のコミット)。
4. 依存関係グラフを構築する
各コミットについて、先に完了しておく必要があるコミットをリストアップします。
[dependencies] テーブルとしてエンコードします。キーはコミットID、値は依存コミットIDのリストです。
オーケストレーターはこれを使って並列実行を判断します。
5. テストをコミットにマッピングする
各コミットについて、それを検証する test-plan.md の特定のテスト名をリストアップします。
tests = [
"test_protocol_encode_acquire_request",
"test_protocol_decode_roundtrip",
]
test-plan.md のすべてのテストは、正確に1つのコミットの tests 配列に出現しなければなりません。
これにより、監査可能なトレースが作成されます: test-plan.md → implementation-plan.toml → コード。
6. 重要制約を抽出する
各コミットについて、設計の重要制約テーブルから関連エントリをコピーします。
acceptance= 必ず満たさなければならない基準 (CC-N とテスト名を参照)anti_patterns= レビューアが拒否すべきもの
7. コミットエントリを記述する
各コミットについて:
[[commits]]
id = N # 連続する整数
title = "..." # このコミットが達成すること
message = "..." # 完全な conventional commit メッセージ
files = ["..."] # ワークスペースからの相対パス
acceptance = ["..."] # CCテーブル + テスト説明から
anti_patterns = ["..."] # CCテーブルから、または空の []
tests = ["..."] # test-plan.md からのテスト名 (必須)
8. 独立したエージェントで検証する
計画の草案を作成した後、検証エージェントを起動します。
result = spawn(
prompt=draft_spawn_prompt(SkillDefined(
"実装計画が test-plan.md のすべてのテストをカバーしていることを検証する"
)),
context_files=[
f"{skill_dir}/agents/verifier.md",
f"{feature_dir}/test-plan.md",
f"{feature_dir}/implementation-plan.toml",
],
response_model=VerificationResult,
read_only=True,
)
if not result.parsed.valid:
# ギャップを修正してから続行
agent_feedback(f"計画が不完全です: {result.parsed.gaps}")
検証エージェントは以下をチェックします。
- test-plan.md のすべてのテストがコミットに割り当てられている
- どのテストも複数のコミットに割り当てられていない
- 受け入れ基準が特定のテストを参照している
9. TOML を検証する
# TOML がパースできるか確認
python3 -c "import tomllib; tomllib.load(open('implementation-plan.toml', 'rb'))"
コミットサイズのガイドライン
目標: コミットあたり 200～400 行の変更
小さすぎる:
- 実装のない型
- 少なくとも1つの実装がないトレイト
- テストのない実装
大きすぎる:
- 複数の無関係な機能
- 500行を超える
- 5～6ファイル以上に触れる
ちょうど良い:
- 型、実装、テストを含むモジュール (約200～400行)
- ハンドラとテストを含むCLIコマンド (約150～350行)
- テストを含む完全なアダプタ (約200～400行)
検証モデル
from pydantic import BaseModel
class VerificationResult(BaseModel):
valid: bool
total_tests_in_plan: int
tests_assigned: int
gaps: list[str] # どのコミットにも割り当てられていないテスト
duplicates: list[str] # 複数のコミットに割り当てられているテスト
例
完全な例については、docs/features/0000-templates/implementation-plan.toml を参照してください。
次のステップ
計画を作成して検証した後:
- 実現可能性とサイズを確認する
implement-commitスキルを実行して実装する