复合工程：让代码库加速而不是衰减

大多数代码库随着增长而变慢，而我的却在加速。在构建了95个hooks、44个skills和14个配置文件的.claude/基础设施之后，每个新功能的成本都低于前一个，因为基础设施承担了更多的工作。¹

摘要

复合工程描述的是这样一种代码库：每增加一个功能，后续功能的构建成本就会降低。我亲身经历了这一点：我的Claude Code hook系统从3个hooks起步，发展到了95个。第一个hook花了一个小时来构建，而最近的hooks只需要10分钟，因为基础设施（生命周期事件、配置加载、状态管理、测试工具）已经就位。与之相反的模式是熵增工程——每增加一个功能都会提高后续功能的成本。一个团队在第三年比第一年交付更快，还是陷入停滞，关键在于他们的工程决策是正向复合还是负向复合。

复合实践：我的.claude/基础设施

增长曲线

第一个hook（git-safety-guardian.sh）需要构建整个hook生命周期：理解PreToolUse事件、编写解析JSON输入的bash脚本、处理错误情况、手动测试。第95个hook继承了所有这些基础设施。每个hook的耗时降低了6倍，并非因为hooks本身变简单了，而是因为基础设施承担了更多的工作。

什么在复合

模式一致性。 每个hook遵循相同的结构：读取JSON输入、用jq解析、检查条件、输出决策JSON。任何开发者（或AI代理）阅读任何一个hook都能立即识别这种模式。我的12模块博客检查器遵循同样的一致性原则：每个模块导出相同的接口（check(content, meta) -> findings），使得添加新模块变得轻而易举。

配置驱动行为。 所有14个JSON配置文件编码了原本硬编码的阈值和规则。当我将审议共识阈值从Python中硬编码的0.70迁移到deliberation-config.json时，我获得了按任务类型调优的能力（安全=85%，文档=50%），而无需修改代码。同样的模式也驱动着我的信号评分管线，其中可调的权重和阈值以确定性的方式路由着7,700多条知识条目。²

测试基础设施。 前20个hooks没有测试。添加测试工具（48个bash集成测试、81个Python单元测试）花了两周时间。此后每个hook在5分钟内就能附带测试完成交付，因为fixtures、断言辅助工具和测试运行器已经就绪。

记忆系统。 我的MEMORY.md文件跨会话记录错误、决策和模式。54条记录帮助我避免重蹈覆辙。hook #23中的((VAR++))bash陷阱已经防止了hooks #24到#95中的同类错误。每条记录在未来的每次会话中都在持续复合。³

复合模型

正向复合

工程生产力遵循复利公式：

Productivity(n) = Base × (1 + r)^n

其中r是每个功能的生产力变化率，n是已交付的功能数量。

正r值（复合）： 每个功能使下一个功能的成本降低2-5%。50个功能后：1.03^50 = 4.38倍生产力提升。

负r值（熵增）： 每个功能使下一个功能的成本增加2-5%。50个功能后：0.97^50 = 0.22倍生产力，即78%的退化。

这两种轨迹在50个功能后产生了20倍的工程效率差距。⁴

我的真实数据

我的blakecrosley.com网站最初只是一个FastAPI路由和一个HTML模板。九个月后：

最后一项就是复合的回报：添加一个新的检查器模块只需15分钟，因为模块接口、CLI集成、测试工具和CI管线已经就绪。第一个模块花了3小时，因为这些基础设施都不存在。⁵

我自己代码库中的熵增案例

复合不是自动发生的。我也经历过熵增：

ContentMeta Schema的捷径

我在一次会话中定义了博客文章的ContentMeta数据类：title、slug、date、description、tags、author、published。我没有包含category、series、hero_image、scripts或styles。后续每次添加都需要修改解析器、更新每个使用元数据的模板，并重新测试整个管线。三个月内的五次添加所花费的总时间，比一开始就仔细设计schema要多得多。这就是决策时机问题：不可逆的决策值得进行前期分析。

i18n缓存键冲突

翻译缓存的快速实现使用博客slug作为缓存键。当同一slug在不同语言环境下存在两个翻译时，缓存返回了错误的语言。调试花了3小时，修复只花了15分钟（为缓存键添加locale前缀）。实现时节省5分钟的捷径，在调试和对系统中每个缓存键的架构审查上花费了3小时。⁶

3.2GB的调试目录

Hook调试输出在~/.claude/debug/中不断累积，没有清理机制。三个月后，该目录增长到3.2GB。我后来构建的上下文审计skill发现了这个问题并清理了超过7天的文件，但清理机制本应在第一次调试输出时就一起构建。

产生复合效应的实践

一致的模式优于最优的模式

一个团队在50个功能中使用相同的”足够好”模式，运作速度快于每个功能都使用”最优”模式的团队。一致性降低了认知负担，支持自动化工具，并加快了代码审查速度。⁷

我的hook系统对所有95个hooks使用相同的bash模式，尽管某些hooks用Python表达会更自然。这种一致性意味着任何读过一个hook的人（或AI代理）都能读懂所有hook。语言选择上的次优被新hooks零学习成本的优势所充分弥补。

基础设施作为第一个功能

我在blakecrosley.com上构建任何产品功能之前，先构建了CI/CD管线、测试工具和部署工作流。当时这种投入感觉很慢，但此后的每个功能都能在2分钟内完成自动化测试和部署。⁸

记忆宫殿模式

我的.claude/目录像一座”记忆宫殿”——一组为人类和AI消费而优化的结构化文档：

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

记忆宫殿之所以能产生复合效应，是因为每一条新记录都丰富了未来开发会话的可用上下文。有了54条MEMORY.md记录，AI代理能够避免我已经解决过的错误。有了95个hooks，新hooks能够按照既定模式自行编写。更丰富的上下文产生更贴合需求的AI生成代码，从而使下一个功能的成本更低。⁹

AI时代的复合效应

AI放大双向趋势

AI编码助手会加速代码库已有的模式。我的95个hooks具有一致的模式，因此能产生优秀的AI生成hooks，因为AI能够匹配既定结构。一个拥有5种不同hook风格的代码库则会产生更差的AI生成代码，因为AI没有一致的模式可以匹配。¹⁰

复合效应加倍：一致的模式使人工开发更快（降低认知负担），同时也使AI辅助开发更快（模式匹配）。不一致的模式则使两者都变慢。

代理可读的代码库

我的.claude/基础设施是为AI代理消费而设计的：

• 结构化配置（JSON，而非硬编码值），代理可以程序化解析
• 一致的命名约定（hooks使用verb-noun.sh，skill定义使用SKILL.md）
• 机器可验证的质量检查（141个测试，代理可自主运行）——元认知层在其之上增加了自我监控
• 显式文档（MEMORY.md、handoffs、docs/），代理在会话开始时读取

对代理可读性的每一项投入，都随着AI工具能力的增强而持续复合。¹¹

核心要点

对工程师而言： - 追踪代码库增长过程中的”每个功能耗时”；如果在增加，说明存在熵增；如果在减少，说明正在复合 - 在提取抽象之前应用”三次原则”：先构建两次具体方案，在第三次出现时再提取可复用模式 - 将每个迭代周期的15-20%投入到基础设施和工具改进中；复合回报在3-5个迭代周期内就会超过短期功能速度的成本

对工程管理者而言： - 通过功能交付前置时间随时间的变化来衡量工程健康度；前置时间增加意味着熵增 - 将文档和测试基础设施视为功能而非开销；我的测试基础设施投入（2周）在95个hooks上已节省了50多个小时

常见问题

什么是复合工程？

复合工程描述的是这样一种代码库：每增加一个功能，后续功能的构建成本就会降低。其机制是把正向复利应用到工程基础设施上：一致的模式、配置驱动的行为、测试基础设施和不断积累的记忆，共同拉低了长期的单个功能成本。按每个功能3%的改进率计算，50个功能之后生产力提升4.38倍。与之相反的熵增工程按同样的算法侵蚀生产力，在复合与衰减的代码库之间拉开20倍的差距。⁴

AI代理如何随时间推移改善代码库？

AI代理会放大代码库已有的模式。模式一致时，模型能够匹配既定结构，因而生成质量出色的代码。我的95个hooks使用完全相同的bash模式，第一个hook需要60分钟，而现在生成一个高质量的AI hook只要10分钟。¹ 复合效应是双重的：一致的模式既加快人工开发（降低认知负担），也加快AI辅助开发（模式匹配）。不一致的代码库会产出更差的AI结果，因为模型没有可靠的模式可循。¹⁰

如何判断我的代码库是在复合还是在衰减？

追踪代码库增长过程中的”每个功能耗时”。如果耗时在增加，说明存在熵增；如果在减少，说明正在复合。更细致的信号是团队层面的功能交付前置时间随时间的变化。我的数据显示，新hook耗时在9个月内从60分钟降到10分钟，新检查器模块从3小时降到15分钟。⁵ 如果您的同类指标呈上升趋势，说明工程决策正在负向复合。

开始复合所需的最小投入是什么？

三项基础设施投入回报最快：带自动化测试的CI/CD管线（第3个功能时回本）、解析方式一致的内容或数据管线（第5个功能时回本）、带共享fixtures和断言辅助函数的测试基础设施（第5个模块时回本）。⁸ 经验法则是把每个迭代周期的15-20%投入到基础设施和工具改进中，复合回报在3-5个迭代周期内就会超过短期功能速度的成本。

为什么一致性比优化更重要？

一个团队在50个功能中使用相同的”足够好”模式，运作速度快于每个功能都使用”最优”模式的团队。一致性降低了认知负担，支持自动化工具，并加快了代码审查速度。⁷ 我的hook系统对所有95个hooks使用相同的bash模式，尽管某些hooks用Python表达会更自然。新hooks零学习成本的优势，足以弥补单个hook在语言选择上的次优。

参考文献