spec-to-code-compliance

仕様とコードの適合性

2つの成果物に食い違いがあり、その箇所を見つけるのが目的です。ドキュメントはシステムの動作を説明し、コードは実際の動作を決定します。その間にある食い違いは、バグかドキュメントの修正事項のいずれかであり、どちらに当たるかが指摘事項になります。

使用する場合

意図された動作を説明するドキュメントと、それを実装するコードの両方がある場合に使用します。プロトコルに対するホワイトペーパー、サービスに対する設計メモ、README に記載された保証と、それを支える関数などが該当します。

ドキュメントが権威あるもの、つまりクライアントが作成、公表したもの、または監査の基準となるものの場合に、特に有用です。その場合、乖離は古い説明ではなく欠陥となります。

使用しない場合

意図された動作を説明するドキュメントのないコードには使わないでください。照合する対象がなく、コードから推測した要件をコード自体と照合することになります。まず audit-context-building でシステムモデルを構築してください。

一般的なバグ探しには使わないでください。対象となるのは、コードとドキュメントが食い違うケースです。どちらにも触れられていないバグは対象外であり、ドキュメントが認めているバグはドキュメントに対する指摘事項になります。

ドキュメントの作成や改善にも使わないでください。ただし、修正が必要な箇所の一覧は作成されます。

このコンテキストでは要件を確認しないでください

/spec-to-code-compliance:spec-compliance <path> を実行してください。スラッシュコマンドにはパスを渡します。仕様を直接指定する場合や、対象範囲を広げる場合は、その値を指定して実行するよう依頼してください。たとえば、「./contracts に対して SPEC.md を使い、20件の要件を確認して spec-compliance を実行」と依頼すると、値は {path, spec, limit} としてスクリプトに渡されます。スラッシュコマンドの後にオブジェクトをそのまま入力しても動作しません。文字列として渡され、パスとして扱われます。

このコマンドはドキュメントを見つけ、個別に確認できる要件に分割し、各要件に専任のエージェントを割り当ててコードを調査します。さらに、報告前に独立したエージェントがそれぞれの乖離を反証しようと試み、spec-compliance/REPORT.md と、spec-compliance/requirements/ 以下に要件ごとのファイルを1つずつ書き出します。ここに戻るのは、要約された記録のみです。

単一の要件を確認するには、spec-to-code-compliance:spec-compliance-checker エージェントにその要件を調査させてください。

これは出力先の好みに関する話ではありません。誠実に実行するなら、この確認作業は1つのコンテキストウィンドウに収まりません。1つの要件を判断するには、その要件を強制するコードと、その呼び出し先および呼び出し元を読む必要があります。これを30件の要件について行うには、30本の呼び出しチェーンを同時に把握しなければなりません。インラインで試みると、最初の数件は実際に確認され、残りはもっともらしい確認になります。どちらの場合もトランスクリプトは同じように見えます。見込みのありそうな関数名だけを根拠にした判断も、その関数を読んだうえでの判断も、見た目では区別できないためです。要件ごとに個別のコンテキストで行うことが、この違いを明らかにします。

次の2つの性質は指示ではなくスクリプトによって実現されるものであり、ここでは得られません。

• 指摘事項の作成者が行っていない反証。 Claude は確認を依頼されたとき、自身が作成した指摘事項を支持する傾向があります。このワークフローでは、各乖離を、それを作成していないエージェントに渡します。1つはコードを再度読み、もう1つはドキュメントを読み直し、どちらかが否定した指摘事項は除外されます。
• 文章ではない形式の記録。 返却スキーマに従うサブエージェントは、読んだ行と実行した検索を明記する必要があります。absent の判定には、試したパターンとその結果が付随します。これだけが、本当に存在しない場合と、検索を早々に打ち切った場合を区別します。

routes-not-inline eval で測定した結果、このプラグインがインストールされていると毎回作業がディスパッチされ、インストールされていないと一度もディスパッチされません。差は +1.00 です。このセクションを削除してもワークフローを残せば、何も変わりません。ワークフロー自体が実行可能なコマンドとして存在し、独立して検出、ディスパッチされるからです。これを、このテキストではなく動作を担う仕組みだと捉えてください。このセクションは、人間が何が実行されるのか、その理由は何かを知るためにあります。ルーティングがこのセクションに依存しているからではありません。

何が返されるか、その読み方

各要件には、implemented、partial、contradicted、stronger-than-spec、 absent、undecidableの6つの判定のいずれかが付けられます。注目すべきなのは、中央の4つです。

• **partial**は通常、レポートの中で最も深刻な項目です。誰もがテストするような経路では要件を満たしますが、誰もテストしなかった経路では満たさないため、発見されるまで長く見過ごされていました。
• **absent**は、完全にsearchedレコードに依拠します。内容を確認してください。適用の仕組みは、検索対象外の場所、たとえばモディファイア、基底クラス、先にチェックを行う呼び出し元などにあることがよくあります。
• **undecidable``と、あらゆるdocumentProblem`は、ドキュメントに関する指摘です。確認できないほど曖昧な要件は、クライアントが誰かに遵守を求められない要件です。
• **stronger-than-spec**は、文書化されていない制約です。現時点では機能していますが、そのコードを変更する次の担当者には、何かがその制約に依存していることが伝わりません。

このレポートには逆方向の情報、つまり、どの文書にも記載されていないコードの動作も含まれます。要件ごとの分析は文書を起点に進めるため、この種の情報は原理的に見つけられません。

レポートが完全だと判断する前に、notChecked、unverified、unreadableDocumentsを確認してください。ファンアウトの上限を下回る要件は一度もチェックされておらず、反証を試みた両方のエージェントが失敗した乖離は、確認済みではなく未検証として扱われます。

ワークフローが代わりに判断しないこと

重大度は、テキストとの隔たりではなく、その結果で決まります：DIVERGENCE_RUBRIC.md。プールの資金を流出させる丸め処理は、文書とは異なる方法でMUSTを満たすケースより重大です。また、動作への影響を伴わないドキュメントのずれは、ドキュメントのチケットにすぎません。

判定そのものが指摘事項なのではありません。必須要件に対するabsentは指摘事項ですが、ロードマップ項目を説明する文に対するabsentはそうではありません。どちらに当たるかを判断するのがこのスキルの役割であり、ワークフローはその判断に必要な証拠を提示します。

対象が契約である必要はありません

どの対象でも問うことは同じです。この要件は何を求めているのか、どこで適用されるべきか、すべての経路で適用されているか。ただし、何を仕様とみなすか、適用の仕組みがどこに隠れているかは、それぞれ異なります。 DOMAIN_NOTES.mdでは、コントラクト、CおよびC++、サービス、逆コンパイルされたファームウェアにおける違いをまとめ、仕様がプロジェクト文書ではなくRFCや標準である場合についても説明しています。対象がコントラクトでない場合や、大規模な標準に対するチェックの範囲を定める場合は、こちらをお読みください。

参考資料

• ANALYSIS_FORMAT.md — 要件ごとの分析を保存する形式です。このプラグインを拡張するときや、レコードの信頼性を判断するときにお読みください。
• WORKED_EXAMPLE.md — 判定まで追跡した3つの要件を紹介します。いずれも誤りやすい判定の例で、要件とは異なる形で満たされる算術処理、検索結果そのものが指摘事項となる不在、誰もテストしなかった経路以外ではあらゆる経路で適用されているケースを取り上げています。
• DOMAIN_NOTES.md — ドメインごとの仕様と適用方法の対応関係です。
• DIVERGENCE_RUBRIC.md — 重大度と、乖離の2つの方向について説明しています。