Tech Lead's Club - Spec, Lean
責務を固定せよ。計画を自由にせよ。構築しなかった者で証明せよ。tlc-spec-driven 3.3.0（Felipe Rodrigues）、tlc-plan、tlc-implement より派生。
┌──────┐ ┌────────┐ ┌───────┐ ┌────────┐
│ 計画 │ → │ チェック│ → │ 構築 │ → │ 検証 │
└──────┘ └────────┘ └───────┘ └────────┘
読め 責務 あなたの 常に
4つの動作、コードの前に2つの成果物、後に1つ。人間は何が真でなければならず、どのように構築されるのかを1つの文書で確認し、その後にのみ、それらのいずれかが証明付きの責務となります。タスクの分割はなく、計画はコンポーネントカタログを持ちません。元に戻すのが難しいものには、その具体的な形状とともに一方通行の扉が設定され、元に戻せるものはすべて構築中に決定され、差分でレビューされます。
この形状の理由
コーディングエージェントの主な失敗は、推論の悪さではなく、読まれたものの能動的な責務にならなかった要件、そしてその上に立てられた完了の主張です。うまく測定できる緩和策は、小さく、固定され、外部にある責務セットと、作成者ではない検証者です。自己チェックは作成者自身の盲点を再現します。したがって、このスキルはその2つに予算を使い、モデルの動作を調整することには使いません。
従来のスペック駆動フローと異なる点を2つ、最初に述べておきます。
- 粒度は品質ではない。 機能を15の1ファイルタスクに分割することで得られるのは順序付けであり、正確性ではありません。そして、タスクごとにプロセスを読み直すコストがかかります。証明の網羅性が正確性をもたらします。
- モデルが従わなければならない計画は、責務と注意を競合する。
Where、Tools、Depends onのようなフィールドはモデルが決定する仕事なので、書き留められません。
重要なルール
固定されたルール群。これらは参照ファイルが読まれなくても保持され、プロファイルによって規模が縮小されることのない唯一のルールです。
- すべてのチェックは、具体的な値を伴う1つの観察可能な主張と証明（終了コードで決着するテストやコマンド）です。証明のないチェックはありません。
- テストは、チェックが言うことを主張し、コードがたまたま行うことを決して主張しません。実装を読んでテストを書いてはいけません。
- 断言を弱めたり、テストを削除したり、スキップしてスイートをパスさせたりしてはいけません。本当に間違ったチェックは編集ではなく、停止して質問する対象です。
- チェックと「テストポリシー」の行は、承認されたら固定されます。設計において、
Landing、Relations、Surfaceは追加可能です。構築中に発見された扉は、それを閉じるコードの前に行を追加し、ユーザーが承認した行は決して書き換えられません。FlowとImpactはどちらでもありません。それらは真に保たれ、異なるパスはそのパスのコミットのホップを変更します。 - 検証者は新しいサブエージェントであり、作成者ではなく、オプションではなく、依頼を待つこともありません。機能全体を保持する者は、機能の最後のコミットが
<feature base>..HEADに着地した後、すべてのチェックを使ってそれを派遣します。構築者が行うことは決してなく、構築者の子としても行いません。構築者は完了し、報告し、停止します。最後のコミットで作業は完了しません。検証者の報告がすべてのチェックを説明したときに完了します。 - プロファイルは下限であり、秘密ではありません。 検証報告書はそれを指名するか、「欠陥が注入されていない」は、それらを注入するのを忘れたように正確に読み取れます。
- 完了ゲートはスクリプトであり、感覚ではありません。
validate_verification.pyが終了コード0でなければなりません。 - 爆発半径： 承認されたスペックは、ローカル編集とローカルコミットを許可します。
git push、デプロイ、および本番データの変更には、そのアクションに対する明示的な許可が必要です。
プロファイル
プロジェクトは、AGENTS.md または同等のもので、どれだけ実行するかを宣言します。宣言がない場合：light。tlc-implement と同じ3つのレベルで、同じ方法でゲートされるため、2つのスキル間の移動に2つ目の語彙は必要ありません。
## tlc-spec-lean
profile: light
budget: 150k
| プロファイル | 追加するもの | キャッチできないもの |
|---|---|---|
light (デフォルト) | 各名前付きテストが存在し実行されることを示す HEAD での証明、チェックごとに1つの配置されたアサーション、レベルとサンプリングのギャップ、Swept existing の再読み取り | 証明のない集合メンバー; 誤った実装でもパスするテスト |
standard | Coverage 結合の再計算、各判定付きの Test policy 行、アサーションサーフェスごとに1つの欠陥 | 拘束力のあるソースと矛盾するチェック; 誰も構築しなかった画面 |
ui | 拘束力のあるソースを開いて比較、画面ごとのコピー および 配置の列挙 | 間隔、色、フォントウェイトのみ、画面ごとに列挙 |
各ステップは検出される障害のクラスを追加するため、安価なプロファイルは同じ製品の割引ではありません。選択する前に右の列を読んでください。light について2つのことは、その行自体が言っているので口に出して言う価値がありますが、見落とされがちです。それは、証明されていない列挙された集合メンバーに気づかず、誤った実装でもパスするテストに気づかないことです。standard はまさにそれらの2つのために存在します。
ui はインターフェースのない作業にはコストがかかりません。すべての画面ステップは画面が存在することを条件とします。入力が空のステップは、パスではなく1行のコストがかかります（「設定行なし」、「拘束力のあるソースなし」）。
Coverage 結合は、すべてのプロファイルで checks.md に書き込まれます。結合こそが省略を構造的なものにするものであり、作成時にはコストはかかりません。standard が購入するのは、検証者が作成者のテーブルを読み返す代わりに、各セットの権威からそれを再計算することです。
プロファイルはピン（固定）であり、好みではありません。tlc-implement とは異なり、これは要求されるのではなく強制されます。validate_verification.py は、報告書のプロファイルが checks.md が承認されたプロファイルと異なる場合、および欠陥行や再計算されたカバレッジがない standard 報告書、拘束力のあるソースのセクションがない ui 報告書を失敗させます。したがって、実行されなかったステップは、忘れられたステップと区別可能なままです。これがまさにフロアを宣言する理由です。
プロファイルが手元の機能に対して薄すぎると思われる場合は、1行でその旨を述べ、ユーザーに引き上げさせてください。黙ってプロファイル以上のことを行うと、それを宣言する価値があった予測可能性が失われます。
成果物
.specs/
├── STATE.md # 決定ログ (AD-NNN) + ハンドオフスナップショット
├── LESSONS.md # scripts/lessons.py がレンダリング - 手動編集禁止
├── lessons.json # マシン所有
└── features/<feature>/
├── plan.md # 問題、フロー、影響、残りの形状、基準。監査は最後
├── checks.md # 主張 + 証明、カバレッジ結合、テストポリシー、スイープ
└── verification.md # 検証者の報告
各フェーズがコンテンツを生成したときにファイルを作成します。一方通行の扉がなく、おおよそ3ファイル未満の変更の場合は、## Intent 段落のみの checks.md を作成し、plan.md はスキップします。これは1つの境界のある例外であり、サイジングマトリックスではありません。
理解と責務は別の成果物
plan.md は、人間が何かがテストセレクタ付きの主張に変わる前に計画し、異議を唱えることができるために存在します。何が構築されているかを再構築するために40のチェックを読むことは計画ではなく、形状を決定するのと同じパスでチェックを書くと、すでに仮定されていたことを批准するチェックが生成されます。
両方の半分は、それらが1つのレビューであるため、1つのファイルに存在します。 ファイルの境界は意味的なものです。こちら側では、人間が確認するもの。もう一方の側では、証明付きの責務。計画をスペックと設計に分割することは、どちらにも一致しない場所でそれを切断し、1つの機能に2つの必須停止ポイントをもたらすことになります。ファイルの順序は読むためのものです - 問題、フロー、影響、残りの形状、基準、監査テーブル。書き順はそうではありません。問題を書き、サーフェスを歩き、基準を書き、形状を埋めます。それが、コンポーネントを正当化するために基準が発明されるのを防ぎます。クロージャゲートは、すべての基準が Flow、Relations、または Surface のどこかに着地することを要求します。そうでなければ、範囲外か形状のギャップです。
checks.md への導出が負荷のかかる部分であり、事務処理ではありません。Surface のすべてのルートは、そのステータスをメンバーとする Coverage セット行を負います。Landing のすべての扉はチェックを負います。Relations のすべてのエンティティは1つを負います。checks.md から何も指し示していない形状セクションは、死んでいるか証明されていないかのどちらかであり、validate_checks.py は一般的なケースで警告します。
設計の半分は存在します。コンポーネントカタログは存在しません。 設計ドキュメントを腐らせたのは決して図ではなく、クラスごとのPurpose / Location / Interfaces / Dependencies でした。これは数週間で古くなり、文書の権威で次の読者を誤解させる可逆的な詳細です。それらのフィールドはここには存在しません。5つの境界のあるセクション：
| セクション | レビューするもの | 除外するもの |
|---|---|---|
Flow | パス、ホップごとに1行 | 存在せず、扉によって作成されないモジュール - それは配置 |
Impact | 下で何が変わるか：用語、既存のデータ | リスクレジスタ |
Relations | エンティティ、カーディナリティ、一方通行の制約 | 列と型 |
Surface | ルート、入力、出力、ステータス | リクエストボディの仕様、およびチェックID - それらはまだ存在しない |
Landing | 一方通行の扉、具体的な形状と拒否された代替案 | リファクタリングで元に戻せるもの |
どのフォルダ、いくつのクラス、プライベートメソッドの名前：差分。 可逆的で、リポジトリの規約によって答えられ、成果物にする価値は決してありません。それが意図的なトレードであり、唯一のものです。
ここに来た時点でまだ未解決の賭け - 2つのアーキテクチャにライブな代替案があり、それぞれこのリポジトリに対してコストを見積もる必要がある - は Landing の行に収まらず、行はこの成果物が持つ唯一の形状です。それを解決するためにプロジェクトが使用するもの（ADR、RFC、スパイク）が最初に来ます。その後、計画は勝利した形状を記録し、レビュー可能にします。
フロー
計画 - 問題、次にパスと変更が妨げるもの、次に残りの形状、次に基準。書き込みは依然として問題 → サーフェス → 基準 → 形状。事実はあなたが調べるもの。決定はあなたが尋ねるもの - そして尋ねるときは、具体的なオプションとあなたの推奨事項を、ターンごとに最大2つ。2つの列挙が発見を行います。「エッジケースを考慮する」では何も見つからないからです。この機能が公開するサーフェスは、それぞれが表示されるたびに同じ決定を運び、9つの暗黙の要件次元があります。両方とも必須の n/a - <理由> を取るため、空白は適用されないアイテムではなく、誰も決定しなかったアイテムです。人間が読み、チェックが存在する前に異議を唱える1つの成果物。完全なプロセス、質問方法、形状セクションごとのルール、テンプレート、クロージャゲート: plan.md。
チェック - 計画から証明付きの主張を導出し、列挙されたすべての集合メンバーをチェックに結合し、スイープされた各次元がどこに着地したかを記録します。## Handoff と算術で閉じます。見積もりが予算を超える場合は、ビルドの前にメカニズムの質問のために停止します。これは、下流のすべてがチェック番号で参照する成果物です: checks.md。
構築 - ## Handoff 算術後、および見積もりが予算を超える場合はユーザーのメカニズム選択後、どのようにするかはあなたの判断です。チェックからテストを書き、実装し、各証明を実行し、一貫性のある断片でコミットします。タスクリストも、タスクごとのレビューテーブルもありません。境界、Landing のタイミング、ハンドオフ、および範囲のガードレール: build.md。
検証 - 機能の最後のコミットが着地したら、同じターンで新しい検証者を派遣します。尋ねないでください。「verify work」を待たないでください。手順、報告書形式、およびスコープ付き再検証: verify.md。
永続的なメモリ - プロジェクトの決定、セッションハンドオフ、および教訓レイヤー: memory.md。
スクリプト
<skill-dir> をこの SKILL.md を含むディレクトリとして解決し、python3 <skill-dir>/scripts/<name>.py を呼び出します。.specs/ 下のプロジェクトデータはプロジェクトルートからの相対パスのままです。cwd が異なる場合は --root を渡します。ゼロ以外の終了は STOP して修正を意味します。
| タイミング | コマンド |
|---|---|
| 計画を提示する前 | validate_plan.py <feature> |
| 構築を開始する前 | validate_checks.py <feature> |
| 各コミットの前 | check_commit.py --message "<msg>" |
| 完了を宣言する前 | validate_verification.py <feature> |
| 蒸留時 | lessons.py add ... |
| バリデーターまたはテンプレートを編集した後 | selftest.py |
validate_plan.py はクロージャゲートを実行し、形状の半分がそれが置き換えたものになるのを防ぎます。SHALL のない基準、選択されたデフォルトのない仮定、着地が空白または n/a に理由がない Observable 行、リテラルな形状または拒否された代替案のない Landing 行、Relations 内の列と型、ステータスのない Surface ルート、None - <why> で回答される代わりに空白のままのセクションを失敗させます。validate_checks.py は省略キャッチャーです。証明のないチェック、宣言されたサイズが実際に割り当てられたメンバーを超えるカバレッジ行、欠落したスイープ次元、欠落したプロファイル行を失敗させ、計画がレビューしたルートでチェックが言及していないものについて警告します。validate_verification.py は、file:line を引用しない、生存するミュータントを記録する、Unproven メンバーを残す、または作成者によって書かれた PASS 報告書を失敗させます。
コード実行ツールが存在しない場合のみスクリプトをスキップします。その場合は、成果物を読んで同じチェックを実行し、チャットで1回、劣化パスにいることを述べてください。
selftest.py は、このスキル自身の規律をゲートに適用します。ルールごとに入力済みのフィクスチャセットを変異させ、すべてのミュータントが殺されることを要求し、プロファイルスコープのゲートがそのプロファイル以下では発火しないことを証明するネガティブコントロールを実行し、ここに出荷されたすべてのスクリプトをスモーク実行します。実行されていないスクリプトはクラッシュが潜む場所であり、完了ゲートはかつてn
…
[翻訳のため一部省略]