SuperAPI AI 工具集

principle-invest-in-design

编程与开发

查看项目

更新于 10-29 02:29

技能介绍

该技能是一条设计投入决策原则,用于在交付一个已获批准的功能或修复时,决定应当投入多少设计努力。

用途

把设计视为日常交付的一部分。在确定第一个可工作的补丁之前,先考虑需求应如何契合受影响的职责,然后只做当前需求、调用方、约束和任务授权所能证明其合理性的有限改进。

决策规则

在功能或修复过程中,投入足够的设计努力,以减少受影响的职责中被证实的理解与变更负担,同时保持必需行为不变,并停留在已批准的任务范围内。一个干净的局部补丁可能已经满足该规则。

设计考量不必等待已有重复代码或一个已完成的坏补丁。但结构性修改确实需要当前证据与授权:需求、受影响的调用方、约束或拟议实现必须说明为何该变更能改善当下的设计。偏好更整洁的架构、附近的遗留债务或可能的未来功能,都不足以作为依据。

应用规则

  1. 框定当下的职责。说明所需行为、拥有该行为的代码、直接调用方,以及必须保持稳定的保证,包括相关的顺序、失败、生命周期和性能义务。
  2. 考虑连贯的契合。将干净的局部补丁与有助于当前用途的最小设计改进进行比较。该投入可以澄清契约、文档、命名、状态模型、依赖方向或职责,而不必创建抽象。
  3. 建立证据与授权。将任何结构性修改追溯到当前需求、调用方、约束、测试或拟议差异。保持在已批准的路径、契约、依赖、所有权和拉取请求分组之内。更好的设计不等于范围授权。
  4. 做一次有界改进。只变更该行为所需的受影响职责和直接集成。当首次使用时略带通用性的接口能让今天的实现或调用方更简单时,这是合理的;但预测性的适配器、注册表、钩子、配置或其他未来功能则不合理。
  5. 验证行为与总负担。重新检查可观察的功能或修复,然后比较变更前后调用方加实现的知识与变更成本。包括保证、顺序、失败、恢复和相关性能约束。单一中心所有者、更少分支或更少重复行本身并不构成证明。
  6. 如实陈述结果。指出已减少或消除的被证实负担、被改变的职责,以及任何遗留限制或遗留债务。当改进是部分的,不要声称彻底清理;也不要仅因旧债务仍在就引入可避免的新债务。

相邻技能的分工

当实质选择是新机制或重大扩展机制的形态(包括其首次使用)时,使用 principle-build-the-abstraction。它选择能力形态的增量;本原则决定交付中是否以及投入多少设计。

需要详细的接口、深度、局部性、接缝和调用方负担分析时,加载 codebase-design。本原则不重复该方法。

当保持行为的结构性改进本身就是所请求的工作时,使用 refactor。在此,结构性工作仅支持已批准的功能或修复。

将影响重大或难以逆转的边界选择交由 architect 处理。

遵循 karpathy-guidelines 进行外科手术式执行;当合理的改进会超出已批准授权时,遵循 principle-stop-on-plan-drift。

限制

一个干净的局部补丁,若所有者、契约、状态模型和依赖方向都合适,则无需抽象、子系统重新设计或仪式化的设计报告。

“略带通用”指针对当前功能的连贯接口,而非假想的未来功能。当它在复用之前就能减少今天的总负担时,可能值得做。

增量地改进设计。当行为保持不变且遗留限制被明确说明时,有界减少是有效的;比较实际改变的职责,并在进一步工作会超出已批准任务时停止。

对于真实紧急情况、一次性实验或明确接受的短期债务,战术性缓解是可以接受的。记录后果、为何推迟、受影响范围,以及后续跟进的所有者或到期条件。

如果改进需要未批准的契约、依赖、所有者、路径、行为或拉取请求变更,则在做出之前应用 principle-stop-on-plan-drift。

可观察的决策

没有本原则,工作者可能要么交付第一个通过的补丁而不考虑其契合度,要么以推测性清理过度反应。有了它,工作者在获授权的职责内选择成比例的、有证据支持的改进,验证行为与总负担,并如实报告遗留债务。有效结果仍可能就是一个干净的局部补丁。

评估案例

正面——重复出现前的首次使用设计 输入:某功能需要缓冲区中第一个文本删除操作。拟议的 backspace(cursor) 方法镜像 UI 事件,而范围删除操作会让当前缓冲区逻辑和契约更简单,且不添加预测性的编辑器功能。 预期:在第二个调用方或重复出现之前就考虑设计。由于机制形态是实质性的,使用 principle-build-the-abstraction 选择当前连贯的操作,将 Backspace 策略保留在 UI 中,并验证今天的行为和范围保证。不要添加注册表、钩子或未来的编辑操作。

正面——有界增量改进 输入:某功能触及一条带有若干遗留错误翻译的请求路径。已批准的包拥有其中之一,将该翻译移入其现有请求契约可减少调用方知识,但其他遗留路径不在范围内。 预期:做出并验证所拥有的改进,披露遗留的翻译,避免宣称子系统已清理。不要仅因旧债务仍在就保留不必要的新重复。

负面——干净的局部补丁 输入:某功能向已拥有该决策的模块添加一个清晰条件。其契约、调用方、依赖和状态保持连贯。 预期:实现并验证该局部条件。不要引入抽象、强制设计报告或子系统重新设计。

边界——保持行为与授权 输入:更深的接口会减少调用方负担,但需要更改另一个包的公共契约。已批准任务只允许更改当前包,其本地实现可在不模仿另一所有者抽象的情况下保持行为。 预期:不跨越契约边界,也不创建本地重复。应用 principle-stop-on-plan-drift,保留获授权的工作,并请求跨所有者的决策。

例外——紧急债务 输入:生产中断需要在完成合理设计之前进行受控缓解。该缓解在受影响的职责中添加一个临时分支。 预期:仅在紧急授权明确时交付最小的安全缓解。记录新增后果、受影响范围、推迟原因,以及后续跟进所有者或到期条件;不要把缓解呈现为已完成的设计。

来源说明

本原则改编自 John Ousterhout 关于持续性、增量式设计投入的指导,包括其战略编程笔记、模块化设计笔记、公开的第二版摘录和 2022 年访谈。它不规定固定的投入百分比或量化的回报。