design-principles

设计原则审计

根据广为人知的设计原则审计代码库。生成一份带评分的 DESIGN_AUDIT.md，并列出按优先级排序的整改措施。

核心原则： 调查代码，不要仅凭模式匹配。阅读实际代码，判断违规是真实存在、有意为之，还是误报。只有提供具体文件:行号证据的发现才应标出。

前置检查

git --version 2>/dev/null && git rev-parse --is-inside-work-tree 2>/dev/null

如果当前目录不在 git 仓库中，请发出警告但继续执行——无法使用 git 历史记录，但仍可分析文件。

第 1 步：检测上下文

确定语言、框架和编程范式——这决定了适用的原则以及违规的表现方式：

ls go.mod package.json pyproject.toml Cargo.toml *.csproj 2>/dev/null

阅读 README.md 和 CONTEXT.md（如果存在），了解架构意图。

根据输入确定审计范围：

• 完整审计（默认）——整个代码库，不包括 vendor/、 node_modules/ 和生成的文件
• 模块审计——指定的目录或软件包
• 委派模式——由 tech-debt 调用；重点检查已更改的文件， 并为评分卡提供发现

各原则针对特定语言的违规模式，请参阅 references/principles-guide.md。

第 2 步：扫描违规项

对于每项适用的原则，阅读实际代码并找出违规项。不要通过 搜索关键词来判断——应追踪调用路径和职责。

SOLID

• S — 单一职责：找出有多个不同修改原因的文件、类或函数。 迹象：文件超过 300 行且混杂多种关注点；函数同时处理 I/O、 业务逻辑和格式化。
• O — 开闭原则：找出添加新行为时必须修改而非扩展的代码。 迹象：针对类型标签的长 switch/if-else 链；扩展点上没有接口或抽象。
• L — 里氏替换原则：找出削弱前置条件、强化后置条件或抛出意外错误的子类型。 迹象：什么也不做的重写方法、对有效输入触发 panic、使用前进行类型断言。
• I — 接口隔离原则：找出迫使实现者实现其用不到的方法的宽泛接口。 迹象：接口方法超过 5 个；存根或空操作实现。
• D — 依赖倒置原则：找出导入具体底层类型的高层模块。 迹象：直接实例化依赖项；软件包边界上没有接口；代码无法测试。

DRY

找出在两个或更多位置重复的逻辑、结构或数据，而采用单一抽象 可以降低维护风险的情况。区分真正的重复与偶然相似——两个 看起来相似、但会独立演进的函数不构成 DRY 违规。

YAGNI

找出没有当前使用场景却添加的抽象、配置选项或通用性。 迹象：未使用的参数、无效代码路径、只有一种实现的接口、从未读取的配置键。

KISS

找出不必要复杂的解决方案。迹象：没有带来价值的间接层； 解决代码库中不存在的问题的抽象；为简单操作设置多层委派。

迪米特法则

找出暴露内部结构的调用链：a.GetB().GetC().Do()。 每个单元只应与其直接协作者交互。

关注点分离

找出混杂的层：领域模型中包含 HTTP 逻辑、处理程序中包含 SQL、 业务规则中包含表示逻辑。追踪从入口点开始的数据流。

组合优于继承

找出过深的继承层次结构（超过 2 层）、为满足子类需求而修改的基类， 或通过继承产生的紧密耦合。注意：在 Go 和函数式语言中，应标出 接口使用不足，而非继承误用。

12-Factor（与代码相关的子集）

• 配置：本应来自环境变量的硬编码值（URL、凭据、功能开关、阈值）。
• 日志：使用 fmt.Println、print() 或临时字符串拼接，而非结构化日志库。
• 无状态进程：妨碍水平扩展的内存状态（包级可变全局变量、用户数据的本地文件缓存）。

步骤 3：评定发现

根据 references/report-template.md 中的框架，为每项发现分配影响、工作量和优先级。

• 影响：CRITICAL / HIGH / MEDIUM / LOW
• 工作量：S（< 1 天）/ M（1–5 天）/ L（1–2 周）/ XL
• 优先级：P1（高影响 + 低工作量）至 P4（低影响，任何工作量）

为每个原则领域打 0–10 分，用于汇总评分卡。

步骤 4：对抗式辩论

找出影响 × 工作量综合得分最高、且违规确实存在争议的前 3 项发现（合理的工程师可能会有不同意见）。跳过结论明确的发现。

针对每项有争议的发现：

• 红方（重构）：主张修复违规。必须提出具体的差异或重构方案，并质疑当前设计是否合理。
• 蓝方（保留）：根据具体情境论证当前设计正确。必须引用“能正常运行”之外的具体理由，并指出所提变更的风险。
• 白方（裁决）：基于证据进行评估，作出以下裁决：重构、保留或添加说明注释。

辩论规则

• 红方和蓝方必须引用具体代码，不能泛泛而谈
• 红方必须提出具体变更，不能只指出代码异味
• 蓝方不能只是不加理由地为现状辩护
• 白方的裁决为最终结论，且必须在报告中落实

步骤 5：生成 DESIGN_AUDIT.md

使用 references/report-template.md 中的模板编写报告。 包括执行摘要、原则评分卡、附有证据的详细发现、辩论裁决和按优先级排列的修复路线图。

对生成的文件运行 markdownlint：

markdownlint DESIGN_AUDIT.md 2>/dev/null || \
  npx markdownlint-cli DESIGN_AUDIT.md 2>/dev/null

修复所有问题后再提交。

步骤 6：呈现摘要

向用户展示：

1. 原则评分卡（名称、0–10 分、最重要的发现）
2. 总体设计健康度评分（原则得分总和 / 最高分）
3. 有争议发现的辩论裁决
4. 需要立即处理的 P1 项
5. 前 5 项修复优先事项及预估工作量
6. 询问用户想先处理哪些事项