comprehension-check

理解检查

概述

AI 生成代码的速度远超人类吸收信息的速度。发布自己无法充分解释的更改会造成认知债务——也就是无法排查问题、扩展功能或理解已构建内容。

核心原则： 理解先于承诺。如果无法用日常语言阐明每项修改，就还没有资格提交这些修改。

首要指令

NO COMMIT UNTIL EVERY CHANGE IS UNDERSTOOD

在任何 AI 生成或 AI 辅助编写的代码进入版本控制之前，开发者必须理解每项更改的作用，以及为何采用这种实现方式。

适用时机

以下情况触发：

• 涉及 3 个或更多文件的任何修改
• 非简单的算法或数据结构实现
• 结构性调整（新模块、数据流更改、依赖关系重构）
• 安全相关代码（身份验证、加密、输入净化）
• 自主 Agent 的决策（你未明确指定的更改）

以下情况可跳过：

• 单字符修改或拼写错误更正
• 开发者逐行原样指定的更改
• 纯样板代码生成（脚手架配置、锁定文件）

流程

阶段 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 Agent 经常会顺手进行“有帮助”的补充更改。每一项都必须披露。

真正理解的标志

开发者应能够：

• 描述每个已修改文件现在有何不同
• 说明每项修改为何必要
• 预测回滚特定更改会导致什么问题
• 列出引入的任何新依赖或模式
• 确定如果之后这段代码出现错误，应从哪里着手排查

认知陷阱

自我安慰	事实
“测试套件通过了，所以我信任它”	测试验证的是行为，不是理解。之后你会在毫无头绪的情况下调试。
“等事情没那么忙时我再审查”	你不会这么做。你一转身，相关上下文就会消失。
“大部分都是样板代码”	样板代码中一个错误的行就可能造成安全漏洞。
“我大致理解整体概念”	到调试时，高层直觉就会失效。必须具体理解。
“深入审查会降低我的速度”	发布无法解释的代码，出问题时造成的速度损失会大得多。
“AI 很可靠”	AI 会生成看似合理的内容。看似合理不等于正确。

防护措施

禁止的操作：

• 未阅读更改说明就提交 AI 编写的代码
• 隐瞒未经请求的更改
• 对开发者的疑惑或不确定性敷衍了事
• 将测试全绿等同于真正理解

必须执行的操作：

• 为所有多文件修改生成更改说明
• 披露所有超出原始请求范围的更改
• 提交前获取明确确认
• 彻底解答开发者提出的每个问题

集成

在以下步骤之后调用：

• godmode:delegated-execution —— 审查委派 Agent 的实现结果
• godmode:test-first —— 代码编写完成且测试通过后
• godmode:parallel-execution —— 合并并行 Agent 工作的结果后

在以下步骤之前调用：

• godmode:completion-gate —— 先理解，再验证
• godmode:merge-protocol —— 合并到目标分支之前先理解