本文件有双重用途:
- 可直接复制进你自己的项目,作为团队精简版开发&Review 公约。
- 为本仓库(modern-software-engineering-guide)贡献的指南。
完整理论与全部条目见 SPEC.md。本文件是其中"开发者每天要做的动作"的精简提炼。
所有规则都服务于两个目标——为学习优化、为管理复杂度优化。当某条规则明显阻碍目标时,你有权在达成共识 + 记录理由后打破它,事后复盘。规则是默认值,不是教条。
学习 / 反馈
- 任务拆成可独立验证的小增量(默认 1~2 天内合并)。
- 走最薄的端到端切片,但保留轻量级架构前瞻,别走成死胡同。
- 默认短分支、频繁合主干;长跑分支需共识 + 更频繁中间集成 + 记录理由。
- 本地一条命令跑完快速测试;CI 红了先修 CI,不叠新代码。
- 不确定的技术/性能问题先做限时 spike;结论用数据,不靠"我觉得"。
- 改 bug 先写能复现的失败测试再修。
管理复杂度
- 职责单一、内聚;一个函数/类只讲一件事。
- 业务逻辑与框架/IO/DB 细节分离。
- 抽象基于真实稳定概念;业务重复守 rule of three,基础设施级重复可更早统一。
- 默认松耦合;警惕以"复用"之名制造耦合。
两块试金石(完成定义必查)
- 可测试:不依赖真实外部系统即可测,确定性、无 flaky。难测 = 设计问题,回头改设计。
- 可部署:能独立部署 / 回滚;DB 变更向后兼容;用 feature flag 实现"部署 ≠ 发布"。
- PR 小而单一目的;描述写清 为什么改 / 改了什么 / 怎么验证。
- CI 全绿;自己先 review 过一遍 diff。
- 关联 issue;关键业务边界 / 外部 API errcode / 时间窗 / 隐式契约已内联注释。
- 不夹带无关重构(重构单独开 PR)。
- 是否有覆盖行为与边界(而非仅 happy path)的测试?
- 职责是否内聚?抽象是否恰当(不过度、不投机)?耦合是否必要?
- 难测吗?→ 标记为设计问题。能独立部署/回滚吗?
- 半年后的人读得懂吗?性能/安全断言有数据或测试支撑吗?
- 文化:对事不对人,给理由和替代方案;区分 must-fix 与 nit;有分歧用最小实验/度量裁决,不靠职级压人。
本仓库本身就遵循上面的精神演进:
- 小步、单一目的:一个 PR 只改一件事(改某条规则 / 加一个案例 / 修订措辞)。
- 带理由:规范的每处改动都要在 PR 描述里说明为什么——最好附上真实项目中的证据或反例。
- 欢迎"实战检验"型贡献:用真实代码库验证某条规则是否站得住、是否需要例外,把结论沉淀回 SPEC。
- 保持可勾选:新增条目尽量是
- [ ]可检查动作,而非抽象口号。 - 提 Issue 讨论有争议的规则,用证据而非偏好说话。
这份规范追求的不是"正确",而是"对真实工程有用且可被反驳"。欢迎用你的项目来挑战它。