comprehension-check

理解度の確認

概要

AI は、人間が理解する速度をはるかに上回るペースでコードを生成します。完全に説明できない変更をリリースすると、認知的負債が生じます。認知的負債とは、実装された内容のトラブルシューティング、拡張、推論ができなくなることです。

基本原則： 理解がコミットに先行します。すべての変更を平易な言葉で説明できないなら、そのコードをコミットする資格はありません。

最重要指針

NO COMMIT UNTIL EVERY CHANGE IS UNDERSTOOD

AI が生成または支援したコードをバージョン管理に追加する前に、開発者は各変更が何を実現し、なぜその方法で実装されたのかを理解していなければなりません。

使用するタイミング

次の場合に実施します：

• 3 つ以上のファイルに及ぶ変更
• 自明でないアルゴリズムやデータ構造の実装
• 構造的な変更（新しいモジュール、データフローの変更、依存関係の再構成）
• セキュリティに関連するコード（認証、暗号化、入力のサニタイズ）
• エージェントによる自律的な判断（明示的に指示していない変更）

省略できる場合：

• 1 文字の修正やタイプミスの修正
• 開発者が行単位で逐語的に指示した変更
• 純粋なボイラープレートの生成（設定ファイルのひな形、ロックファイル）

プロセス

フェーズ 1：変更内容の説明を作成する

実装が完了した後、コミットする前に：

For EVERY modified file, articulate:

1. WHAT: What is different now? (Describe the meaning, not the diff)
2. WHY: What motivated this particular change?
3. CONTEXT: How does this change interact with the broader modification set?
4. HAZARD: What failure modes does this change introduce?

フェーズ 2：変更内容を説明する

次の形式で出力を構成します：

## Modification Walkthrough

### [path/to/first-file]
**What:** Introduced sliding-window rate limiting that counts requests per IP address.
**Why:** The login endpoint was exposed to brute-force enumeration.
**Context:** Middleware executes ahead of authentication routes; relies on Redis for distributed state.
**Hazard:** If Redis becomes unreachable, the limiter fails open (permits all traffic). Worth discussing: should it fail closed instead?

### [path/to/second-file]
**What:** Login handler now returns HTTP 429 when the rate limiter activates.
**Why:** The middleware flags rate-limited requests via `req.rateLimited`.
**Context:** Early exit occurs before password verification, which also blocks timing-based attacks.
**Hazard:** Negligible -- a simple conditional guard.

## Structural Consequences
- New runtime dependency: Redis (stores rate-limit counters)
- New middleware layer inserted between routing and handler execution
- Login request lifecycle now: rate-check -> authenticate -> respond

## Open Questions
1. Should the rate limiter deny all traffic when Redis is unavailable, or allow it?
2. Should rate limiting extend beyond authentication endpoints?

フェーズ 3：明示的な確認を得る

直接尋ねます：「これらの変更を十分に理解し、コミットを進めてもよいですか？」

開発者から質問があった場合：

• 十分に解決します
• 理解できていない点をうやむやにしません
• 理解できない点が残ると、認知的負債が蓄積します

フェーズ 4：依頼にない変更を明らかにする

変更が元の依頼に含まれていなかった場合は、必ず：

HEADS UP: I additionally [modified X] because [rationale].
This was NOT part of your original instruction. Keep it or revert?

AI エージェントは、「役に立つ」補足変更を頻繁に加えます。そのすべてを開示しなければなりません。

真の理解度を示す指標

開発者は次のことができる必要があります：

• 変更された各ファイルが、以前と比べてどう変わったかを説明する
• 各変更がなぜ必要だったのかを説明する
• 特定の変更を元に戻した場合、何が壊れるかを予測する
• 新たに導入された依存関係やパターンを列挙する
• 後でこのコードにバグが見つかった場合、どこを調べるべきか特定する

認知の落とし穴

言い訳	真実
「テストスイートが通ったから、信頼している」	テストが検証するのは動作であり、理解度ではありません。後で何も分からないままデバッグすることになります。
「落ち着いたらレビューする」	しないでしょう。次に移った瞬間にコンテキストウィンドウが閉じます。
「ほとんどボイラープレートだ」	ボイラープレートのたった 1 行の誤りが、セキュリティホールにつながることがあります。
「全体的な概念は理解している」	デバッグ時には、高レベルの直感だけでは通用しません。具体的に理解する必要があります。
「詳細なレビューをすると速度が落ちる」	説明できないコードをデプロイすると、問題が起きたときに速度がはるかに落ちます。
「AI は有能だ」	AI はもっともらしい出力を生成します。もっともらしさと正しさは同じではありません。

ガードレール

禁止事項：

• 変更内容の説明を読まずに、AI が生成したコードをコミットすること
• 依頼にない変更の開示を抑えること
• 開発者の混乱や不確かさを放置して先へ進むこと
• テストがすべて成功したことを、真の理解と同一視すること

必須事項：

• 複数ファイルに及ぶすべての変更について、説明を作成する
• 元の依頼を超える変更をすべて開示する
• コミット前に明示的な確認を得る
• 開発者からの質問をすべて完全に解決する

組み込み

次の後に実行：

• godmode:delegated-execution — 委任されたエージェントの実装結果をレビューします
• godmode:test-first — コードの作成とテストの成功後に実行します
• godmode:parallel-execution — 並列で作業するエージェントの結果をマージした後に実行します

次の前に実行：

• godmode:completion-gate — まず理解し、その後に検証します
• godmode:merge-protocol — 対象ブランチにマージする前に理解します