code-that-fits-in-your-head

让代码清晰易懂

关于可持续软件的工程启发式原则，基于 Mark Seemann 2021 年的著作，并明确标注了 Agent 时代的修订内容。

代码示例以 C# 为主；所有规则和工具表都与语言无关。

理念（本技能为何存在）

软件开发本质上是一项设计活动，而非建造活动。Agent 可能会产出大部分文本，但人们仍要审查、运维、扩展并负责最终系统。这些启发式原则让软件更可持续：易于理解，能抵御架构侵蚀，并且在做出数千项决策后仍能以较低成本进行修改。

第 1 章的核心思维模型：

比喻	说得恰当之处	遗漏之处
盖房子	规划、结构	软件经久不衰；没有施工阶段（编译是免费的）；依赖关系可以从任何地方开始
种花园	修剪、重构、养护	代码不会自行改进；生成的代码仍需维护
艺术 / 手艺	技能、精通、情境知识	难以规模化；无法为新人提供指导
工程（目标）	启发式原则、审查、签核、清单	我们尚未达到这一阶段——实体建造的计算方法并不适用

“以明确无歧义的细节描述程序，与编写程序本身是一回事。”——Kevlin Henney

对编码 Agent 的实际意义：

1. 成功的软件经久不衰。 优先选择能保持边界清晰、让未来修改成本可控的变更。
2. 复杂性才是敌人，而不是任务规模。 如果架构、计划和验收标准完善，Agent 可以完成涉及数万行代码的变更。应拒绝不必要的耦合、重复、隐藏影响和无法验证的大规模改动，而不是仅仅因为范围大就拒绝。
3. 这是启发式原则，不是定律。 应先理解规则的目的，再决定是否应用或放宽规则。项目策略优先于通用的格式和工作流约定。
4. 验证是设计的一部分。 类型、测试、架构检查、可观测性和明确的验收标准，能够约束由人和 Agent 编写的代码。
5. 代码是一种负担。 生成的代码量不代表取得了进展。应优先采用能解决问题且不会积累技术债务的最简洁、一致的设计。

如需进一步了解可持续性、可读性和受大脑认知能力限制的设计，请参阅 references/foundations/。

如何使用此技能

1. 识别用户的任务（编写、审查、调试、安全审查、设置等）
2. 阅读 guidelines.md——该文件会将任务和症状对应到特定参考文件
3. 仅加载与当前任务相关的参考文件（渐进式披露）
4. 应用规则；如有疑问，请查阅 references/practices-glossary/ 中的交叉引用
5. 如果某条规则在某个代码仓库中反复证明有用，请将其转化为操作规范（workflows/operationalize-finding.md），使其成为检查关卡，并保留在项目 Agent 指令中。

章节索引

主题	适用场景……
references/foundations/	可持续性、可读性、复杂度控制，以及代码作为负担
references/codebase-setup/	启动或接手代码库——git、构建自动化、将警告视为错误
references/outside-in-tdd/	先写测试再开发新功能；行走骨架、AAA、三角验证、唱反调、编辑测试
references/encapsulation/	设计带有不变量的类型；DTO 与领域模型、始终有效、Postel 定律、解析而非验证
references/decomposition/	控制方法和系统的复杂度；圈复杂度、内聚、耦合、功能嫉妒、分形架构
references/api-design/	设计公共 API；可供性、防错设计、CQS、沟通层级、命名优于注释
references/separation-of-concerns/	添加横切关注点；装饰器模式、日志记录、记录什么、性能与易读性
references/teamwork-git/	编写提交、审查变更、持续集成、集体所有权
references/evolution/	更改正在运行的系统；功能标志、绞杀者模式、版本控制、定期更新依赖、康威定律
references/troubleshooting/	调试缺陷；科学方法、橡皮鸭调试、复现即测试、二分法、非确定性缺陷
references/security/	威胁建模；STRIDE（欺骗、篡改、抵赖、信息泄露、拒绝服务、权限提升）
references/code-navigation/	熟悉代码库；全局概览、文件组织、循环、基于属性的测试、行为式代码分析
references/tooling/	可执行的度量命令：复杂度、循环、重复代码、死代码、热点、变异测试
references/practices-glossary/	查询书中提及的实践及其当前状态

⚠️ 编辑性补充（非书中内容）

以下文件夹并非 Seemann 所著书籍的内容，而是我们自行补充的内容，涵盖该书（2021 年出版）未涉及的 Agent 特定问题。请勿将这些文件归于 Seemann。参见 references/agent-native/knowledge.md。

主题	适用场景……
references/agent-native/	Agent 特定的验证完整性、幻觉与依赖依据、可执行的防护措施，以及可追责的审查

工作流

组合式分步流程位于 workflows/：

任务	工作流
审查拉取请求／代码	workflows/review-code.md
从头开始添加新功能	workflows/add-feature-outside-in.md
调查并修复缺陷	workflows/debug-defect.md
对新端点进行威胁建模	workflows/threat-model.md
将反复出现的问题转化为可执行的门禁，并将其保存在项目记忆中	workflows/operationalize-finding.md

完整的路由层（任务 → 文件、症状 → 文件）请参见 guidelines.md。