你是不是也遇到过这样的场景:花了一整天写完技术方案文档,信心满满地发给团队,结果收到一堆问题——"这个背景是什么?""为什么不用方案B?""这部分看不懂"。你明明觉得写得很清楚,但读者就是get不到点。更尴尬的是,当你把文档丢给Claude想让它帮忙优化时,Claude也一脸懵:"我需要更多上下文才能理解你的文档。"

这种"作者诅咒"(Curse of Knowledge)几乎是所有文档写作者的噩梦。你脑子里有完整的上下文,但写出来的文字却漏洞百出。等到别人指出问题时,文档已经发出去了,返工成本巨大。有没有一种方法,能在文档发出去之前,就帮你发现这些"对读者不友好"的盲区呢?

今天要介绍的 doc-coauthoring 技能包,就是专门为解决这个问题而生的。它不是一个简单的文档生成工具,而是一个结构化的文档协作工作流。这个技能包会像一位经验丰富的文档教练一样,带你走过三个关键阶段:上下文收集(Context Gathering)、内容打磨(Refinement & Structure)、读者测试(Reader Testing)。

最妙的是第三阶段——它会用一个"全新的Claude"(没有任何上下文记忆)来测试你的文档,模拟真实读者的阅读体验。如果这个"零背景"的Claude都能看懂你的文档,那你的同事、老板、客户自然也能看懂。这就像是在文档发布前,给你安排了一次"盲测",提前暴露所有问题。

环境准备

在安装 doc-coauthoring 技能包之前,你需要先安装 Claude Code。具体的安装方法请自行搜索官方文档,这里就不展开了。确保你的 Claude Code 已经正常运行,能够在编辑器中与 Claude 进行对话。

获取技能包

doc-coauthoring 技能包可以在公众号后台输入“技能”即可获取。下载后,你会得到一个名为 doc-coauthoring 的文件夹,里面包含了技能的配置文件和工作流定义。

安装步骤

安装过程非常简单,就是把技能包文件夹放到指定的目录。根据你的使用需求,可以选择两种安装方式:

# 项目级技能(仅当前项目可用):.claude/skills/doc-coauthoring/# 用户级技能(所有项目可用):~/.claude/skills/doc-coauthoring/

如果你只想在某个特定项目中使用这个技能,就把 doc-coauthoring 文件夹放到项目根目录下的 .claude/skills/ 目录中。如果你希望在所有项目中都能使用,就放到用户主目录下的 ~/.claude/skills/ 目录。

放置完成后,重启 Claude Code 或者重新加载项目,技能包就安装好了。你可以在 Claude 的技能列表中看到 doc-coauthoring 已经可用。

如何触发这个技能

doc-coauthoring 技能包的触发非常自然。当你在与 Claude 对话时,只要提到与文档写作相关的关键词,它就会主动询问你是否需要使用结构化工作流。具体来说,以下这些场景都会触发技能:

你可以直接说"我想写一个技术方案文档"、"帮我起草一份项目提案"、"需要创建一个设计文档"。或者提到具体的文档类型,比如"写个PRD"、"做个RFC"、"整理一份决策文档(decision doc)"。只要 Claude 检测到你在启动一个实质性的文档写作任务,它就会弹出提示。

Claude 会向你介绍这个三阶段工作流,并询问:"你想试试这个结构化的协作方式,还是更喜欢自由发挥?"如果你选择接受,工作流就正式开始了。

三阶段工作流详解

第一阶段是上下文收集。Claude 会像一个专业的采访者,先问你一些元信息:这是什么类型的文档?目标读者是谁?你希望读者看完后有什么反应?有没有固定的模板要遵循?有什么特殊的限制条件?

回答完这些问题后,Claude 会鼓励你"倾倒"所有相关信息——项目背景、团队讨论记录、为什么不选其他方案、组织内部的政治因素、时间压力、技术架构、利益相关者的顾虑等等。你不用担心组织得乱七八糟,想到什么说什么就行。

如果你的 Claude 环境配置了集成工具(比如 Slack、Google Drive、SharePoint 等),Claude 还可以直接读取你提到的团队频道消息或共享文档,自动拉取上下文。如果没有配置集成,Claude 会提示你可以在设置中启用连接器,或者直接把相关内容粘贴过来。

第二阶段是内容打磨与结构化。有了充足的上下文后,Claude 会和你一起逐节构建文档。它会先帮你梳理大纲,然后针对每个章节进行头脑风暴,提出多种写作角度,再根据你的反馈迭代打磨。这个过程是高度互动的,你可以随时调整方向、补充信息、修改表达。

第三阶段是读者测试,也是最独特的部分。Claude 会建议你开启一个全新的对话窗口,把文档粘贴给一个"零背景"的 Claude,让它扮演目标读者的角色。这个新 Claude 会指出哪些地方看不懂、哪些逻辑跳跃太大、哪些术语没有解释。这就像是在真实发布前做了一次"盲审",能发现很多你自己意识不到的问题。

完整实操案例:从零到一写技术方案

让我们通过一个完整的例子,看看如何使用 doc-coauthoring 技能包写一份技术方案文档。

假设你刚刚完成技能包的安装,现在打开 Claude Code,在对话框中输入:"我需要写一个关于用户认证系统重构的技术方案。"

Claude 立即响应:"我注意到你要写一份技术方案文档。我可以提供一个结构化的协作工作流,分为三个阶段:上下文收集、内容打磨、读者测试。这个流程能帮助确保文档对读者友好,甚至当别人把它粘贴给 Claude 时也能理解。你想试试这个工作流,还是更喜欢自由发挥?"

你回复:"试试工作流吧。"

阶段一:上下文收集

Claude 开始提问:

• "这是什么类型的文档?技术设计文档、决策文档,还是实施方案?"• "主要读者是谁?技术团队、产品经理,还是管理层?"• "你希望读者看完后做什么?批准方案、提供反馈,还是开始实施?"• "有没有公司的技术方案模板要遵循?"• "还有其他限制或背景信息吗?"

你简短回答:"技术设计文档,给技术团队看的,希望他们理解方案并开始实施。没有固定模板,但需要在三个月内完成。"

Claude 说:"好的,现在请把所有相关信息都告诉我,不用担心组织得是否完美。比如:为什么要重构?现有系统有什么问题?为什么不用其他方案?有没有相关的团队讨论?时间和资源限制是什么?"

你开始"倾倒"信息:"现在的认证系统是五年前的老代码,用的是自己实现的 JWT,有安全漏洞。上个月被安全团队点名了。我们考虑过用 Auth0,但成本太高。团队在 Slack 的 #security 频道讨论过,大家倾向于迁移到 OAuth 2.0 标准实现。技术栈是 Node.js,数据库是 PostgreSQL。三个月的时间是因为下个季度要过合规审计..."

如果你配置了 Slack 集成,Claude 会说:"我可以读取 #security 频道的讨论记录吗?"得到你的同意后,它会自动拉取相关消息,补充更多上下文。

阶段二:内容打磨

上下文收集完成后,Claude 提出一个文档大纲: 1. 背景与问题陈述 2. 现有系统分析 3. 方案对比(自研 vs Auth0 vs OAuth 2.0标准库) 4. 推荐方案详细设计 5. 实施计划与里程碑 6. 风险与缓解措施

你说:"大纲看起来不错,开始写吧。"

Claude 逐节与你协作。在写"方案对比"时,它会问:"你想强调哪些对比维度?成本、安全性、维护难度、迁移风险?" 你说:"主要是成本和安全性。" Claude 就会生成一个对比表格,然后问你:"这个表格准确吗?需要调整哪些数据?"

经过几轮迭代,文档初稿完成了。

阶段三:读者测试

Claude 建议:"现在让我们测试一下这份文档对读者是否友好。请开启一个新的 Claude 对话窗口,把文档粘贴进去,然后问它:'请阅读这份技术方案,告诉我哪些地方不清楚。'"

你照做了。新的 Claude(没有任何之前的上下文)回复:"我对以下几点有疑问:1) 'JWT 安全漏洞'具体是什么漏洞?2) 为什么 Auth0 成本高?没有看到具体数字。3) '下个季度合规审计'是什么审计?为什么影响时间线?"

你回到原来的对话窗口,把这些反馈告诉 Claude。Claude 说:"看来我们需要补充这些细节。让我们在'现有系统分析'中加一段具体说明 JWT 漏洞,在'方案对比'中加上 Auth0 的成本数据,在'实施计划'中解释合规审计的背景。"

修改完成后,你再次用新 Claude 测试,这次它说:"文档很清晰,我理解了整个方案的来龙去脉。"

大功告成!你的技术方案文档不仅内容扎实,而且对读者极其友好。当你把它发给团队时,几乎没有人提出"看不懂"的问题,大家直接进入实质性讨论。

通过这个完整的流程,你可以看到 doc-coauthoring 技能包的核心价值:它不是简单地帮你生成文字,而是引导你完成一个系统化的思考和验证过程。上下文收集确保信息完整,内容打磨确保表达清晰,读者测试确保真正可读。这三个阶段环环相扣,最终产出的文档质量远超"一个人闷头写"的效果。

如果你经常需要写技术文档、产品提案、决策记录、RFC 等结构化内容,doc-coauthoring 绝对是你的效率神器。它就像给你配了一个专业的文档教练,全程陪伴,随时纠偏,最后还帮你做"盲测"。试试看,你会发现写文档不再是痛苦的独角戏,而是一场高效的协作舞蹈 💃

如果你觉得这个技能包有用,欢迎点赞、转发,让更多被文档写作折磨的朋友看到!也欢迎在评论区分享你的使用心得,或者提出你在文档写作中遇到的其他痛点,说不定下一个技能包就是为你量身定制的 😊

关注我,每天一个 Claude Skill,让 AI 成为你的超级助手!🚀