docs: add software engineering truths

2026-07-27 18:57:50 +00:00 · 2026-05-10 08:06:38 +08:00
parent de009a967f
commit 71112af4e3
8 changed files with 305 additions and 10 deletions
@@ -487,6 +487,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 *   [**思维模型**](docs/philosophy/README.md#philosophy-thinking-models): 第一性原理、奥卡姆剃刀、多阶思维、状态空间等认知工具。
 *   [**组合描述模型**](docs/philosophy/README.md#philosophy-compositional-description-model): 用对象、状态、快照、序列、过程、变换、同一/差异与关系描述复杂系统。
 *   [**编程之道**](docs/philosophy/README.md#philosophy-programming-dao): 编程哲学、结构、状态、复杂度与工程判断。
+*   [**软件工程的朴素真理**](docs/philosophy/README.md#philosophy-software-engineering-truths): 代码、复杂度、需求、维护、质量、架构和团队的工程常识。
 *   [**工程实践**](docs/references/README.md#quality-gates): 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。
 *   [**技术栈**](docs/references/README.md#tech-stack-selection): 常见软件系统技术栈、选型维度、组合案例与初学者学习路径。
 *   [**Harness 工程解析**](docs/research/README.md#research-harness-engineering): Harness Engineering 的工程控制、评估器与反馈闭环解析。
@@ -60,6 +60,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
 - docs/philosophy/README.md#philosophy-thinking-models：第一性原理、奥卡姆剃刀、多阶思维、状态空间等认知工具。
 - docs/philosophy/README.md#philosophy-compositional-description-model：对象、状态、快照、序列、过程、变换、同一/差异与关系。
 - docs/philosophy/README.md#philosophy-programming-dao：编程哲学、结构、状态、复杂度与工程判断。
+- docs/philosophy/README.md#philosophy-software-engineering-truths：代码、复杂度、需求、维护、质量、架构和团队的工程常识。
 - docs/philosophy/README.md#philosophy-methodology-toolbox：现象学还原、正反合、可证伪主义、形式化方法等提效工具。
 - docs/references/README.md：工程实践、技术栈、模板、清单和质量门禁参考索引。
 - docs/references/README.md#reference-engineering-practice：项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。
@@ -80,7 +81,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链

 - 新手入门：读取 `docs/getting-started/README.md#vibe-coding-experience`、`docs/getting-started/README.md#learning-map`、`docs/getting-started/README.md#cli-setup`，再读 `docs/concepts/README.md#concept-problem-solving`、`docs/concepts/README.md#concept-glue-coding` 和 `docs/references/README.md#reference-engineering-practice`。
 - 工程开发：读取 `docs/concepts/README.md#concept-glue-coding`、`docs/concepts/README.md#concept-system-building`、`docs/references/README.md#reference-technology-stack` 和 `docs/references/README.md#reference-engineering-practice`。
- 思维模型：读取 `README.md#dao-fa-shu-qi`、`docs/philosophy/README.md#philosophy-thinking-models`、`docs/philosophy/README.md#philosophy-compositional-description-model`、`docs/philosophy/README.md#philosophy-programming-dao` 和 `docs/philosophy/README.md#philosophy-methodology-toolbox`。
+- 思维模型：读取 `README.md#dao-fa-shu-qi`、`docs/philosophy/README.md#philosophy-thinking-models`、`docs/philosophy/README.md#philosophy-compositional-description-model`、`docs/philosophy/README.md#philosophy-programming-dao`、`docs/philosophy/README.md#philosophy-software-engineering-truths` 和 `docs/philosophy/README.md#philosophy-methodology-toolbox`。
 - 新技术判断：读取 `docs/research/README.md`，再读具体研究笔记，例如 `docs/research/README.md#research-harness-engineering`。
 - 标准流程执行：读取 `docs/workflow/README.md#workflow-development-process`。
 - AI Agent 执行：先读 `AGENTS.md` 与 `docs/AGENTS.md`，再读 `docs/workflow/README.md#workflow-development-process`，然后按任务类型读取 getting-started、concepts、references 或 research。
@@ -26,7 +26,7 @@ docs/
 - `getting-started/AGENTS.md`：入门教程目录操作规则。
 - `concepts/README.md`：线性总文档，包含问题求解、拼好码、系统构建方法、开发范式演进、语言层要素和递归自优化系统。
 - `concepts/AGENTS.md`：核心概念目录操作规则。
- `philosophy/README.md`：线性总文档，包含思维模型、组合描述模型、编程之道和方法论工具箱。
+- `philosophy/README.md`：线性总文档，包含思维模型、组合描述模型、编程之道、软件工程的朴素真理和方法论工具箱。
 - `philosophy/AGENTS.md`：哲学方法论目录操作规则。
 - `references/README.md`：线性总文档，包含工程实践和技术栈。
 - `references/AGENTS.md`：参考资料目录操作规则。
@@ -4,7 +4,7 @@

 - 新手先读 `getting-started/`，按网络环境、CLI 配置、开发环境和 Git 闭环推进。
 - 想理解 Vibe Coding 的底层概念，读 `concepts/`。
- 想补思维模型和方法论，读 `philosophy/`。
+- 想补思维模型、软件工程常识和方法论，读 `philosophy/`。
 - 想查工程模板、质量门禁、技术栈和常见坑，读 `references/`。
 - 想记录新技术、优秀 repo 或工程趋势，读 `research/`。
 - 想按标准流程推进任务、提交和推送，读 `workflow/`。
@@ -49,6 +49,7 @@
 - [思维模型](philosophy/README.md#philosophy-thinking-models) - 可复用思维模型索引。
 - [组合描述模型](philosophy/README.md#philosophy-compositional-description-model) - 用对象、状态、快照、序列、过程、变换、同一/差异与关系描述复杂系统。
 - [编程之道](philosophy/README.md#philosophy-programming-dao) - 编程哲学与工程判断。
+- [软件工程的朴素真理](philosophy/README.md#philosophy-software-engineering-truths) - 代码、复杂度、需求、维护、质量、架构和团队的工程常识。

 ### references

@@ -103,7 +104,8 @@
 1. [思维模型](philosophy/README.md#philosophy-thinking-models)
 2. [组合描述模型](philosophy/README.md#philosophy-compositional-description-model)
 3. [编程之道](philosophy/README.md#philosophy-programming-dao)
-4. [递归自优化系统](concepts/README.md#concept-recursive-self-optimizing-system)
+4. [软件工程的朴素真理](philosophy/README.md#philosophy-software-engineering-truths)
+5. [递归自优化系统](concepts/README.md#concept-recursive-self-optimizing-system)

 #### AI Agent 读取路径

@@ -14,7 +14,7 @@

 ```text
 philosophy/
-├── README.md  # 线性总文档：思维模型、组合描述模型、编程之道、方法论工具箱
+├── README.md  # 线性总文档：思维模型、组合描述模型、编程之道、软件工程的朴素真理、方法论工具箱
 └── AGENTS.md  # 本目录操作规则
 ```

@@ -8,7 +8,8 @@
 - 本目录回答“为什么这样判断、如何减少幻觉、如何让复杂问题可描述、可推理、可验证”。
 - 先用“思维模型”选择认知工具。
 - 再用“组合描述模型”把对象、状态、序列、过程和关系说清楚。
- 需要工程判断时读“编程之道”。
+- 需要理解代码、结构和复杂度时读“编程之道”。
+- 需要软件工程底层判断时读“软件工程的朴素真理”。
 - 需要提效方法时读“方法论工具箱”。

 ## 快速导航
@@ -16,7 +17,8 @@
 1. [思维模型](#philosophy-thinking-models) - 第一性原理、奥卡姆剃刀、多阶思维、状态空间等认知工具。
 2. [组合描述模型](#philosophy-compositional-description-model) - 对象、状态、快照、序列、过程、变换、同一/差异与关系。
 3. [编程之道](#philosophy-programming-dao) - 编程哲学、结构、状态、复杂度与工程判断。
-4. [方法论工具箱](#philosophy-methodology-toolbox) - 现象学还原、正反合、可证伪主义、形式化方法等提效工具。
+4. [软件工程的朴素真理](#philosophy-software-engineering-truths) - 代码、复杂度、需求、维护、质量、架构和团队的工程常识。
+5. [方法论工具箱](#philosophy-methodology-toolbox) - 现象学还原、正反合、可证伪主义、形式化方法等提效工具。

 <details>
 <summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
@@ -113,7 +115,39 @@
  - [程序即决策](#philosophy-programming-dao-程序即决策)
  - [18. 语录](#philosophy-programming-dao-18-语录)
  - [结束语](#philosophy-programming-dao-结束语)
- [4. 方法论工具箱](#philosophy-methodology-toolbox)
+- [4. 软件工程的朴素真理](#philosophy-software-engineering-truths)
+  - [一、关于代码](#philosophy-software-engineering-truths-一关于代码)
+    - [1. 代码是写给人读的，顺便让机器执行](#philosophy-software-engineering-truths-1-代码是写给人读的顺便让机器执行)
+    - [2. 清晰比聪明重要](#philosophy-software-engineering-truths-2-清晰比聪明重要)
+    - [3. 命名是编程中最难的事之一](#philosophy-software-engineering-truths-3-命名是编程中最难的事之一)
+    - [4. 最好的代码，是不存在的代码](#philosophy-software-engineering-truths-4-最好的代码是不存在的代码)
+    - [5. 重复代码不一定坏，错误抽象更坏](#philosophy-software-engineering-truths-5-重复代码不一定坏错误抽象更坏)
+  - [二、关于复杂度](#philosophy-software-engineering-truths-二关于复杂度)
+    - [6. 软件工程的核心是管理复杂性](#philosophy-software-engineering-truths-6-软件工程的核心是管理复杂性)
+    - [7. 复杂度不会消失，只会转移、隐藏或命名](#philosophy-software-engineering-truths-7-复杂度不会消失只会转移隐藏或命名)
+    - [8. 简单不是简陋，而是克制](#philosophy-software-engineering-truths-8-简单不是简陋而是克制)
+  - [三、关于需求](#philosophy-software-engineering-truths-三关于需求)
+    - [9. 需求永远不会完整](#philosophy-software-engineering-truths-9-需求永远不会完整)
+    - [10. 需求不清，技术越强，偏得越快](#philosophy-software-engineering-truths-10-需求不清技术越强偏得越快)
+    - [11. 变化是常态](#philosophy-software-engineering-truths-11-变化是常态)
+  - [四、关于维护](#philosophy-software-engineering-truths-四关于维护)
+    - [12. 上线不是结束，而是开始](#philosophy-software-engineering-truths-12-上线不是结束而是开始)
+    - [13. 不动的代码也会腐烂](#philosophy-software-engineering-truths-13-不动的代码也会腐烂)
+    - [14. 技术债不是罪，假装没有技术债才是罪](#philosophy-software-engineering-truths-14-技术债不是罪假装没有技术债才是罪)
+  - [五、关于质量](#philosophy-software-engineering-truths-五关于质量)
+    - [15. 测试不是为了证明代码正确](#philosophy-software-engineering-truths-15-测试不是为了证明代码正确)
+    - [16. 性能问题要靠测量，不要靠感觉](#philosophy-software-engineering-truths-16-性能问题要靠测量不要靠感觉)
+    - [17. 安全不是一个功能，而是一种默认假设](#philosophy-software-engineering-truths-17-安全不是一个功能而是一种默认假设)
+    - [18. 稳定不是没有故障，而是故障可控](#philosophy-software-engineering-truths-18-稳定不是没有故障而是故障可控)
+  - [六、关于架构与权衡](#philosophy-software-engineering-truths-六关于架构与权衡)
+    - [19. 没有银弹](#philosophy-software-engineering-truths-19-没有银弹)
+    - [20. 软件工程本质上是权衡](#philosophy-software-engineering-truths-20-软件工程本质上是权衡)
+  - [七、关于团队](#philosophy-software-engineering-truths-七关于团队)
+    - [21. 软件工程是团队运动](#philosophy-software-engineering-truths-21-软件工程是团队运动)
+    - [22. 系统的形状，往往反映组织的形状](#philosophy-software-engineering-truths-22-系统的形状往往反映组织的形状)
+    - [23. 文档不是装饰品](#philosophy-software-engineering-truths-23-文档不是装饰品)
+  - [八、最终总结](#philosophy-software-engineering-truths-八最终总结)
+- [5. 方法论工具箱](#philosophy-methodology-toolbox)
  - [目录定位](#philosophy-methodology-toolbox-目录定位)
  - [怎么选](#philosophy-methodology-toolbox-怎么选)
  - [相关文档](#philosophy-methodology-toolbox-相关文档)
@@ -159,6 +193,7 @@
 - 遇到复杂问题，先读 [思维模型](#philosophy-thinking-models)，选择合适的分析工具。
 - 需要把复杂对象拆清楚，读 [组合描述模型](#philosophy-compositional-description-model)。
 - 需要判断代码、架构和复杂度，读 [编程之道](#philosophy-programming-dao)。
+- 需要理解真实软件工程中的需求、维护、质量、权衡和团队协作，读 [软件工程的朴素真理](#philosophy-software-engineering-truths)。
 - 需要形成可复用方法，读 [方法论工具箱](#philosophy-methodology-toolbox)。

 ## 正文
@@ -1272,11 +1307,261 @@ UserInput(组合描述模型)
 </details>

 <details>
-<summary><strong>4. 方法论工具箱</strong> - 现象学还原、正反合、可证伪主义、形式化方法等提效工具。（点击展开/收起）</summary>
+<summary><strong>4. 软件工程的朴素真理</strong> - 代码、复杂度、需求、维护、质量、架构和团队的工程常识。（点击展开/收起）</summary>
+
+<a id="philosophy-software-engineering-truths"></a>
+
+## 4. 软件工程的朴素真理
+
+> 软件工程不是把代码写出来，而是在变化中持续交付可靠价值。
+
+软件工程的核心，不是写代码，而是管理复杂性。
+
+代码只是结果。真正困难的是：需求会变化，人会误解，系统会膨胀，历史包袱会累积，边界会模糊，成本会被低估。
+
+软件工程不是把复杂问题变成复杂代码，而是尽量把复杂问题变成可理解、可维护、可演进的系统。
+
+<a id="philosophy-software-engineering-truths-一关于代码"></a>
+### 一、关于代码
+
+<a id="philosophy-software-engineering-truths-1-代码是写给人读的顺便让机器执行"></a>
+#### 1. 代码是写给人读的，顺便让机器执行
+
+机器不在乎变量名叫 a1 还是 user_discount_rate，但人会在未来反复阅读、修改、排查这段代码。
+
+代码首先是一种沟通媒介，其次才是机器指令。
+
+可读性比聪明感重要。没人会长期欣赏只有你自己能看懂的代码。
+
+<a id="philosophy-software-engineering-truths-2-清晰比聪明重要"></a>
+#### 2. 清晰比聪明重要
+
+聪明的代码可能让人佩服一分钟，清晰的代码能让团队少痛苦几年。
+
+调试通常比写代码更难。如果代码本身已经写得过于“聪明”，未来排查问题的人会付出更高代价。
+
+<a id="philosophy-software-engineering-truths-3-命名是编程中最难的事之一"></a>
+#### 3. 命名是编程中最难的事之一
+
+一个好名字抵得上一段注释，一个坏名字会制造无数误解。
+
+命名困难，往往说明概念还没有想清楚。
+
+<a id="philosophy-software-engineering-truths-4-最好的代码是不存在的代码"></a>
+#### 4. 最好的代码，是不存在的代码
+
+能不写的代码，永远是最好的代码。
+
+代码越多，维护成本越高，出错面越大。删除代码常常才是真正的进步。
+
+少即是多，不是偷懒，而是克制。
+
+<a id="philosophy-software-engineering-truths-5-重复代码不一定坏错误抽象更坏"></a>
+#### 5. 重复代码不一定坏，错误抽象更坏
+
+抽象是有代价的。
+
+好的抽象减少复杂性，坏的抽象制造复杂性。没有被真实使用验证过的抽象，往往只是提前制造复杂度。
+
+过早抽象，很多时候比适度重复更糟。
+
+<a id="philosophy-software-engineering-truths-二关于复杂度"></a>
+### 二、关于复杂度
+
+<a id="philosophy-software-engineering-truths-6-软件工程的核心是管理复杂性"></a>
+#### 6. 软件工程的核心是管理复杂性
+
+软件开发本质上，是把业务世界里的混乱逻辑，转化为可运行、可理解、可维护的数字逻辑。
+
+业务本身有多复杂，系统最终就会有多复杂。
+
+工程能力不是消灭所有复杂度，而是让复杂度有边界、有位置、有解释。
+
+<a id="philosophy-software-engineering-truths-7-复杂度不会消失只会转移隐藏或命名"></a>
+#### 7. 复杂度不会消失，只会转移、隐藏或命名
+
+你可以通过架构、抽象、封装、平台化来移动复杂度，但很难真正消灭复杂度。
+
+如果一个系统看起来简单得不可思议，复杂度很可能被推给了用户、运维、调用方，或者藏在某个尚未暴露的角落里。
+
+<a id="philosophy-software-engineering-truths-8-简单不是简陋而是克制"></a>
+#### 8. 简单不是简陋，而是克制
+
+简单不是少写几行代码，而是少让人记住东西。
+
+好的设计不是堆更多功能，而是减少不必要的概念、状态、分支和例外。
+
+真正的简单，是让正确的事情容易发生，让错误的事情难以发生。
+
+<a id="philosophy-software-engineering-truths-三关于需求"></a>
+### 三、关于需求
+
+<a id="philosophy-software-engineering-truths-9-需求永远不会完整"></a>
+#### 9. 需求永远不会完整
+
+用户往往知道自己不满意什么，却未必能准确描述自己真正需要什么。
+
+很多失败项目，不是因为程序员不会写代码，而是因为一开始就没有搞清楚要解决什么问题。
+
+<a id="philosophy-software-engineering-truths-10-需求不清技术越强偏得越快"></a>
+#### 10. 需求不清，技术越强，偏得越快
+
+需求不清时，技术能力越强，越可能把错误的方向实现得又快又复杂。
+
+最贵的 bug，通常不是写错了代码，而是理解错了问题。
+
+<a id="philosophy-software-engineering-truths-11-变化是常态"></a>
+#### 11. 变化是常态
+
+软件不是在稳定世界里运行的静态产物。
+
+市场会变，用户会变，组织会变，依赖会变，监管会变，基础设施也会变。
+
+所以软件设计不能只追求“第一次做对”，还要考虑未来如何修改、扩展、替换和回滚。
+
+<a id="philosophy-software-engineering-truths-四关于维护"></a>
+### 四、关于维护
+
+<a id="philosophy-software-engineering-truths-12-上线不是结束而是开始"></a>
+#### 12. 上线不是结束，而是开始
+
+软件不是一次性交付物，而是一项长期债务。
+
+上线只是软件开始接受现实检验的第一天。维护、扩展、排障、迁移、兼容，才是成本的大头。
+
+<a id="philosophy-software-engineering-truths-13-不动的代码也会腐烂"></a>
+#### 13. 不动的代码也会腐烂
+
+即使一行代码都不改，系统也可能逐渐失效。
+
+依赖会过时，环境会升级，接口会废弃，业务规则会变化，安全风险会积累。
+
+不维护的系统，迟早会出问题。
+
+<a id="philosophy-software-engineering-truths-14-技术债不是罪假装没有技术债才是罪"></a>
+#### 14. 技术债不是罪，假装没有技术债才是罪
+
+为了赶进度牺牲质量，有时是现实选择。
+
+但技术债必须被看见、被记录、被评估。债可以借，但要知道借了多少，利息是什么，什么时候还。
+
+“以后再重构”通常意味着“以后也不会重构”。
+
+<a id="philosophy-software-engineering-truths-五关于质量"></a>
+### 五、关于质量
+
+<a id="philosophy-software-engineering-truths-15-测试不是为了证明代码正确"></a>
+#### 15. 测试不是为了证明代码正确
+
+测试不能证明系统没有 bug，但能阻止很多旧 bug 复活。
+
+它最大的价值，是让修改不那么可怕。
+
+没有测试的系统，越成功越难改；越难改，越容易变成负担。
+
+<a id="philosophy-software-engineering-truths-16-性能问题要靠测量不要靠感觉"></a>
+#### 16. 性能问题要靠测量，不要靠感觉
+
+过早优化是万恶之源。
+
+先让它跑起来，再让它正确，最后才是让它快。
+
+大多数性能问题不是靠猜出来的，而是靠监控、profiling、压测和真实数据定位出来的。
+
+<a id="philosophy-software-engineering-truths-17-安全不是一个功能而是一种默认假设"></a>
+#### 17. 安全不是一个功能，而是一种默认假设
+
+系统最脆弱的地方，通常不在算法，而在边界。
+
+输入、权限、网络、并发、时间、状态、依赖、异常路径，才是事故高发区。
+
+安全的基本假设应该是：任何输入都可能有问题，任何边界都可能被突破。
+
+<a id="philosophy-software-engineering-truths-18-稳定不是没有故障而是故障可控"></a>
+#### 18. 稳定不是没有故障，而是故障可控
+
+稳定系统靠的不是永远不出问题，而是出问题时能够被发现、被定位、被隔离、被恢复。
+
+日志、监控、告警、追踪、降级、限流、回滚，都是系统稳定性的一部分。
+
+日志不是给程序看的，是给凌晨三点处理事故的人看的。
+
+<a id="philosophy-software-engineering-truths-六关于架构与权衡"></a>
+### 六、关于架构与权衡
+
+<a id="philosophy-software-engineering-truths-19-没有银弹"></a>
+#### 19. 没有银弹
+
+没有任何语言、框架、架构、平台或工具能解决所有问题。
+
+换语言不一定能解决性能问题，引入新框架不一定能解决组织问题，使用 AI 写代码也不等于解决了需求定义和工程责任。
+
+技术只是手段，不是答案本身。
+
+<a id="philosophy-software-engineering-truths-20-软件工程本质上是权衡"></a>
+#### 20. 软件工程本质上是权衡
+
+软件世界里很少有绝对最优，更多是当前条件下的相对合适。
+
+速度、质量、成本、灵活性、稳定性、安全性、复杂度，往往互相牵制。
+
+架构设计不是寻找完美方案，而是在多个不完美选项中，选择团队当前最能承担的代价。
+
+<a id="philosophy-software-engineering-truths-七关于团队"></a>
+### 七、关于团队
+
+<a id="philosophy-software-engineering-truths-21-软件工程是团队运动"></a>
+#### 21. 软件工程是团队运动
+
+再厉害的独行侠，也比不上一个沟通顺畅的团队。
+
+代码是媒介，协作才是核心。
+
+团队里的隐性知识越多，系统风险越大。没有被写下来、讲清楚、传递出去的知识，都会在未来变成成本。
+
+<a id="philosophy-software-engineering-truths-22-系统的形状往往反映组织的形状"></a>
+#### 22. 系统的形状，往往反映组织的形状
+
+沟通混乱的团队，很难产出边界清晰的软件。
+
+职责不清、目标不一、协作低效，最终都会反映到系统里，变成混乱的模块、模糊的接口和难以维护的依赖关系。
+
+<a id="philosophy-software-engineering-truths-23-文档不是装饰品"></a>
+#### 23. 文档不是装饰品
+
+文档不是为了证明你写过什么，而是为了让别人少猜。
+
+尤其是记录“为什么这么做”的文档，通常比解释“代码做了什么”更有价值。
+
+代码能说明系统当前怎么运行，但文档能解释当时为什么做出这个选择。
+
+<a id="philosophy-software-engineering-truths-八最终总结"></a>
+### 八、最终总结
+
+软件工程的朴素真理是：
+
+技术只是手段，解决问题才是目的。
+
+优秀的工程师，不是写出多复杂的代码，而是能用尽可能简单、清晰、可靠的方式解决复杂问题。
+
+每一行代码，都是未来要承担的责任。
+
+每一个抽象，都是未来要维护的承诺。
+
+每一个系统，都会在变化中接受检验。
+
+所以，软件工程的本质不是“把代码写出来”，而是：
+
+在变化中持续交付可靠价值。
+
+</details>
+
+<details>
+<summary><strong>5. 方法论工具箱</strong> - 现象学还原、正反合、可证伪主义、形式化方法等提效工具。（点击展开/收起）</summary>

 <a id="philosophy-methodology-toolbox"></a>

-## 4. 方法论工具箱
+## 5. 方法论工具箱

 > 现象学还原、正反合、可证伪主义、形式化方法等提效工具。

@@ -1302,6 +1587,7 @@ UserInput(组合描述模型)
 | 想快速获得可复用认知工具 | [思维模型](#philosophy-thinking-models) |
 | 想描述复杂系统的对象、状态和变化 | [组合描述模型](#philosophy-compositional-description-model) |
 | 想理解代码、结构、状态和复杂度 | [编程之道](#philosophy-programming-dao) |
+| 想理解真实工程里的需求、维护、质量、权衡和协作 | [软件工程的朴素真理](#philosophy-software-engineering-truths) |
 | 想把探索过程变成可验证工程流程 | 本文件的方法论工具箱 |

 <a id="philosophy-methodology-toolbox-相关文档"></a>
@@ -1309,6 +1595,7 @@ UserInput(组合描述模型)

 - [思维模型](#philosophy-thinking-models) - 第一性原理、奥卡姆剃刀、网络效应、多阶思维、状态空间等可复用认知工具。
 - [编程之道](#philosophy-programming-dao) - 用更抽象的方式理解代码、结构、状态、复杂度与工程判断。
+- [软件工程的朴素真理](#philosophy-software-engineering-truths) - 用底层常识理解代码、复杂度、需求、维护、质量、架构与团队。
 - [组合描述模型](#philosophy-compositional-description-model) - 对象、状态、快照、序列、过程、变换、同一/差异与关系。

 <a id="philosophy-methodology-toolbox-目录"></a>
@@ -32,6 +32,7 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮
 - docs/philosophy/README.md#philosophy-thinking-models
 - docs/philosophy/README.md#philosophy-compositional-description-model
 - docs/philosophy/README.md#philosophy-programming-dao
+- docs/philosophy/README.md#philosophy-software-engineering-truths
 - docs/philosophy/README.md#philosophy-methodology-toolbox
 - docs/references/README.md#reference-engineering-practice
 - docs/references/README.md#reference-technology-stack
@@ -121,6 +121,9 @@ documents:
    - path: docs/philosophy/README.md#philosophy-programming-dao
      title: 编程之道
      role: 编程哲学、结构、状态、复杂度与工程判断
+    - path: docs/philosophy/README.md#philosophy-software-engineering-truths
+      title: 软件工程的朴素真理
+      role: 代码、复杂度、需求、维护、质量、架构和团队的工程常识
    - path: docs/philosophy/README.md#philosophy-methodology-toolbox
      title: 方法论工具箱
      role: 现象学还原、正反合、可证伪主义、形式化方法等提效工具