Skip to content
Spec Kit Guide

`specs/**` 履歴資産運用ガイド

このページは、specs/** を implement 後にどう扱うべきか、また前段コマンドへ遡って再実行する際に既存ファイルを削除すべきか・そのまま使えるかを整理した運用ガイドです。

次の前提で読み進めてください。

  • docs/**: Spec Kit に入力する人が作成・メンテナンスする正式仕様書
  • brief: Spec Kit に入力する際の入力情報を取りまとめた文書（引数相当）

1. 先に結論

Section titled “1. 先に結論”

最も重要な結論は次の 4 点です。

  1. implement 後に継続的にメンテナンスすべき主対象は通常 docs/** 側である
  2. specs/** は通常、日常保守の正本ではなく、feature / 改修テーマ単位の履歴資産として保持する
  3. ただし specs/** を一切見直さない、という意味ではない
  4. 再実行時に既存ファイルを事前削除することは、通常は必須ではない

より正確には、次の表現が今回の議論の整理に最も近いです。

specs/** は基本的に Spec Kit 実行時点の feature 記録であり、implement 後に継続保守する主対象ではない。
ただし、実装結果との整合や参照価値向上のために、完了時に軽微な修正・追記を行うことはある。
長期的な保守対象は通常 docs/** 側の正式仕様書である。

2. なぜ specs/** を主保守対象にしないのか

Section titled “2. なぜ specs/** を主保守対象にしないのか”

2.1 docs/** と specs/** の役割が違う

Section titled “2.1 docs/** と specs/** の役割が違う”
  • docs/** は正式仕様・長期保守対象
  • specs/** はそのテーマを実行した時点の要求整理・設計判断・タスク分解の記録

つまり、実装後に最新状態を保ち続けるべき主対象は docs/** であり、specs/** は「当時どう判断したか」を後で追えるように残す方が価値が高いです。

2.2 履歴資産を毎回最新化すると役割がぼやける

Section titled “2.2 履歴資産を毎回最新化すると役割がぼやける”

specs/** を毎回最新の正式仕様と同一化しようとすると、次の問題が起きやすくなります。

  • 当時の判断経緯が見えなくなる
  • docs/** と specs/** のどちらが正本か曖昧になる
  • 追加開発時に「今の正式仕様」と「当時の計画」を区別できなくなる

3. ただし「一切メンテしない」は強すぎる

Section titled “3. ただし「一切メンテしない」は強すぎる”

specs/** を implement 後に完全放置してよい、という意味ではありません。議論では次のように整理されています。

  • 通常は積極的メンテ不要
  • ただし、最終整合のために軽く見直すことはある

3.1 比較的見直し価値が高いもの

Section titled “3.1 比較的見直し価値が高いもの”
  • quickstart.md
  • contracts/
  • data-model.md
  • plan.md

3.2 通常は履歴としてそのまま残しやすいもの

Section titled “3.2 通常は履歴としてそのまま残しやすいもの”
  • spec.md
  • tasks.md

3.3 見直しを検討する条件

Section titled “3.3 見直しを検討する条件”
  • 実装中に仕様解釈が確定し、文書が誤解を招く状態になった
  • 設計判断が一部変わり、後で読む人が誤認しやすい
  • quickstart.md の手順が実装後の実態とズレた
  • contracts/ や data-model.md が実装と大きくズレた
  • PR レビューで「この記述は修正した方がよい」と判断された
  • 後続 feature の参照資産として価値を高めたい

4. implement 後のファイル別方針

Section titled “4. implement 後のファイル別方針”
ファイル / ディレクトリimplement 後の基本方針補足
spec.md基本は履歴として残す要件の正本は docs/** で管理する
plan.md原則は履歴。誤解を招く場合のみ軽微修正正式設計変更は docs/** を先に更新する
research.md通常はそのまま残す当時の調査論点として価値がある
data-model.md実装と大きくズレるなら軽微修正を検討正式 DB 仕様は docs/** 側で維持する
quickstart.md実態とズレるなら軽微修正を推奨再現手順として参照価値が高い
contracts/実装との差が大きいなら軽微修正を検討正式 API 契約は docs/** が正本
tasks.md基本は履歴として残す実装後に無理に最新化しない

5. 実装で仕様が変わったときの原則

Section titled “5. 実装で仕様が変わったときの原則”

実装中に仕様解釈や正式設計が変わった場合の順番は一貫しています。

  1. 先に docs/** を更新する
  2. 必要なら brief を更新する
  3. 必要最小限の段階まで戻って再実行する
  4. その後、必要なら specs/** を軽く整合させる

やってはいけないのは次の運用です。

  • specs/** だけ直して正式仕様を更新しない
  • docs/** と specs/** のどちらを正とするか曖昧にする

6. 前段コマンドへ遡って再実行する時、既存ファイルは消すべきか

Section titled “6. 前段コマンドへ遡って再実行する時、既存ファイルは消すべきか”

結論から言えば、通常は削除必須ではありません。ただし、「同じテーマの上書きでよいか」「旧版を退避すべきか」「新テーマとして切るべきか」は段階ごとに判断が必要です。

7. 段階別の推奨方針

Section titled “7. 段階別の推奨方針”

7.1 specify へ戻るとき

Section titled “7.1 specify へ戻るとき”

どういう時に戻るか

Section titled “どういう時に戻るか”
  • 要件が変わった
  • ユーザーストーリーが変わった
  • 受け入れ条件が変わった
  • 権限や業務ルールが変わった

既存ファイルの扱い

Section titled “既存ファイルの扱い”
  • 先に docs/** と specify-brief を更新する
  • 既存 specs/** をどう扱うか決める
  • 軽微変更なら同じ feature テーマで上書き再実行してよい
  • 変更が大きければ新しいテーマとして切る方を推奨する

判断の目安

Section titled “判断の目安”
状況推奨
clarify 反映や軽い要求修正同じ specs/NNN-feature/ で再生成・上書き
要件の意味合いが変わる / 再定義に近いspecs/NNN-redefine-.../ や NNN-enhance-.../ を新設

7.2 plan へ戻るとき

Section titled “7.2 plan へ戻るとき”

どういう時に戻るか

Section titled “どういう時に戻るか”
  • 技術選定が変わった
  • API 仕様が正式変更された
  • DB 仕様が変わった
  • 非機能要件が変わった
  • 実装構成方針が変わった

既存ファイルの扱い

Section titled “既存ファイルの扱い”
  • 先に docs/** の設計系文書を更新する
  • plan-brief を更新する
  • 同じテーマの軽微設計変更なら、既存 plan.md, research.md, data-model.md, contracts/, quickstart.md を上書き再生成してよい
  • 大きな設計変更なら、新しい specs/NNN-enhance-.../ を切る方が履歴管理しやすい

7.3 tasks へ戻るとき

Section titled “7.3 tasks へ戻るとき”

結論

Section titled “結論”

既存 tasks.md は通常、削除不要です。

推奨方針

Section titled “推奨方針”
  • 軽微変更 → 上書き
  • 大きな変更 → tasks.prev.md に退避、または Git 履歴で残してから再生成
  • 再生成後は 新しい tasks.md を正本 とする

重要な注意

Section titled “重要な注意”
  • 旧 tasks.md にチェック済み項目があっても、設計変更後はその完了状態を自動継承しない
  • 完了履歴を残したい場合は旧版を退避する

7.4 implement をやり直すとき

Section titled “7.4 implement をやり直すとき”

結論

Section titled “結論”

必ずしもクリーンな状態に戻す必要はありません。

正しい整理

Section titled “正しい整理”
  • 軽微修正なら戻さなくてよい
  • 設計変更・要求変更で旧コードが邪魔なら、部分整理または大きなクリーンアップを行う
  • コードは文書よりも整合性を優先して扱う

既存コードを活かしてよいケース

Section titled “既存コードを活かしてよいケース”
  • 軽微なバグ修正
  • UI 微調整
  • 小さな API 修正
  • テスト追加
  • PR 指摘の軽微修正

整理・巻き戻しを検討すべきケース

Section titled “整理・巻き戻しを検討すべきケース”
  • 設計変更で構造が変わった
  • 要求変更で不要コードが出た
  • 旧実装が新仕様に反する
  • 差分修正より作り直しが安全

8. 削除・上書き・退避・新テーマの使い分け

Section titled “8. 削除・上書き・退避・新テーマの使い分け”
対応向いているケース典型例
削除せず上書き軽微変更、同じテーマで十分tasks.md の粒度微調整、軽い clarify 反映
旧版を退避して再生成同じテーマだが旧版も残したいtasks.prev.md を残したい、レビュー中比較したい
新テーマとして切る変更が大きく、履歴を分けたいNNN-enhance-..., NNN-redefine-...
部分整合だけするimplement 後に参照価値だけ高めたいquickstart.md, contracts/, data-model.md の軽微修正

補足: 「ファイルを削除しないこと」と「旧版を正本扱いし続けること」は別です。削除不要でも、新版を正本にする判断は必要です。

9. 実務フローとしての推奨形

Section titled “9. 実務フローとしての推奨形”
  1. 何が変わったかを 要求 / 設計 / タスク / 実装 のどれかに分類する
  2. 先に docs/** を更新する
  3. 対応する brief を更新する
  4. 既存 specs/** を 上書き / 退避 / 新テーマ のどれで扱うか決める
  5. 必要最小限の段階まで戻って再実行する
  6. implement 後は specs/** を無理に全部最新化せず、必要なら軽微整合だけ行う

10. よくある誤解

Section titled “10. よくある誤解”

10.1 implement 後は specs/** を一切見直さなくてよい

Section titled “10.1 implement 後は specs/** を一切見直さなくてよい”

強すぎます。正しくは「通常は積極的メンテ不要だが、整合のために軽く見直すことはある」です。

10.2 再実行前には必ず既存ファイルを削除すべき

Section titled “10.2 再実行前には必ず既存ファイルを削除すべき”

通常は不要です。特に tasks.md は文書なので、上書きか退避で十分なことが多いです。

10.3 コードも tasks.md と同じ感覚で上書き再実行すればよい

Section titled “10.3 コードも tasks.md と同じ感覚で上書き再実行すればよい”

そうではありません。コードは実体なので、前提変更が大きい場合は整理・巻き戻し・再実装が必要になります。

11. この論点だけを短く覚えるための要点

Section titled “11. この論点だけを短く覚えるための要点”
  • 長期保守対象は通常 docs/**
  • specs/** は通常、履歴資産
  • implement 後の specs/** は必要時だけ軽微整合
  • tasks.md は削除必須ではない
  • 新版を正本にするか、旧版を退避するかを決める
  • コードは整合性優先で扱い、常にクリーン状態へ戻す必要はない