企业官网建设流程全解析

Claude Code 火起来之后，我身边几乎所有人都在折腾 Agent——让模型自己规划、自己调工具、自己跑完整个流程。Anthropic 放出官方 Skills 仓库那会儿，我一开始也没太当回事：一堆 Markdown 指令文件而已，能有多厉害？直到我把 document-skills 目录里的 coauthoring 技能翻完，并且老老实实用它跑了一篇两万字左右的技术方案之后，我的看法彻底变了。这个 skill 解决的不是"写什么"，而是"怎么写才能不翻车"——它把长文档写作这个看似靠灵感的活儿，拆成了可恢复、可审校、可迭代的工程流程。这篇就围绕 doc-coauthoring 这个官方技能，聊聊它的核心原理、接入方式，以及我实测下来的体会和踩过的坑。适合正在用 Claude Code、经常写长文档、或者想搞明白官方 Skill 到底怎么用的人。

1. 为什么官方技能仓库里，我先盯上的是 coauthoring

1.1 Skills 到底是什么：先和 Agent 划清界限

很多人把 Skill 和 Agent 混为一谈。搜索热词里常年挂着"skill和agent的区别"，这里我先给出一个尽量简单的说法：

• Agent 是一个拥有工具、可以自主循环执行任务的"执行体"，它会自己拆解目标、调用工具、检查结果；
• Skill 是一份"操作手册"或"专业打法"，它不会自动跑起来，而是被 Claude 在合适的时机加载，用来规范某类任务该怎么做。

一句话：Agent 负责"自己去干"，Skill 负责"教它怎么干得专业"。两者不冲突。Claude Code 里跑着的 Agent 骨架，加上 coauthoring 这份 skill，就等于一个"懂长文档写作规范的 Agent"。

Claude Code 加载 skill 的路径一般是自动发现：把 skill 目录放进~/.claude/skills（个人全局）或.claude/skills（当前项目），描述信息匹配到用户请求时就会触发。doc-coauthoring 在官方仓库里对应document-skills/coauthoring，是官方文档类技能中的一员。

1.2 它解决的问题：长文档不是"长提示词"

我见过太多人让 Claude 写长文的方式：把需求一股脑塞进一条提示词，然后期待模型吐出一篇完整的万字文档。结果往往分成三种：写到一半开始车轱辘话来回说；前后章节口径不一致；或者被上下文窗口掐断，后半段完全是空壳。

doc-coauthoring 的全部设计，都在对抗同一个物理现实：上下文窗口是有限的，而长文档的信息量超过了窗口容量。"一次性写太长"注定失败，那就把它切成"恰好能装进上下文"的块，一块一块写，再靠外部状态把块与块之间衔接起来。这就是它最核心的工程思想。

2. 拆解核心机制：把文档本身变成"记忆体"

2.1 分块生成：chunk 不是简单分段

官方这套分块流程，第一步不是"开始写"，而是"理解文档结构"。Claude 会先摸清目标文档的标题层级、已有段落、缺失部分，然后给出分块计划。每个块有独立编号和语义目标，例如"块1：问题背景与术语定义""块2：架构总览"。

分块的标准有几个关键约束：

• 单个块的字数要控制在当前上下文能从容处理的范围。官方参考文档里强调的是"一个块 + 已产出的摘要 + 工作指令"三者的总和不能撑爆窗口；
• 块之间要有清晰的边界锚点，最常见的做法是围绕标题（Heading）切分，让每一块对应一个可独立审校的单元；
• 每个块被标记为pending（待写）、in_progress（写作中）、complete（完成）三种状态。

块状态不是写完之后就扔掉。每块完成后，Claude 会生成一段摘要写进一个"清单"里。后面任何一个块开写之前，Claude 都先读这份清单，保证后写的部分知道前面定过的口径、术语和结论。

2.2 用 XML 上下文块做状态管理

这个设计是整份 skill 里最巧妙的地方。为了让状态可以跨会话存活，coauthoring 把一份结构化的流程状态直接嵌进文档自身（通常是文档末尾的一个 XML 区域），我把它称为"上下文块"。它的样子大致如下：

<ctx> <phase>writing</phase> <plan> <item id="p1">梳理大纲，确定六个主要章节</item> <item id="p2">为每章建立 chunk 注册信息</item> <item id="p3">逐块写作并同步审校</item> </plan> <manifest> <chunk id="1" title="概述与背景" status="complete" summary="定义问题为X，约束条件为Y-Z；术语表第一版包含W=N等三条" /> <chunk id="2" title="架构总览" status="complete" summary="采用三层架构；模块A与模块B通过接口C通信，边界在D处" /> <chunk id="3" title="核心实现" status="in_progress" summary="" /> </manifest> <active_doc id="local:/docs/guide.md" /> </ctx>

为什么要用 XML 而不是普通文字？原因很实际：Claude 生成 XML 这类严格语法的格式远比生成自由文本可靠，解析也明确；XML 区块可以整个覆盖更新，不容易把前面的正文搅乱；而且文档保存一次，状态就保存一次，不需要额外的数据库或记忆文件。

这对"写长文写一半断掉"的场景非常友好：就算会话上下文耗尽，重新开一个新会话，Claude 读一遍文档尾部的 ctx 区块，就能准确知道写到哪里、哪些块完成了、哪些没写，然后接着干。这种"文档即状态"的思路，比任何外置记忆方案都简单直接，也更容易被用户检查和干预。

2.3 渐进式摘要：让后面的块永远知道前面写了什么

分块之后最大的敌人是断裂感：每个块都是独立生成的，如果不做衔接，合出来的文档完全不像一个人写的。coauthoring 的做法是"渐进式摘要"。每个块完成后，Claude 用两三句话概括这一块的实质内容，摘要必须包含具体锚点——人名、名词、决策、数字、术语定义，而不是"本章介绍了相关背景"这种废话。

我自己的体验是：摘要的质量直接决定后半程文档的质量。摘要具体，后面的块才能引用前面块里定义过的概念，不会出现前面叫"订单模块"、后面写成"销售模块"这类尴尬；摘要抽象，后面基本就是各写各的。这也是我后面要专门讲的一条经验。

3. 两种写作模式：Google Docs 与本地文件

3.1 Google Docs 模式：为协作场景设计

据官方仓库的说明，coauthoring 在设计上考虑了对 Google Docs 的对接。比较典型的场景是：文档本身托管在 Google Docs 上，Claude 借助 Google Docs 的接口能力读取正文结构、按计划分块、再把写好的内容同步回去。因为分块流程天然支持"一次只提交一个块的改动"，多人协作时其他人能实时看到文档推进，Claude 的修改也有清晰的块边界可追踪。

搭这种模式需要把 Google Docs 的访问权限配好（OAuth 或者对应的集成工具）。就我了解，不少人是在自己的自动化环境中封了一层 Google Docs API 调用，然后把 coauthoring 的分块清单当成中间数据来驱动。这个方向适合"文档需要在线上协作、最终交付物就是 Google Docs 本身"的团队。具体接口细节不同版本可能会有调整，建议以官方仓库当前代码为准。

3.2 本地文件模式：Claude Code 场景下的主战场

对我来说，用得最多的反而是本地文件模式。文档就是一个 markdown 文件，直接放在项目目录里；Claude Code 读文件、写文件、更新文件尾部 ctx 区块，全都在本地完成。好处是零额外配置，而且一切变更都能用 git 追踪。

本地模式下整个流程非常顺滑：

1. 给 Claude 一份大纲或半成品文档；
2. Claude 读取结构，输出分块计划并写入 ctx；
3. 逐块写作，每完成一块就更新 manifest 摘要；
4. 你随时可以打断，说"块 3 重写"或"块 5 再补一段"，它只动对应块，不碰其他内容。

这种"本地文件 + 尾部状态区"的组合，实际上是把复杂的文档协同变成了版本控制里的常规操作：diff、review、合入主干。我很推荐团队内部做技术方案、产品需求、甚至知识库长文时用这套组合。

4. 和"一次性丢给 Claude"相比，实测差距在哪

4.1 三个维度上的直观对比

我自己做过的对照实验不算太严谨，但结论足够有说服力。同一份两万字左右的技术方案，分成"一次性生成"和"coauthoring 分块"两种方式，差距集中在几个维度：

还有一个容易被忽略的点：成本。一次性生成长文时，模型为了保持"记得前面写了什么"，会在上下文里反复回看全文，token 消耗指数级上升；分块后每块的上下文只有"摘要 + 当前块 + 指令"，token 消耗线性可控。写两万字的时候，这个差异能明显体现在账单上。

4.2 什么时候不该用它

任何工具都有边界，coauthoring 也不是万能的。我自己的判断标准如下：

• 文档小于三四页：分块的上下文维护开销反而大于收益，直接写更干净；
• 需要极度口语化、私人化的内容（比如一封短信、一条朋友圈文案）：不需要工程化流程；
• 处于头脑风暴阶段：思路可能随时推翻，硬套 chunk 清单只会拖慢节奏；
• 你本身没有审校的意愿：coauthoring 强调 "co"（协作者），它默认你会逐块参与修改，而不是交出去就完事。

换句话说，这是一把给"认真写长东西的人"准备的螺丝刀，不是给所有写作场景准备的万能锤子。

5. 接入实操：从拉仓库到跑通一次长文协作

5.1 获取技能并装进 Claude Code

第一步还是去官方仓库拿代码，命令很直接：

git clone https://github.com/anthropics/skills.git mkdir -p .claude/skills cp -r skills/document-skills/coauthoring .claude/skills/

如果你的项目已经初始化过，也可以放在用户级目录，让所有项目都能用：

mkdir -p ~/.claude/skills cp -r skills/document-skills/coauthoring ~/.claude/skills/

Claude Code 会自动发现项目目录.claude/skills和用户目录~/.claude/skills下的技能。装好后开一个新会话，直接说"用 coauthoring 技能帮我把这份大纲扩写成完整文档，目标两万字"，只要请求内容和技能描述匹配，它就会进入分块协作流程。

如果你发现没有自动触发，别慌。一个很实用的兜底办法是在提示里点名技能名称，例如："请加载 coauthoring 技能，进入长文档协作模式"。

5.2 一次典型会话的完整流程

我拿最近一次写技术方案的经历为例，把整个流程还原一下：

1. 我丢了一份只有三级标题的空大纲给 Claude，要求最终产出约 15000 字；
2. Claude 先回传"文档结构分析"，把大纲里的章节数量、每章预计体量、需要补充的缺失小节列出来，并给出分块计划（约 12 个块）；
3. 我确认计划后，它把 ctx 区块写进文档尾部，开始写块 1；
4. 每写完一块，它会短暂停下，把摘要更新进 manifest，然后继续写下一块；
5. 写到第 5 块时我觉得某处口径不对，直接说"块 3 里的术语定义要改"，它定位到块 3 重写，随后把块 4 以后涉及的引用顺带更新。

整个流程最舒服的一点是"可打断"。以前我让模型写长文，最怕中途改需求，一改就是全文重来；分块之后，改动被限制在一个块内部，成本肉眼可见地小。

5.3 顺带学会：照着官方 skill 自己写一个

如果你在搜索"skill 怎么编写"，那 coauthoring 本身就是一份很值得仿写的范例。一个标准 skill 的三要素：

• SKILL.md 的 YAML 头部：name给技能起名；description是触发判断的依据，要写清楚"何时该用、用在什么任务上"，太含糊会导致该触发时不触发；
• 正文指令：按步骤描述工作流，比如"先分析结构→再生成计划→再分块写作"；
• 参考文件：把细节较多的规则（比如分块大小的判断标准、摘要写法规范）放进 reference 目录，按需加载，避免占用主指令的篇幅。

我自己后来给团队写过内部写作规范 skill，骨架完全是从 coauthoring 学来的。有一点特别值得说：description 写得越具体，触发越准确。别写"帮助写文档"这种话，要写"用于超过 5000 字的长文档协作写作，支持分块、审校、断点续写"这种带条件、带能力边界的描述。

6. 我踩过的坑和几条使起来才懂的规矩

6.1 摘要写得太抽象，等于白写

第一次用的时候，我发现块 3 写完后 manifest 里只有一句话："本章介绍了系统设计。"结果块 7 开写时，它完全不知道前面定了什么表名、什么接口名，直接造了一套新名词。后来我强制要求摘要里必须包含三类信息：关键实体（名字/编号）、关键决策（选了 A 没选 B 的原因）、关键口径（术语定义和边界）。

好的摘要长这样："块3 定义订单状态机包含 pending/paid/cancelled 三态，取消订单不触发退款流程，退款仅通过 refund API 处理；术语'订单模块'统称 order-service。" 坏摘要就是那句"本章介绍了系统设计"。这条经验同样适用于你自己写任何 skill 或长流程 Agent 的中间状态设计。

6.2 块大小、计划粒度、审校节奏

三个参数我实测下来的推荐值：

• 块大小：技术文档 500-1200 字/块比较稳；叙事类或偏总结的内容可以放到 1500 字左右。太大了上下文压力重新出现，太小了清单本身喧宾夺主；
• 计划粒度：不要一次性规划 30 个块。先规划 5-8 个块，产出部分内容后让模型基于新情况重新拆后续。文档是生长的，不是浇筑的；
• 审校节奏：不要攒到全部写完再慢慢看。每 2-3 个块就把当前文档拉出来通读一遍，有问题立刻改。这个节奏下 ctx 区块里的状态永远和你的意图保持同步。

顺带一提，如果你和我一样用 git 管理文档，可以留意一下：块 3 完成后的那份提交信息，直接写"chunk3: 订单状态机 + 术语表"，比"update doc"好一百倍。这是流程带来的额外好处。

6.3 几个使起来才懂的通用技巧

最后分享几条零散的实操技巧，都是我反复用之后沉淀下来的：

1. 术语表可以放进 manifest 前面的固定位置，每写一个块顺带更新，长文档的一致性会非常扎实；
2. 文档尾部的 ctx 区块是"命根子"，任何自动化工具都不要去动它；如果你自己写脚本合并文档，务必备份好 ctx 再操作；
3. 如果文档本身非常长（比如几万字），可以把 manifest 里已完成块的 summary 再做一个"总摘要"压缩到极简，防止 ctx 区块自身越来越臃肿；
4. 在 Claude Code 里，如果技能没有自动触发，除了点名之外，还可以检查一下当前目录的权限设置——有时候是权限拦住了技能目录的读取。

按我个人的经验，真正要评估一个技能值不值得用，就看它能不能让你"写到一半敢停下来"。coauthoring 做到了。我不太确定它对所有人都是最优解，但对经常和长文档、大方案打交道的人来说，这个官方技能至少提供了一条比"硬背上下文"可靠得多的路。如果你也正被长文写作的一致性问题折磨，不妨照着上面的流程跑一遍，再根据自己的节奏调整块的大小和摘要的写法。