软件工程世界观与做事方法

用途： 每个新项目启动前通读一遍。

目标： 快速建立同一套「世界观 + 做事方法」，避免一上来就写代码、越做越乱。

与仓库内其他文档的关系： Agent/agent.md 定义人机协作契约；本文是通用工程思维，适用于任何项目。

一、一句话世界观

软件工程不是「把功能写出来」，而是在约束下持续交付可验证的价值。

价值 = 用户能完成真实任务；约束 = 时间、人力、技术债、风险；可验证 = 能测、能观测、能复现、能演进。

记住这条，其余都是展开。

二、核心信念（Worldview）

2.1 问题先于方案

• 先弄清谁、在什么场景、要完成什么、怎样算成功，再谈框架和算法。
• 没有清晰问题陈述时，任何「先进」技术都是在赌博。
• 反模式： 接到需求直接开 repo、先搭脚手架再回头想需求。

2.2 简单是战略，不是懒惰

• KISS： 能用一个模块解决，不拆三个；能用成熟库，不造轮子。
• YAGNI： 不为「以后可能需要」写大量代码；演进时再加。
• DRY： 知识只应有一处权威来源（配置、类型、业务规则）；复制粘贴是技术债的利息。
• 简单 ≠ 粗糙：边界清晰、命名准确、错误可读的简单，是高级工程。

2.3 变化是常态，设计要可演进

• 需求会变、团队会变、技术栈会变——僵化的大设计和完全没有结构同样危险。
• 好架构：高内聚、低耦合；模块边界稳定，内部实现可替换。
• 偏好演进式架构：小步交付、用反馈修正设计，而非一次性「完美蓝图」（Big Design Up Front）。

2.4 质量内建，而非事后修补

• 测试、类型、lint、CI、代码评审不是「额外工作」，是开发的一部分。
• Shift Left： 安全、性能、可访问性、可运维性越早考虑，返工越少。
• 没有自动化验证的功能，等于「声称完成」，不是「已经交付」。

2.5 人是系统的一部分

• 软件是社会技术系统：代码 + 流程 + 文档 + 工具 + 协作习惯。
• 系统要围绕谁构建、谁维护、谁使用来设计（InfoQ 2025 架构趋势的核心观点）。
• 心理安全、清晰文档、可读的 onboarding，和算法正确性一样重要。

2.6 AI 时代：编排者，而非打字员

• AI 能加速实现，但不能替代判断：范围、架构、验收、风险仍由人负责。
• 从「凭感觉写代码」（vibe coding）走向上下文工程（context engineering）：给 AI 明确的约束、接口、示例、边界，输出才可靠。
• 工程师价值上移：问题分解、接口设计、质量护栏、系统集成、验收。

2.7 可持续交付胜过英雄主义

• 可预测的小步发布 > 熬夜大包上线。
• 流动（Flow）、反馈（Feedback）、持续学习（Continuous Learning）——Gene Kim「三步法」仍是现代 DevOps 的底色。
• 平台与工具链是产品：开发者体验（DX）差，整体交付就会慢。

三、方法论框架（How）

3.1 项目启动：先澄清，再动手

启动清单（5～10 个问题）：

维度	要问什么
目标	一句话业务目标？谁买单/谁用？
场景	典型用户故事 1～3 条？失败场景？
输入输出	数据从哪来、到哪去、格式是什么？
验收	怎样算完成？怎样算做得好？
边界	明确不做什么（Out-of-Scope）
约束	技术栈、部署环境、时限、合规
风险	最大未知是什么？如何先验证？

产出： 一页需求摘要（可扩展为 docs/00-requirements.md）。

原则： 关键判断留给决策者拍板；执行者提供候选 + 取舍说明。

3.2 方案设计：对比，不要单选

• 至少 2～3 个候选方案，用表格比：收益、成本、风险、可逆性。
• 画架构图（推荐 mermaid）+ 接口契约（类型、API、数据结构）先行。
• 切里程碑 M1/M2/M3：每个里程碑都能独立演示价值。
• 记录已知风险 + 缓解措施；没有风险分析要说明原因。

3.3 骨架先行，再填业务

顺序：

1. 目录 + 模块职责
2. 接口 / 类型 / Schema（空实现 + docstring）
3. 自动化护栏（lint、测试框架、冒烟、make test）
4. 垂直切片：按用户故事打通最薄路径，不是按「先写满所有 model 再写 UI」

Walking Skeleton： 第一个可运行版本可以丑、可以功能少，但必须端到端可验证。

3.4 小步交付，频繁集成

• 单次改动可控：约 ≤3 个文件、≤200 行（可按团队调整）；超出主动拆分。
• 每个切片 = 改动 + 验证 + 可审计记录（commit / 日志 / 文档）。
• 集成频率越高，冲突和惊吓越少。

3.5 测试策略：金字塔

      /\
     /E2E\        少量：关键用户路径
    /------\
   /集成测试 \     中等：模块协作、API
  /----------\
 /  单元测试   \   大量：纯逻辑、边界条件
/--------------\

• 不写测试就交付业务逻辑——红线。
• 测试应验证行为，不是实现细节；避免脆弱测试绑死重构。
• 修 bug：先写失败测试，再修（能写时）。

3.6 可观测：运行时要能回答三个问题

1. 系统在做什么？（日志 / tracing）
2. 做得好不好？（metrics / 质量指标）
3. 出问题时如何定位？（错误上下文、复现路径）

关键路径要有结构化日志；用户可见的错误要人话 + 可操作建议。

3.7 文档：为未来的自己和协作者写

文档	何时写	内容
README	始终	安装、运行、一分钟上手
设计 doc	方案确定后	架构、接口、取舍
Runbook	可部署后	调试、运维、常见故障
回顾	里程碑/项目末	踩坑、改进项

文档与代码同源更新；过期的文档比没有更糟。

3.8 排错协议（禁止无脑重试）

1. 复述错误现象（期望 vs 实际）
2. 列 2～3 个假设（按可能性排序）
3. 一次只验证一个假设
4. 修复后写清根因，必要时补测试或文档

四、设计原则速查（经典且仍有效）

4.1 SOLID（面向对象 / 模块设计）

原则	含义	实践提示
S 单一职责	一个模块一个变化理由	函数做一件事；巨型 handler 要拆
O 开闭	对扩展开放，对修改关闭	用策略/插件，而非到处 if backend ==
L 里氏替换	子类型可替换父类型	接口语义一致，不偷偷改前置条件
I 接口隔离	不强迫依赖用不到的方法	小接口优于「上帝接口」
D 依赖倒置	依赖抽象，不依赖具体	核心业务不 import 具体 UI/DB 实现

4.2 架构与边界

• 高内聚： 相关逻辑放一起（同一 Tab、同一包、同一聚合）。
• 低耦合： 模块通过稳定接口通信，不读对方内部状态。
• 单向依赖： 领域核心不依赖 UI / 框架；适配层做翻译。
• 失败隔离： 子进程、超时、重试、降级——长任务不要拖死主界面。

4.3 API / 接口设计

• 契约明确：输入、输出、错误码、副作用。
• 幂等与可重试对异步任务至关重要。
• 版本化或扩展字段要事先想好；破坏性变更要有迁移路径。

4.4 前端 / 产品（凡有 UI 的项目）

• 用户任务优先，不是功能菜单优先。
• 信息架构先于视觉：导航、分组、主/次操作、状态（空/加载/成功/失败）。
• 渐进披露：默认简单，专家可展开。
• 反馈回路要短：>100ms 要有响应感，>1s 要有进度。
• 一致性：术语、布局、交互模式统一。

4.5 安全与可靠（默认要有意识）

• 最小权限；密钥不进仓库；输入校验。
• 外部进程 / 网络调用：超时 + 资源清理。
• 用户数据：覆盖/删除前确认；长任务可取消。

五、决策与取舍

5.1 常用决策维度

维度	问题
可逆性	这个决定容易改吗？
blast radius	错了会影响多大范围？
学习成本	团队多久能熟练？
运维成本	谁半夜被叫醒？
用户价值	对用户路径是 P0 还是锦上添花？

优先做可逆、小范围、高价值的决定；不可逆的大决定要文档化并评审。

5.2 Build vs Buy vs Compose

• Buy/用库： 通用能力（UI 框架、ORM、图表）。
• Build： 差异化核心、领域规则、性能关键路径。
• Compose： 胶水层要薄，业务规则不要散落在脚本里。

5.3 技术债

• 有意识借债：知道还不起就别借。
• 每次迭代留还债预算（重构、测试、删死代码）。
• 债的利息 = 改一处坏三处、新人看不懂、不敢动。

六、协作与流程（单人 / 小团队也适用）

6.1 角色清晰

• 定方向、验收、关键取舍 → 负责人 / PM / 架构师
• 方案、实现、验证、记录 → 执行者（含 AI 搭档）
• 执行者不替负责人做关键判断；负责人不微操每一行代码。

6.2 节奏

澄清 → 设计(对比) → 骨架 → 护栏 → 垂直切片 → 里程碑 → 沉淀

与 Agent/agent.md 七步工作流对齐；小修可省略文档，但不可跳过验证。

6.3 评审什么

• 是否解决正确的问题？
• 边界与接口是否清晰？
• 如何验证？测试在哪？
• 有无过度设计？有无明显风险未处理？

6.4 有效沟通产物

• 每次有意义的工作结束：做了什么、结果如何、未做项、下一步。
• 用图表、表格、可运行 demo 代替长篇空谈。

七、AI 辅助开发守则

1. 先规划后执行： AI 动手前，人确认范围与步骤。
2. 上下文要 curated： 需求、接口、约束、反例；不是堆满整个仓库。
3. 不臆造： API、路径、版本先查证。
4. 小 diff 审阅： 大段生成代码必须分段审查与测试。
5. 规则沉淀： 有效的 prompt、检查清单写入 .cursor/rules/ 或项目文档。
6. 人验收： AI 说「完成」不等于完成；跑测试、点界面、对验收标准。

八、项目启动前 10 分钟自检

复制到每个新项目 docs/ 或 issue 里勾选：

• 能用一句话说清业务目标与用户
• 有 1～3 条用户故事 + Out-of-Scope
• 有验收标准（功能 + 至少一条非功能）
• 至少对比过 2 种实现思路
• 架构草图 + 关键接口/数据结构已写
• 目录/模块职责清晰，依赖方向单一
• 有最小测试/冒烟入口（make test 或等价物）
• 知道第一个垂直切片是什么
• 最大风险已识别，有 spike/验证计划
• README 或运行说明能让陌生人跑起来

若勾选 < 7 项： 先补澄清或 spike，再大规模写代码。

九、常见反模式（看见就警惕）

反模式	后果
需求不清就开写	返工、范围蔓延
一次改几十个文件	难审、难回滚
没有测试的「能跑」	回归噩梦
复制粘贴业务规则	改一处漏一处
上帝类 / 上帝文件	没人敢动
静默失败 / 吞异常	用户与调试都痛苦
文档与代码两套故事	信任崩塌
追求新技术而非解决问题	简历驱动开发
AI 生成不审就用	隐蔽 bug、安全洞
无观测上线	靠猜排 prod 问题

十、推荐阅读脉络（按需深入）

主题	参考
软件工程知识域	IEEE SWEBOK Guide（需求、设计、构造、测试、维护等）
流动与反馈	Gene Kim — The DevOps Handbook（三步法）
演进式架构	Neal Ford 等 — 演进式架构、适应度函数
敏捷本质	Manifesto + 极限编程实践（小发布、反馈）
架构决策	ADR（Architecture Decision Records）模板
2025+ 趋势	平台工程、AI-native SDLC、上下文工程、绿色软件（碳意识）

不必一次读完；遇到对应问题时再深挖。

十一、心智模型速记卡

• 价值 > 炫技
• 问题 > 方案
• 可验证 > 声称完成
• 演进 > 一步到位
• 简单 > 复杂（在同样正确的前提下）
• 人话错误 > Error code
• 小步 > 大爆炸
• 文档与代码同步 > 靠记忆
• 上下文给 AI > 让 AI 猜
• 你负责判断，工具负责加速

十二、与本文配套的项目内文档

启动具体项目后，建议依次落地：

文件	内容
docs/00-requirements.md	需求与验收
docs/01-design.md	方案对比与架构
docs/02-skeleton.md	骨架与模块职责
docs/03-guardrails.md	测试与 CI
docs/04-progress.md	进度与决策记录
docs/05-runbook.md	运行与排错
docs/99-retrospective.md	回顾

人机协作细则见 Agent/agent.md 与 .cursor/rules/。

---

最后更新：2026-06-18