tlc-plan

TLC Plan

ビルダーが決めることがなくなるまで質問します。見知らぬ人でも実装できるように書き残します。

┌─────┐   ┌───────┐   ┌──────┐   ┌─────────┐
│ ASK │ → │ SHAPE │ → │ CHECK│ → │ APPROVE │ → tlc-implement
└─────┘   └───────┘   └──────┘   └─────────┘

コーディングエージェントによくある失敗は、要件が義務として明確にならないまま、完了を宣言することです。始まりはここにあります。計画が推測で決着させた曖昧な点、提案として扱われたキャプチャ、依頼文のどこにも反映されなかった一文です。このスキルで作成するのは、コードが存在する前に人間が読み、異議を唱えるための唯一の文書です。また、これまでの会話を知らない別のエージェントがビルドすることも多いため、ビルド担当者に渡すブリーフ全体でもあります。

ルール

1. 各基準は、具体的な値を持つ観測可能な結果を1つだけ示し、1回の実行で確定できるものにします。ステータスコード、フィールド、境界値、ラベルなどが該当します。「適切に処理する」、パーセンタイル、「列が存在する」は基準ではありません。
2. 計画を提示する前に、曖昧な点をすべて質問します。ユーザーが決めるべきことで、複数の妥当な答えがあり、コードでも決まらないことが対象です。質問を1つ減らすために、仮定で代用してはいけません。質問で明らかにするのは方法であり、機能を追加するかどうかではありません。
3. 依頼に含まれるキャプチャ、フレーム、または稼働中のサイトは、ユーザーが参考情報と明示していない限り、拘束力のある情報源です。拘束力のある情報源を変更できるのはユーザーだけです。そこから逸脱する場合は質問し、その内容を .specs/STATE.md に AD-NNN として記録し、## Differences from the source に列挙します。
4. ユーザーに表示される内容を変えるルールは、リポジトリのテストが実行するレイヤーで動かします。フィルタリング、検索、並べ替え、件数の集計はルールです。
5. ここで決めるのは、元に戻すのが難しいことだけです。その具体的な形もここで決めます。慣例の範囲内での配置、名前、型はビルダーが決め、差分で確定します。
6. 計画を提示する前に validate_plan.py が 0 を返すようにします。人間による確認は承認の1回だけです。承認は計画タイトルの下に **Approved**: <date> - user: "<their words>" と記録します。ユーザーが実際に述べていない言葉を記録してはいけません。また、回答は届いたターン内に計画へ反映します。コンパクション後も保持されるのはファイルであり、チャットではありません。コンパクション後、または新しいセッションでは、このファイルと計画への参照を読み直してから、plan.md を起点に作業を続けます。ビルド中も計画の内容は維持します。Landing、Surface、データは追加していきます。パスと Changes underneath は、それらを変更するコミットで更新します。

分割：計画の数

すべての情報源を最後まで読み、計画をいくつに分けるか決めます。基本は1つです。これにより、後戻りできない判断をすべてまとめて確認し、相互の影響を把握できます。6つに分けると、同じ判断が6回に分かれて提示され、全体を見る人がいなくなります。

証拠に基づいて説明できる理由がある場合に限り、分割します。ある部分を先にリリースすると本番環境を壊してしまう、ある部分は他の誰かにしか答えられない質問の回答待ちである、またはある部分は別のチームの担当である、といった理由です。それぞれの部分は、専用の計画を持つ独立した機能フォルダーにします。

規模が大きい場合は、その理由も明示します。まず後戻りできない判断、その中に移行があれば次に示し、続いて分割数を示します。既存の境界を示し、まず順序の制約を、まとめられないものとして明記します。そのうえで、どこで分けるかをユーザーに選んでもらいます。

計画内の各スライスは、誰かが目で確認できる1つの結果であり、レイヤーではありません。それ自体では何も証明しない準備作業（NULL 許容の列、呼び出し元のないクライアントなど）は、スライスではなくコミットです。

成果物

.specs/
├── STATE.md                    # decisions log (AD-NNN)
├── LESSONS.md                  # rendered by scripts/lessons.py - read it
└── features/<feature>/
    ├── plan.md                 # problem, shape, surface, doors, criteria
    └── captures/               # the binding source files

計画の形式、質問方法、サーフェスの確認、EARS については references/plan.md を参照してください。セクション見出しは tlc-implement とバリデーターが読み込むスキーマです。本文はプロジェクトの言語に合わせ、識別子は翻訳しません。

決定事項と教訓

.specs/STATE.md には、今後の機能が従うべき決定事項を記載します。

# Project state

## Decisions

| ID | Decision | Rationale | Status | Date |
| --- | --- | --- | --- | --- |
| AD-001 | Webhook ingest is idempotent on provider delivery id | replays are routine and cheap to dedup at the edge | active | 2026-02-14 |

## Decisions の本文のみを編集します。リポジトリに ADR や決定ログがすでにある場合は、そちらに追記してください。active の各項目はプランを制約します。内容に従うか、置き換える項目を追記してください（古い行のステータスは superseded by AD-NNN に変更します）。その理由も記載してください。拘束力のある情報源から逸脱する回答は決定事項です。製品に代わりに何を表示するのかを示し、その根拠として質問と選択した選択肢を引用します。

教訓は、実際の検証で判明した内容に基づいて tlc-implement が記録します。質問する前に、該当する領域の確認済みの教訓を読んでください。

python3 <skill-dir>/scripts/lessons.py --root <project> list --status confirmed [--scope <area>]

スクリプト

<skill-dir> は、この SKILL.md が格納されているディレクトリとして解決します。カレントディレクトリがプロジェクトのルートでない場合は、--root を指定してください。スクリプトの内容を読むのではなく、実行してください。変更すべき内容はスクリプトのメッセージに示されます。

タイミング	コマンド
プランを提示する前、およびプランを変更するたび	python3 <skill-dir>/scripts/validate_plan.py <feature>
質問する前	python3 <skill-dir>/scripts/lessons.py --root <project> list --status confirmed
バリデーターまたはテンプレートを編集した後	python3 <skill-dir>/scripts/selftest.py

必要なもの

必要なもの	用途	ない場合
Python 3.8 以降（標準ライブラリのみ）	スクリプトの実行	プランは引き続き有効です。バリデーターを実行できなかったことを伝えてください
画像を読み取れるモデル	拘束力のあるキャプチャ	ユーザーに各状態の説明を依頼し、Sources にその旨を記載してください
デザインソースへのアクセス（ファイル、MCP、URL）	各状態を captures/ にエクスポートする	blocks の質問としてファイルを依頼してください

出力

成果物を作成し、フェーズについて説明しないでください。終了する際は、まず結論を示してください。プランを提示し、最初に作業を妨げる質問とその推奨事項を挙げ、その後にユーザーが修正できるよう選択したデフォルトを示します。セクション見出しは英語のままにしてください。