AI 时代,开源项目写好文档不如写好 Skill

提升开源项目的易用性，通常取决于三个核心支柱：高质量的 API、丰富的 Samples 和详尽的文档。然而，这恰恰撞上了编程界最著名的“三大难题”之一：写文档。

相比于命名和缓存失效，写文档的体力消耗与维护成本往往让开发者望而生畏。但在 AI Native 的工程范式下，这个曾被视为“难题”的环节，正在产生新的标准答案。

写文档困境

写文档困境大家都懂：

• 写文档费时费力，维护成本高
• 文档更新总是滞后于代码
• 用户看文档还是不会用，得去翻示例代码
• 新手看完文档还是一头雾水，只能去社区问

更要命的是，现在用户根本不看文档了。他们直接问 Claude、ChatGPT、Cursor：

“帮我写一个 dubbo-go 的服务”

然后 AI 给出的代码，用的是三年前的 API，配置格式也是错的。

AI 编程工具的盲区

Claude Code、Cursor、GitHub Copilot 这些 AI 工具很强大，但它们有个致命问题：训练数据截止日期。

对于 dubbo-go 这种快速迭代的框架：

• API v3 已经发布，AI 还在用 v2 的写法
• 配置格式改了，AI 生成的还是旧格式
• 扩展点机制变了，AI 完全不知道

结果就是：用户用 AI 生成代码 → 跑不起来 → 去 issue 里问 → 维护者疲于解释 → 恶性循环。

新思路：从文档到 Skill

dubbo-go 项目的积极贡献者韩信同学（Tsukikage）最近提出了一个提案（issue #3276）：与其写文档，不如写 AI Skill。

什么是 Skill？简单说，就是教 AI 怎么干活的工作流脚本。

比如一个 new-service.md skill：

# new-service创建一个符合 dubbo-go 规范的 Provider 服务。## 步骤1. 生成 proto 文件（使用 dubbo-go v3 规范）2. 生成服务实现代码3. 生成配置文件（支持 Nacos/Zookeeper）4. 生成启动代码## 注意事项- 使用 dubbo.NewInstance() 而不是旧的 config.Load()- 配置文件使用 YAML 格式- 服务注册使用 global.ProviderConfig

用户只需要在 Claude Code 里输入：/new-service，AI 就会按照这个 skill 的步骤，生成完全符合当前版本规范的代码。

为什么 Skill 比文档更好？

1. 永远是最新的

Skill 文件和代码在同一个仓库，代码改了，Skill 也会同步更新。不像文档网站，经常和代码脱节。

2. 直接可执行

文档是给人看的，Skill 是给 AI 执行的。用户不用理解原理，AI 直接帮你生成能跑的代码。

3. 覆盖真实场景

传统文档讲概念，Skill 解决具体问题：

• /new-service – 我要写个服务
• /configure – 我要配置注册中心
• /debug – 我的服务起不来
• /migrate – 我要从 gRPC 迁移过来

这些都是用户真实的需求场景。

4. 降低维护成本

一个 Skill 文件几十行，维护成本远低于几十页的文档。而且 Skill 出错了，用户会立刻反馈，因为代码跑不起来。

dubbo-go 的实践方案

提案建议在 dubbo-go 仓库中添加以下文件：

1. CLAUDE.md – 项目整体上下文，告诉 AI 这个项目是干什么的，核心概念是什么

2. .claude/skills/*.md – 具体的工作流 Skill：

• new-service.md – 生成 Provider 服务
• new-client.md – 生成 Consumer 代码
• configure.md – 生成配置文件
• debug.md – 排查常见问题
• migrate.md – 从其他框架迁移

3. llms.txt – 通用的 LLM 上下文文件，类似 robots.txt，所有 AI 工具都能读

4. .cursor/rules/dubbo-go.mdc – Cursor 专用的编码规范

5. .github/copilot-instructions.md – GitHub Copilot 的仓库级指令

这些文件加起来可能就几百行，但能让所有主流 AI 工具都能正确理解和使用 dubbo-go。

这不是替代文档

需要说明的是，Skill 不是要替代文档，而是补充：

• 文档：给人看的，讲原理、讲架构、讲设计思想
• Skill：给 AI 执行的，解决具体问题、生成可运行代码

两者配合，才能覆盖不同用户的需求。

行业趋势

这不是 dubbo-go 的独创，已经有很多项目在做了：

• OpenAI 的 Python Agent 框架有完整的 CLAUDE.md
• Cloudflare、Stripe、Vercel 都采用了 llms.txt 标准
• Anthropic 官方示例项目也在用这套方案

这说明一个趋势：AI 时代的开源项目，需要为 AI 工具提供专门的上下文。

对开源项目的启示

如果你在维护开源项目，不妨思考一下：

1. 用户真的在看文档吗？ 还是直接问 AI？
2. AI 生成的代码能跑吗？ 还是用的三年前的 API？
3. 你的 issue 里有多少是 AI 生成错误代码导致的？

如果答案让你不太满意，也许该考虑为 AI 工具写点东西了。

不需要很复杂，从一个 CLAUDE.md 开始，告诉 AI 你的项目当前是什么样的。再写几个常用场景的 Skill，解决用户最常遇到的问题。

这比写几十页文档要轻松得多，效果可能还更好。

写在最后

程序员的三大难题，命名和缓存失效还得继续头疼，但关乎易用性的写文档这事儿，AI 时代有了新玩法。

与其花大力气维护文档网站，不如花小力气写几个 Skill，让 AI 帮用户生成正确的代码。

毕竟，能跑的代码，才是最好的文档。

欢迎你加入dubbogo社区钉钉群:23331795，也欢迎你扫码加入 dubbogo 社区交流群：