Imported from kagyuu/SpecDrivenDevSkill (
V0.8/SKILL.md). Install upstream withnpx skills add kagyuu/SpecDrivenDevSkill --skill V0.8. Copyright stays with the author.
name: spec-driven-dev description: 仕様駆動でアプリケーションを開発するときに、設計から実装・テスト・納品まで人間のレビューを挟まず一気通貫で実行し、事後の変更要求(CR)にもとづく改修だけ人間とやり取りする。
仕様駆動開発 (Spec-Driven Dev)
- 本格的なアプリケーションを、要件定義から実装・テスト・納品まで一気通貫で作らせるための、使い回し可能なフェーズ・ワークフロー。
- 各フェーズは、現在のプロジェクトの
docs/配下にMarkdown成果物を生成する。1回の実行につき1フェーズだけ進める。 - 次フェーズに必要な情報が技術的に揃っていても、複数フェーズを一度に進めてはいけない。
- 各フェーズは前フェーズの内容が正しいことを前提にしているため、フェーズを飛ばすとこの手順の意味がなくなる。
- V0.3までと異なり、フェーズごとに人間のレビューを待たない。設計の矛盾チェックや実装後のテストはすべてAI自身が行い、既定の停止条件(3回差し戻しても解消しないなど)に達した場合のみ処理を止めて人間に報告する。
- 各フェーズは、現在のプロジェクトの
- ソースコードの作成やテストの実施は、この SKILL が生成する Markdown (定義書、または定義書兼作業指示書) にもとづいて行う。定義書の作成と、それにもとづく実装・テストの実行は、性能の異なるAgent(高性能モデル/低性能モデル)に分担させることを想定する。
- このワークフローは日本のシステム開発で標準的なソフトウェアの製造工程(ウォーターフォール/V字モデル)をベースに、設計・実装・テスト・納品までを1セッションの中で完結させる。
- 納品後にユーザーから改善・修正の要望が出た場合は、変更要求書(CR)を作成したうえで
Refactor(修正)ステップに入り、必要なフェーズだけをやり直す。ADR(Architecture Decision Record)とCR(Change Request)は V0.4 から導入する新しい成果物であり、それぞれ「なぜ今の仕様になっているか」「何をどう変えてほしいか」を、後続のAIが読み直しやすい大きさに要約して残す。
アプリケーションの作成ステップ
以下の7ステップに沿って、後述の「WBS」に列挙したフェーズ(P番号)を順番に実行する。P番号は 001〜999 の通し番号で、Stepをまたいでも重複しない。
Require Development Step (システム要求定義)
- 概要: システム要求定義を作成する
- 作業主体: 人間 + AI (Wizard形式orひな形提供)
- 終了条件: システム要求定義が作成される
- 差戻条件: なし
- 停止条件: なし
WBS (PはPhaseの略)
- P001 システム要件定義
Plan Loop Step (設計)
- 概要: P001システム要件定義をもとに、仕様を詳細化して、実装を行えるようにする
- 作業主体: AI (高性能モデル)
- 終了条件: P010設計書横断レビューで、設計書全体の整合性をレビューする。矛盾がなければ Overview Step に移行する
- 差戻条件: P010設計書横断レビューで矛盾があれば、P011影響分析・P012設計書修正を行い、再度P010を行う
- 停止条件: P010を3回実行してもなお設計の矛盾が解消されなければ、処理を停止して人間に報告する(Refactor経由の再入時は、対象CRごとに実行回数をリセットして数える)
- その他: 変更要求(CR)にもとづいて設計書を修正した場合、その修正が新たな技術的決定を含む場合はADR(P021、Refactor経由ではP905)に追記する。文言修正や既存決定の範囲内にとどまる修正など、新たな技術的決定を伴わない修正はADR追記を要しない(要否の判定はP021/P905が行う)。
- その他: 非機能要件のうちインフラ寄りの項目(可用性・TLS・スケーラビリティ・ログ集約基盤など)の担当フェーズについては、
SKILL-P003-backend-spec.mdの規定に従う(P003が確定できない範囲はP005・P302に委譲する旨をP003側に明記させる。詳細は同ファイル参照)。P004・P010の充足確認は、この委譲先の記載を踏まえて判定する。
WBS (PはPhaseの略)
- P002 ユーザインタフェース設計 (既存のP002、およびP001・P021・CRから作成/更新する)
- P003 システム詳細設計 (既存のP003、およびP001・P002・P021・CRから作成/更新する)
- P004 要求トレーサビリティマトリクス作成 (P001で定義された要求事項がP002・P003で満たされているかを検証する。満たされていない箇所は、その内容の性質に応じてP002またはP003に差し戻す。詳細は
SKILL-P004-traceability-matrix.mdを参照) - P005 実装計画 (既存のP005、およびP001・P002・P003・P004・P021・CRから作成/更新する)
- P006 テスト計画 (既存のP006、およびP001・P002・P003・P004・P005・P021・CRから作成/更新する)
- P007 プログラム実装定義 (既存のP007、およびP002・P003・P005・P006から作成/更新する)
- P008 結合テスト定義 (既存のP008、およびP002・P003・P005・P006・P007から作成/更新する。スプリント内/モジュール間の結合テストが対象)
- P009 受け入れ結合テスト定義 (既存のP009、およびP001・P006から作成/更新する。スプリントをまたぐ結合テスト・システムテスト・受入テストが対象)
- P010 設計書横断レビュー (P001〜P009を横断的にレビューして、矛盾点を列挙する。矛盾点がなければ設計ループは終わり)
- P011 影響分析 (P010で列挙した矛盾点の関係箇所を分析する)
- P012 設計書修正 (P011で分析した関係箇所を修正して、再度P010を行う)
Overview Step (概観)
- 概要: 設計内容を整理して、後続処理のAIがすべての資産を読み直さなくてよいようにする
- 作業主体: AI (高性能モデル)
- 終了条件: P020、P021、P022が完成
- 差戻条件: なし
- 停止条件: 必要な成果物が不足していた場合、処理を停止して人間に報告する
WBS (PはPhaseの略)
- P020 実装構造生成/修正 (コードベースがあれば、その目次となる
{ソースツリー}/INDEX.mdを作る。無ければ、見出しと「(実装前)」の注記を持つ最小限のプレースホルダファイルを作る。ソースツリーのディレクトリ自体が無ければ先にディレクトリを作成する。INDEX形式に準じる。主にAIが参照するが人間も見る) - P021 ADR.mdを整理する (仕様決定までの経緯を整理して、最終的にその仕様になった理由を簡潔に整理する。LLMが読み込める程度に小さくする。削除した経緯は別途ADR_master.mdに退避する)
- P022 ArchitectureHandbook.mdを作る (アプリケーションの技術的側面を明らかにする。ADR.md(P021)を入力として参照するため、P021の後に実行する)
Executor (実装)
- 概要: P007プログラム実装定義、P008結合テスト定義にもとづいて実装とテストを行う
- 作業主体: AI (低性能モデル)
- 終了条件: P103結合テストが終わったら、Reviewer Loop (最終確認ループ)に移行する (結合テストに失敗があってもよい)
- 差戻条件: なし
- 停止条件: P102プログラム実装で、3回自己修正しても単体テストを合格にできない場合は、処理を停止して人間に報告する
WBS (PはPhaseの略)
- P101 実装コンテキスト構築 (P020・P021・P022から実装に必要なコンテキストを構築する)
- P102 プログラム実装 (P007・P020・P021・P022にもとづいて実装・修正を行い、単体テストを行う。単体テストはスプリント内ですべて合格させる)
- P103 結合テスト実行 (P008・P020・P021・P022にもとづいて結合テストを行う。結合テストに失敗しても修正せず記録に残すのみとする)
- P104 実装構造修正 (コードベースの目次となる
{ソースツリー}/INDEX.mdを更新する。INDEX形式に準じる。主にAIが参照するが人間も見る)
Reviewer Loop (最終確認ループ)
- 概要: すべての結合テスト・受け入れ結合テストの失敗を解消する
- 作業主体: AI (高性能モデル)
- 終了条件: P201で結合テスト・受け入れ結合テストにすべて合格していることが確認できたら Closing (納品物作成)に移行する
- 差戻条件: P201で失敗しているテストを見つけた場合には、P202〜P205で修正を行う
- 停止条件: P201を3回実行してもなお結合テスト・受け入れ結合テストにすべて合格とならなければ、処理を停止して人間に報告する(Refactor経由の再入時は、対象CRごとに実行回数をリセットして数える。通算では数えない)
WBS (PはPhaseの略)
- P201 実装横断レビュー (P103の結合テストにすべて合格すること、および未実施のP009受け入れ結合テストを実行してすべて合格することを確認する)
- P202 修正計画 (P201でみつけた失敗したテストの修正計画を作成する)
- P203 修正実施 (P202の計画にもとづき修正を行う)
- P204 影響分析 (P203の修正内容が、他機能を壊していないかを確認する。他機能を壊している場合はP202に差し戻す)
- P205 結合テスト再実施 (P103・P009を再実施して、P201の判断を行う。すべてのテストに合格でなければP202に差し戻す)
Closing (納品物作成)
- 概要: 作成した資産から納品物を作る
- 作業主体: AI (低性能モデル)
- 終了条件: P301、P302が完成
- 差戻条件: なし
- 停止条件:
SKILL-P302-deliver.mdの実行前チェック項目7・8の是正が仕様変更を要し、コード修正のみでは解消できない場合、処理を停止して人間に報告する(この場合はP302を完了させず、該当事項をCRの起票候補として記録する)
WBS (PはPhaseの略)
- P301 このプロジェクトリポジトリ全体の
./INDEX.mdを作成する (INDEX形式に準じ、主にAIが参照する。人間も見る。ただしソースツリーは操作せず{ソースツリー}/INDEX.mdのみを./INDEX.mdに載せる) - P302 納品物作成 (docker compose化、起動方法の説明書作成)
Refactor (修正)
- 概要: 変更要求(CR)にもとづいて、設計書・実装の修正を行う
- 作業主体: 人間 + AI
- 終了条件: P002〜P302が再完了する
- 差戻条件: なし
- 停止条件: なし
- 利用シーン1: 新規アプリ作成で、いったんP002〜P302をAIに任せて作った後に、変更要求にもとづいてAIに修正を行わせる (P002〜P302を実行する)
- 利用シーン2: 既存アプリ改修で、改修要件を変更要求書に取りまとめてAIに修正を行わせる (P001〜P302を実行する)
WBS (PはPhaseの略)
- P901 変更要求作成 (人間から任意の形式で示された要望を、
TEMPLATE-P901-cr-direction.mdにもとづきdocs/P901-cr-direction/CR-NNN.mdとして起票し、docs/CR.md(状態の台帳)に1行追加する) - P902 既存のP001および変更要求から、P001システム要件定義を更新する (原本はリネームして保持する)
- P903 修正 (着手前に
docs/P903-cr-records/CR-NNN.mdを作成してスコープ決定を記録したうえで、P002〜P302を実行する。完了時に変更内容・事前想定との差異・テスト結果を追記する) - P904 変更要求の内容が設計・実装に盛り込まれているか確認する (「期待する振る舞い」の各項目をテストIDと突き合わせ、結果を
docs/P903-cr-records/CR-NNN.mdに追記し、docs/CR.mdの状態列を更新する) - P905 今回の変更要求にともなうADRの更新を確認する (判定結果を
docs/P903-cr-records/CR-NNN.mdに追記する)
フェーズ一覧
| Step | フェーズ | フェーズ名 |
|---|---|---|
| Require Development Step | P001 | システム要件定義 |
| Plan Loop Step | P002 | ユーザインタフェース設計 |
| Plan Loop Step | P003 | システム詳細設計 |
| Plan Loop Step | P004 | 要求トレーサビリティマトリクス作成 |
| Plan Loop Step | P005 | 実装計画 |
| Plan Loop Step | P006 | テスト計画 |
| Plan Loop Step | P007 | プログラム実装定義 |
| Plan Loop Step | P008 | 結合テスト定義 |
| Plan Loop Step | P009 | 受け入れ結合テスト定義 |
| Plan Loop Step | P010 | 設計書横断レビュー |
| Plan Loop Step | P011 | 影響分析 |
| Plan Loop Step | P012 | 設計書修正 |
| Overview Step | P020 | 実装構造生成/修正 |
| Overview Step | P021 | ADR整理 |
| Overview Step | P022 | ArchitectureHandbook作成 |
| Executor | P101 | 実装コンテキスト構築 |
| Executor | P102 | プログラム実装 |
| Executor | P103 | 結合テスト実行 |
| Executor | P104 | 実装構造修正 |
| Reviewer Loop | P201 | 実装横断レビュー |
| Reviewer Loop | P202 | 修正計画 |
| Reviewer Loop | P203 | 修正実施 |
| Reviewer Loop | P204 | 影響分析 |
| Reviewer Loop | P205 | 結合テスト再実施 |
| Closing | P301 | 全体INDEX作成 |
| Closing | P302 | 納品物作成 |
| Refactor | P901 | 変更要求作成 |
| Refactor | P902 | 要件定義更新 |
| Refactor | P903 | 修正実施 |
| Refactor | P904 | 変更要求の反映確認 |
| Refactor | P905 | ADR更新確認 |
各フェーズで作成するドキュメント
| フェーズ | ドキュメント名 | ドキュメントの内容 | Agentに対する実行指示書を兼ねる設計書 |
|---|---|---|---|
| P001 | docs/P001-requirement.md |
システム要件定義書 | |
| P002 | docs/P002-frontend-spec.md |
ユーザインタフェース設計書 | |
| P003 | docs/P003-backend-spec.md |
システム詳細設計書 | |
| P004 | docs/P004-traceability-matrix.md |
要求トレーサビリティマトリクス | |
| P005 | docs/P005-impl-plan.md |
実装計画書 | |
| P006 | docs/P006-test-plan.md |
テスト計画書 | |
| P007 | docs/P007-impl-direction.md |
プログラム実装定義 兼 プログラミング指示書 の目次(OKF形式) | ✓ |
| P007 | docs/P007-impl-direction/U000-{sprint-name}.md |
プログラム実装定義 兼 プログラミング指示書 の内容(1ファイル=1スプリント。内部に複数タスクU0NN-TxxをOKF副目次付きで含む。TEMPLATE-P007-impl-direction.md参照) |
✓ |
| P008 | docs/P008-test-direction.md |
結合テスト定義(スプリント内/モジュール間) 兼 結合テスト指示書 の目次(OKF形式) | ✓ |
| P008 | docs/P008-test-direction/T000-{test-name}.md |
結合テスト定義 兼 結合テスト指示書 の内容 | ✓ |
| P009 | docs/P009-acceptance-direction.md |
受け入れ結合テスト定義(スプリント横断/システム/受入) 兼 テスト指示書 の目次(OKF形式) | ✓ |
| P009 | docs/P009-acceptance-direction/A000-{test-name}.md |
受け入れ結合テスト定義 兼 テスト指示書 の内容 | ✓ |
| P010 | docs/P010-design-review.md |
設計書横断レビュー結果(矛盾点一覧) | |
| P011 | docs/P011-impact-analysis.md |
矛盾点の影響分析結果 | |
| P012 | (該当するP002〜P009の各文書を直接更新する。専用文書はなし) | 設計書修正差分の記録 | |
| P020 | {ソースツリー}/INDEX.md |
実装構造の目次(INDEX形式) | |
| P021 | docs/ADR.md / docs/ADR_master.md |
現在有効な設計判断(ADR) / 廃止済みADRの退避先 | |
| P022 | docs/ArchitectureHandbook.md |
アプリケーションの技術的側面のハンドブック | |
| P101 | docs/P101-impl-context.md |
実装担当Agent向けの実装コンテキスト要約 | ✓ |
| P102 | {application root}/ 配下のソースコード + 単体テスト |
プログラム実装成果物 | |
| P103 | docs/test-records/YYYYMMDD-HHMM-test-record.md |
結合テスト実行記録 | |
| P104 | {ソースツリー}/INDEX.md |
実装構造の目次(更新後) | |
| P201 | docs/P201-review-report.md |
実装横断レビュー結果 | |
| P202 | docs/P202-fix-plan.md |
修正計画書の目次(OKF形式) | ✓ |
| P202 | docs/P202-fix-plan/F000-{fix-name}.md |
個別修正指示書(未対応分) | ✓ |
| P202 | docs/P202-fix-plan/fixed/F000-{fix-name}.md |
個別修正指示書(対応済み・詳細付き) | |
| P202 | docs/P202-fix-plan/P202-fix-resolved.md |
解決済み修正障害一覧 | |
| P202 | docs/P202-fix-plan/P202-fix-unresolved.md |
未解決テスト・未修正障害一覧 | |
| P204 | docs/P204-impact-analysis.md |
修正による影響分析結果 | |
| P205 | docs/test-records/YYYYMMDD-HHMM-test-record.md |
結合テスト再実行記録(追記) | |
| P301 | ./INDEX.md |
プロジェクトリポジトリ全体の目次(INDEX形式) | |
| P302 | docs/P302-deliver.md / ./INDEX.md(更新) |
納品物まとめ・配布手順指示書。完了時に ./INDEX.md へ配布資産へのリンクを追記する |
✓ |
| P901 | docs/P901-cr-direction/CR-NNN.md |
変更要求書(1件1ファイル。人間が何をなぜ変えてほしいか)。他の P0NN-*-direction と異なり、目次ファイル docs/P901-cr-direction.md は作らない(docs/CR.md が目次を兼ねるため) |
|
| P901 | docs/CR.md |
CR状態の台帳(一覧表のみ)。CR本文は持たない。P901が 未対応 の行を追加する |
|
| P902 | docs/P001-requirement.md(更新) + docs/P001-requirement_{YYYYMMDD}_{CR番号}.md(原本退避) |
更新後のシステム要件定義書 / 更新前の原本 | |
| P903 | docs/P903-cr-records/CR-NNN.md |
CR対処の記録。着手前にスコープ決定(対象/対象外フェーズとその理由)を記録し、完了時に変更内容・事前想定との差異・テスト結果を追記する。docs/CR.md の状態列を 対応中 に更新する |
|
| P904 | docs/P903-cr-records/CR-NNN.md(追記) + docs/CR.md(状態列の更新) |
「期待する振る舞い」の各項目とそれを確認したテストID・確認方法の対応表、および反映確認の結論 / 台帳の状態を 反映確認中 → 完了 に更新 |
|
| P905 | docs/P903-cr-records/CR-NNN.md への追記(必須。ADR更新の要否によらず) + 更新がある場合は docs/ADR.md も |
ADRを更新した場合はその更新内容と、記録ファイルへの追記。更新不要と判断した場合も、その判定結果と理由の記録(「ADR更新: 不要(理由: ...)」の1行など)を記録ファイルに必ず残す | |
| - | docs/.inprogress |
現在実行中のフェーズ番号(P番号)を記録するファイル |
各フェーズ共通指示
- Markdown 内の図について
- Markdown 内に図を作成する場合は Mermaid記法 で作成する
- Agent 側で図の記述内容を類推できる場合は Agent 側で想定する図を作成する (人間に一から書かせない)
- 図に関しては記述内容(図そのものの完成度・網羅性)を評価しない。ただし、これは図の内部品質を採点しないという意味であり、図と周辺の本文とのあいだで内容が食い違っていないか(例: 本文にある画面遷移が図に無い、図にあるAPI呼び出しが本文の記述と矛盾する)を確認する対象から図を除外するものではない。図と本文の整合性チェックは、P010(設計書横断レビュー)の「参照関係の整合性」観点に含める。
- ADR番号の暫定参照について
docs/ADR.mdはP021(Overview Step)の成果物であり、それより前のフェーズ(P002・P003・P005・P007など)が、まだ作成されていないADRを参照する必要が生じることがある。この場合、そのフェーズは暫定的な番号(例: 「ADR-001見込み」)を付けて記述し、その行(または直後の行)に "★FIXME★" を付す。- P021は、初回実行時に、これより前のフェーズが暫定番号でADRを参照している箇所をすべて洗い出し、実際に確定したADR番号と一致するように参照元の記述を更新する(P021のアウトプットである
docs/ADR.md自体だけでなく、参照元の各文書側の暫定表記も確定させる)。これはP021のアウトプット文書の一部として扱う。
- 各フェーズで作成するドキュメントがない場合、あるいは不足する項目が多数(目安: そのドキュメントで期待される項目のうち4件以上、または全体の半数以上が不足している場合。項目の単位は各フェーズのアウトプット記載内容に列挙されている粒度に従う)にわたる場合は、Agent自身の想定にもとづいてドキュメントを作成し、想定で補った具体的な記述の直後(同じ行、または直後の行)に "★FIXME★" を記載する。
docs/.inprogressに、現在のフェーズ番号(P番号)を記入する。 - 各フェーズで作成するドキュメントがあり、かつ不足する項目が少数(目安: 3件以下)な場合は、ドキュメントの記述内容の十分性を評価する。
- 記述不足箇所がある場合、Agent自身の想定で補完し、補完した具体的な記述の直後(同じ行、または直後の行)に "★FIXME★" を記載する。
- 記述不足の箇所が無ければ、そのフェーズは完了とする
- "★FIXME★" は、必ずそれが指す具体的な記述に隣接する位置(同じ行の末尾、または直後の行)に置く。文書末尾にまとめて記載しない。1つの文書内に複数箇所の想定・補完がある場合は、その数だけ★FIXME★がインラインで散らばることになる(これは意図した挙動であり、まとめようとしなくてよい)。人間は、後から文書全体を検索して★FIXME★の箇所だけをレビューできる。
- いずれの場合も、V0.4ではフェーズの完了に人間のレビュー待ちを挟まない。"★FIXME★" は、後で人間がまとめて確認・修正するための目印であり、処理を止める合図ではない。処理を止めるのは、各Stepで定義された「停止条件」に該当したときだけである。
docs/.inprogressの更新について- フェーズに着手したら、
docs/.inprogressに現在のフェーズ番号(P番号)を記入する。 - フェーズが完了したら、
docs/.inprogressを次に実行すべきフェーズの番号へ直ちに更新する(完了したフェーズ自身の番号を残したままにしない)。これにより、セッションが完了直後に切れても、次回のステップ0は次フェーズから正しく再開できる。 - 最後のフェーズ(P302)が、通常のフロー(Closing Step)として完了した場合は
docs/.inprogressを削除する。 - ただし、P903(Refactor)が内部でP002〜P302を再実行しており、その中でP302が完了した場合は、削除ではなく
P904に更新する(前述「ステップ0」およびSKILL-P903-refactor-execute.md参照)。Refactorはこの後もP904・P905が残っているため、削除すると「Refactor全体が完了した」ことと区別がつかなくなる。
- フェーズに着手したら、
- テスト実行コマンドをドキュメントに記載する場合、記載する前に一度実際に実行し、意図したテストが実際に実行されること(パス指定の誤りで0件が静かにスキップされていないか、存在しないパスを指していないかなど)を確認してから記載する。実行して確認していないコマンドを、動作確認済みであるかのように記載しない。
- "★ACCEPTED★"(意図的に受け入れた制約の記法)について
- 検討したうえで意識的に選んだ制約・簡略化・割り切りには、その記述に隣接して "★ACCEPTED★" を記載し、同じ位置に「何を検討したか」「なぜそれを採らなかったか」「その結果として残る制約(残存リスク)」を併記する。理由を書かずに記号だけを置いてはならない。
- ★ACCEPTED★ が付いた内容は、既知であり、かつ既に判断済みである。レビュー担当、および後続バージョンの検証担当は、これを未対処の不備として再度指摘しなくてよい(指摘しても同じ結論を繰り返すだけになる)。判断の前提が崩れる新しい事実が出てきた場合に限り、CR(P901)として起票して見直す。
- "★FIXME★" との違いを取り違えないこと。★FIXME★ は「Agentの想定で補った、後で人間の確認が必要な箇所」= 未解決の目印である。★ACCEPTED★ は「検討のうえ結論が出ており、追加の対応が要らない箇所」= 解決済みの目印である。人間が確認すべき対象は前者だけである。
- ★FIXME★ と同様、★ACCEPTED★ も必ずそれが指す具体的な記述に隣接する位置(同じ行の末尾、または直後の行)に置き、文書末尾にまとめて記載しない。判断の理由がその記述から離れた場所(別ファイルの改訂履歴など)にしか無いと、その記述だけを読んだレビュー担当は理由に到達できず、結局同じ論点が繰り返し提起される。この記法は、まさにその再提起を止めるために設けている。
- 例外: 一覧そのものがその節の主題である場合(例:
TEMPLATE-ArchitectureHandbook.md第9章「既知の制約・技術的負債」)は、各項目がそれぞれ「何を検討したか」「なぜ採らなかったか」「残存リスク」を自己完結して含んでいる限り、その節にまとめて記載してよい。この例外は、あくまで「各項目が自己完結していること」が条件であり、理由を別の場所に分散させてよいという意味ではない。
- 例外: 一覧そのものがその節の主題である場合(例:
- ★ACCEPTED★ の付与を義務化するものではない。「意識的な割り切りには必ず付けよ」という網羅義務を課すと、Agentは判断のたびに★ACCEPTED★を量産し、記号が意味を失う。付けるのは、レビューや後続バージョンの検証で指摘されうると具体的に予見できる論点、および過去に実際に指摘された論点に限る。
- ★ACCEPTED★ は、各フェーズが生成する成果物に対しても、本SKILL自身の各SKILLファイルの記述に対しても、同じ意味で使う。
- 目次(OKF形式)について
- フェーズP007・P008・P009・P202では、複数の子ドキュメント(スプリント/テスト/修正単位)を1つの目次ドキュメントにまとめる。この目次の形式を本SKILLでは OKF形式 と呼ぶ(Googleの Open Knowledge Format とは無関係の、本SKILL独自のチェックボックス付き目次形式である)。
- OKF は「状態(O: 状態マーク) + 番号(K: キー) + ファイルへのリンク(F: ファイルリンク)」を1行で表す一覧形式を指す。1項目1行とし、次の形式に従う。
- [状態] 番号 [タイトル](相対リンク) — 一言概要- 状態は
[ ](未着手) /[~](進行中) /[x](完了) の3種類のチェックボックスとする。 - 例:
- [ ] U001 [ユーザー登録画面の実装](./P007-impl-direction/U001-user-register.md) — 登録フォームとバリデーション
- 子ドキュメントの作業(実装・テスト・修正)が完了したら、実行担当Agentは目次ドキュメントの該当行のチェックボックスを
[x]に更新する。これにより、docs/.inprogressがフェーズ単位の粗い進捗しか持たない代わりに、目次ドキュメント側でスプリント/テスト/修正単位の細かい進捗を追跡できる。 - フェーズP007・P008・P009・P202は、目次内の全項目が
[x]になって初めてフェーズ完了とみなす。 - 子ドキュメントの保存場所が完了後に変わる場合(例: フェーズP202で
docs/P202-fix-plan/F000-*.mdをdocs/P202-fix-plan/fixed/F000-*.mdに移動する)は、チェックボックスの更新と同時に目次のリンク先も新しい保存場所に書き換える。リンク切れのまま[x]にしない。 - OKFの粒度はフェーズによって異なる。P008・P009・P202の目次は1項目=1テスト/1修正タスクだが、P007の目次は1項目=1スプリントであり、スプリント内部の複数タスク(
docs/P007-impl-direction/U000-{sprint-name}.mdの§4で定義)はさらに1段細かい粒度を持つ。この粒度差はP007側の子ドキュメント内部のタスク単位チェックボックスで扱う(詳細はTEMPLATE-P007-impl-direction.md・SKILL-P102-implement.md参照)。目次側と子ドキュメント側で粒度が異なること自体は仕様であり、統一しようとしなくてよい。 - 再オープン: 変更要求(CR)対応などにより、既に
[x]になっている項目に追加作業が必要になった場合は、チェックボックスを[~]に戻し、目次の該当行に変更理由を注記する(例: 「※CR-001対応中」)。作業が完了したら、通常どおり[x]に戻す。[x]のまま追加作業を進めると、目次からその作業が見えなくなり、かつフェーズ完了判定(全項目[x])が実態と食い違う。
- INDEX形式について(P020・P104・P301)
- ソースツリーおよびプロジェクトリポジトリ全体の目次を作る際の形式を、本SKILLでは INDEX形式 と呼ぶ。前述のOKF形式(進捗チェックボックス付き目次)とは目的が異なる、単純なディレクトリ・ファイルの目次(パス + 一言概要の一覧)であり、進捗管理の意味は持たない。
{ソースツリー}/INDEX.mdは、そのソースツリー配下のディレクトリ・主要ファイルを一覧し、各項目に一言概要を添える。./INDEX.md(P301) は、各ソースツリーのINDEX.mdへのリンクと、docs/配下の主要ドキュメントへのリンクをまとめた、プロジェクト全体の目次である。ソースツリー自体の内容は転記せず、リンクのみを載せる。
ステップ0: どのフェーズを実行するか判定する
V0.4では、フェーズ完了ごとに人間の確認を待たない。ステップ0は、セッションの再開時や停止条件に達したあとの再開時に「どこから再開するか」を機械的に判定するためのものであり、判定結果をそのまま実行する(人間への確認入力は求めない)。
現在のプロジェクトの docs/ を確認する:
docs/.inprogressが存在する場合、その内容を確認する。P903:P0NNの入れ子表記(例:P903:P006)であれば、これはRefactor(P903)の内側でP002〜P302を再実行している最中であることを意味する。この場合は台帳のチェックより先に、そのCR文脈のまま内側のP0NNから再開する(素のPlan Loop等として再開してはならない。CRの内容を無視した全面書き直しになることを防ぐため、この判定を台帳チェックより優先する)。- 素の
P0NN(入れ子表記でない)であれば、そのP番号から通常のフローとして再開する。
docs/.inprogressが存在しない、かつdocs/P001-requirement.mdが存在しない → P001 から開始するdocs/.inprogressが存在しない、かつdocs/P001-requirement.md〜docs/P302-deliver.mdの一部が存在する → 存在するフェーズの続き(存在する最後のフェーズの次)から再開するdocs/.inprogressが存在せず、docs/P001-requirement.md〜docs/P302-deliver.mdがすべて存在する場合、直ちに「全フェーズ完了」と判定してはならない。Refactor(P901〜P905)が進行中だった可能性を必ず確認する。- P903は内部でP002〜P302を再実行するが、その中で再実行されるP302自身の完了時には、
docs/.inprogressは削除されずP904に更新される(前述の入れ子表記の解消。詳細は「各フェーズ共通指示」およびSKILL-P903-refactor-execute.md参照)。したがって、この分岐に到達している時点で内側のP302は完了済みであり、.inprogressが存在しないことは「P002〜P302の再実行が終わった」ことだけでなく「その直後にP904へ進むべき状態だった」ことも意味しうるが、既に何らかの理由で.inprogress自体が失われている場合に備え、以下の確認を必ず行う。 docs/CR.md(状態の台帳)の状態列を確認し、対応中または反映確認中のCRが残っていないかを見る。残っている場合は、そのCRについて P904 から再開する。台帳は完了したCRの行も削除せず状態列だけを更新して残すため、この判定は常に台帳の全行を対象に行える。docs/CR.mdに未完了のCRが無い場合でも、直近で処理されたCRのdocs/P903-cr-records/CR-NNN.mdに、P905の判定結果(ADR更新内容、または「ADR更新: 不要」の記録。前述「各フェーズで作成するドキュメント」表のP905行を参照)が記載されているかを確認する。記載が無い場合は、そのCRについて P905 から再開する。- 上記いずれにも該当しない(全CRが
完了/却下であり、かつ最新のCRについてP905の記録も存在する)場合にのみ、Refactorも含めて完了しているとみなす。
- P903は内部でP002〜P302を再実行するが、その中で再実行されるP302自身の完了時には、
- すべてのフェーズ(P001〜P302)が完了しており、直近のRefactor(あれば)もP904・P905まで完了しており、かつ
docs/CR.mdに状態が未対応のCRの行がある → そのCRについて P902 (Refactor) から開始する(要求はdocs/P901-cr-direction/CR-NNN.mdに既に存在するため、P901は再実行しない)。人間から新しい要望が示された場合は P901 (Refactor) から開始する - すべてのフェーズが完了しており、
docs/CR.mdが存在しないか、その全行の状態が完了または却下である → 全フェーズ完了済みとして、その旨を報告して終了する
再開先が Plan Loop Step (P002〜P012)・Reviewer Loop (P201〜P205) の場合は、各Stepの「差戻条件」「停止条件」も合わせて評価し、ループの続きから自動的に処理を継続する。
フェーズ詳細
Require Development Step
P001 — システム要件定義 (docs/P001-requirement.md)
SKILL-P001-requirement.md を実行する
Plan Loop Step
P002 — ユーザインタフェース設計 (docs/P002-frontend-spec.md)
SKILL-P002-frontend-spec.md を実行する
P003 — システム詳細設計 (docs/P003-backend-spec.md)
SKILL-P003-backend-spec.md を実行する
P004 — 要求トレーサビリティマトリクス作成 (docs/P004-traceability-matrix.md)
SKILL-P004-traceability-matrix.md を実行する
P005 — 実装計画 (docs/P005-impl-plan.md)
SKILL-P005-impl-plan.md を実行する
P006 — テスト計画 (docs/P006-test-plan.md)
SKILL-P006-test-plan.md を実行する
P007 — プログラム実装定義 (docs/P007-impl-direction.md)
SKILL-P007-impl-direction.md を実行する
P008 — 結合テスト定義 (docs/P008-test-direction.md)
SKILL-P008-test-direction.md を実行する
P009 — 受け入れ結合テスト定義 (docs/P009-acceptance-direction.md)
SKILL-P009-acceptance-direction.md を実行する
P010 — 設計書横断レビュー (docs/P010-design-review.md)
SKILL-P010-design-review.md を実行する
P011 — 影響分析 (docs/P011-impact-analysis.md)
SKILL-P011-impact-analysis.md を実行する
P012 — 設計書修正
SKILL-P012-design-fix.md を実行する
Overview Step
P020 — 実装構造生成/修正 ({ソースツリー}/INDEX.md)
SKILL-P020-source-index.md を実行する
P021 — ADR整理 (docs/ADR.md)
SKILL-P021-adr.md を実行する
P022 — ArchitectureHandbook作成 (docs/ArchitectureHandbook.md)
SKILL-P022-architecture-handbook.md を実行する
Executor
P101 — 実装コンテキスト構築 (docs/P101-impl-context.md)
SKILL-P101-impl-context.md を実行する
P102 — プログラム実装
SKILL-P102-implement.md を実行する
P103 — 結合テスト実行 (docs/test-records/YYYYMMDD-HHMM-test-record.md)
SKILL-P103-integration-test.md を実行する
P104 — 実装構造修正 ({ソースツリー}/INDEX.md)
SKILL-P104-source-index-update.md を実行する
Reviewer Loop
P201 — 実装横断レビュー (docs/P201-review-report.md)
SKILL-P201-review.md を実行する
P202 — 修正計画 (docs/P202-fix-plan.md)
SKILL-P202-fix-plan.md を実行する
P203 — 修正実施
SKILL-P203-fix-execute.md を実行する
P204 — 影響分析 (docs/P204-impact-analysis.md)
SKILL-P204-impact-analysis.md を実行する
P205 — 結合テスト再実施 (docs/test-records/YYYYMMDD-HHMM-test-record.md)
SKILL-P205-integration-retest.md を実行する
Closing
P301 — 全体INDEX作成 (./INDEX.md)
SKILL-P301-root-index.md を実行する
P302 — 納品物作成 (docs/P302-deliver.md)
SKILL-P302-deliver.md を実行する
Refactor
P901 — 変更要求作成 (docs/P901-cr-direction/CR-NNN.md / docs/CR.md)
SKILL-P901-cr-create.md を実行する
P902 — 要件定義更新 (docs/P001-requirement.md)
SKILL-P902-requirement-update.md を実行する
P903 — 修正実施 (docs/P903-cr-records/CR-NNN.md)
SKILL-P903-refactor-execute.md を実行する
P904 — 変更要求の反映確認 (docs/P903-cr-records/CR-NNN.md への追記)
SKILL-P904-cr-verify.md を実行する
P905 — ADR更新確認
SKILL-P905-adr-update-check.md を実行する