使用 Claude Code 撰写技术文档并配图的基础教程

使用 Claude Code 撰写技术文档并配图的基础教程

• 前置学习教程claude code
• 前置学习教程agent skills
• skills工具链接
• Claude Code安装教程

本教程面向熟悉命令行和基本开发工具的开发者，介绍如何利用 Claude Code 高效撰写技术文档，并使用 baoyu-article-illustrator 技能为文章智能配图。

前置准备

确保你已经：

• 安装并配置好 Claude Code CLI
• 拥有可用的 API 密钥
• 具备以下技能：
  • baoyu-article-illustrator（文章配图技能）
  • baoyu-image-gen（底层图片生成能力，被 article-illustrator 调用）

工具链关系

• baoyu-article-illustrator：分析文章结构，识别需要配图的位置，决定图片类型和风格
• baoyu-image-gen：执行实际的图片生成任务

第一部分：用 Claude Code 写技术文档

1.1 基本工作流程

Claude Code 写文档的核心优势在于它能够：

• 直接读取代码库理解上下文
• 根据代码自动生成准确的文档
• 保持文档与代码的一致性

启动方式：

# 在项目目录中启动 Claude Code
cd your-project
claude

1.2 常用文档撰写命令示例

为代码生成文档

请为 src/utils/auth.ts 文件生成 API 文档

创建项目 README

分析当前项目结构，帮我撰写一份 README.md，包含：
- 项目简介
- 安装步骤
- 使用示例
- 配置说明

撰写教程类文档

帮我写一篇关于 [主题] 的技术教程，目标读者是 [描述]，
重点讲解 [要点1]、[要点2]、[要点3]

1.3 提升文档质量的技巧

技巧	说明
提供上下文	告诉 Claude 目标读者是谁、技术水平如何
明确结构	预先说明你希望的文档结构（章节、格式）
迭代修改	生成后可以针对具体段落要求修改
结合代码	让 Claude 先读取相关代码再写文档

第二部分：使用 baoyu-article-illustrator 智能配图

2.1 技能简介

baoyu-article-illustrator 是一个智能文章配图技能，核心能力：

• 自动分析文章结构：识别标题、段落、关键概念
• 智能识别配图位置：判断哪些地方需要视觉辅助
• Type × Style 二维配图法：根据内容类型和期望风格生成最合适的图片
• 调用底层 baoyu-image-gen：实际图片生成由底层能力完成

2.2 基本使用方法

方式一：一键为文章配图（推荐）

/baoyu-article-illustrator

或者用自然语言：

为文章配图
请给这篇文章添加插图
illustrate article

方式二：指定文章路径

/baoyu-article-illustrator path/to/your-article.md

2.3 Type × Style 二维配图法

这是 baoyu-article-illustrator 的核心方法论：

维度	说明	示例
Type（类型）	图片要表达什么	概念图、流程图、场景图、对比图
Style（风格）	视觉呈现方式	扁平插画、3D渲染、手绘风、科技感

组合示例（以本教程为例）：

文章内容	Type	Style	配图效果
工具链关系	架构图	扁平插画	展示两个工具的调用关系
Type × Style 方法	概念图	信息图表	二维矩阵示意图
完整工作流	流程图	科技感	写作→配图→迭代的流程

2.4 文档配图的完整工作流（以本教程为例）

步骤 1: 撰写文档
────────────────────
你: 帮我写一篇用 Claude Code 写技术文档并配图的基础教程，
    面向有基础的开发者

Claude: [生成本教程内容...]

步骤 2: 智能配图（一条命令搞定）
────────────────────
你: /baoyu-article-illustrator

Claude:
  - 分析文章结构...
  - 识别到 4 处适合配图的位置：
    1. 开头：需要一张封面图（程序员与 AI 协作写作场景）
    2. "工具链关系"：需要架构示意图
    3. "Type × Style 二维配图法"：需要概念解释图
    4. "完整工作流"：需要流程图
  - 调用 baoyu-image-gen 生成图片...
  - 将图片插入文档对应位置

步骤 3: 微调（可选）
────────────────────
你: 封面图换成更有科技感的风格

Claude: [重新生成并替换...]

第三部分：实战示例（以本教程为例）

3.1 完整对话示例

以下是创作本教程的实际对话流程：

你: 帮我写一篇用 Claude Code 写技术文档，然后使用 baoyu-article-illustrator
    给文章配图的基础教程，面向有基础的开发者

Claude: 在开始写这篇教程之前，我想先确认几个问题...
        [询问目标读者、输出形式等]

你: 有基础的开发者，创建 Markdown 文件

Claude: [生成教程内容，创建 claude-code-writing-tutorial.md]

你: /baoyu-article-illustrator

Claude:
  分析文章结构完成，识别到以下配图位置：

  1. 文章封面 - Type: 主题图 | Style: 科技感
     描述：程序员在终端与 AI 协作撰写文档的场景

  2. "工具链关系" - Type: 架构图 | Style: 扁平插画
     描述：两个技能的调用关系示意图

  3. "Type × Style 二维配图法" - Type: 概念图 | Style: 信息图表
     描述：二维矩阵展示类型和风格的组合

  4. "完整工作流" - Type: 流程图 | Style: 简洁现代
     描述：写作→配图→迭代的三步流程

  开始生成图片...
  [调用 baoyu-image-gen 生成 4 张图片...]

  配图完成，已插入文档。

你: 封面图的背景换成深色科技风

Claude: [重新生成封面图并替换...]

3.2 配图类型参考

文章类型	推荐 Type	推荐 Style
技术教程	流程图、步骤图	扁平插画、信息图表
概念解释	概念图、类比图	简洁图示、手绘风
产品介绍	场景图、功能图	3D渲染、产品风
最佳实践	对比图、清单图	专业商务、简约风

3.3 过程图示

• 输入文章要求

claude "帮我写一篇用 Claude Code 写技术文档，然后使用 baoyu-article-illustrator给文章配图的基础教程，面向有基础的开发者"

• 开始规划配图

/baoyu-article-illustrator /Users/zhangjian/works/workspace_vibe/skills_md/write_article_with_cc/claude-code-writing-tutorial.md

• 文生图国产模型配置

注意原始的工具是不支持国产模型【默认支持OPENAI及GOOGLE的文生图模型】，这里我做了改造，增加了阿里云的【通义-文生图-Z-Image，单模型白嫖额度100张图片，如下图，还有其他模型，可以修改环境变量调整【~/.baoyu-skills/.env中增加DASHSCOPE_IMAGE_MODEL=z-image-turbo】】支持改造后代码【分支 my-baoyu-skills】 注意PR已合并，直接安装最新版即可。

1. 替换生图技能【baoyu-image-gen】中的文件内容【这里也可以手动直接安装我fork过来的版本，修改内容已提交】
2. 新增阿里云模型配置apikey 创建用户环境变量

mkdir ~/.baoyu-skills

增加apikey配置【在~/.baoyu-skills】目录下创建.env文件内容如下【对应的api key从阿里云百炼平台获取】：

#指定模型
DASHSCOPE_IMAGE_MODEL=z-image-turbo
#指定api key
DASHSCOPE_API_KEY=sk-xxxxxxxxxxx

4. 图片prompt生成

baoyu-article-illustrator会根据文章内容进行分析然后生成插图规划，然后根据规划生成对应的文生图prompt 5. prompt生成后会调用baoyu-image-gen按照规划的图片prompt进行图片生成

6. 生产完成后会将图片插入预定的位置

7. 注意：有时候会未自动插入，干预提示一下即可，也可根据文件目录下的outline.md文件内容进行手动粘贴

8. 效果截图

常见问题

Q: baoyu-article-illustrator 和 baoyu-image-gen 有什么区别？

A: baoyu-article-illustrator 是面向用户的智能配图技能，会分析文章并决定在哪里配什么图；baoyu-image-gen 是底层的图片生成能力，被前者调用来实际生成图片。一般情况下，直接使用 baoyu-article-illustrator 即可。

Q: 生成的图片保存在哪里？

A: 默认保存在当前工作目录或文章所在目录。

Q: 可以只为文章的某一部分配图吗？

A: 可以，在调用时指定具体位置，如："只为'工具链关系'这一节配图"。

Q: 如何修改已生成的图片风格？

A: 直接描述你的修改需求，如："把封面图换成 3D 风格"，Claude 会重新生成并替换。

Q: 支持哪些图片风格？

A: 支持扁平插画、3D渲染、手绘风、科技感、简约风、信息图表等多种风格，可根据文章调性自由选择。

总结

Claude Code + baoyu-article-illustrator 的组合让技术文档创作变得高效：

1. 写作阶段：利用 Claude 对代码的理解能力，生成准确的技术文档
2. 配图阶段：一条命令智能分析 + 自动配图，无需手动指定每张图
3. 迭代优化：在对话中持续调整，直到满意为止

工具链优势：

• baoyu-article-illustrator 负责"思考"：分析文章、决定配图策略
• baoyu-image-gen 负责"执行"：生成高质量图片

掌握这套工作流，可以大幅提升技术文档的创作效率和视觉质量。

附录

更多工具请参考源

---