記事

仕様管理:仕様をコードとして保存し、バージョン管理し、レビューする

仕様管理とは、チームがソフトウェアの仕様を保存し、各変更を記録し、その変更をレビューし、仕様を最新に保つやり方です。仕様の管理は同じ仕事です。仕様とは、ソフトウェアが何をしなければならないかを述べる文書であり、それを管理するとは、その文書が見つけられ、信頼できるままになることです。仕様をコードとして管理するとは、それらの文書がバージョン管理システムのファイルであることであり、仕様への変更はレビューアが diff できるコミットです。仕様のバージョン管理とは、それらのコミットの履歴と、各文書に書かれた状態とを合わせたものです。仕様をコードと同期したまま保つとは、仕様の構造を壊す提案された変更が、コードの変更が通るのと同じ自動検査で失敗することです。仕様駆動開発(SDD、spec-driven development)は、コードの前に仕様を書き、仕様を真実の源として扱うやり方です。継続的インテグレーション(CI、continuous integration)は、提案された変更のたびに走る自動検査です。製品要求文書(PRD、product requirements document)は、問題と範囲を述べる散文です。MarkdownのPRDテンプレート は、その形をした SpecScore の機能ファイルの一つです。Easy Approach to Requirements Syntax(EARS)は、要件の文型です。SpecScore では、要件(REQ)は機能の中の名前付き規則であり、受け入れ基準(AC、acceptance criterion)は、それらの規則の一つ以上を指す任意の抽象的な条件です。検査はコマンドラインインターフェース(CLI、command-line interface)のコマンド specscore spec lint であり、CIで仕様リンターを使って仕様をリントする に文書化されています。フォーマットは公開リポジトリ specscore/specscore(CC BY 4.0)にあります。CLI は specscore/specscore-cli(Apache-2.0)にあります。

最終更新: 2026年11月9日

仕様を保存する場所

仕様管理は、ファイルが置ける場所から始まります。このリポジトリでは、仕様は spec/ の下の Markdown です。spec の README が挙げるディレクトリは、features、plans、ideas、decisions、lessons です。機能は README.md を一つ持つディレクトリです。機能仕様 がそのファイルの契約であり、PRDテンプレート は、リンターが受け入れた記入済みの例です。

specscore spec lint は、どのツリーを読むかを推測しません。internal/cli/spec.go はタグ v0.55.1 にあり、同じ関数は タグ v0.39.1 にもあります。その関数は作業ディレクトリから上へたどり、specscore.yaml を見つけるまで進みます。その関数のコメントは、コマンドがこのファイルを必須とすること、ないときは終了コード 3 を返すこと、specscore init を実行するよう示すことを述べています。このリポジトリの dogfood ワークフロー は CLI v0.39.1 をインストールしてから specscore spec lint を実行するので、それがリントするチェックアウトにはその設定ファイルがあります。

機能ファイルのそばにインデックスがあります。規則 feature-index-row-sync は、v0.39.1 と v0.55.1 の lint カタログではエラーです。カタログの行は、機能インデックスの各行がその機能ファイルと一致することを要求する、と述べています。それは、インデックスが指す文書と揃っているということです。要件の文言をソースファイルと比べることではありません。

仕様のバージョン管理

git にコミットされたファイルについての仕様のバージョン管理は、それらのファイルのコミット履歴です。SpecScore は機能に第二のバージョン番号を加えません。レビューアが見るリビジョンは、ブランチ上のコミットです。文書の状態の行は、その機能がライフサイクルのどこにあるかを述べます。それは git のハッシュとは別の事実です。

リポジトリの 機能仕様 は、それ自身が **Status:** Stable です。タイトルの直後に **Status:** の行を要求し、値は Draft、In Review、Approved、Implementing、Stable、Amending、Rejected、または Deprecated のいずれかでなければなりません。規則 status-mirror は、上で名指しした両方のカタログにおいて、状態を持つ成果物の frontmatter の status: がその本文の行と一致することを要求し、状態を持たない型では status: を禁じます。二つのコピーを一致させることは、八つの値の外にある語を拒否することと同じではありません。どちらのカタログの行も、その集合の外の機能状態を拒否する規則を述べていないので、このページはそのような規則があると主張しません。

プランは別の集合を使います。規則 P-006 は、両方のカタログにおいて、単一ファイルのプランの本文の **Status:** が Draft、In Review、Approved、Executing、Blocked、Implemented、Failed、Rejected、Withdrawn、Superseded、または Deprecated のいずれかであることを要求します。規則 idea-status-values は、その規則が許す集合の外のアイデアの状態を拒否します。カタログがその一覧です。このページは、アイデアの語を再掲しません。

プラン仕様 は、列が Date、Git Hash、Action、Comment である任意の ## Snapshots 表も説明します。各スナップショットは、その時点のプランの状態を指す git のコミットハッシュを参照する、と述べています。このページのために確認した二つの lint カタログは、そのハッシュを解決する規則を名指ししていないので、このページは、リンターがコミットの存在を検査するとは主張しません。ハッシュは、人が git でたどれるポインタです。公開されている プラン仕様 は、その文書のフォーマットのページです。

仕様をレビューする

Markdown の仕様のレビューは、それを変更するプルリクエストです。dogfood.yml は pull_request と、main への push で実行されます。ジョブはリポジトリをチェックアウトし、SPECSCORE_VERSION を v0.39.1 に設定して CLI をインストールし、追加のフラグなしで specscore spec lint を実行します。そのプロセスが非ゼロで終わると、GitHub Actions はそのステップを失敗にします。ワークフローの権限は contents: read です。

機能の状態 In Review は、機能がレビューに出されていることを意味します。その語を書くことは、Markdown ファイルへの編集です。プルリクエストは、人が diff を読む場所です。status-mirror は、frontmatter と本文が同じ状態を名指ししているかを検査します。レビューアが散文に同意したことは記録しません。バリデーターのページ は、その構造の検査と、人がまだしなければならない読みとを分けています。specscore spec lint が報告することの規則ごとの説明は、CIで仕様リンターを使って仕様をリントする にあります。

仕様をコードと同期したまま保つ

このサイトで仕様をコードと同期したまま保つとは、仕様がプロジェクトと同じリポジトリにあり、仕様ツリーがフォーマットに違反すると CI がプルリクエストを失敗させることです。プルリクエストは、同じ diff の中で機能ファイルとコードを変更できます。規則 feature-index-row-sync は、インデックスの行を、それが名指しする機能ファイルと揃えます。ソースファイルを読んで、コードが要件を実装しているかを決めることはしません。

下の抜粋は、dogfood.yml のインストールと lint のステップです。ワークフローのファイルは、権限、並行性グループ、ピンが latest ではない理由のコメントも設定します。それらの行は、ここでは省いています。コマンドは、そのファイルが実行するものです。

dogfood.yml のインストールと lint のステップ
name: Dogfood lint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - name: Install specscore CLI (pinned)
        env:
          SPECSCORE_VERSION: v0.39.1
        run: |
          curl -fsSL https://specscore.md/install/get-cli | \
            SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          specscore --version
      - name: Lint spec tree
        run: specscore spec lint

そのファイルのコメントは、浮動する latest のピンはリポジトリの下の関門を変える、と述べています。プルリクエストと、それが対象とする main ブランチとでは、見える規則が異なり得ます。ピンは v0.39.1 です。ジョブは --fix を渡しません。違反のない実行と失敗する実行は、file:line [severity] rule: message の行を含めて、CIで仕様リンターを使って仕様をリントする に示しています。

コードをもはや説明しない仕様の文は、それらの発見には入りません。specscore spec lint が検証するのは構造です。必須のファイルと節、インデックスの行、見出しの形、そして規則が名指しする参照です。実装が要件と一致するかを採点しません。その限界が、バリデーターのページ の要点です。散文を正しいままに保つことは、いまも diff のレビューです。

他の仕様駆動のツールが仕様を検査する方法

下の段落は、2026年11月9日に取得したページを使います。それらのツール自身の検査を説明します。製品がいくつ存在するかは述べず、市場に順位も付けません。ツールまとめ が、より長い比較です。

GitHub Spec Kit のエージェント型 SDD リファレンス は、/speckit.analyze を、spec.md、plan.md、tasks.md にわたる読み取り専用の検査として説明します。衝突、欠落、曖昧さを報告し、ファイルを編集することはなく、実装の前にエージェントの中で実行します。同じページのコマンド一覧は、SpecScore のツリーに対して specscore spec lint を実行する CI ジョブを説明していません。

OpenSpec は、変更を openspec/changes/ の直下のディレクトリとして保存します。openspec validate は、変更と仕様の構造上の問題を検査します。リファレンスは、終了コード 0 は検証した項目がすべて通ったことを意味し、終了コード 1 は、項目が失敗したか、報告の要求が無効か、設定を読めないか、実行が失敗したことを意味する、と述べています。その検査は OpenSpec の形であり、要件のブロックとシナリオのブロックを含み、SpecScore の ### AC: 見出しではありません。別のコマンド openspec status について、同じリファレンスは、一つの変更を読み込めないバッチでも終了コードは 1 のままである、“so CI doesn’t accept an incomplete report as successful.” と述べています。その文は openspec status についてのものであり、openspec validate についてではありません。

よくある質問

仕様管理とは何ですか。

仕様管理とは、ソフトウェアの仕様を保存し、各変更を記録し、その変更をレビューし、仕様を最新に保つことです。SpecScore では、ファイルは git リポジトリの Markdown であり、specscore spec lint は、CI ジョブが失敗させられる構造の検査です。

仕様の管理とは何ですか。

仕様の管理は同じやり方です。仕様は、ソフトウェアが何をしなければならないかを述べる文書です。それを管理するとは、文書に既知の場所、履歴、レビュー、そして構造がいまもフォーマットと一致するという検査があることです。

仕様をコードとして管理するとは、どう動きますか。

仕様は、spec/ の下にある Markdown ファイルのツリーに、リポジトリのルートの specscore.yaml を加えたものです。変更はコミットです。プルリクエストが diff をレビューします。dogfood.yml がそのプルリクエストで specscore spec lint を実行します。

仕様のバージョン管理はどう動きますか。

git の履歴が、ファイルのバージョン履歴です。機能はまた、機能仕様が要求する八つの値の一つを **Status:** に持ちます。プランは、Git Hash がそのプランの状態のコミットである ## Snapshots の行を記録できます。ここで引用したリンターのカタログは、そのハッシュを解決する規則を説明していません。

仕様をコードと同期したまま保つには、どうしますか。

仕様をリポジトリに置き、specscore spec lint が構造違反を報告したときは、機能ファイルと一致しないインデックスの行を含めて、プルリクエストを失敗させます。コマンドは、コードが要件を実装しているかを決めません。コードからずれてしまった文は、いまも人が diff を読む必要があります。

仕様をリポジトリに置いたままにする。

翻訳の誤りやこのページの改善案がありますか?