Software 2.0

用 Claude Skills进行技术写作

admin -

作为一名开发者倡导者，我一直面临一个挑战：如何保持高质量的技术文档，使其在技术准确性、写作质量和格式上都保持一致，并与最新的更新保持一致？最近，我发现了使用 Claude Code 的子代理和代理技能的一种强大方法，这改变了我的工作流程。

1、挑战：更新一篇复杂的 技术文章

我最近需要更新我在 ADK 官方文檔網站 上撰写的文章 使用 ADK Bidi-streaming 的自定义音频流应用：

这不仅仅是修复几个拼写错误——我想：

  • 提高写作质量和一致性
  • 确保代码示例遵循最佳实践
  • 验证技术一致性与最新 SDK 实现

这个看似简单的任务揭示了高质量技术写作的核心挑战。

2、高质量技术写作的挑战

创建优秀的技术文档需要多层专业知识：

  1. 专业编辑：一致的写作风格、正确的语法、清晰的结构和适当的交叉引用
  2. 代码审查：格式良好的代码片段，一致的编码实践和适当的错误处理
  3. 主题专家知识：对所记录技术的深入了解——在本例中，是以下内容的源级理解：

传统上，你需要多个评审人员——编辑、代码评审员和主题专家（SME）——才能达到这种质量水平。但如果你能使用 AI 结合三者呢？

3、解决方案：Claude Code 子代理和代理技能

Claude Code 提供了两个强大的功能，可以作为你的专家评审：

3.1 什么是 Claude Code 子代理？

子代理 是你可以配置执行特定任务的专用 AI 助手。你可以在项目中的配置文件中定义它们的专业领域、工具和行为。

3.2 什么是代理技能？

代理技能 为子代理提供对特定知识库的访问权限，如文档、源代码或 API 参考资料。这使它们对你的技术栈有深入、上下文相关的理解。

4、我的策略

我创建了两个专门的子代理：

docs-reviewer

  • 角色：专业编辑和代码评审员
  • 职责：确保一致的写作风格、正确的文档结构和代码质量

adk-reviewer

  • 角色：ADK 主题专家
  • 配备三个代理技能：google-adk 以访问 ADK 源代码，gemini-live-api 以访问 Gemini Live API 文档，以及 vertexai-live-api 以访问 Vertex AI Live API 文档
  • 详见：使用 Claude Code 技能加速 ADK 开发

提示：为了简化计费并利用 Google Cloud 的基础设施，我使用了 Vertex AI 上的 Claude。此集成允许我在保持与现有 Google Cloud 计费整合的同时使用 Claude Code。

4.1 定义 docs-reviewer 子代理

docs-reviewer 子代理被配置为高级文档评审员。这是其代理定义中的一个片段，展示了它的核心能力（请参阅 docs-reviewer.md 获取完整定义）：

# 你的角色  

你是一个高级文档评审员，确保所有文档部分保持一致的结构、风格、格式和代码质量。你的目标是创造一个无缝的阅读体验，让用户可以在所有文档中导航而不会遇到组织、写作风格或代码示例方面的不协调问题。  

## 当被调用时  

1. 读取 docs 目录下的所有文档文件并理解上下文  
2. 根据下面的 Review Checklist 审查目标文档  
3. 输出并保存名为 `docs_review_report_<target>_<timestamp>.md` 的文档评审报告

该代理有一个全面的评审清单，涵盖：

  • 结构和组织：一致的标题层次、部分顺序和文档类型
  • 写作风格：主动语态、现在时态、一致的术语和适当的交叉引用
  • 代码质量：正确的格式、注释哲学和示例一致性
  • 表格格式：对齐规则和单元格内容标准

评审报告将发现分类为：

  • 严重问题 (C1, C2, …)：必须修复 —— 严重影响可读性或正确性
  • 警告 (W1, W2, …)：应该修复 —— 影响一致性和质量
  • 建议 (S1, S2, …)：考虑改进 —— 将提高质量

4.2 定义 adk-reviewer 子代理

adk-reviewer 子代理通过代理技能配备了专业知识。这是它的代理定义（请参阅 adk-reviewer.md 获取完整定义）：

# 你的角色  

你是一个高级代码和文档评审员，确保目标代码或文档与最新的 ADK 源代码和文档保持一致，并了解 ADK 如何内部使用和封装 Gemini Live API 和 Vertex AI Live API 特性。  

## 当被调用时  

1. 使用 google-adk、gemini-live-api 和 vertexai-live-api 技能学习 ADK，  
   并了解 ADK 如何内部使用和封装 Gemini Live API 和 Vertex AI  
   Live API 特性。  
2. 根据下面的 Review Checklist 审查目标代码或文档。  
3. 输出并保存名为 `adk_review_report_<target>_<timestamp>.md` 的评审报告

关键的评审原则是：

  • 源代码验证：代理会调查实际的 adk-python 实现以验证问题，而不是仅仅依赖 API 文档
  • 最新设计一致性：确保代码和文档与最新的 ADK 设计意图一致
  • 功能完整性：识别缺失的重要 ADK 功能
  • 深度 API 理解：知道 ADK 如何封装和使用 Gemini Live API 和 Vertex AI Live API 内部

这种方法之所以强大，是因为代理可以参考实际源代码来捕捉像过时参数、API 变化和实现细节这样的问题，这些可能从文档中并不明显。

5、审核过程的实际操作

让我带你走过这些子代理如何改变我的文章审核过程。

5.1 使用 docs-reviewer 代理进行文档审核

我运行了 docs-reviewer 代理在我的文章上，它产生了 一份全面的审核报告，指出了在一致性、写作和代码质量方面跨多个领域的严重和警告级别问题：

有了这份报告，我开始了一个与 Claude Code 的交互式审核过程，我逐一查看每个问题，理解代理提出的问题和可能的修复方法，并决定如何修复它（或者如果我认为适当的话跳过）。

以下是交互式修复过程的一些例子：

  • 示例 1：修复不完整的导入

在这个问题中，代理指出了一个代码质量问题。C2 表示它是第 2 个严重问题。

由于我同意这一评估，我输入了这个提示给 Claude Code：

我的提示：

修复 C2

Claude Code 响应：

我只是输入了这两个词，Claude Code 就处理好了。当然，我审查了结果以再次检查并避免幻觉的风险。

让我们看看另一个文档审核问题的例子。

  • 示例 2：修复不一致的标题级别

在这个问题中，代理指出了一个文本格式问题。W1 表示它是第一个警告问题。

这是编码代理真正擅长自动修复的典型问题：语义文本编辑。它就像一个完全理解内容含义的文本编辑器，所以你可以询问如何进行语义编辑文本。在这种情况下，“使用 #### 作为函数/代码示例标题”的建议代表了语义文本编辑的绝佳例子。

我的提示：

修复 W1

Claude Code 响应：

  • 其他文档审核示例

docs-reviewer 代理在文章中总共发现了 25 个问题。以下是主要发现的摘要：

严重问题 (5):

  • C1: 代码与文本中模型名称不一致 —— 混合使用 gemini-2.0-flash-exp 和 gemini-2.0-flash-live-001
  • C2: 会话恢复部分中不完整的导入
  • C3: 错误的函数引用 —— 使用 InMemoryRunner 而不是 Runner
  • C4: 缺失的函数定义和初始化上下文
  • C5: 代码注释中的拼写错误（“parial” 应为 “partial”）

警告 (12):

  • W1: 不一致的标题级别结构
  • W2: 不一致的代码注释风格
  • W3: 缺少交叉引用
  • W4: 不一致的表格格式
  • W5: 不清楚的部分目的（会话恢复放置）
  • W6: 不一致的术语（app 与 application，agent 与 ADK agent）
  • W7: 缺少错误处理解释
  • W8: 包含未定义变量的不完整示例代码
  • W9: 不一致的代码块语言标签
  • W10: 缺少先决条件部分
  • W11: 头部中的模糊编号
  • W12: 不一致的列表格式

建议 (8):

  • 添加视觉架构图
  • 添加完整的可运行示例
  • 改进故障排除部分
  • 添加生产部署注意事项
  • 通过教学背景增强代码注释
  • 添加音频格式规范
  • 改进介绍
  • 添加最佳实践部分

在与 Claude Code 逐一处理每个问题后，我能够显著提高文章的文本和代码质量，在很短的时间内超越了原始版本。

5.2 使用 adk-reviewer 代理进行 ADK 审核

在对文本和代码质量有信心之后，我开始与另一个子代理 adk-reviewer 合作。配备对 ADK 内部的深入了解，它产生了 另一份审核报告，专注于 API 使用、技术准确性和与最新 ADK 发布的一致性。

让我们看看代理发现了哪些问题以及我们是如何修复它们的。

  • 示例 3：修复过时的 API 使用

在这个问题中，代理发现原始文章与最新 ADK 版本之间存在不一致：

session_id 参数现在是调用 run_live 的必填项，而 session 参数不再受支持。让我们让 Claude Code 来修复它。

我的提示：

修复 C1

Claude Code 响应：

令我印象最深的是 adk-reviewer 代理，它深入研究了 google-adk Python SDK 源代码并理解了设计意图和对象之间的复杂交互。它甚至了解 google-adk 如何通过与外部库（如 Gemini API 和 Vertex AI APIs）的交互来公开其功能。凭借这种专家视角，代理可以找到问题并推荐最佳修复选项。

  • 示例 4：深入探讨流媒体行为

就像拥有一个人类主题专家作为你的评审员一样，你也可以与 Claude Code 进行交互式的深入研究和讨论，以更好地理解基本问题并构建实用的解决方案。

在这个例子中，adk-reviewer 代理指出原始示例代码只使用了代理的部分（增量）文本，忽略了完整的文本：

按 Enter 或点击以全屏查看图片！

但我对此不确定。如果我们把所有带有 partial=True 的文本连接起来，是否与 partial=False 的文本完全相同？同时，我们不想丢失任何来自代理的文本。因此，我没有直接选择修复选项，而是开始与 Claude Code 进行讨论。

我的提示：

对于 W2，如果我将所有带有 partial=True 的文本连接起来，是否会与 partial=False 的文本完全相同？请使用 google-adk 技能进行检查。

如前所述，我已经在这台 Claude Code 上定义了 google-adk 技能，因此它可以访问 ADK Python SDK 源代码、Gemini Live API 文档和 Vertex AI Live API 文档。在上面的提示中，我明确要求使用该技能进行深入研究。

经过几分钟的研究，Claude Code 回复道：

Claude Code 响应：

现在我们确认了在 ADK 源代码层面，部分文本不会丢失任何来自代理的文本。

这是令人印象深刻的地方。通过这次互动会话，Claude Code 能够以更高的分辨率理解情况，并提供更深入的互动审核过程。

  • 其他 ADK 审核示例

adk-reviewer 代理总共发现了 6 个关于 ADK API 使用和最佳实践的问题。以下是所有发现的摘要：

严重问题 (1):

警告 (2):

  • W1: 缺少会话创建要求的解释 —— 不清楚何时需要会话创建，何时可选
  • W2: 音频流的不完整事件处理 —— 未处理完整的（非部分）文本事件

建议 (3):

  • S1: 为 WebSocket 断开添加错误处理 —— 在意外客户端断开时优雅地清理
  • S2: 更清晰地记录会话恢复配置 —— 何时使用它，何时跳过
  • S3: 添加有关 runner 生命周期管理的信息 —— runners 应该创建一次并重复使用，而不是每次连接都创建

代理对 ADK 内部的深入了解帮助它通过检查实际源代码并理解 ADK 如何封装 Gemini Live API 和 Vertex AI Live API 功能来识别这些问题。这种级别的分析很难在没有直接访问 SDK 实现的情况下实现。

6、关键收获

使用 Claude Code 子代理和代理技能来审核我的技术写作彻底改变了我的工作流程并带来了显著的结果：

  1. 专业评审团队：docs-reviewer 担任专业编辑和代码评审员，而 adk-reviewer 担任 ADK 主题专家。他们一起找到了 31 个问题（ADK 审核 6 个，文档审核 25 个），我原本可能会错过。
  2. 源级深入研究：代理技能使 adk-reviewer 能够直接访问 adk-python SDK 源代码、Gemini Live API 文档和 Vertex AI Live API 文档。这使它能够捕捉过时的 API 参数，理解实现细节，并验证文档中不明显的设计意图。
  3. 互动解决问题：不仅接受自动化修复，我还可以与 Claude Code 进行深入的技术讨论。例如，当对 W2 文本流问题不确定时，我要求它“使用 google-adk 技能进行检查”，并收到了对 ADK 源代码的详细分析，解释了当前方法实际上是正确的。
  4. 语义文本编辑：Claude Code 在理解内容背后的意义并应用语义更改方面表现出色。像“使用 #### 作为函数/代码示例标题”这样的任务在整个文档中执行得非常完美，手动完成会很繁琐且容易出错。

7、开始使用

想尝试这种方法用于你的技术写作吗？以下是开始的方法：

  1. 设置 Claude Code：安装 Claude Code 并为你的项目配置它
  2. 与 Vertex AI 集成（可选）：使用 Claude on Vertex AI 以简化计费
  3. 创建子代理：在 .claude/agents/ 中定义不同审核方面的专用代理 - 请参阅 Subagents 文档 和 示例代理定义
  4. 配置代理技能：在 .claude/skills/ 中添加相关文档和源代码作为技能 - 请参阅 Agent Skills 文档 和 示例技能定义

有关 ADK 开发与 Claude Code 技能的更多详情，请参阅我的前一篇文章：使用 Claude Code 技能加速 ADK 开发。

8、结束语

高质量的技术写作需要多个评审人员：一个编辑负责一致性，一个代码评审员负责质量，一个主题专家负责准确性。通过 Claude Code 的子代理和代理技能，我创建了这个整个评审团队。

两个代理 —— docs-reviewer 和 adk-reviewer —— 找到了我原本会错过的 31 个问题。它们不仅识别了问题；它们还引用了实际源代码并解释了推荐的原因。工作流程很简单：查看报告，输入“修复 C1”，然后 Claude Code 在完整上下文中应用修复。

这种方法增强了你的专业知识，而不是取代它。代理会捕捉你忽略的内容，并帮助你在写作中保持一致性。由于配置是版本控制的，你可以为每篇文章重复使用它们。

如果你撰写技术文档，尝试这种方法。设置投资每次你审核或创建内容时都会得到回报。

原文链接：Supercharge Your Tech Writing with Claude Code Subagents and Agent Skills

汇智网翻译整理，转载请标明出处