Appearance
Document Status Guide
本ガイドは、aidev-template におけるすべてのドキュメント（タスク、課題、TODO、実装計画、実装ロードマップ、ユースケース、仕様書、意思決定記録、フェーズ台帳等）の進捗ステータス定義、ライフサイクル遷移、フロントマター属性、正本管理場所、およびレビュー連携ルールを一元的に定義するものです。
プロジェクト内のすべてのドキュメントおよび各種ガイド（backlog-*-guide.md 等）におけるステータス管理・記述は、本ガイドの定義を参照・遵守してください。
1. 共通ステータス定義 (Common Status Definitions)
開発・実装ドキュメントで共通して使用する基本ステータスの一覧と定義です。
| ステータス | 名称 | 説明 | 主な遷移元・先 |
|---|---|---|---|
DRAFT | 起草中 | ドキュメントの作成・計画立案中。 | (新規) → REVIEW:DRAFT |
REVIEW:DRAFT | 計画レビュー中 | 計画策定完了後の事前レビュー中（review-document 実行）。 | DRAFT → TODO (合格) / DRAFT (差戻し) |
TODO | 着手待ち | レビュー承認完了。作業開始の前提条件が整った着手待ち状態。 | REVIEW:DRAFT → WIP | CLOSE |
WIP | 作業中 | 実装作業・タスク実行が開始され進行中の状態。 | TODO → REVIEW:WIP |
REVIEW:WIP | 完了レビュー中 | 作業完了後の品質レビュー・受入確認中（review-document 実行）。 | WIP → DONE (合格) / WIP (差戻し) |
DONE | 完了 | 成果物の作成・検証・レビューがすべて承認完了した状態。 | REVIEW:WIP → (完了) |
CLOSE | 終了・中止 | 作業の中止、起草取り下げ、対応不要判定、昇格等による終了状態。 | DRAFT / TODO / WIP → (クローズ) |
2. 意思決定記録（DR）専用ステータス
意思決定記録（docs/decision-records/DR-XXX.md）では、意思決定プロセスの性質に応じた専用ステータスを使用します。
| ステータス | 説明 |
|---|---|
PROPOSED | 意思決定事項を提案中・検討中の状態。 |
ACCEPTED | 提案が承認・合意され、正式に採択された状態。 |
REJECTED | 検討の結果、採用が見送られた状態。 |
DEPRECATED | 過去に採択されたが、システム刷新等に伴い廃止・無効化された状態。 |
SUPERSEDED | 後続の新しい意思決定（別の DR-XXX）によって上書き・置換された状態。 |
3. ドキュメント種別ごとのステータス管理場所とライフサイクル
Single Source of Truth（SSOT）の原則に基づき、ステータスの「正本（Single Source）」を保持する場所と、それを参照・同期する「ビュー（台帳）」を明確に区分します。
| ドキュメント種別 | 対象ファイル | ステータス管理場所 (正本) | ライフサイクル遷移 | 連動する台帳・ビュー |
|---|---|---|---|---|
| タスク (Task) | backlog/tasks/SPEC-XXX-Y.md | フロントマター (status) | DRAFT → REVIEW:DRAFT → TODO → WIP → REVIEW:WIP → DONE | CLOSE | wbs.md, 親実装計画 |
| 課題 (Issue) | backlog/issues/ISSUE-XXX.md | フロントマター (status) | DRAFT → REVIEW:DRAFT → TODO → WIP → REVIEW:WIP → DONE | CLOSE | wbs.md |
| TODO | backlog/todos/TODO-XXX.md | フロントマター (status) | DRAFT → REVIEW:DRAFT → TODO | CLOSE | wbs.md |
| 意思決定記録 (DR) | docs/decision-records/DR-XXX.md | フロントマター (status) | PROPOSED → ACCEPTED | REJECTED | DEPRECATED | SUPERSEDED | docs/decision-records/index.md |
| 実装計画 | docs/backlog/implementations/<AppID>-<ID>.md | フロントマター (status) | DRAFT → REVIEW:DRAFT → TODO → WIP → REVIEW:WIP → DONE | spec.md, 親ロードマップ, phase.md |
| 実装ロードマップ | docs/backlog/roadmaps/<feature>.md | フロントマター (status) | DRAFT → REVIEW:DRAFT → TODO → WIP → REVIEW:WIP → DONE | usecase.md, phase.md |
| ユースケース | docs/usecases/USECASE-XXX.md | docs/backlog/usecase.md (台帳) | DRAFT → REVIEW:DRAFT → TODO → WIP → REVIEW:WIP → DONE | phase.md |
| 機能仕様書 (SPEC) | specs/SPEC-XXX.md | backlog/spec.md (台帳) | DRAFT → REVIEW:DRAFT → TODO → WIP → REVIEW:WIP → DONE | CLOSE | phase.md |
| フェーズ台帳 | docs/backlog/phase.md | なし（参照ビュー） | 参照先要素（feature または specification）のステータスと同期 | - |
IMPORTANT
台帳管理文書（SPEC / USECASE）の特則: 機能仕様書（SPEC-XXX.md）およびユースケース定義書（USECASE-XXX.md）は恒久的な仕様書・設計書であるため、ファイル自体のフロントマターにはステータスを持たせず、台帳ファイル（backlog/spec.md および docs/backlog/usecase.md）をステータスの単一の正本として管理します。
4. フロントマター属性と理由・メタデータ規則
1. reason（タスク・課題の理由種別）
タスク（tasks/）および課題（issues/）では、作成・実施理由を表す reason 属性をフロントマターに記述します。
reason 値 | 説明 |
|---|---|
feature | 新規機能の開発・追加 |
defect | 不具合・バグの修正 |
security | セキュリティ対策・脆弱性対応 |
spec-change | 仕様変更に伴う改修 |
investigation | 調査・検証・PoC |
performance | パフォーマンスチューニング・最適化 |
refactor | リファクタリング・コード改善 |
ops | 運用・環境構築・CI/CD整備 |
2. review（レビューメタデータ）
ステータスが REVIEW:DRAFT または REVIEW:WIP から遷移する際は、レビュー結果としてフロントマターに review メタデータを記録します。
yaml
review:
result: ACCEPTED # ACCEPTED | REJECTED
timestamp: 2026-08-21T22:00:00+09:00 # レビュー実行日時（ISO 8601）
reason: "" # REJECTED時は1行の却下・差戻し理由。ACCEPTED時は空文字 ""ACCEPTED（合格）:REVIEW:DRAFT→TODOに遷移REVIEW:WIP→DONEに遷移
REJECTED（差戻し）:REVIEW:DRAFT→DRAFTに差し戻しREVIEW:WIP→WIPに差し戻しreasonに修正・対応が必要な理由サマリーを必ず記述
5. 特殊ライフサイクル・昇格ルール
1. TODO の昇格（Promotion）とクローズ
- TODO（
todos/TODO-XXX.md）に記録された項目を具体的に処理・着手する場合、直接作業を行うのではなく、SPEC（機能仕様書）または ISSUE（課題・不具合）へと昇格 させて正式なフローへ移行します。 - SPEC または ISSUE へ昇格・移行した時点で、元の TODO ドキュメントのステータスを
CLOSEに更新します。
2. 実装計画・ロードマップの完了条件評価
- 実装計画 (
docs/backlog/implementations/): タスク一覧の全タスクがDONEになった際、完了条件を満たしたか評価しREVIEW:WIP→DONEへ遷移します。 - 実装ロードマップ (
roadmaps/): 関連コンポーネントの実装計画がすべてDONEになった際、スライスの完了条件を評価しREVIEW:WIP→DONEへ遷移し、親ユースケースの完了を評価します。
6. レビュースキルとステータス連携 (Review Skills & Status Transition)
本テンプレートでは、すべての管理対象ドキュメントの初期ステータスを DRAFT とし、着手前レビューとして DRAFT → REVIEW:DRAFT → TODO を経てから実装・作業を開始します。 レビュー対象のステータスは REVIEW:<直前ステータス>（REVIEW:DRAFT または REVIEW:WIP）の形式で指定し、review-document スキルが対象ドキュメントおよびステータスに応じて自動的にレビュー観点（モード）を切り替えて検証を実行します。
1. ステータスと対応レビュースキル一覧
| ドキュメント種別 | ステータス値 | 実行スキル | ステータスに応じた主なレビュー観点 |
|---|---|---|---|
| ユースケース | REVIEW:DRAFTREVIEW:WIP | review-document | REVIEW:DRAFT: ユーザー価値・実現条件の論理整合性、feature詳細・シーケンス図の妥当性 REVIEW:WIP: 全feature完了確認、実現条件の充足評価、受入シナリオ検証 |
| 機能仕様 (SPEC) | REVIEW:DRAFTREVIEW:WIP | review-document | REVIEW:DRAFT: 上位要件・設計との整合性、入出力仕様の明確さ、受入基準の妥当性 REVIEW:WIP: 実装コードとの整合性、受入基準（AC）の充足、テスト実施確認 |
| 実装ロードマップ | REVIEW:DRAFTREVIEW:WIP | review-document | REVIEW:DRAFT: 親ユースケース/feature連携、完了条件の明確さ、依存関係・実装順序の妥当性 REVIEW:WIP: 全コンポーネント実装計画の完了確認、ロードマップ完了条件の充足評価 |
| 実装計画 | REVIEW:DRAFTREVIEW:WIP | review-document | REVIEW:DRAFT: 機能仕様（SPEC）との整合性、完了条件の妥当性、タスク分割・依存関係の正確性 REVIEW:WIP: タスク一覧の全タスク完了確認、実装計画完了条件の充足確認 |
| タスク詳細 | REVIEW:DRAFTREVIEW:WIP | review-document | REVIEW:DRAFT: 作業項目（WI）の明確さ、受入条件（AC）の具体性、Verification手順の妥当性 REVIEW:WIP: 作業項目（WI）の実装完了確認、受入条件（AC）および検証結果の充足確認 |
| 課題・不具合 (ISSUE) | REVIEW:DRAFTREVIEW:WIP | review-document | REVIEW:DRAFT: 現象・再現手順の具体性、原因分析の妥当性、対応方針（Action Plan）の網羅性 REVIEW:WIP: 対応方針・作業内容の実装完了確認、検証結果チェックの充足確認 |
| TODO管理 | REVIEW:DRAFT | review-document | REVIEW:DRAFT: メモ内容の具体性、昇格先（SPEC/ISSUE）の検討妥当性確認 |
| 意思決定記録 (DR) | PROPOSED | review-document | PROPOSED: 背景課題の明確さ、決定事項の具体性、代替案比較、影響・インライン相互リンクの妥当性確認 |
2. レビュー運用フロー
初期起票とレビュー依頼 (
DRAFT→REVIEW:DRAFT):- ドキュメント作成後、初期ステータス
DRAFTからREVIEW:DRAFTに更新してレビューを依頼します。
- ドキュメント作成後、初期ステータス
レビュースキルの実行とモード自動切替:
- 対象ドキュメントを引数に指定して
review-documentスキルを実行します。スキルはステータスに応じたモード（Mode A: 策定フェーズ / Mode B: 受入・完了フェーズ）で自動検証し、3段階の重篤度（🔴 問題, 🟡 要確認, 🟢 提案）でレポートを出力（wiki/reviews/配下に保存）します。
- 対象ドキュメントを引数に指定して
指摘対応と承認:
- 🔴 問題: 修正必須。指摘内容を反映して再度レビューを実施します。
- 🟡 要確認: ユーザーまたはチームで確認・合意を形成します。
- 🟢 提案: 必要に応じて品質向上のため反映を検討します。
レビュー判定とステータス遷移:
- 合格時 (
ACCEPTED):- 策定フェーズ（
REVIEW:DRAFT）:TODO（着手待ち）へ昇格。フロントマターにreview.result: ACCEPTEDを記録。 - 完了フェーズ（
REVIEW:WIP）:DONE（完了）またはCLOSEへ昇格。フロントマターにreview.result: ACCEPTEDを記録。
- 策定フェーズ（
- 差し戻し時 (
REJECTED):- 策定フェーズ（
REVIEW:DRAFT）: 直前のDRAFTへ差し戻し。フロントマターにreview.result: REJECTEDおよびreview.reason（理由サマリー1行）を記録。 - 完了フェーズ（
REVIEW:WIP）: 直前のWIPへ差し戻し。フロントマターにreview.result: REJECTEDおよびreview.reason（理由サマリー1行）を記録。
- 策定フェーズ（
- 合格時 (
7. ステータス更新・同期手順
ステータスの手動更新による台帳間不整合を防ぐため、ステータス変更時は update-document-status スキル を使用してフロントマターおよび関連台帳（wbs.md, spec.md, usecase.md, phase.md 等）を一括同期してください。
sh
# タスクステータスを WIP に更新
/update-document-status docs/webui/backlog/tasks/SPEC-001-1.md WIP
# レビュー承認による TODO への遷移
/update-document-status docs/webui/backlog/tasks/SPEC-001-1.md TODO --review-result ACCEPTED