speccheck

speccheck

仕様は、それに実際に応える作業があってこそ価値があります。要件が書かれ、課題が登録され、プルリクエストがマージされ、コードが取り込まれます。そして、その積み重ねのどこかで、「仕様が求めたこと」と「対応したと主張するもの」の対応関係が、気づかれないまま朽ちていきます。speccheck はその対応関係を監査します。仕様の要件と、それに対してなされた主張を渡すと、どの要件がカバーされているか、されていないか、どの主張が存在しない要件を参照しているか、各要件がいくつの主張を集めているかを報告します。

データは何も取得されません。少なくとも1つの主張が要件の ID を指定した時点で、その要件はカバーされているとみなされます。主張の出所は課題、プルリクエスト、コード参照のいずれでもよく、重複する主張もそれぞれカウントされます。同じ要件を3つの課題が主張していることは、重複排除すべきノイズではなく、件数で確認する価値のある事実です。どの要件にも存在しない ID を指定する主張は宙ぶらりんです。受け取った順に全文がそのまま返され、カバレッジにも、どの要件の合計にもカウントされません。これは通常、要件名の変更か入力ミスを意味します。いずれにしても、推測で判断するツールではなく、仕様のオーナーが確認すべき問題です。

判定結果はレポートを1つの言葉にまとめたものです。すべての要件に主張がある場合、仕様は fully_covered です。それ以外の場合は、カバレッジ率（カバーされた要件数を全要件数で割り、最も近い整数に丸めた値）で判定します。80以上は mostly_covered、50以上は partial、それ未満は sparse です。判定結果には常に件数が添えられるため、その言葉を根拠なく信じる必要はありません。

不正な入力は、該当するパスを示す検証エラーとなり、部分的な結果は返されません。requirements は、空でない id と text をそれぞれ持つオブジェクトの空でない配列でなければなりません。要件 ID は一意である必要があり、重複があれば ID を示すエラーになります。claims は配列でなければならず、空でもかまいません。各オブジェクトには空でない requirement_id と source_ref、および issue、pr、code のいずれかの source_kind が必要です。未知の追加フィールドは無視されます。計算は純粋かつローカルで行われます。ネットワークも設定も不要で、リポジトリを読み取ったり変更したりすることもありません。

CLI

npx @reneturcios/speccheck check --input args.json
npx @reneturcios/speccheck --version

args.json には引数オブジェクト全体を格納します。

{
  "requirements": [
    { "id": "REQ-1", "text": "Users can sign in with a passkey" },
    { "id": "REQ-2", "text": "Sessions expire after 24 hours" },
    { "id": "REQ-3", "text": "Admins can revoke any session" }
  ],
  "claims": [
    { "requirement_id": "REQ-1", "source_kind": "pr", "source_ref": "PR #412" },
    { "requirement_id": "REQ-1", "source_kind": "issue", "source_ref": "issue #388" },
    { "requirement_id": "REQ-2", "source_kind": "code", "source_ref": "src/session.ts" },
    { "requirement_id": "REQ-9", "source_kind": "issue", "source_ref": "issue #401" }
  ]
}

結果は JSON として出力されます。

{
  "covered": ["REQ-1", "REQ-2"],
  "uncovered": ["REQ-3"],
  "dangling_claims": [
    { "requirement_id": "REQ-9", "source_kind": "issue", "source_ref": "issue #401" }
  ],
  "claim_counts": { "REQ-1": 2, "REQ-2": 1, "REQ-3": 0 },
  "coverage_percent": 67,
  "verdict": "partial",
  "requirement_count": 3,
  "claim_count": 4
}

claim_counts には、ゼロ件の要件も含め、すべての要件の項目が含まれます。キーは、要件が渡された順序になります。終了コード：成功時は 0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）時は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/speccheck mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "speccheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/speccheck", "mcp"]
    }
  }
}

ツール

• check_spec_coverage — 呼び出し元から渡された要件と主張の情報に基づき、課題、プルリクエスト、またはコードによって仕様の要件が主張されていることを確認します。

  • requirements（配列、必須、1項目以上）— 仕様の要件です。各項目は空でない id と text を持つオブジェクトで、ID は一意でなければなりません。
  • claims（配列、必須、空でも可）— 課題、プルリクエスト、またはコード参照が要件に対応していることを示す主張です。各項目は空でない requirement_id と source_ref、および issue、pr、code のいずれかの source_kind を持つオブジェクトです。

  {covered, uncovered, dangling_claims, claim_counts, coverage_percent, verdict, requirement_count, claim_count} を返します。

Docker

docker run -i ghcr.io/cloudcorprecords/speccheck
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/speccheck check --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios