AGENT SKILL

philosophy-of-software-design

Design modules, review code, reduce complexity.

License 许可
MIT
最近更新
2026-08-19
Stars
★ 0
Forks
0

01 前言 Front Matter

name
philosophy-of-software-design
description
Design modules, review code, reduce complexity.

02 资源文件 5

03 SKILL.md 正文

A Philosophy of Software Design — 路由核心

来源: John Ousterhout《A Philosophy of Software Design》(斯坦福 CS 190) 核心论点: 软件设计的核心挑战是管理复杂性。所有原则服务于一个目标:让系统容易理解和修改。 元原则: 任何原则与"是否真的降低复杂性"冲突时,以后者为准(作者原意,勿教条)。


复杂性的三个症状(诊断入口)

症状 含义 识别方法
变更放大 简单修改需改动多处代码 改一个功能要碰多少个文件/方法?
认知负荷 开发者必须吸收大量信息才能安全完成任务 完成任务要读多少不相关代码?⚠️ 行数少 ≠ 简单,有时更多代码反而更简单
未知的未知 不清楚该改哪些代码 最危险——修改时"不知道该看哪里"

根源:依赖(无法独立理解/修改)+ 晦涩(重要信息不明显)。 关键洞察:复杂性是增量累积的——不是灾难性错误,而是成百上千个小决定堆积。必须零容忍。


15 条设计原则速查

  1. 复杂性是逐步增加的——必须处理小事情
  2. 能跑起来的代码不够
  3. 持续小额投资改善系统设计(10-20% 时间)
  4. 模块应该深
  5. 接口设计让最常见的用法最简单
  6. 简单接口 > 简单实现
  7. 通用模块更深("有点通用")
  8. 通用与专用代码分开
  9. 不同层应有不同抽象
  10. 把复杂性往下压
  11. 把错误(和特例)定义掉
  12. 设计两次
  13. 注释描述代码中不明显的内容
  14. 软件为易读而设计,不为易写
  15. 开发增量是抽象而非功能

14 个危险信号速查(评审检查表)

危险信号 含义
浅模块 接口不比实现简单
信息泄漏 一个设计决策反映在多个模块
时间分解 结构基于执行顺序而非信息隐藏
过度暴露 API 强迫调用者为常用功能而了解不常用功能
透传方法 方法只是把参数传给签名相似的另一方法
重复 非平凡代码反复出现
特殊-通用混合 专用代码未与通用代码分离
联合方法 两方法依赖太强,不理解一个就无法理解另一个
注释重复代码 注释内容从代码立即可见
实现文档污染接口 接口注释描述用户不需要的实现细节
含糊名称 名字无法传达有用信息
难以取名 为实体找不到精确直观的名字(= 设计问题信号)
难以描述 完整文档必须很长
非显而易见代码 行为/含义不易理解

使用场景路由

场景 加载内容 位置
写代码 / 设计模块接口 深模块指南 + 错误处理哲学 + 注释命名 references/deep-modules.md + references/error-handling.md + references/comments-and-naming.md
代码评审 危险信号检查表(配合 code-review skill 的 Standards 轴) references/red-flags-checklist.md
重构 深模块指南 + 修改现有代码原则 references/deep-modules.md
快速提醒 本文件的原则/危险信号速查 本文件

与相邻 skill 的分工:

  • 深模块词汇表(seam/adapter/leverage)→ 用 codebase-design skill(不重复建设)
  • 评审流程(双轴、sub-agent)→ 用 code-review skill
  • 本 skill 提供:原则依据 + 独有哲学(错误处理/注释/命名)+ 危险信号检查表

边界与注意事项

  • 原则冲突时回到元原则:"这个选择真的降低复杂性了吗?"
  • 深模块 ≠ 类越大越好:同时检查接口是否真的简单
  • AI/Agent 场景映射:AGENTS.md = "把复杂性往下压"(让 agent 用户简单);repo-as-spec = 消除 unknown unknowns

04 同仓库更多 Skills