能控制好变量进行可控的增量迭代是工程经验的体现
2023 年的时候,@gneubig 曾经让我读过 Steve Hicks 在 2021 年写的这篇工程博客,讲的是如何写 Small, Focused Pull Requests。到了 2026 年,再重新读这篇文章,觉得其中的工程准则比以前更加珍贵。
这篇文章讲了一个在今天 AI 生成代码的时代特别容易被忽略的区别:small 不等于 focused。五个互不相关的改动,即使总共只有几十行,也可能是一个很糟糕的 PR;一个完整的 feature 即使目标非常明确,如果改动范围太大,也可能根本没有办法被认真 review。真正好的工程实践,是把代码组织成一个其他工程师能够理解、验证,并且愿意对其负责的变更单元。
文章给出了很多非常实际的方法:先搭建能够运行的 walking skeleton,再逐渐完善功能;把 infrastructure change 和 feature implementation 分开;把有争议的架构决策与常规实现隔离;尽量增量集成,而不是等一个巨大功能全部完成之后,再一次性提交一个庞大的 PR。
我觉得 AI coding 让这些原则变得更加重要了。我们已经极大降低了代码生成的成本,但并没有同等程度地降低理解代码的成本。Agent 可以在一个下午生成几千行看起来相当合理的代码,但这不代表 human reviewer 就突然获得了在同样时间里认真理解几千行变更的能力。
更麻烦的是,如果一个巨大的 AI-generated PR 同时混合了 refactoring、架构设计、性能优化和新功能,即使测试全部通过,我们仍然很难判断其中哪些假设需要特别谨慎地审查。最终,我们只是把原本开发者需要承担的认知成本,转移给了 reviewer 和未来的 maintainer。
我非常喜欢(至少似乎不得不用) coding agent,也完全不想回到(其实我还挺想回到的,但不能只是我一个人回到)每一行代码都必须亲手写的时代。但我一直强调,AI-assisted software engineering 并不只是如何生成更多代码,而是如何把这些代码组织成能够被人类真正理解、验证和维护的变更。
Small, focused PR 不是一种过时的工程仪式,而是避免开发速度最终演变成 review debt 的重要手段。
我自己的工程启蒙很大一部分来自 Graham。我从他那里学到的远远不只是科研。他大概是最早教会我应该怎样严肃地思考软件工程的人。非常感谢 @gneubig @vijaytarian
artsy.github.io/blog/2021/03…
得设计一份面向 agent 的接口设计标准
需要至少包含这些概念
分层, 用例文档, 分页, 过滤, 类型化, payload 可挑选, 支持区分人/替身的身份, 变更管理, 有副作用的操作要人类确认,副作用分级管理
等等
github.com/KLR-Pattern/hono-…
hono 版本的自动构建 graphql,以及 graphql 驱动的 mcp
之后其他符合条件的 web framework 都能搓一份出来
Turn your @FastAPI into agent friendly, token efficient MCP server just in two lines of code
Agent could send multiple queries in just one round, and pick fields from payload
Try github.com/KLR-Pattern/fasta…
本来觉得今年基于 graphql 的 mcp 方案会爆发, 但现在这个节点看起来好像瓶颈落在了 graphql 上,这玩意构造简单维护麻烦
但换个思路, 在 fastapi / pydantic 的约束下, 把一个个 api 变成可选字段的模式, 对agent 而言,倒是能带来不少优化的
github.com/KLR-Pattern/fasta…
展开说一下 GraphQL 的问题吧
GraphQL 核心的优势并不是所谓的类型系统,实际上强类型约束的在 RESTful 体系下也能很好的实现。充分利用了 Zod 能生成多端代码的 orpc 方案,Python 生态中的 FastAPI + Pydantic 方案都能实现类似的效果
GraphQL 最核心的优势是在于数据放题,即客户端可以根据自己的需求灵活的请求数据。这也是传统 BFF 层实现的主要功能之一。
但是和传统 BFF 层不一样的地方在于,现在 GraphQL 的实现通常会和业务进行强绑定,没有抽离出单独的基建来处理类似的问题。
而在这种情况,灵活性将会带来非常多的问题,在 GraphQL 体系下(或者说类似的 BFF 方案下沉到业务后都会面临的问题)。
最简单的一点,灵活性将带来更大的攻击面。最简单的一点,恶意用户可以构造出足够复杂的 Query 来通过单纯的 AST 解析来大量消耗你的服务器资源。
当然很多人可能会说,啊,你限制 Query 的复杂度不就好了?那我问你,计算 Query 的复杂度是不是需要也还是需要解 AST ?
当然还有人可能会说,那你限制 Query 的 Pattern 不就好了?那我问你,你的 Pattern 是不是也需要解 AST ?而且你把 GraphQL 最大的优势给限死了,你和传统的 RESTful API 有什么区别?
而且 GraphQL 的 AST 解析这一点如果不从业务解出来,配合 Node 这种单线程模型,你 Event loop lag 直接被拉炸,用户体验上升了N个台阶
GraphQL 本身要做的很多东西都需要单独的基建来和业务解开,比如 Query 级别的 Rate Limit, 特殊的鉴权逻辑等等
坦白说,对于数据平台或者内部服务,GraphQL 可能是个还不错的选择。但是对于上了量的 toC 业务来说,GraphQL 会比传统的 RESTful API 带来更多的复杂度和不确定性,会格外的吃基建的开发。
使用了几周之后,我大约可以确信,脑图的 md 形态, 这种交互方式是非常高效的。
通过节点编号来缩小交互范围。
使用 Markdown 来显示信息。
暴露 MCP 来让 Agent 交互,补充调整信息。
形式是自由的,结构是清晰的,调整是灵活的。
github.com/KLR-Pattern/fasta…
之前老吹 nexusx , 但客观来说它对架构的侵入性还是很强的
这次把里面一个有趣的 mcp 方案单独摘出来, 让fastapi 可以变成 mcp, 但是以更加优雅一些的方式
tag 的层级披露, 字段的meta 信息, 以及 pick 字段的能力
优化模型的理解, 改善上下文的占用
personal agent 在企业级别的隐私管理模式下, 想象空间还挺大的
替身使者参加会议, 替身使者回答问题, 替身使者做总结, 替身使者接收任务处理
用 mcp 打通中枢之后, 替身使者们就能自由流动了









