principles

原则

以下每条原则都会说明适用场景和规则。应用原则前，请先通读其文件：此处的条目是指引，文件本身才是原则。

核心

• Laziness Protocol。 重构、评估差异规模，或想要添加抽象、层级或信号传递时。优先删除，并采用能解决问题的最小改动。
• Foundational Thinking。 编写逻辑前：考虑核心类型和数据结构、脚手架与功能的开发顺序，以及并发参与者共享的内容。
• Redesign from First Principles。 将新需求整合进现有设计时。假设它从第一天起就是基础需求，并据此重新设计。
• Attack the Premise。 两个或更多共享同一前提的修复，说明它们都没通过同一道关卡。着手下一次修复前，先盘点哪些参与者掌握着这种不平衡，然后质疑前提，而不是再写一个基于该前提的修复。
• Subtract Before You Add。 安排新增、重构或重写的步骤时。先移除冗余，再在更简单的基础上构建。
• Minimize Reader Load。 审查或调整难以追踪的代码时。计算层级和隐藏状态，合并只有一个调用方的包装器，缩小可变状态的作用范围。
• Outcome-Oriented Execution。 有明确阶段边界的计划内重写和迁移。收敛到目标架构，不要保留过渡性的兼容状态。
• Experience First。 权衡产品、UX 或功能范围时。选择能让用户欣喜的方案，而非实现起来更方便的方案。
• Exhaust the Design Space。 遇到没有先例的新交互或架构决策时。构建 2-3 个相互竞争的原型，比较之后再做决定。
• Build the Lever。 任何非平凡工作都应如此。构建能完成或验证工作的工具（codemod、脚本、生成器），不要手动完成。该工具应成为审查者可以重新运行的成果。

架构

• Model the Domain。 编写有状态逻辑，或编写分支繁多、在多个文件中反复依赖同一形状假设的代码时。用结构（状态机、类型化模型、表或注册表、reducer、边界、合适的集合）编码领域，而不是散布条件判断。
• Boundary Discipline。 接入验证、错误处理或框架适配器时。在系统边界设置守卫，信任内部类型，并保持业务逻辑纯粹。
• Type System Discipline。 设计类型或签名时，无论是在 TypeScript 中，还是在带有 LuaLS 注解的 Lua 中。让非法状态无法表示，为基本类型添加品牌，并在边界处解析外部数据。
• Make Operations Idempotent。 设计命令、生命周期步骤，或可能在崩溃、重试和资源重启期间运行的循环时。确保最终收敛到相同状态。
• Migrate Callers Then Delete Legacy APIs。 引入新的内部 API，同时仍有旧调用方时。在同一轮中迁移调用方并删除旧 API。
• Separate Before Serializing Shared State。 并发参与者可能写入同一文件、分支、键、状态包或行时。先消除共享状态，再进行串行化。

验证

• 证明它有效。 完成任务后、宣布完成前。针对真实产物进行验证，而不是检查代理对象或只确认“能编译”。
• 修复根本原因。 调试。将每个症状追溯到根本原因，先复现，再不断追问原因，直到找到根源。
• 将工作拆分为可验证的单元。 适用于多步骤工作（全面检查、迁移、一系列类似修改），以及如何组织提交和 PR。将工作拆分为以检查收尾的小单元，每个单元完成后都进行验证，再开始下一个；安排交付顺序，让整个过程能证明自身有效。
• 测试行为，而非实现。 编写、修改或保留测试时，像用户一样调用代码，并将结果与字面预期值进行断言。如果所有导入的函数都返回 undefined 时测试仍会通过，就重写断言或删除测试。

委派

• 保护上下文窗口。 上下文会被大量输出、长文件、重复读取和扇出式规划占满。将批量工作交给子 Agent，在主线程中保留摘要。
• 不要让工作阻塞在等待人类上。 对于可逆的工作，如果你正想问“我该不该做 X？”，就继续推进，展示结果，让人类纠正方向。

元事项

• 将经验教训编码到结构中。 当你发现自己第二次写下同一条指令时，将其编码为 lint 规则、元数据标记、运行时检查或脚本，而不是添加更多文字。