ds-principles

工程原则

如果匹配某条触发条件，就应用相应规则。指出改变决策的原则。

设计

1. 先删减，再少量添加。 先删除无用代码和过时检查，再做出能解决问题的最小改动。不要为只有一个使用者的场景引入抽象。在确定改动范围或想要添加一层时应用。
2. 先定数据形状。 在编写逻辑前，先选择核心类型和结构。在编写新逻辑前应用。
3. 对领域建模。 将状态放在一个结构中，例如带类型的联合类型、状态机或查找表，而不是散落在各处的条件语句中。在代码分支过多或多个文件重复相同结构时应用。
4. 为新需求重新设计。 按照新需求从一开始就存在的方式来适配。在新增内容让设计显得勉强时应用。
5. 降低读者负担。 将只有一个调用者的包装函数内联，并缩小可变状态的作用范围。在代码难以追踪时应用。
6. 在边界处设防。 在输入进入的地方进行验证：命令行、配置、网络、文件、外部 API。内部信任类型，并保持核心逻辑纯粹。在添加验证或错误处理时应用。
7. 步骤保持幂等。 即使发生崩溃后重新运行，步骤也应达到相同状态。适用于命令、设置和重试。
8. 避免共享写入者。 使用锁之前，先为每个并发执行者分配独立的文件、分支或键。在并行工作会触及共享状态时应用。
9. 先迁移，再删除。 在一次改动中迁移所有调用方，并删除旧 API。不要使用垫片。在替换 API 或分阶段重写时应用。
10. 比较选项。 对于前所未有的设计，列出两三个方案。优先选择更少且打磨完善的功能。适用于新的架构、UX 或范围决策。

调试与验证

11. 修复根因。 在状态最初出错的地方进行修复。只有在状态本身合理时，守卫才有用。在调试时应用。
12. 质疑前提。 两次基于同一假设的修复都失败后，写下该假设并直接测试。进行第三次尝试前应用。
13. 证明它有效。 运行实际程序并查看真实输出，而不是代理指标。在声称完成前应用。
14. 划分可验证的单元。 将工作拆分成若干步骤，每一步都以检查通过结束。适用于全面检查、迁移和叠加提交。
15. 测试行为。 断言调用方可观察到的内容，让测试能够经受重构。在编写或保留测试时应用。
16. 解释数值。 找出限制测量结果的因素，并确认测量对象是正确的工作。适用于基准测试和评估分数。
17. 构建工具。 将批量或重复工作编写成脚本，以便重复运行。适用于大量编辑或检查。

流程

18. 保护上下文。 保留摘要，不要倾倒大量内容。将大规模阅读交给子 Agent。在输出或文件很大时应用。
19. 不要等待人类决策。 对于可撤销的工作，继续推进并展示结果。在想问“要不要这样做？”时应用。
20. 将重复经验固化。 同一项纠正被提出两次后，就将其变成 lint 规则、测试或脚本。在错误重复发生时应用。
21. 注释解释原因。 只有当代码无法体现某个原因时才保留注释，例如外部限制或公共 API 契约。删除叙述性注释和无用代码。对于需要注释才能解释其意外行为的代码，应修复代码。在编写或审查代码时应用。

类型

• 让非法状态无法表示。使用可辨别联合类型，而不是由可选字段组成的对象。
• 在边界处将外部数据解析一次，转换为具名类型。在内部信任它。
• 对不可信输入使用 unknown。绝不使用 any。验证前不要使用 as 类型断言。
• 从架构定义推导类型，不要手写守卫。
• 在默认分支中添加 never 检查，让新增变体导致构建失败。
• 对不应混用的基本类型添加品牌标记，例如用户 ID 和订单 ID。