SpecScore.md

比較一覧

SpecScore vs Plain Markdown

ほとんどのチームはすでに「スペック」を持っています — docs フォルダの場当たり的な Markdown、Notion ページ、Jira チケットとして。無料で、すでにそこにあり、 機能します。SpecScore は 同じ Markdown に、 AI エージェントが lint・クエリし、コードまでトレースできる構造を加えたものです。

共通点。

  • どちらも Markdown です — プレーンテキストで、人間が読め、diff に強い。
  • スペックはリポジトリに配置でき、バージョン管理され、PR でレビューされます。
  • 独自フォーマットもロックインもありません — どんなエディタでも読めます。
  • あなたは散文を書き続け、SpecScore はそれを置き換えるのではなく、周囲に構造を加えます。

デフォルトの優れた点。

Plain Markdown、Notion、Jira こそが本当のデフォルトです。それだけの理由があります。

学習コストゼロ

スキーマも、必須フィールドも、ループに入る CLI もありません。ファイルを開いて、 書き始めるだけ。一度きりのメモや小さなプロジェクトなら、それがまさに正解です — 必要のない構造は摩擦でしかありません。

すでにインストール済み

あなたのチームはすでに Notion、Confluence、あるいは docs/ フォルダの中にいます。 導入するものも、移行するものもありません。最も摩擦の少ない選択肢は、 すでに使っているものです。

どこでも使える可搬性

Plain Markdown はどこでも開け、どんなツールよりも長持ちします。SpecScore は まさにこの性質の上に作られています — だからこそ SpecScore もデータベースではなく Markdown なのです。

機能比較。

違いはファイルそのものではなく — エージェントがそれで何ができるかです。

機能Plain Markdown / NotionSpecScore
フォーマット自由形式の Markdown / ドキュメントMarkdown + YAML frontmatter（構造化）
要件の置き場所Jira、Notion、Slack、誰かの頭の中リポジトリ内、コードの隣
「このスペックは完成しているか？」人間が読んで判断するspecscore lint — 自動
曖昧さの検出なし — 曖昧な動詞が黙ってリリースされる曖昧な動詞、欠落した AC、未解決の参照を検出
要件 / AC IDなし機械可読な ID（REQ: slug）
ライフサイクルステータス暗黙的、追跡されていればの話強制 — Draft → Approved → Implementing → Stable
コードからスペックへのトレーサビリティなしspecscore: アノテーション + Verifies: トレーラー
エージェントのナビゲーション何かを探すたびに全ファイルを読むスペックグラフをクエリ（CLI から）
CI 品質ゲートなしspecscore lint がリンターのようにゼロ以外で終了
学習コストなし学ぶべきフォーマット（段階的に）
コスト / ライセンス無料無料、オープンソース

SpecScore がさらに進んでいる点。

曖昧さは解釈されるのではなく、検出される

自由形式のスペックでは、すべてのエージェントとのやり取りが解釈から始まります — 「ログインは動作すべき」は、正解ともっともらしい誤りの間のコイン投げです。 SpecScore の lint は、エージェントが行動する前に、曖昧な動詞と 欠落した受け入れ基準を検出します。

$ specscore lint auth/login.md
  ✗ R1  "should work" — 測定不能
  ✗ R1  no acceptance criteria

誤解が積み重なるのを止める

あるエージェントが要件を読み違え、2つ目がその上に構築し、3つ目が両方に依存する — そして気づくのは3つのエージェントを経た後です。構造化された受け入れ基準は、 すべてのエージェントに同じ合否条件を与えるため、解釈がエージェント間で ドリフトしません。

コードがスペックまでトレースできる

プレーンなドキュメントは、それを実装したコードへのリンクを持ちません。SpecScore はspecscore: ソースアノテーションと Verifies:コミットトレーラーを加えます — specscore code refs が「この要件を 実装しているコードはどれか？」に確定的に答えます。

40枚のチケットの代わりに1つのスペック

新しいチームメイト（あるいは新しいエージェント）は、40枚の Jira チケットと Slack スレッドから意図を再構築する代わりに、すべての文脈を含む1つのフィーチャー スペックを読みます。

エージェントは再読の代わりにクエリする

docs フォルダでは「進行中のものは何か？」を知るにはファイルを開く必要があります。 SpecScore では specscore feature list で済みます — スペックグラフが CLI から答えるため、エージェントはリポジトリの再読でコンテキストを浪費しません。

品質は CI で強制される

自由形式のスペックにはゲートがありません — 書きかけのものも完成したものと同じくらい 簡単にマージされます。specscore lint は、ESLint や go vetがコードを守るのと同じように、問題があればゼロ以外で終了します。

使い分けの指針。

Plain Markdown で十分なのは…

  • 一度きりのメモ、スパイク、または構造を必要としないほど小さなプロジェクトの場合。
  • ドキュメントから AI エージェントが構築せず — 人間が読んで理解するだけの場合。
  • 誰かが実装する要件ではなく、ラフなアイデアを書き留めている場合。

SpecScore を使うべきなのは…

  • AI エージェントがスペックから構築する場合 — 曖昧さが誤ったコードになります。
  • 複数のエージェントや人が同じ要件に依存する場合。
  • どのコードがどの要件を実装しているかを知る必要がある場合。
  • 「このスペックは完成したか？」を会議ではなくツールが答えるべき場合。
  • すべてを再読するのがスケールしないほどプロジェクトが大きい場合。

すでに持っているスペックを成長させる。

バックログを変換したり、ツールを変えたりする必要はありません。次のフィーチャーを選び、 そのための SpecScore スペックを書いて、specscore lint を実行してください — チケットが見落としたものを検出するか確かめましょう。実装するときに specscore:アノテーションを加えます。役に立った場合のみ、次のスプリントへ広げてください。

Plain Markdown は入り口です。SpecScore はその成長した先の姿です。

フィードバック

合格するスペックを。

CLI をインストールエージェント用 AI スキルを入手GitHub でオープンソース公開中

翻訳の誤りやこのページの改善案がありますか？ お知らせください.