本文永久链接 – https://tonybai.com/2026/01/29/write-a-good-claude-md

大家好，我是Tony Bai。

在使用 Claude Code、Cursor 或 Gemini Cli 等 AI 编程工具时，你是否遇到过这样的情况：

明明在项目根目录写了 CLAUDE.md（或 AGENTS.md），洋洋洒洒列了几十条项目规范：“使用 TypeScript”、“不要用 any”、“单元测试覆盖率要达标”……

但 AI 就像个叛逆的实习生，经常对这些指令视而不见，反复犯同样的低级错误。

是你写的 Prompt 不够严厉吗？还是模型不够聪明？

最近，HumanLayer 团队发布的一篇深度分析文章揭示了真相：

问题恰恰在于你写得太多了。

Claude Code 的内部机制会给模型注入一条系统级提醒：

“IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant.”
（重要：此上下文可能与您的任务无关。除非高度相关，否则请忽略。）

这意味着，你的 CLAUDE.md 越臃肿，包含的无关信息越多，它被系统判定为“噪音”并整体忽略的概率就越大。

今天，我们来聊聊如何用工程化的思维，重构你的 AI 上下文管理。

第一性原理：AI 是无状态的“新员工”

要写好 CLAUDE.md，首先要理解 LLM 的本质：它是无状态的（Stateless）。

每次你开启一个新的 Session，对于 AI 来说，都是入职第一天。它对你的代码库一无所知。CLAUDE.md 是它唯一的“入职手册”和“长期记忆”。

但这并不意味着你要把公司历史全塞给它。一个优秀的入职手册应该包含什么？

HumanLayer 的文章中 总结了 “The Trinity”（三要素）：

1. WHAT（地图）： 技术栈是什么？项目结构是怎样的？（特别是 Monorepo，告诉它哪里是 App，哪里是 Lib）。
2. WHY（目标）： 这个项目的核心价值是什么？核心模块的职责边界在哪里？
3. HOW（工具）： 怎么构建？怎么跑测试？用 npm 还是 bun？

除此之外的任何废话，都是在消耗 AI 宝贵的注意力。

最佳实践一：少即是多 (Less is More)

研究表明，即便是最前沿的推理模型（Thinking Models），能稳定遵循的指令上限也就在 150-200 条左右。而小模型（如 Haiku 或 GPT-4o-mini）的遵循能力随着指令数量增加呈指数级下降。

更糟糕的是 “位置偏见（Position Bias）”。LLM 高度关注开头（System Prompt）和结尾（最新对话），夹在中间的 CLAUDE.md 如果过长，极易沦为“被遗忘的中间层”。

因此，请遵循以下黄金法则：

• 不要试图涵盖所有边缘情况。
• 将根目录的 CLAUDE.md 控制在 300 行以内，HumanLayer 的生产环境甚至控制在 60 行以内。
• 每一行都要问自己：“如果没有这句话，AI 真的干不了活吗？”

最佳实践二：渐进式披露 (Progressive Disclosure)

如果你确实有很多规范要交代，怎么办？

答案是：不要把所有鸡蛋放在一个篮子里。

想象一下，HR 会在入职第一天把 500 页的《数据库运维手册》扔给一个前端开发吗？不会。

你需要构建一套“渐进式”的文档体系：

1. 建立文档库：

在项目中创建一个 .ai/docs/ 目录，存放特定领域的指南：

• testing.md：详细的测试编写与运行指南。
• database.md：Schema 定义与迁移规范。
• architecture.md：核心架构图与数据流。

2. 建立索引：

在主 CLAUDE.md 中，只保留“触发器”：

• “编写或运行测试前，请务必阅读 .ai/docs/testing.md。”
• “涉及数据库变更时，请参考 .ai/docs/database.md。”

这样，当 AI 只是在写一个前端组件时，它的上下文窗口就不会被无关的后端 Schema 污染。保持注意力的纯净，是提升 AI 智商的关键。

最佳实践三：别把 AI 当 Linter 用

这是最常见的资源浪费：在 CLAUDE.md 里写了 50 行关于代码风格的规定——“缩进用 2 个空格”、“花括号不换行”、“变量名用驼峰”……

请记住：LLM 是昂贵的推理引擎，不是廉价的格式化工具。

让 AI 去关注缩进，就像让法拉利去送外卖，既贵又慢。而且，AI 即使知道规则，也经常因为概率性生成而“手滑”。

正确的解法是：Tooling > Prompting。

1. 配置工具： 使用 Prettier, Biome, ESLint, govet 等确定性工具来处理格式。
2. 设置 Hook： 配置 Claude Code 的 Stop Hook。如果 AI 生成的代码格式不对，让 Linter 报错，把错误信息喂回给 AI。
   • AI: (生成代码)
   • System: “Lint Error: Missing semicolon.”
   • AI: “Ah, fixing it.”

AI 极其擅长修复报错，但并不擅长凭空遵守“隐形的规则”。

小结：杠杆的层级

在 AI 原生开发中，CLAUDE.md 处于“杠杆层级”的顶端。

• 写错一行代码 = 1 个 Bug。
• 写错一行 CLAUDE.md = 成百上千次错误的规划、错误的检索、错误的代码。

不要盲目依赖 /init 自动生成的文件，那只是个起点。你需要像维护核心代码一样，精心雕琢你的 CLAUDE.md。

现在，打开你的项目，检查一下那个文件。

删掉那些废话，把长文档拆分，把格式化交给工具。

给你的数字员工减负，它才能跑得更快。

资料链接：https://www.humanlayer.dev/blog/writing-a-good-claude-md

你的 CLAUDE.md 有几行？

读完这篇文章，不妨现在就去检查一下你项目里的 CLAUDE.md。它是清爽的“入职手册”，还是臃肿的“裹脚布”？你目前的行数是多少？

欢迎在评论区晒出你的“瘦身”成果！让我们一起给 AI 减负。

如果这篇文章帮你解决了 AI “不听话”的难题，别忘了点个【赞】和【在看】，并转发给你的团队，规范大家的 Prompt 工程！

构建工程化的 AI 工作流

CLAUDE.md 只是构建 AI 原生工作流的起点。

• 如何配置 Hooks 来实现自动化代码审查？
• 如何编写 Sub-Agents 来处理隔离的脏活累活？
• 如何设计 Slash Commands 来固化团队的 SOP？

如果你想深入掌握 Claude Code 的高阶玩法，不仅仅是写 Prompt，而是构建一套“自动纠错、按需加载”的工程化体系。

欢迎关注我的极客时间专栏《AI 原生开发工作流实战》。

我们不聊虚的，只讲能在生产环境中落地的 AI 工程实践。

扫描下方二维码，开启你的AI原生开发之旅。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

本文永久链接 – https://tonybai.com/2026/01/29/wso2-goodbye-java-hello-go-tech-stack-shift

大家好，我是Tony Bai。

“当我们 2005 年创办 WSO2 时，开发服务端企业级基础设施的正确语言毫无疑问是：Java。然而，当我们走过第 20 个年头并展望未来时，情况已经变了。”

近日，全球知名的开源中间件厂商 WSO2 发布了一篇震动技术圈的博文——《Goodbye Java, Hello Go!》。

这是企业级软件在云原生时代技术风向标的一次重要偏转。作为 Java 时代的既得利益者，WSO2 曾在 API 管理、集成中间件领域构建了庞大的 Java 帝国。为何在今天，他们会做出如此激进的转向？Java 真的不适合未来了吗？Go 到底赢在哪里？

让我们深入剖析这背后的技术逻辑、架构变迁与社区的激烈争议。

时代的变迁——从“服务器”到“函数”

WSO2 的转向并非一时冲动，而是基于对过去 15 年基础设施软件形态深刻变化的洞察。其博文中极其精准地总结了这一变迁：

“服务器”概念的消亡

在 2010 年代之前，中间件是以独立“服务器”（Server）的形式交付的。

• 应用服务器 (App Servers)：如 WebLogic, WebSphere, Tomcat。
• 企业服务总线 (ESB)：集成了各种协议适配器的庞然大物。
• 业务流程服务器 (Process Servers)：管理长周期的业务状态。

那是一个“重量级”的时代。你部署一个服务器，然后把你的业务逻辑（WAR 包、JAR 包）扔进去运行。这正是 Java 和 JVM 的黄金时代——JVM 作为一个强大的运行时环境，提供了热加载、动态管理、JIT 优化等一系列高级功能，完美匹配了这种“长时间运行、多应用共享”的服务器模式。

然而，容器化时代终结了这一切。

现在的“服务器”不再是一个独立的实体，而变成了一个库 (Library)。

• 你的业务逻辑不再是“寄生”在服务器里，而是包含了服务器。
• 整个应用打包成一个 Docker 镜像，作为一个独立的进程运行。
• 任务完成后，容器销毁，进程结束。

在 WSO2 看来，“独立软件服务器的时代已经结束了”。这对于 Java 来说，是一个底层逻辑的打击。

生命周期：从“月”到“毫秒”

在过去，一个服务器启动慢点没关系，因为它一旦启动，可能会运行数月甚至数年。JVM 的 JIT（即时编译）机制通过预热来换取长期运行的高性能，这是一种非常合理的权衡。

但在 Kubernetes 和 Serverless 主导的今天，服务器变得极度短暂 (Ephemeral)。

• 容器根据负载自动扩缩容，新实例必须瞬间就绪。
• Serverless 函数可能只存活几秒钟。

在这种场景下，启动时间就是服务质量 (SLA)。

WSO2 指出：“容器应该在毫秒级内准备好起舞，而不是秒级。” Java 庞大的生态依赖（Spring 初始化、类加载、注解扫描）和 JVM 的启动开销，在云原生环境下显得格格不入。内存膨胀（Memory Bloat）也直接推高了云厂商的账单。

生态位的错位：修补 vs. 原生

面对挑战，Java 社区并非无动于衷。GraalVM Native Image 试图通过 AOT（提前编译）解决启动速度问题；Project Loom 试图通过虚拟线程解决并发资源消耗问题。

但在 WSO2 的架构师们看来，这些努力更像是一种“追赶式的修补”。

“这些解决方案感觉就像是在为一个不同时代设计的语言和运行时进行翻新。”

GraalVM 虽然强大，但带来了构建时间的剧增、反射的限制以及调试的复杂性。相比之下，Go 语言在设计之初就原生 (Native) 地考虑了这些问题：编译即二进制，启动即巅峰，并发即协程。这是一种“原生契合”与“后天适配”的本质区别。

WSO2 的架构重构——前端不动，后端大换血

WSO2 并没有盲目地全盘推翻，他们对企业级软件的三层架构（前端、中间层、后端）进行了冷静的评估：

前端 (Frontend)：维持现状

• 现状：Web (JS/TS), iOS (Swift/Flutter), Android (Kotlin/Java)。
• 未来：No Change。
• 理由：前端技术栈受限于终端设备（浏览器、手机 OS），且更新换代极快（“fad-driven”，时尚驱动）。目前没有改变的必要。

中间层 (Middle Tier)：Ballerina 的独角戏

• 现状：Java, Ballerina。
• 未来：Ballerina。
• 核心逻辑：这一层通常被称为 BFF (Backend for Frontend)，负责 API 聚合、编排。WSO2 自研的 Ballerina 语言正是为此而生，它将网络原语（Network Primitives）作为语言的一等公民，极其适合做集成工作。

后端 (Backend)：Go 与 Python 的双雄会

• 现状：Java, Go, NodeJS, Python。
• 未来：Go, Python。
• 核心逻辑：这是基础设施逻辑的核心。Python 将继续统治 AI/ML 领域，而 Go 将彻底接管原本属于 Java 的领地，成为构建高性能、高并发基础设施的首选。

为什么是 Go，而不是 Rust？

这是一个每个技术决策者都会面临的灵魂拷问：既然要追求性能和原生编译，为什么不选 Rust？它不是更快、更安全吗？

WSO2 的回答展现了极高的工程务实精神。他们确实评估了 Rust，但最终选择了 Go。理由如下：

抽象层级的匹配

• Rust 的战场：操作系统内核、浏览器引擎、嵌入式设备。这些场景需要对内存布局、生命周期做极致的微操，且进程几乎永不重启。
• Go 的战场：中间件、API 网关、编排系统。

WSO2 构建的是中间件基础设施（如 API Gateway, Identity Server）。在这个层级，“我们总是比裸金属 (Bare Metal) 高那么一点点”。Go 提供的自动垃圾回收 (GC) 和高效的并发原语，恰好处于这个“甜点”位置。

避免“过度杀伤” (Overkill)

Rust 的所有权模型 (Ownership) 和借用检查器 (Borrow Checker) 虽然保证了内存安全，但也带来了极高的学习曲线和开发摩擦。对于大多数企业级业务逻辑来说，Rust 提供的控制力是多余的，而为此付出的开发效率代价是昂贵的。

云原生生态的引力

这是一个无法忽视的因素。Go 是云原生的“普通话”。

Kubernetes、Docker、Prometheus、etcd、Terraform…… 几乎所有现代基础设施的基石都是用 Go 构建的。选择 Go，意味着：

• 库的复用：可以直接调用 K8s 的库，而不是通过 API。
• 人才的复用：DevOps 工程师和 SRE 通常都懂 Go，可以无缝参与开发。
• 社区的共鸣：更容易融入 CNCF 生态，获得社区贡献。

实战验证——WSO2 的 Go 之旅

WSO2 并非纸上谈兵，他们在过去十年中已经在多个关键项目中验证了 Go 的能力：

OpenChoreo (CNCF Sandbox Project)

这是 WSO2 最具野心的项目之一，一个面向 Kubernetes 的开发者平台（IDP）。

• 挑战：需要深度集成 K8s，处理复杂的 GitOps 流程，且自身必须轻量、快速。
• Go 的价值：作为 K8s 原生语言，Go 让 OpenChoreo 能够像原生组件一样运行在集群中，资源占用极低。

Ballerina 编译器的彻底重写

这是一个惊人的决定。Ballerina 语言最初是基于 Java 实现的（运行在 JVM 上）。现在，WSO2 正在用 Go 完全重写 Ballerina 编译器。

• 目标：摆脱 JVM 的束缚，实现瞬间启动。
• 新架构：前端编译器用 Go 编写，直接生成基于 Go 的中间表示 (BIR)，这让 CLI 工具的体验得到了质的飞跃。

Thunder：下一代身份认证平台

身份认证（IAM）通常处于请求链路的关键路径上，对延迟极其敏感。Thunder 利用 Go 的高并发处理能力，实现了在高负载下的低延迟认证，且在容器化环境中具备极快的冷启动能力。

社区激辩——理性的探讨与情绪的宣泄

这篇博文在 Reddit 的 r/golang 板块引发了数百条评论的激烈讨论。这不仅仅是语言之争，更是两种工程文化的碰撞。

反方阵营：Java 依然是王者

1. “这是管理层的愚蠢决定”：
   一位愤怒的网友评论道：“计算资源是廉价的，开发人员的时间才是昂贵的。” 他认为，虽然 Go 节省了内存，但在业务逻辑极其复杂的企业级应用中，Java 强大的 IDE 支持、成熟的设计模式和庞大的生态库能显著降低开发成本。强行切换到 Go，可能会导致开发效率的崩塌。

2. “Java 并没有停滞不前”：
   很多 Java 支持者指出，WSO2 对 Java 的印象似乎还停留在 Java 8 时代。现代 Java (21+) 引入了 Virtual Threads (Project Loom)，在并发模型上已经可以与 Go 的 Goroutine 媲美；而 GraalVM 的成熟也让 Java 能够编译成原生镜像，启动速度不再是短板。

3. “生态位的不可替代性”：
   在处理遗留系统（如 SOAP, XML, 复杂的事务处理）方面，Java 积累了 20 年的库是 Go 无法比拟的。用 Go 去重写这些复杂的业务逻辑，无异于“重新发明轮子”，且容易引入新的 Bug。

正方阵营：Go 是未来的选择

1. “运维友好才是真的友好”：
   一位 DevOps 工程师反驳道：“在微服务架构下，运维成本是巨大的。” Go 生成的静态二进制文件（Static Binary）是运维的梦想——没有依赖地狱，没有 JVM 版本冲突，所有东西都打包在一个几 MB 的文件里。这种部署的便捷性，是 Java 永远无法达到的。

2. “简洁是一种防御机制”：
   Java 项目容易陷入“过度设计”的泥潭——层层叠叠的抽象、复杂的继承关系、魔法般的注解。Go 的强制简洁性（没有继承、显式错误处理）虽然写起来啰嗦，但读起来轻松。在人员流动频繁的大型团队中，Go 代码的可维护性往往优于 Java。

3. “云原生的网络效应”：
   正如 WSO2 所言，如果你在写 K8s Controller，如果你在写 Sidecar，如果你在写网关，Go 就是默认语言。这不仅仅是语言特性的问题，这是生态引力的问题。逆流而上使用 Java 编写这些组件，会让你失去整个社区的支持。

小结：没有终极语言，只有最适合的工具

WSO2 的声明并非要“杀死” Java。他们明确表示，现有的 Java 产品线将继续得到长期支持。但在新一代的云原生基础设施平台上，他们坚定地选择了 Go。

这一选择揭示了软件行业的一个趋势：通用编程语言的时代似乎正在结束，“领域专用语言”的时代正在到来。

• 做前端？选 TS/JS。
• 做 AI 模型训练？选 Python。
• 做操作系统、浏览器或者嵌入式系统？选 C/Rust/C++。
• 做企业级业务逻辑（尤其是遗留系统）？Java 依然稳健。
• 做云原生基础设施、中间件、高并发服务？Go 是当之无愧的王者。

对于 Gopher 而言，WSO2 的转型是一个强有力的信号：你们选对了赛道。Go 不仅是 Google 的语言，它正在成为定义未来十年企业级基础设施的通用语。

资料链接：

• https://wso2.com/library/blogs/goodbye-java-hello-go
• https://www.reddit.com/r/golang/comments/1qomr6g/goodbye_java_hello_go/

你的技术栈“保卫战”

WSO2 的转身，是时代的缩影，也是个体的写照。在你的团队中，是否也发生过类似的“去 Java 化”或“拥抱 Go”的讨论？你认为在云原生时代，Java 还能守住它的江山吗？

欢迎在评论区分享你的观点或经历，无论是坚守者还是转型者，我们都想听听你的声音！

如果这篇文章引发了你的思考，别忘了点个【赞】和【在看】，并转发给你的架构师朋友，看看他们怎么选！

还在为“复制粘贴喂AI”而烦恼？我的新专栏 《AI原生开发工作流实战》 将带你：

• 告别低效，重塑开发范式
• 驾驭AI Agent(Claude Code)，实现工作流自动化
• 从“AI使用者”进化为规范驱动开发的“工作流指挥家”

扫描下方二维码，开启你的AI原生开发之旅。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。