让 Claude Code 帮你写文档,但它默认写的不是你需要的

你让 Claude Code 帮你写这个模块的文档。Claude 写了，正确、完整。新人拿着这份文档，看了二十分钟，还是不知道这个模块是用来解决什么问题的，怎么开始第一个调用。

问题不是 Claude 写得不好。问题是它写了 API reference，你需要的是使用教程。

Claude 写的文档正确、完整、没有用——因为你需要的不是这种文档。

文档有四种类型

• • 教程：带新人完成第一个任务，目标是上手
• • 操作指南：解决具体问题的步骤，假设读者有基础
• • 参考文档：完整 API 说明，给查阅用（Claude 的默认输出）
• • 解释文档：背景、设计决策、架构思路，说明「为什么」

Claude 默认写参考文档。需要其他类型，你要说清楚。

说清楚类型、读者、目的

写新手教程：

请为这个模块写一个新手教程。读者是：刚加入团队的后端开发，熟悉 Python，但没用过这个模块。目标是：让他们在 30 分钟内完成第一个成功的调用。从最简单的例子开始，一步一步走，每步说明为什么。不需要覆盖所有功能，只覆盖最常用的 80%。

写架构说明：

请写这个模块的架构说明。读者是：需要修改这个模块的开发者。需要覆盖：解决什么问题、核心数据流、关键设计决策和权衡、容易踩坑的地方。不需要覆盖每个函数参数。

让 Claude 审查现有文档

以一个刚加入团队的开发者身份阅读这份文档。找出：1. 哪些地方读完还是不知道怎么做2. 哪些假设没有说明3. 有没有过时或不准确的内容4. 最重要的信息有没有被埋在不显眼的地方

更多 Java 工程实战与 AI 工具内容，欢迎关注公众号：SamLai 效率研习社