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
- 许可证LICENSE1.0 KB
- 参考文档references/comments-and-naming.md3.3 KB
- 参考文档references/deep-modules.md4.3 KB
- 参考文档references/error-handling.md2.1 KB
- 参考文档references/red-flags-checklist.md2.2 KB
03 SKILL.md 正文
A Philosophy of Software Design — 路由核心
来源: John Ousterhout《A Philosophy of Software Design》(斯坦福 CS 190) 核心论点: 软件设计的核心挑战是管理复杂性。所有原则服务于一个目标:让系统容易理解和修改。 元原则: 任何原则与"是否真的降低复杂性"冲突时,以后者为准(作者原意,勿教条)。
复杂性的三个症状(诊断入口)
| 症状 | 含义 | 识别方法 |
|---|---|---|
| 变更放大 | 简单修改需改动多处代码 | 改一个功能要碰多少个文件/方法? |
| 认知负荷 | 开发者必须吸收大量信息才能安全完成任务 | 完成任务要读多少不相关代码?⚠️ 行数少 ≠ 简单,有时更多代码反而更简单 |
| 未知的未知 | 不清楚该改哪些代码 | 最危险——修改时"不知道该看哪里" |
根源:依赖(无法独立理解/修改)+ 晦涩(重要信息不明显)。 关键洞察:复杂性是增量累积的——不是灾难性错误,而是成百上千个小决定堆积。必须零容忍。
15 条设计原则速查
- 复杂性是逐步增加的——必须处理小事情
- 能跑起来的代码不够
- 持续小额投资改善系统设计(10-20% 时间)
- 模块应该深
- 接口设计让最常见的用法最简单
- 简单接口 > 简单实现
- 通用模块更深("有点通用")
- 通用与专用代码分开
- 不同层应有不同抽象
- 把复杂性往下压
- 把错误(和特例)定义掉
- 设计两次
- 注释描述代码中不明显的内容
- 软件为易读而设计,不为易写
- 开发增量是抽象而非功能
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-designskill(不重复建设) - 评审流程(双轴、sub-agent)→ 用
code-reviewskill - 本 skill 提供:原则依据 + 独有哲学(错误处理/注释/命名)+ 危险信号检查表
边界与注意事项
- 原则冲突时回到元原则:"这个选择真的降低复杂性了吗?"
- 深模块 ≠ 类越大越好:同时检查接口是否真的简单
- AI/Agent 场景映射:AGENTS.md = "把复杂性往下压"(让 agent 用户简单);repo-as-spec = 消除 unknown unknowns
04 同仓库更多 Skills
jekyll-chirpy-blog
Use when editing the Jekyll/Chirpy blog or fixing mermaid.
★ 0
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
★ 0
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
★ 0
spike
Throwaway experiments to validate an idea before build.
★ 0
simplify-code
Parallel 4-agent cleanup of recent code changes.
★ 0
requesting-code-review
Pre-commit review: security scan, quality gates, auto-fix.
★ 0