最佳实践

第一篇介绍了我的写作流程，第二篇讲怎样把它沉淀成可以持续使用的工作流。这一篇分享我在协作、审稿和维护内容时的具体做法，以及哪些判断仍需要作者亲自作出。

1. 与 AI 协作

1.1 借助 AI 充分发散，再围绕主题筛选

写作前期，可以让 AI 围绕一个初步想法，梳理相关概念、不同观点和容易忽略的边界情况。先尽量展开，再结合调研资料决定哪些内容值得写。

比如写 Rush monorepo 的「迁移已有仓库」一节时，AI 梳理出的内容除了渐进迁移、按依赖顺序推进，还包括迁移期间两套依赖环境如何避免互相影响、循环依赖如何处理、移除旧基建前需要检查哪些引用。这些问题我凭经验也能想到，但未必能一次列全。借助 AI 提前梳理，就更容易看清这个话题涉及哪些问题，以及哪些值得进一步调研。

内容梳理出来之后，再围绕自己想表达的主题做筛选：哪些能支撑核心观点，需要重点展开；哪些只需简要交代；哪些虽然相关，却不属于本篇讨论的范围，可以留到其他文章。前期尽量想全，成文时聚焦主题。

1.2 show me your prompt

我个人的观点是，AI 时代分享技术实践，应该 Prompt First，Prompt 的优先级高于代码。过去读技术文章，代码往往是最有用的知识载体：它把抽象的解释落成具体实现，读者可以运行、修改，再用到自己的项目里。而在分享 AI 辅助实践时，我更希望先看到生成这些代码的 Prompt，了解作者是怎样引导 AI 完成任务的。

一段好的 Prompt，包含了如何描述问题、提供哪些上下文、明确哪些约束，以及怎样判断结果是否合格。这些内容承载着解决问题的方法。读者替换自己的材料和目标，就能让 AI 按照这套方法工作，再根据实际情况调整。相比只拿到一份生成后的代码，拿到生成它的 Prompt，读者更容易理解作者如何拆解任务、如何引导 AI，也更容易把这份经验用到不同的项目里。

因此，介绍 AI 辅助开发或写作时，可复用的 Prompt 应该成为教学主体，代码则用于展示具体实现、验证结果。例如，分享如何让 AI 审稿，仅展示一篇改好的文章，读者很难知道修改依据；给出包含审查维度、判断标准和修改要求的 Prompt，读者才能把同样的方法用于自己的文章。

用 Prompt 的方式，授人以渔。

1.3 多 agents 交叉写作与审查

写一篇技术文章，调研、写作和审查关注的问题各不相同：调研要找到可靠的材料，写作要把观点讲清楚，审查则要核对论据、推理和表达。可以把能够独立完成的任务分给不同 agents，再由主写 agent 整合结果。

我目前的实践是：用 Codex 作为写作主力，用 Claude Code 核查事实，用 deepcode 检查中文表述。这些是我当前使用的工具与任务分工，可以根据题材、所用模型和实际效果调整。独立审查同一版稿件、汇总后统一改写的机制，见上一篇的多路审查部分。这里重点讲写作任务怎样拆分。

能够独立整理的资料、已有论点下的案例，以及边界清楚的章节草稿，可以同时推进。每项任务都应带上已确认的主题、大纲、素材和规范，明确负责范围与输出位置。章节之间若有前提依赖，就先确定前一节的判断，再展开后面的内容，不能为了并行各写一套定义。

可以用下面这段 Prompt，让主写 agent 安排写作分工：

请作为主写 agent，组织多个 agents 协作完成这篇文章。
先读取主题说明、已确认的大纲、素材和写作规范：<文件路径>。

1. 按大纲识别可独立完成的资料整理、案例补充和章节草稿任务。
   有前提依赖的任务按顺序推进，不为了并行拆开尚未确定的论证。
2. 为每项任务指定范围、输入材料和独立的输出文件，避免同时改同一份正文。
   各 agent 使用同一套术语和核心判断；需要调整大纲时，只提交建议及原因。
   事实和案例须有素材依据，缺少证据的标为待补。
3. 收齐结果后，由你整合正文，检查章节衔接、重复内容、术语和论据是否一致。
   涉及章节顺序、核心判断或讨论范围的变化，先交我确认。
4. 整合后进入现有 new-article 审查流程，沿用事实核查、评分和最多三轮的修订上限，
   通过后再交我人工审核，不另建一套审稿循环。

先检查所需工具是否可用，无法调用的如实说明，不以自查冒充其他工具的审核。

这样分工后，主写 agent 仍需负责全文的一致性。子任务完成，只说明各部分已有草稿；论证是否连贯、篇幅是否合适，要在合稿后沿着全文再检查。

2. 审稿与表达

2.1 去 AI 味，先结构后词句

刚开始用 AI 写作时，它的遣词造句总让我有一种强烈的不适感：这个词不自然，那个句式又像翻译过来的。于是，修改时的注意力几乎全放在词句上，总想先把这些别扭的表达改掉。后来写得多了才发现，表达结构是否合理，远比单个词句是否漂亮重要。词句不够自然，读者仍可能理解文章；但如果主次不清、推理断裂，甚至把意思表达错了，再精致的措辞也无济于事。

所以我认为，修改 AI 生成的文章，应先理顺结构，再润色词句。先看论述有没有主次、推理是否连贯、每段是否把意思讲清楚，再处理遣词造句。大纲里已经确定的重点，成文后仍可能被大量补充内容冲淡，因此结构检查也要贯穿到正文审核里。

具体审核时，可以先关注这些结构问题：

• AI 容易把有主从关系的内容写成并列。 一个观点、它的解释和例子，本来应该放在一起，却被拆成几个同级小节。因此，要检查各节之间的关系，把解释和例子归回对应观点下面，让读者看清哪些是主张，哪些是在支持主张。
• 篇幅分配不当也会掩盖重点。 次要背景写了好几段，核心判断却只有一句；或是每个点都展开得一样多，读者难以分辨主次。因此，要按内容与主题的关系重新分配篇幅：重点补足论据和推导，次要内容压缩，偏离主题的直接删除。
• 重复论述往往只是换了一套措辞。 这种重复既可能散落在不同章节，也可能挤在同一段里。例如，「每个阶段把结果存成文件」「下一步读取这些文件」「各阶段通过文件复用成果」，几句话没有增加多少信息。审核时要看每句话是否补充了新的事实、解释或推理，没有就合并或删除。
• 判断成立的条件没有交代清楚，就容易显得前后矛盾。 比如前面说「方案很轻量」，后面又说「实现成本很高」，却不解释区别。此时要核对两句话各自成立的条件：如果前者指使用方式、后者指建设成本，就把两个层面说清楚；如果确实冲突，就回到事实修正判断。

可以用下面这段 Prompt 检查和修改结构：

请阅读这篇文章，以及对应的主题说明、已确认的大纲和素材：<文件路径>。
先检查表达结构，暂不润色词句：
- 主次：是否把一个观点及其解释、例子拆成了同级小节？将支撑内容归回对应观点。
- 详略：是否次要内容展开过多、核心判断缺少解释？围绕主题调整篇幅，
  需要补充的论据只能来自现有素材，缺少依据的列为待补。
- 重复：逐节、逐段检查是否换着措辞重复同一判断，没有新信息的合并或删除。
- 矛盾：检查前后判断是否冲突；若只是适用条件不同，就补清条件，
  无法根据素材判断的单独列出，不自行猜测。

直接修改能确定的问题，保留文章主题和已确认的核心判断。
若涉及章节顺序、核心判断或讨论范围的变化，先列出建议及原因，交作者确认后再改。
完成后简要说明改动位置、理由和仍需作者判断的问题。

结构理顺后，再处理词句里常见的问题：

• AI 容易写出翻译腔，句子能读通，却不符合自然的中文表达。 比如「理解了 X，再看 Y 就顺了」「这也说明／这恰恰印证了」，有时只是多加了一句过渡，并没有解释两件事的关系。可以删掉这类过门，直接讲清 Y 是什么、为什么，或补上真正缺少的推理。
• AI 容易用情绪化措辞代替具体解释。 「不是白拿的」「这笔账得算清楚」看起来强调了代价，却没有说清代价是什么。修改时直接写出需要投入的时间、维护工作或适用限制，把没有信息量的提气删掉。
• AI 容易为了生动而堆比喻、造新词。 「给反熵地基浇混凝土」「拆墙／物理墙」这类表达，如果没有准确的技术对应，读者还得先猜比喻，再理解概念。应换回具体的技术表述，只有确实能降低理解难度的比喻才保留。

这里要删除的是没有信息量的词藻和重复强调。能够表达作者态度的措辞，例如「没有银弹！」这样的判断，或「我个人认为」这样的观点说明，都可以保留，不必为了去 AI 味把语气也一并删掉。

词句层面的修改，可以用这段 Prompt：

请阅读这篇文章、写作规范和作者范文：<文件路径>，修改不自然的中文表达。
保留已经确认的结构、观点、技术含义和引用，重点处理：
- 翻译腔：删掉没有信息量的过渡，改成自然的中文语序；
  如果问题是缺少推理，标出来，不要只换连接词掩盖它。
- 情绪化表达：把「不是白拿的」「这笔账得算清楚」等说法改成具体解释，
  没有依据可补充时，删除空泛强调，不编造数据或代价。
- 无意义的比喻和生造词：改回准确、易懂的技术表述。

发现一处问题时，检查全文是否还有同类表达，结合语境修改，不机械替换。
保留有信息量的个人态度、自然口语和有效比喻，不因某个标点或词语就判定有问题。
不要为了精简省掉必要的主语、条件和解释。改完给出几组有代表性的改前、改后对照。

这两类检查还可以补进上一篇的 new-article skill，让后续文章在交稿前自动执行。下面这段 Prompt 用于更新 skill：

请读取现有的 new-article skill：<skill 目录路径>，
将下面的写作与审稿要求整合进它的规则和执行流程。

审稿先处理结构，再处理词句。每次读取文章的主题说明、已确认的大纲、
素材、写作规范和作者范文（如有），按以下要求检查和修订。

结构检查：
- 主次：不要把一个观点及其解释、例子拆成同级小节，将支撑内容归回对应观点。
- 详略：围绕主题分配篇幅，压缩次要背景，补足核心判断的论据和推导，删除无关展开。
- 重复：跨章节、逐段检查同义重述，没有增加事实、解释或推理的句子合并或删除。
  例如，「保存各阶段结果」「下一步读取结果」「通过文件复用结果」，
  可以合并成「每个阶段将结果保存到文件，供下一步读取」。
- 矛盾：核对前后判断的适用条件。例如，「使用轻量」与「建设成本高」
  需要说明各自指什么；确实冲突的依据素材修正，无法判断的标为待确认。

词句检查：
- 翻译腔：改成自然的中文语序，删除没有信息量的过渡。
  例如，「理解了 X，再看 Y 就顺了」可以删去，直接解释 Y；
  如果缺少的是推理，就指出缺口，不靠替换连接词掩盖问题。
- 情绪化表达：将「不是白拿的」「这笔账得算清楚」等说法，
  改为有依据的具体代价；没有信息可补充时，删除空泛强调。
- 无意义的比喻和生造词：改回准确、易懂的技术表述。
  例如，「物理墙」若实际指模块边界约束，就直接写「模块边界约束」。

修改边界：
- 保留文章主题、已确认的核心判断、技术含义和引用。
  涉及章节顺序、核心判断或讨论范围的变化时，先列出建议和原因，交作者确认后再改。
- 补充事实和论据必须有素材依据，缺少证据的列为待补，不自行编造。
- 发现一处问题后检查全文同类表达，结合语境修改，不机械删词。
  保留有内容的个人态度、自然口语和有效比喻，不因标点或单个词语就判错。
- 不为精简省掉必要的主语、条件和解释。
  修订后简要记录改动位置、理由，以及仍需作者判断的问题。

请将这些要求落实到 skill 中：
1. references/writing-style.md：合并上述规则和正反例，已有同类规则不重复追加；
   有冲突的单独指出，不直接覆盖。
2. references/review-and-retry.md：加入先结构、后词句的审查顺序及修改边界，
   接入已有修订循环，保留事实核查、评分和修订轮次上限，不另建重复流程。
3. references/writing.md：引用这些规则，供初稿写作和后续修订使用。
4. 主 SKILL.md：补齐对应阶段读取上述 references 的说明。
如果现有文件命名不同，更新职责对应的文件，不新建一套平行规则。

本次只更新 skill 的规则和执行说明，不修改具体文章。
完成后列出修改了哪些文件、合并了哪些规则，方便我 review。

2.2 连贯性检查

上一节检查了主次、详略和重复，但即使每节内容都合适，读者也未必能顺着论述理解下去。还需要检查段落之间是否交代了必要的前提：概念有没有先解释，结论能否从前文推出，话题为什么在这里切换。

例如，上文只讲到「多个项目需要协作」，下文就开始介绍 Monorepo 的配置。读者还不知道协作中遇到了什么问题、为什么需要这种组织方式，就已经进入操作细节。此时需要补充的是选用 Monorepo 的理由，加一句「接下来，我们看看如何配置」并不能解决问题。

因此，审核时要站在目标读者的角度，沿着正文读一遍，检查读者在每个位置掌握的信息，是否足以理解接下来的内容。可以重点关注：

• 概念是否提前交代：一个术语或判断首次出现时，读者是否已经知道它指什么？必要的解释应放在使用之前，不能要求读者看完后文再回来理解。
• 推理是否有缺口：从前提到结论之间，是否省略了只有作者才知道的原因？缺少哪一步，就补哪一步，不能只靠「因此」「进一步来说」连接。
• 话题切换是否自然：下一段是在解释、举例，还是转向另一个问题？有关系的把关系说清楚，没有直接关系的就分开讨论，必要时调整顺序。

可以用下面这段 Prompt 做一次阅读连贯性检查：

请阅读这篇文章：<文章路径>，目标读者是：<知识背景>。
按正文顺序检查，只根据读者到当前位置已经获得的信息，判断能否理解后文。
重点找出：未经解释就使用的概念、缺少中间推理的结论，以及突然切换的话题。

每处指出具体位置，并说明：读者会在哪里卡住、缺少什么信息、应如何调整。
建议要具体到补充哪项解释、移动哪个段落，或将哪两个话题分开。
不要只建议添加连接词，也不要重复解释目标读者已经熟悉的常识。
先列问题和修改建议，不直接重写全文。

2.3 用样本建立自己的风格

前面的规则能帮助删除不自然的表达，却不能单独说明作者喜欢怎样写。想让 AI 写出自己的风格，还要给它看自己认可的样本。

提供几篇范文，以及「AI 原文 → 人工改后」的具体对照，AI 才能看到作者如何组织论证、分配详略、选择措辞。比如，同样是删掉一段背景，可能是因为读者已经熟悉，也可能是因为它与主题无关；把修改理由一起交代，后续才有可参考的判断依据。如何从这些样本中提炼规范、积累偏好，可以参考上一篇文章。

3. 作者的判断与责任

3.1 署名的内容必须亲自审核

AI 很容易把一份尚不完整的想法写成看起来已经成熟的文章。它会补背景、加例子、扩展结论，让上下文显得完整，但这些补充未必都有依据，也未必符合作者的原意。例如，素材只记录了某个项目的一次实践，正文却写成了普遍适用的建议；作者原本只想说「可以尝试」，成稿里却变成了「应该采用」。句子越流畅，这些变化越容易在快速浏览时被忽略。

事实核查和自动评分能帮助发现其中一部分问题，但很难替作者确认每个判断是否表达了自己的意思。某个建议即使技术上成立，也可能不适合本文的读者；一个例子即使真实，也未必足以支持紧接着的结论。读者看到的是作者署名的文章，其中的事实和判断，最终都需要作者负责。

因此，署名的内容必须亲自审核。交稿前逐段确认：新增的例子和数据是否有依据，结论有没有超出材料能支持的范围，措辞是否改变了原本的判断。遇到 AI 自行补充、自己又无法解释为什么成立的内容，就回到材料核实，补清条件，或者删掉。

3.2 保留自己的认知与品味

AI 生成的文章还有一种更难察觉的问题：各方面都谈到了，优缺点也列齐了，却看不出作者究竟想表达什么。它容易把不同观点并列展开，再补上一个四平八稳的总结。如果长期接受这样的成稿，写作就可能逐渐变成对现有说法的整理，最初那个值得讨论的疑问、来自实践的不同判断，反而被大量通用解释冲淡了。

文章是否有自己的见解，需要作者持续作出取舍。同样讨论一个技术方案，有人关心实现原理，有人更在意维护成本，也有人想解释它为什么在某些场景下失效。AI 可以提供这些角度，而作者需要根据自己的实践和理解，决定追问哪个问题、为哪个结论寻找论据。

因此，审稿时除了检查对错，还要回头问：这篇文章是否讲清了自己真正想说的观点？ 哪些段落只是因为 AI 写出来了才留下，哪些重要判断反而没有展开？如果 AI 提供了新的看法，可以核实、思考后吸收；如果它只是把原有观点改得更含糊、更面面俱到，就应重新明确重点。写作规范和范文能帮助复用过去的判断，但面对新的题材、变化后的认识，仍需要重新思考，不能把是否符合旧规则当成唯一标准。

4. 建立自己的博客

文章写完以后，还需要考虑在哪里发布、如何持续更新。我强烈建议有能力的同学，维护一个属于自己的博客站点。

以我的使用感受，公众号这类平台的阅读体验其实很差，尤其是阅读代码、查找系列文章、在相关内容之间跳转时，很难按自己的需要调整。它们能带来流量，但对技术写作来说，我更愿意把它们当作引流渠道，把完整、持续更新的内容放在自己的博客里。

过去，维护一个自己的站点需要投入不少精力：页面要写，功能要开发，还得处理部署发布和线上问题。如今，从编码、发布到线上运维，都可以借助 AI 完成，搭建和维护个人博客的成本已经低了很多。我自己就维护着一个个人博客：tecvan.fun。

个人博客的缺点是引流困难，需要通过其他渠道让读者发现它；但阅读体验完全可以做得很好。文章怎样排版、代码怎样展示、系列内容怎样组织，都可以按自己的想法设计，也可以随着读者反馈持续调整。配合 Git 管理正文、配图和示例，从写作、修改、版本记录到发布，就能形成一套连贯的流程。后续补充内容或修正错误，也可以直接在原稿上修改，再更新到站点。

这样的博客也可以成为一个长期展示自己的窗口。哪些问题值得讨论、如何分析技术方案、怎样组织内容和设计阅读体验，都在表达你的观点与品味。随着文章逐渐积累，读者不仅能找到某个问题的答案，也能通过这些内容持续了解你的思考。

如何借助 AI 搭建、发布和维护个人博客，我后面会单独写一篇。

5. 结语

这个系列就先写到这里。分享这些经验，是希望那些有想法、有实践，却迟迟没有动笔的同学，能借助 AI 把自己的思考写下来。可以从最近解决的一个问题、一次改变了看法的经历开始，不必等到所有东西都想明白了再写。写的过程本身，也会帮助我们发现新的问题、加深原有的理解。希望以后能读到更多来自真实实践、带着个人见解的文章，也期待与你交流。