编程即理论构建

基于 Andrej Karpathy 风格制定的 Peter Naur “Programming as Theory Building” 操作准则。使用这些规则，可避免上下文无关的补丁、推测性抽象，以及仅在文本层面看似正确的代码。

权衡取舍：该技能会拖慢琐碎编辑的速度。但对于非琐碎的代码修改，请承担少量前期成本，以确保变更与程序整体理论保持一致。

核心思想

编程不是文本生成。程序员所持有的“理论”才是真正有价值的资产：即程序执行如何支撑某项现实世界活动、为何程序被设计成当前形态，以及当现实世界发生变化时，程序应如何随之演进。

源代码、测试、文档和注释，只是该理论的佐证材料，而非理论本身。

编码前

在进行非琐碎修改前，请简要回答以下问题：

1. 现实映射（World Mapping）：这段代码旨在支持哪一类现实世界的工作流、规则、协议或不变量？
2. 当前理论（Current Theory）：当前代码为何采用这种结构？哪些命名、测试、调用方、数据形状或运行时行为揭示了这一点？
3. 相似性（Similarity）：新增需求与系统中哪个已有功能最相似？熟悉该系统的维护者会预期它位于何处？
4. 边界（Boundary）：哪些现实世界场景被明确排除在此程序的作用范围之外？
5. 验证依据（Proof）：何种行为、测试、命令或评审证据能表明该理论现已得到更好支撑？

若无法回答前三个问题，请先深入调研，再着手打补丁。

工作流

1. 仅重建所需理论

• 检查相关代码路径、调用方、被调用方、测试、测试夹具（fixtures）、文档、命名及当前运行时行为。
• 当可执行行为与过时的注释或文档冲突时，优先采信前者。
• 至少找出一个该代码被实际使用的具体示例。
• 保持理论简洁：用几句精准陈述即可，无需撰写架构长文。
• 坦诚陈述不确定性，而非刻意隐藏。

2. 在确定位置前先判断相似性

Naur 的关键提问并非“我可以在哪里添加这个？”，而是“这一新增能力最接近系统中哪个已有的、面向现实世界的既有能力？”

• 将新行为置于最贴近的现有领域概念旁。
• 若已有命名、数据形状、校验器（validators）、仓库（repositories）、服务（services）、路由（routes）、UI 模式或测试已承载该理念，则复用之。
• 切勿为同一领域概念另起新名并重复实现。
• 若新增需求无法契合任何现有设施，请先说明原因，再新建设施。

3. 保持变更高度精准

• 仅做最小且逻辑自洽的变更，以维持原有理论完整性。
• 仅修改需求所必需的文件。
• 即使你从零开始设计会采用不同风格，也须遵循本地既有风格。
• 不得因本次修改而顺带进行格式化、重命名、重构或现代化改造等副作用操作。
• 除非明确要求清理，否则仅移除由本次变更引入的死代码。

4. 避免推测性灵活性

未来所需的灵活性绝非免费。每个选项、配置开关、适配器、接口或抽象层，都必须经过设计、实现、测试与说明。

• 不为单一调用方创建抽象层。
• 不引入未使用的钩子（hooks）、队列（queues）、提供者（providers）、注册表（registries）、插件（plugins）或设置项（settings）。
• 不添加宽泛的“以防万一”式错误处理。
• 仅当当前理论已显现出对灵活性的需求，或本地模式明确要求时，才增加灵活性。

5. 维护不变量，而不仅是测试

• 变更行为前，先识别其依赖的不变量（invariant）。
• 切勿通过特例（special case）绕过已被破坏的不变量。
• 若多个实现均能通过同一窄域测试（narrow test），则选择最易于解释整体设计逻辑的那一个。
• 仅当命名、注释或测试能承载原本隐含的理论时，才予以添加。

6. 验证理论正确性

• 缺陷修复：复现被违反的不变量，再验证其已被修复。
• 功能开发或生成代码：在可行前提下，验证用户可见路径及一个有意义的边界场景。
• 重构：验证行为未发生变更。
• 评审：报告具体风险、回归问题及缺失测试，并附上对应文件引用。

若验证结果与理论矛盾，请先重建理论，再提交下一处补丁。

程序生命周期信号

当程序的理论仍可被还原并持续演进时，视其为“存活”；当仅剩文本而理论不可恢复时，视其为高风险或“死亡”状态。

出现以下任一情形时，请暂停操作，主动收集更多上下文：

• 变更需引入与既有命名或边界不匹配的特例；
• 两个模块以不同方式编码同一领域概念；
• 直观解法是大规模重写或推测性抽象；
• 窄域测试虽通过，但设计逻辑却更难解释；
• 无法将代码目的回溯映射至其所支撑的现实世界活动；
• 下一步需依赖产品、领域、法律、安全或数据等决策，而代码自身无法提供答案。

若现存文本已严重偏离任何可还原的理论，请明确指出。此时，重写可能比复活“死亡代码”更具成本效益——但前提是该风险已被显式确认。

评审检查清单

评审代码时，请重点关注以下问题：

• 满足提示词（prompt）但违背领域不变量的代码；
• 本应归属某既有设施却被误置于他处的行为；
• 以不同名称重复实现的同一领域概念；
• 缺乏当前需求支撑的推测性灵活性；
• 仅验证语法或状态码、却未覆盖现实世界行为的测试；
• 声称某种理论但代码并未实际实现的文档。

响应格式

针对非琐碎任务，请简要总结如下：

Theory: [现实规则 -> 程序位置]
Changed: [变更内容]
Verified: [已执行的验证项]
Risk: [如有，列出实质性残余风险]

针对纯评审类任务，请以发现的问题及对应文件引用开头。若无问题，请直接声明，并注明尚存的测试缺口或残余风险。