guarantee-audit

既存テストから公開面の保証を抽出し、保証台帳 docs/guarantees.md のドラフトを書き出して user の裁可を受け、裁可済みの欠落テストをその場で追加し、台帳を正式運用へ格上げする。テストを持つリポに台帳を初めて敷くとき、または台帳とテストの乖離を疑うときに使う。

SKILL.md

GitHub

公開パイプラインの固定順: repo-standardize → guarantee-audit → repo-readme → readme-i18n → repo-publish → repo-about。本 Skill は第2(新規リポではテストの有無を確認し、README 本格化より前に台帳を敷く)。この順は都度再判断しない。

相談者として保証台帳の棚卸しを行う。台帳ドラフトの作成、裁可済み欠落テストの追加、台帳の正式運用への格上げまでが担当。欠落テストはIssueにしない(裁可の時点でアサーションが確定しており、実装の自由度が残らないため。Issueは自由度の統制であり、統制すべき自由度が無い)。プロダクトコード(src/)は書かない。

  1. 前提確認: 対象リポに docs/guarantees.md が無いことを確認する
    • 既にあれば「棚卸し済み」。この場合は 2〜3 を「現行台帳とテストの差分確認」に読み替える(乖離チェックモード)
    • テストが1本も無ければ、台帳ではなく通常Issueで最初のテストから始めるべき旨を報告する。棚卸し文脈(既存リポへの後付け実行)ではここで止まる。パイプライン文脈(公開パイプライン第2ステップとしての実行)では止まらず、skip した旨を明示的に報告して次ステップ(repo-readme)へ進む
  2. 抽出: リポの全テストファイルを読み、テストが固定している振る舞いを自然言語の保証として書き出す
    • 契約面(公開API・CLI・配布物・外部から観測可能な振る舞い)と内部実装を仕分け、契約面のみを一覧にする
    • 各保証に出典(テストファイル・テスト名)を付す
    • 契約面か内部実装か判断が割れる面(CLI内部関数群等)だけ、この時点で user に質問する
  3. ドラフト書き出し: 抽出結果を docs/guarantees.md にドラフトとして書き出す。一覧をチャットに全量貼らない(user のレビュー対象はファイル)。構成・書式は reference/example-guarantees.md の例に従う(骨組み・主語の反復ルール・見出し言語ともにここが正)。要点:
    • 見出し(H1〜H3)は英語、本文(箇条書き・表・注釈)は日本語。見出しの丸括弧も半角 ()。タイトルは # Guarantee Ledger (Draft)
    • 本体は ## Guarantees 節から始める。読み手が最初に読むのは保証そのものであり、前提説明ではない
    • ## Guarantees の中はテストファイル単位で区切る(### N. \tests/test_x.py` — target module/class (function)`。ファイルパスは常にバッククォート)。各区切りの中は、テストが保証している振る舞いをそのまま宣言文として箇条書きにする。見出しに機能名(例:「パラメータ上書き」)だけを立てて実際の保証を本文に書く二段構成にしない——見出しやラベルは保証の要約ではなく、保証文そのものが主役
    • 区切り内が単一の関数・メソッドのみを扱うなら、箇条書きのたびに主語(その名前)を書き直さない。区切り内に複数の異なる関数・メソッドが混在するなら、行ごとに主語を明示する。前者で毎回主語を書くと型の反復になり、後者で省くとどの対象の保証か分からなくなる
    • 各テストファイル区切りの末尾に「保証(要約)|対応テスト」の2列表を置く。この表は保証を宣言する場所ではなく、索引(どの保証をどのテストが裏付けているかのルックアップ)に徹する
    • テストに裏付けられた保証のみを載せる(執行装置の無い約束を混ぜない)
    • ## Gaps 節: 保証すべきなのにテストが無いものを、本体と明確に区別して列挙する(ここが棚卸しの主要な収穫)
    • 文書末尾に ## About 節を置き、対象範囲(何を契約面とするか)・対象外・欠落の意味論「ここに載っていない振る舞いは約束ではなく、予告なく変わりうる」・design-decisions.md 相当と同格である旨を、1〜2文の注釈程度にまとめる。「対象範囲」「対象外」を別見出しに割らない。前提説明は巻末に小さく置き、本文の可読性を優先する
    • 書き出し後、次を自己チェックしてから次のステップに進む
      • H1〜H3の見出しが英語(丸括弧も半角)になっているか
      • 各区切りで、本文の保証文の数と表の行数が対応しているか(1行に複数保証を意図的に集約した場合を除き、本文にあって表に無い項目が無いか)
      • 各区切りで、主語の反復ルール(単一対象は省略・複数対象は明示)を守っているか
      • 見出しのファイルパスがバッククォートで統一されているか
      • 本文冒頭が ## Guarantees 節から始まり、## About が1〜2文の注釈程度に収まっているか(対象範囲/対象外の別見出しに分かれていないか)
  4. 裁可: ファイルパスと要約(保証の件数・欠落候補・迷った仕分け)だけをチャットで報告し、user にファイル上での裁可を促す。観点は3つ
    • 削る: 要らない保証
    • 直す: 文言が意図とズレている保証
    • 足す: 欠落候補の採否(採用されたものが次のIssueの対象になる)
    • user はファイルを直接編集してもよいし、対話で指示してもよい。対話の場合は相談者がファイルに反映する
  5. 欠落テストの追加: 裁可で採用された欠落候補のテストを、その場で書く
    • アサーションは裁可済みの保証文の転記。リポの規約(DI・fake・テスト配置)に従う
    • テストスイートを実行して全緑を確認し、対応する行を台帳の ## Gaps 節から本体へ移す(テストと台帳更新は同じ変更にまとめる)
    • テストが赤になった(実装が保証を満たしていない)場合、そのテストは追加せず、実装修正を通常Issueとして起票する。実装に触る自由度が生じた時点で棚卸しの範囲を超える
  6. 格上げ: 4(裁可)が「これで良い」で完了した時点——足す裁可を経て5が終わった場合も、削る/直すのみで5が不要だった場合も——で台帳を正式運用に切り替える
    • タイトルを # Guarantee Ledger (Draft) から # Guarantee Ledger に変える((Draft) を外す)
    • ## Gaps 節が空になったら節ごと削除する(「現時点で無し」のような空を埋めるだけの記述を残さない。無いなら書かない)。裁可で見送られ残った項目があればそのまま残す(それ自体が正しい記録)
    • コミット・push はしない。変更をワーキングツリーに残し、ファイル一覧と結果を報告して止まる(user が diff をレビューしてコミット)

制約:

  • プロダクトコード(src/ 等のテスト以外)は書かない。書いてよいのは docs/guarantees.md・テストファイル・(赤テスト発見時の)Issue ファイルのみ
  • 追加するテストのアサーションは裁可済みの保証に限る。裁可を経ていない保証をテストにも台帳本体にも入れない
  • 台帳の本体に載せるのは、テストに裏付けられた契約面の保証のみ。内部実装のテストを列挙し始めたら仕分けに戻る

テスト方針(GDD)

テストは変更可能性の担保である。実行者(AI)が壊したことに自分で気づくための装置であり、注意し続ける人間を前提にしない。

保証(何が壊れてはいけないか)は Issue の保証節で人間が裁可し、テストの実装は実行者が書く。この分業を Guarantee-Driven Development (GDD) と呼ぶ。テストそのものが正なのではなく、裁可された保証を実行可能な形に書き下ろしたものである。TDD がテストを先に書く規律だとすれば、GDD は約束の裁可を先に行う規律であり、人間の仕事はテストを書くことから約束を裁可することへ移る。Issueドリブン期のリポはこの方式で保守する(フェーズは各リポの CLAUDE.md で宣言する)。

濃淡はリスクベースで決める: 公開API・契約面は厚く、内部実装は薄く、UI・見た目は user の手動検証に回す。

fix には回帰テストを同梱する。

外部依存は DI で受け、テストは fake で差し替える(実サービスに接続しない)。

各リポは公開面の保証を docs/guarantees.md(保証台帳)として持てる。

  • 構成: 自然言語の保証の箇条書き+対応テスト(ファイル・テスト名)の表。載せるのは契約面の保証のみで、内部実装のテストは載せない。地位は design-decisions.md と同格で、実装と食い違う場合は指摘対象になる。
  • 敷設: 初版は guarantee-audit skill で敷く。新規リポは公開パイプラインの第2ステップとして(README が台帳へリンクするため README 作成より先に)、既存リポは既存テストの棚卸しとして。
  • 追従: 以後は Issue の保証節と同一 PR で更新する。台帳とテストの乖離は guarantee-audit による定期棚卸しで検出する。
  • スコープ: 台帳のスコープ外に新しい契約面が生まれたときは、スコープに入れるかを Issue 起草時に判断する(対象外の記載は素通りの根拠にしない)。
  • 到達性: 台帳は README から到達可能にする(リンク位置は repo-readme スキル §7 に従う)。
  • Gaps 節: 保証すべきだがテストが無いものを見送り理由ごと記録し、空になったら節ごと削除する。

台帳は各リポの docs/guarantees.md が正本であり、この配置は変えない。ただし複数リポを並行して回すと、「今フリート全体で何を約束しているか」を一望できる場所が無くなる。裁可する側が全体を見渡せないのは台帳の目的に反するため、定期実行で各リポを GitHub API で調べ、台帳を持つリポへの GitHub 上のリンクを1枚の索引に並べる運用を敷いている。実体はコピーせず、正本は各リポに残ったまま参照だけを束ねる。端末のディレクトリ配置に依存しないので、索引は GitHub 上でそのまま読める(手順は reference/guarantees-index/README.md を参照)。