tlc-spec-lean

Tech Lead's Club - Spec, Lean

義務を固定し、計画を自由にします。実装していない人が検証します。tlc-spec-driven 3.3.0（Felipe Rodrigues）、tlc-plan、tlc-implement に基づいています。

┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────┘   └────────┘   └───────┘   └────────┘
 read it    obligations   yours       always

コーディングエージェントによくある失敗は、要件が有効な義務にならないまま、完了を宣言してしまうことです。それに対抗するには、小規模で固定された外部の義務セットと、作成者ではない検証者が有効です。そうすれば、予算をモデルの振る舞いの演出ではなく、そこに振り向けられます。人間が、何が真実でなければならないか、そしてどのように構築するかを1つのドキュメントで確認します。その後に初めて、それは証明を伴う義務になります。タスクの細分化もコンポーネント一覧もありません。元に戻しにくいものには、その具体的な形を定めた一方通行の扉を設け、それ以外は構築しながら決めます。

ルール

参照ファイルを読んでいなくても、以下のルールは適用されます。それぞれの内容はここに記載されており、参照先からもここに戻るようになっています。

1. すべてのチェックは、具体的な値を伴う観測可能な主張と、それを確定する証拠の組み合わせです。証拠は、終了コードで判定できるテストまたはコマンド、あるいは、状態をキャプチャ画像で表す場合は、その画像をキャプチャと照合して判定するもの（ルール 9）です。
2. テストでは、コードが実際にどう動くかではなく、チェックに書かれた内容を検証します。実装を読んでテストを書いてはいけません。
3. テストを変更できるのは、それが証明する主張を変更するときだけです。また、そのテストが証明するコードと同じコミットで変更してください。テストを変更してテストスイートを通すと、テストが明らかにするはずの失敗が隠されます。チェックが誤っている場合は、作業を止めて確認を求めてください。
4. validate_checks.py が成功したら、チェックは固定されます。ウォークスルーまたは Verifier が不足している要件を見つけた場合は、チェックを追加できます。計画では、Landing、Surface、保存された形状は追加できます。一方、パスと Changes underneath は、それらを変更するコミットでも正しい状態に保ってください。
5. Verifier は新たに割り当てられるサブエージェントであり、作成者が担ってはいけません。また、機能ごとに必ず一度、screens サブエージェントと並行して実行します。check_proofs.py は機械的な部分、つまりすべての証拠の実行と HEAD での成功、画像、ウォークスルー、ミューテーションの検出を確認します。Verifier は判断に時間をかけます。誤ったルールでも成功してしまうミューテーション、誰も挙げていない例、基準より緩いアサーションを確認します。すべての指摘がコミットで解消され、proofs.md が HEAD で成功したら、作業は完了です。
6. ミューテーション数は checks.md の Mutations: に記載します（デフォルトは 3）。この数で Verifier が調査するルールの数が決まりますが、作業の質が決まるわけではありません。N の値にかかわらず、コード品質、各チェックを裏付けるテスト、完全な Coverage の結合が求められます。チェックは最低限です。チェックに明記されていないエッジケースやガードも、依然として作業の一部です。
7. 完了ゲートはスクリプトです。validate_verification.py が 0 で終了する必要があります。最終報告はその最終行から始めてください。ゲートが失敗した場合は、最初に伝え、読者に見つけさせるようなことは決してしないでください。
8. 承認済みの仕様があれば、ローカルでの編集とローカルコミットを行えます。git push、デプロイ、本番データの変更には、その操作に対する明示的な許可が必要です。
9. キャプチャ画像が示す状態には、画像を 1 枚用意します。 作成者はキャプチャのサイズに合わせたブラウザーウィンドウでその状態を再現し、キャプチャと同じ場所に <capture>.running.png として保存します。サイズとは、画像のスケールに対するピクセルサイズです。ウィンドウの幅が広いとページのレイアウトが変わり、後から画像をリサイズするとそれが隠れてしまいます。アプリを開き直して判定することはありません。screens サブエージェントがファイルを判定します（verify-screens.md）。画像内の文字がキャプチャより小さく見える場合は、画像がリサイズされています。撮り直してください。画像は ## Differences from the source に記載された点を除き、キャプチャと一致している必要があります。キャプチャ画像にない状態と、機能によって変更されない既存画面は、画像や判定者を使わず、テストまたは walk の証拠で証明します。
10. 依頼に添えられたキャプチャ画像、フレーム、またはライブサイトは、ユーザーが参考資料だと明示した場合を除き、準拠すべき対象です。準拠対象はユーザーだけが変更できます。それが示す内容を削除、改名、または逸脱する場合は、ユーザーに確認してください。その確認結果を .specs/STATE.md に決定事項として記録し、計画の ## Differences from the source に Confirmed: y - AD-NNN と記載してください。
11. 実行内容を保持するのはファイルであり、チャットはコンテキスト圧縮後に残りません。 ユーザーの承認は **Approved**: <date> - user: "<their words>" という形式で plan.md に記録してください。ユーザーが実際に述べていない内容を記録してはいけません。回答は届いたターン中に各ファイルへ記録してください。サブエージェントを送る前に、checks.md の ## Handoff にある **Dispatched:** 行へ各サブエージェントを記載してください。コンテキスト圧縮後、または新しいセッションでは、このファイルと現在のフェーズの参照資料を読み直してから、ファイルに記録された内容をもとに再開してください（memory.md）。

設定

プロジェクトでは、AGENTS.md または同等のファイルでこれを宣言し、checks.md の Mutations: 行に件数を記載します。

## tlc-spec-lean

mutations: 3

項目	実行内容	検出できないこと
check_proofs.py（常時）	各ランナーで HEAD の各証明を1回実行し、各チェックがフィルターで選択したテストと一致すること、画像とウォークを確認し、ミューテーションを注入します	誤った理由で成功するテスト
Verifier（常時）	ルールがどこにあるかにかかわらずN件のミューテーションを実施し、誰も指定していない2つの例、基準より緩いアサーション、拘束力のあるキャプチャと矛盾するチェックを確認します（verify.md）	ミューテーションで検証されなかったルール
screensサブエージェント（基準がキャプチャを参照している場合）	各キャプチャを作成者の画像と照合し、各行を same または differs として、指定された HEAD で記録します（verify-screens.md）	余白、色、フォントの太さ、スクリーンショットに表示されない細部、キャプチャに描かれていない画面

画面の確認ではミューテーションを行いません。誤った実装による影響が最も大きい箇所にNを使います。 機能に対してNが少なすぎると思われる場合は、その旨を1行で記載し、ユーザーが増やせるようにします。

成果物

.specs/
├── STATE.md                    # Decisions log (AD-NNN)
├── LESSONS.md                  # rendered by scripts/lessons.py - do not hand-edit
├── lessons.json                # machine-owned
└── features/<feature>/
    ├── plan.md                 # problem, shape, surface, doors, criteria
    ├── checks.md               # claims + proofs, the coverage join, swept, handoff
    ├── captures/               # binding source files, and the author's <capture>.running.png
    ├── screens.md              # the screens sub-agent's inventory and verdict, per picture
    ├── proofs.md               # written by check_proofs.py: every proof and mutation at HEAD
    ├── mutations.json          # the Verifier's mutations, re-run after the fix
    └── verification.md         # the Verifier's findings, each closed by a commit

一方向にしか戻せない変更がなく、おおよそ3ファイル未満の変更であれば、## Intent の段落を含む checks.md のみを作成し、plan.md は省略します。

フェーズ

フェーズ	作成するもの	参照先
計画	問題、構成、対象範囲、後戻りできない変更点、基準。人間による確認を求める唯一の既定の停止地点です	plan.md
チェック	証拠付きの主張、各セットのメンバーごとの照合、9つの側面の網羅的な確認	checks.md
ビルド	チェックから作成したテスト、コード、コミット、確認して保存した画面	build.md
検証	ルール5	verify.md、verify-screens.md

決定事項と教訓：memory.md。

スクリプト

<skill-dir> を、この SKILL.md があるディレクトリとして解決し、 python3 <skill-dir>/scripts/<name>.py を実行します。cwdがプロジェクトのルートでない場合は --root を渡します。終了コードが0以外の場合は停止して修正します。 スクリプトを読むのではなく実行してください。変更すべき内容はスクリプトのメッセージに示されます。

実行タイミング	コマンド
計画を提示する前	validate_plan.py <feature>
ビルドを開始する前	validate_checks.py <feature>。計画の **Approved**: 行も必須です
各コミットの前	check_commit.py --message "<msg>"
Verifierを実行する前、および修正後	check_proofs.py <feature> [--mutations <mutations.json>]
完了を宣言する前	validate_verification.py <feature>
教訓の抽出時	lessons.py add ...
バリデーターまたはテンプレートの編集後	selftest.py

selftest.py は scripts/fixtures/ のフィクスチャに対し、各ゲートルールにつき1回ミューテーションを行い、すべてのミュータントが検出されることを必須とします。フィクスチャは、合格する成果物セットの実例でもあります。

必要要件

必要なもの	用途	ない場合
Python 3.8以降（標準ライブラリのみ）	すべてのスクリプト	ゲートは実行されません。フェーズは引き続き適用されます
git	mutate.py と check_proofs.py（HEAD、クリーンな作業ツリー）	ミューテーションと HEAD のチェックは行われません。レポートにその旨を記載してください
サブエージェント	Verifierとscreensサブエージェント	ファイルを新しいセッションで実行し、self-verified と記載します。ゲートは警告を出します
画像を読み取れるモデル	screensサブエージェント	画像とキャプチャをユーザーに渡します
エージェントが操作できるブラウザー	<capture>.running.png の保存とウォーク	手順をユーザーに渡します

テストランナー：check_proofs.py はbun、vitest、jest、pytest、go testをそれぞれ1回の実行にまとめます （scripts/runners.py）。その他のコマンドはそれぞれ単独で実行し、終了コードで判定します。

出力

成果物を作成し、フェーズについて説明しないでください。最初に判定を示し、決定事項を明確に記載してください。 セクション見出しは英語のままにし、文章はプロジェクトの言語に合わせ、識別子は翻訳しないでください。