TL;DR在用 Codex 开发一个大型多角色 Agent 系统后我逐渐意识到当 LLM 参与开发时代码架构需要多一个新的优化目标降低模型的理解成本。传统的软件架构主要优化的是解耦分层可维护性团队协作但当 LLM 成为开发参与者之后还必须考虑代码是否容易被模型快速理解、修改并且不会迅速腐化。我把这种设计原则总结为最小理解闭包Minimum Understanding Closure核心思路可以概括为 7 条设计目标不是优雅分层而是最小理解闭包垂直切片通常比纯水平分层更适合 LLM稳定入口比抽象层数更重要文件不是越小越好而是越独立、越完整越好窄契约、少跳板、集中副作用可以显著降低 context 消耗避免把关键行为隐藏在难以定位的自动机制中架构需要能够抵抗 LLM 的反复修改与结构腐化下面是我在实际开发中的一些观察和总结。面向 LLM 的代码设计模式我越来越觉得LLM 参与开发之后“写好代码”这件事的标准其实已经发生了一些变化。过去我们讨论代码设计更多是围绕解耦复用分层可维护性但今天还必须多一个维度代码是否适合被 LLM 快速理解、反复修改并且不会迅速腐化。我最近在用Codex开发一个大型多角色 Agent 系统。在这个过程中我不断遇到一个很具体的问题不是模型不会写代码而是context 很快就乱掉、满掉、失去连续性。后来我慢慢意识到问题不只是上下文窗口而是代码组织方式本身。很多代码结构其实是为人类工程师团队优化的但未必适合LLM 的阅读方式。LLM 在阅读代码时通常具有一些特点上下文窗口有限阅读是顺序的依赖搜索与跳转来建立局部理解这意味着如果代码结构让模型必须频繁跳转多个文件context 很快就会被消耗掉。所以我开始重新思考一个问题如果今天写代码的主要读者之一已经不只是人类工程师而是 LLM那么代码应该如何组织这篇文章不是某种成熟的方法论而是我在实际开发中踩坑之后的一些总结。先说结论我现在的基本判断是面向 LLM 的代码设计核心不是追求传统意义上的“优雅分层”而是追求最小理解闭包。这里的“闭包”并不只是文件数量而是为了形成一个正确判断模型需要建立多少个独立语义单元以及这些语义单元之间需要跨多少跳才能连起来。不同模型差异很大但它们大都共享一种共同限制受限上下文顺序阅读依赖搜索与跳转建立局部地图所以我目前把面向 LLM 的代码设计总结为 7 个核心观点设计目标不是优雅分层而是最小理解闭包。衡量架构是否友好的标准不是抽象是否漂亮而是为了完成一个任务模型需要读取多少文件、跨多少跳、读取多少真正有信息增量的内容。纯水平分层未必比垂直切片更适合 LLM。如果一个功能被拆散在很多层之间routerservicemodelstoreutilsLLM 为了理解完整流程就必须穿透很多文件。相比之下按功能垂直收拢、切片内保留轻量分层更容易形成紧凑的理解闭包。稳定入口比抽象层数更重要。一个好的入口文件应该让模型快速回答四个问题这个模块负责什么对外暴露哪些能力输入输出是什么下一步该看哪个实现一个薄而清晰的入口本质上是一个导航工具。文件不是越小越好而是越独立、越完整越好。很多时候代码被拆成很多小文件helpersutilsmappervalidator每个文件都很小但逻辑被切得很碎。LLM 为了理解完整逻辑反而必须把这些文件全部读进 context。所以更好的标准是一个文件应该承载一个稳定责任并且读完以后能理解一个完整的小单元。窄契约、少跳板、集中副作用。如果模块之间传递整个 context整个 session整个 state那说明模块之间其实没有真正边界。更好的方式是使用窄契约例如MemorySnapshotExecutionRuntimeStateSkillInvocationResult这样 LLM 在理解模块关系时不需要同时记住巨大对象。避免把关键行为隐藏在难以定位的自动机制中。例如decoratormiddleware框架 hook自动注册逻辑这些机制有时很优雅但它们会让行为变得不在主流程代码里直接出现。对于 LLM 来说这意味着需要额外搜索需要额外读取因果链被打断所以一个更安全的原则是关键行为尽量显式表达而不是隐藏在难以定位的自动机制中。尤其是在关键路径上例如状态更新历史写入事件分发权限判断这些行为越显式LLM 越容易稳定理解。架构要能够抵抗 LLM 的时间轴腐化。LLM 在开发过程中有一些典型行为在现有逻辑后继续追加分支为了兼容旧行为保留多条路径在文件末尾补新逻辑添加保护性判断这些行为短期看是合理的但长期会导致入口越来越模糊状态越来越分散文件越来越长副作用越来越难追踪所以好的结构不仅要支持一次修改还要能够承受连续几十次修改之后仍然保持可读和可控。一些同样重要的补充原则1 文件名要可推断避免helperscommonprocessor文件名本身就是导航系统。2 在模块开头写清楚边界例如负责什么不负责什么上游是谁下游是谁这会让 LLM 更容易判断当前文件是不是目标文件。3 尽量使用显式状态例如status: pending | running | failed | completed比多个布尔变量更容易理解。4 测试可以成为“可执行文档”好的测试能告诉模型典型输入正常输出异常路径很多时候模型读测试比读实现更容易建立理解。5 积极清理死代码死代码对人类来说只是碍眼。但对 LLM 来说它会增加读取成本增加猜测降低修改准确率不是所有代码都需要为 LLM 优化最后还有一个边界需要说明。我并不认为整个代码库都应该为了 LLM 重构。更合理的做法是优先优化那些高频修改区、高频阅读区、高搜索密度区。例如Agent orchestration状态与上下文系统工具调用系统前后端接口层这些地方最容易消耗 context也最容易发生结构腐化。结语面向 LLM 的代码设计本质上不是让文件最小而是让单次任务的理解闭包最小。未来如果 LLM 会越来越多地参与开发那么软件架构可能需要多一个新的优化维度不仅要让人类工程师容易理解也要让模型能够用更少的 context 建立完整理解。换句话说好的架构不只是优雅的抽象而是能让理解闭包尽可能小。附注这篇文章的形成过程本身也和主题有关。它来自我在用Codex 开发一个大型 Agent 系统时遇到的真实问题一开始是在开发过程中不断遇到 context 相关的困难例如模型需要频繁跳转文件、上下文很快被消耗、结构逐渐变得难以修改。后来我围绕这些问题不断和 Codex 讨论、整理思路再由 Codex 协助起草部分段落最后经过Claude 的审查和补充修改才形成现在这篇文章。所以这并不是一篇“完全由 AI 自动生成”的文章而更像是一个人类开发者与 LLM 协作思考的产物。它比较真实地反映了我在这段开发过程中的一些观察、判断和感悟。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。
当 LLM 开始写代码：软件架构需要改变吗？
TL;DR在用 Codex 开发一个大型多角色 Agent 系统后我逐渐意识到当 LLM 参与开发时代码架构需要多一个新的优化目标降低模型的理解成本。传统的软件架构主要优化的是解耦分层可维护性团队协作但当 LLM 成为开发参与者之后还必须考虑代码是否容易被模型快速理解、修改并且不会迅速腐化。我把这种设计原则总结为最小理解闭包Minimum Understanding Closure核心思路可以概括为 7 条设计目标不是优雅分层而是最小理解闭包垂直切片通常比纯水平分层更适合 LLM稳定入口比抽象层数更重要文件不是越小越好而是越独立、越完整越好窄契约、少跳板、集中副作用可以显著降低 context 消耗避免把关键行为隐藏在难以定位的自动机制中架构需要能够抵抗 LLM 的反复修改与结构腐化下面是我在实际开发中的一些观察和总结。面向 LLM 的代码设计模式我越来越觉得LLM 参与开发之后“写好代码”这件事的标准其实已经发生了一些变化。过去我们讨论代码设计更多是围绕解耦复用分层可维护性但今天还必须多一个维度代码是否适合被 LLM 快速理解、反复修改并且不会迅速腐化。我最近在用Codex开发一个大型多角色 Agent 系统。在这个过程中我不断遇到一个很具体的问题不是模型不会写代码而是context 很快就乱掉、满掉、失去连续性。后来我慢慢意识到问题不只是上下文窗口而是代码组织方式本身。很多代码结构其实是为人类工程师团队优化的但未必适合LLM 的阅读方式。LLM 在阅读代码时通常具有一些特点上下文窗口有限阅读是顺序的依赖搜索与跳转来建立局部理解这意味着如果代码结构让模型必须频繁跳转多个文件context 很快就会被消耗掉。所以我开始重新思考一个问题如果今天写代码的主要读者之一已经不只是人类工程师而是 LLM那么代码应该如何组织这篇文章不是某种成熟的方法论而是我在实际开发中踩坑之后的一些总结。先说结论我现在的基本判断是面向 LLM 的代码设计核心不是追求传统意义上的“优雅分层”而是追求最小理解闭包。这里的“闭包”并不只是文件数量而是为了形成一个正确判断模型需要建立多少个独立语义单元以及这些语义单元之间需要跨多少跳才能连起来。不同模型差异很大但它们大都共享一种共同限制受限上下文顺序阅读依赖搜索与跳转建立局部地图所以我目前把面向 LLM 的代码设计总结为 7 个核心观点设计目标不是优雅分层而是最小理解闭包。衡量架构是否友好的标准不是抽象是否漂亮而是为了完成一个任务模型需要读取多少文件、跨多少跳、读取多少真正有信息增量的内容。纯水平分层未必比垂直切片更适合 LLM。如果一个功能被拆散在很多层之间routerservicemodelstoreutilsLLM 为了理解完整流程就必须穿透很多文件。相比之下按功能垂直收拢、切片内保留轻量分层更容易形成紧凑的理解闭包。稳定入口比抽象层数更重要。一个好的入口文件应该让模型快速回答四个问题这个模块负责什么对外暴露哪些能力输入输出是什么下一步该看哪个实现一个薄而清晰的入口本质上是一个导航工具。文件不是越小越好而是越独立、越完整越好。很多时候代码被拆成很多小文件helpersutilsmappervalidator每个文件都很小但逻辑被切得很碎。LLM 为了理解完整逻辑反而必须把这些文件全部读进 context。所以更好的标准是一个文件应该承载一个稳定责任并且读完以后能理解一个完整的小单元。窄契约、少跳板、集中副作用。如果模块之间传递整个 context整个 session整个 state那说明模块之间其实没有真正边界。更好的方式是使用窄契约例如MemorySnapshotExecutionRuntimeStateSkillInvocationResult这样 LLM 在理解模块关系时不需要同时记住巨大对象。避免把关键行为隐藏在难以定位的自动机制中。例如decoratormiddleware框架 hook自动注册逻辑这些机制有时很优雅但它们会让行为变得不在主流程代码里直接出现。对于 LLM 来说这意味着需要额外搜索需要额外读取因果链被打断所以一个更安全的原则是关键行为尽量显式表达而不是隐藏在难以定位的自动机制中。尤其是在关键路径上例如状态更新历史写入事件分发权限判断这些行为越显式LLM 越容易稳定理解。架构要能够抵抗 LLM 的时间轴腐化。LLM 在开发过程中有一些典型行为在现有逻辑后继续追加分支为了兼容旧行为保留多条路径在文件末尾补新逻辑添加保护性判断这些行为短期看是合理的但长期会导致入口越来越模糊状态越来越分散文件越来越长副作用越来越难追踪所以好的结构不仅要支持一次修改还要能够承受连续几十次修改之后仍然保持可读和可控。一些同样重要的补充原则1 文件名要可推断避免helperscommonprocessor文件名本身就是导航系统。2 在模块开头写清楚边界例如负责什么不负责什么上游是谁下游是谁这会让 LLM 更容易判断当前文件是不是目标文件。3 尽量使用显式状态例如status: pending | running | failed | completed比多个布尔变量更容易理解。4 测试可以成为“可执行文档”好的测试能告诉模型典型输入正常输出异常路径很多时候模型读测试比读实现更容易建立理解。5 积极清理死代码死代码对人类来说只是碍眼。但对 LLM 来说它会增加读取成本增加猜测降低修改准确率不是所有代码都需要为 LLM 优化最后还有一个边界需要说明。我并不认为整个代码库都应该为了 LLM 重构。更合理的做法是优先优化那些高频修改区、高频阅读区、高搜索密度区。例如Agent orchestration状态与上下文系统工具调用系统前后端接口层这些地方最容易消耗 context也最容易发生结构腐化。结语面向 LLM 的代码设计本质上不是让文件最小而是让单次任务的理解闭包最小。未来如果 LLM 会越来越多地参与开发那么软件架构可能需要多一个新的优化维度不仅要让人类工程师容易理解也要让模型能够用更少的 context 建立完整理解。换句话说好的架构不只是优雅的抽象而是能让理解闭包尽可能小。附注这篇文章的形成过程本身也和主题有关。它来自我在用Codex 开发一个大型 Agent 系统时遇到的真实问题一开始是在开发过程中不断遇到 context 相关的困难例如模型需要频繁跳转文件、上下文很快被消耗、结构逐渐变得难以修改。后来我围绕这些问题不断和 Codex 讨论、整理思路再由 Codex 协助起草部分段落最后经过Claude 的审查和补充修改才形成现在这篇文章。所以这并不是一篇“完全由 AI 自动生成”的文章而更像是一个人类开发者与 LLM 协作思考的产物。它比较真实地反映了我在这段开发过程中的一些观察、判断和感悟。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。
