agentleFS
yktsnetyktsnet/dotfiles-public/.claude/skills/guarantee-audit/SKILL.md

guarantee-audit

Skill1 starsChanged 5 days agoMITView on GitHub

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

The file

Files
SKILL.md

repo-ship の段の順の外にある。共有のリポ(repo-ship の「共有のリポ」)でテストを持つときだけ、readme 段の前に入れる(README から台帳へリンクするため)。

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

  1. 前提確認: 対象リポに docs/guarantees/ が無いことを確認する
    • 既にあれば「棚卸し済み」。この場合は 2〜3 を「現行台帳とテストの差分確認」に読み替える(乖離チェックモード)。あわせて、3 の組み立てから外れたところ(同じ対象が複数のファイルに散っている、1行に約束が複数ある、載せないものが載っている)を直す
    • 1ファイルの docs/guarantees.md があれば、旧い形である。乖離チェックモードで、3 の形の docs/guarantees/ へ組み直す
    • テストが1本も無ければ、台帳ではなく通常Issueで最初のテストから始めるべき旨を報告する。棚卸し文脈(既存リポへの後付け実行)ではここで止まる。パイプライン文脈(repo-ship の readme 段の前に入れたとき)では止まらず、skip した旨を明示的に報告して readme 段へ進む
  2. 抽出: リポの全テストファイルを読み、テストが固定している振る舞いを自然言語の保証として書き出す
    • 契約面(公開API・CLI・配布物・外部から観測可能な振る舞い)と内部実装を仕分け、契約面のみを一覧にする
    • 各保証に出典(テストファイル・テスト名)を付す
    • 契約面か内部実装か判断が割れる面(CLI内部関数群等)だけ、この時点で user に質問する
  3. ドラフト書き出し: 抽出結果を docs/guarantees/ にドラフトとして書き出す。一覧をチャットに全量貼らない(user のレビュー対象はファイル)。構成・書式は reference/example-guarantees.md の例に従う(骨組みはこの例が正本)。要点:
    • 入口の docs/guarantees/README.md に、人が読んで分かる決まりを置く。台帳は、敷いた人がいなくなっても、開いた人が目的と書き足し方を読み取れなければ、Issue ごとに節が増える形になっていく。README に書くのは次の6つで、どれも数行に収める
      • 目的: いま何を約束しているかを1か所で読む・次の変更で「維持する保証」を引く・テストの無い約束を残す、の3つ。ここに載っていない振る舞いは約束ではなく、予告なく変わりうることも書く。対象範囲(何を契約面とするか)・対象外・design-decisions.md 相当と同格である旨も、ここに1〜2文で書く
      • 分け方: 約束の対象(モジュール・公開 API の群・CLI のコマンドなど、外から見える単位)ごとに1ファイル。テストファイル・Issue・作業の単位では分けない。新しい対象を作ったときだけファイルを足す
      • 書き方: 1ファイルに「保証|対応テスト」の表を1つ置き、1行に約束を1つ、宣言文で書く。要件の出典・経緯・設計の理由は書かない(正本の設計文書が持つ)。載せないもの(UI の見た目・手で確かめる画面の振る舞い・型検査・開発用の検査)も挙げる
      • 引き方: Issue で「維持する保証」を挙げるときは、Issue の対象のファイルを開く。テストが落ちたら、そのテストの名前で台帳を検索すると、破れた約束の行が見つかる。約束が守られていることは、全テストを流す CI が確かめる。コードのファイルから約束を引く仕組みは置かない(実装とテストの名前は1対1でなく、機械では正確に引けない)
      • 運用: 台帳を変えるときの手順。変更の前にこの README を読み、変更が触れるファイルから「維持する保証」を引く。約束を足す・変える・消すときは、承認を受けた保証節の文のまま、該当するファイルの表に行を足す・直す・消し、対応テストも同じ変更で直す。Issue や作業ごとにファイルや節を起こさない。テストの無い約束は Gaps に書き、テストを足したら移す。乖離は guarantee-audit で棚卸しする。あとから台帳に触る AI は、この README だけを読んで手順を決めるので、ここに書いていない運用は守られない
      • ファイルの一覧(## Files)と、テストの無い約束があるときだけ ## Gaps
    • タイトルは # Guarantee Ledger (Draft)(README の H1)。H2 は英語(## Files、あるときだけ ## Gaps)、本文は日本語
    • 約束の対象ごとのファイルは、ファイル名を対象の名前(loader.md、cli-export.md など)にし、H1 に対象の名前を書く。中身は表だけにする。約束が10行以上のファイルは、内容のまとまり(何についての約束か)で ## の見出しを立て、見出しごとに表を置く。1つの見出しには3行以上を入れ、3行に満たないまとまりは近い見出しにまとめる。3行以上ある別のまとまりを、数を揃えるために1つの見出しへ混ぜない。10行未満のファイルは見出しを置かない。見出しは行の主語になる名詞句にし、行に主語が無くても何の約束か分かるようにする。ファイルは分けない(分けるとファイルを指す参照の付け替えが要る)。行を足して10行以上にした Issue が、同じ変更の中で見出しを立てる。この決まりは README の「書き方」に書く
    • 別のファイルにも同じ名前のテストがあれば、test_x(tests/example/)のように置き場を添え、落ちたテストの名前で検索したときに約束の行が1つに決まるようにする
    • 表の1行の保証文が約束の全文であり、表の外に宣言の本文を書かない。本文の箇条と要約の表の両方に書くと、要約が短縮形になり、承認のときにどちらの文を読めばよいかが決まらない
    • 主語は表の行ごとに書く。ファイルが単一の関数だけを扱うなら省いてよい
    • テストに裏付けられた保証のみを載せる
    • ## Gaps 節(README): テストの無い約束があるときだけ置く。保証すべきなのにテストが無いものを、本体と明確に区別して列挙する(棚卸しで新しく分かるのは、主にここである)
    • 末尾に ## About を立てない。対象範囲・対象外は冒頭の目的と同じ問いに答えるので、2か所に分けると片方だけ直されてずれる
    • 書き出し後、次を自己チェックしてから次のステップに進む
      • README の目的・分け方・書き方が、台帳を初めて開いた人に通じる文になっているか
      • 同じ対象の約束が2つのファイルに分かれていないか。テストファイルの単位で分けていないか
      • 各ファイルが H1 と表だけを持ち(10行以上なら3行以上ずつの ## の見出しごとに表)、1行に約束が1つか(「A し、B し、C する」の行は分ける)
      • README の ## Files とファイルが一致しているか
  4. 承認: ファイルパスと要約(保証の件数・欠落候補・迷った仕分け)だけをチャットで報告し、user にファイル上での承認を促す。観点は3つ
    • 削る: 要らない保証
    • 直す: 文言が意図とズレている保証
    • 足す: 欠落候補の採否(採用されたものが次のIssueの対象になる)
    • user はファイルを直接編集してもよいし、対話で指示してもよい。対話の場合は相談者がファイルに反映する
  5. 欠落テストの追加: 承認で採用された欠落候補のテストを、その場で書く
    • アサーションは承認済みの保証文の転記。リポの規約(DI・fake・テスト配置)に従う
    • テストスイートを実行して全緑を確認し、対応する行を README の ## Gaps 節から台帳の該当するファイルの表へ移す(テストと台帳更新は同じ変更にまとめる)
    • テストが赤になった(実装が保証を満たしていない)場合、そのテストは追加せず、実装修正を通常Issueとして起票する。実装に触る自由度が生じた時点で棚卸しの範囲を超える
  6. 格上げ: 4(承認)が「これで良い」で完了した時点——足す承認を経て5が終わった場合も、削る/直すのみで5が不要だった場合も——で台帳を正式運用に切り替える
    • README のタイトルを # Guarantee Ledger (Draft) から # Guarantee Ledger に変える((Draft) を外す)
    • ## Gaps 節が空になったら節ごと削除する(「現時点で無し」のような空を埋めるだけの記述を残さない。無いなら書かない)。承認で見送られ残った項目があればそのまま残す(それ自体が正しい記録)
    • コミット・push はしない。変更をワーキングツリーに残し、ファイル一覧と結果を報告して止まる(user が diff をレビューしてコミット)。コミットの件名に guarantee-audit を含めるよう、報告に添える。local-issue がこの件名で前回の棚卸しを見つけ、そのあとに台帳を変えたコミットを数えて次の棚卸しを促す

制約:

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

テスト方針(GDD)

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

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

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

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

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

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

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

台帳は各リポの docs/guarantees/ が正本であり、この配置は変えない。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.