# claude_code_guide

**Repository Path**: lingxiaobc/claude_code_guide

## Basic Information

- **Project Name**: claude_code_guide
- **Description**: 该项目用来编写claude code教程，可以迁移至其它教程的编写
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-22
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code 中文教程创作项目

> 一套基于 Claude Code 的中文教程创作系统——用 AI 辅助创作面向零基础用户的 Claude Code 中文教程。

## 项目简介

这个项目的目标是**系统地向零基础用户讲解 Claude Code**，让完全不懂技术的人也能学会用 Claude Code 处理自己的项目。

项目提供了一套完整的**教程创作流水线**，包含：

- 3 个自定义技能（Skill）：教程撰写、文章审查、封面图生成
- 3 个子代理（Subagent）：参考文档检索、上一篇教程读取、深度原理审查
- 1 份写作风格指南：确保文章风格统一，读起来像一个真实的人在说话
- 完整的排版规范和内容准确性校验流程

简单来说，你只需要告诉 Claude Code "帮我写一篇关于 XXX 的教程"，剩下的（查资料、衔接上下文、审查质量、生成封面）都会自动完成。

## 核心特色

- **零基础导向**：所有教程面向完全不懂技术的小白，每个概念都配有生活化比喻
- **知识可迁移**：不只是教操作，更教底层原理。把 Claude Code 换成别的工具，学到的知识依然有用
- **上下篇自动衔接**：通过子代理自动读取上一篇教程，确保系列文章前后连贯
- **官方文档对照**：撰写和审查时自动检索官方参考文档，确保内容准确
- **统一的写作风格**：口语化、有温度、有个人观点，读起来像真人在聊天，不像 AI 在输出

## 项目结构

```
claude_code_guide/
├── CLAUDE.md                              # 项目配置（排版规范、子代理调用规则）
├── README.md                              # 本文件
├── LICENSE                                # MIT 开源协议
├── 教程目录.md                             # 教程选题与进度规划（编写前必读）
│
├── claude_code使用教程/                     # 教程输出目录
│   ├── CLAUDE.md                          # 目录说明
│   └── <序号>-<教程名称>/                   # 每篇教程独立目录
│       ├── <教程名称>.md                   # 教程正文
│       └── image/                         # 教程配图
│
├── reference/                             # 官方参考资料（只读）
│   ├── CLAUDE.md                          # 目录说明
│   └── （放置官方文档供教程写作参考）
│
└── .claude/                               # Claude Code 配置
    ├── settings.json                      # 项目共享设置
    ├── settings.local.json                # 本地设置（API 密钥，不入版本控制）
    │
    ├── agents/                            # 子代理定义
    │   ├── reference-searcher.md          # 参考文档检索代理
    │   ├── prev-article-reader.md         # 上一篇教程读取代理
    │   └── review-depth.md               # 深度原理审查代理
    │
    ├── skills/                            # 技能定义
    │   ├── write-tutorial/                # 教程撰写技能
    │   │   └── SKILL.md
    │   ├── review-article/                # 文章审查技能
    │   │   └── SKILL.md
    │   └── cover-generator/              # 封面图生成技能
    │       ├── SKILL.md
    │       ├── scripts/
    │       │   └── cover_generator.py     # Python 生图脚本
    │       └── IP_character/
    │           └── IP_character.jpg       # IP 形象素材
    │
    └── reference/                         # 共享参考资料
        └── style-guide.md                # 写作风格指南
```

## 快速开始

### 前置条件

| 项目 | 要求 | 说明 |
|------|------|------|
| Claude Code | 已安装 | [安装指南](https://docs.anthropic.com/en/docs/claude-code) |
| Python | 3.8+ | 仅封面图生成功能需要 |
| API 密钥 | Anthropic + Gemini | 见下方配置说明 |

### 1. 克隆项目

```bash
git clone https://github.com/<你的用户名>/claude_code_guide.git
cd claude_code_guide
```

### 2. 配置 API 密钥

在项目根目录创建 `.claude/settings.local.json`（此文件已在 `.gitignore` 中，不会被提交）：

```json
{
  "env": {
    "ANTHROPIC_API_KEY": "你的 Claude API 密钥",
    "GEMINI_API_KEY": "你的 Gemini API 密钥"
  }
}
```

| 环境变量 | 用途 | 获取方式 |
|---------|------|---------|
| `ANTHROPIC_API_KEY` | Claude API 调用（教程撰写与审查） | [Anthropic Console](https://console.anthropic.com/) |
| `GEMINI_API_KEY` | Gemini 图像生成 API（封面图生成） | [Google AI Studio](https://aistudio.google.com/apikey) |

> 如果暂时不需要封面图生成功能，可以先只配置 `ANTHROPIC_API_KEY`。

### 3. 安装 Python 依赖（可选）

封面图生成功能需要安装以下依赖：

```bash
pip install google-genai pillow
```

| 依赖包 | 用途 |
|--------|------|
| `google-genai` | 调用 Gemini API 生成封面图 |
| `pillow` | 图片处理辅助库 |

### 4. 准备参考资料

`reference/` 目录用于存放教程写作时的官方参考文档，子代理会自动检索该目录下的文件作为内容依据。

**这个目录需要你自行填充**，项目不自带参考文档。获取方式：

- 从 [Claude Code 官方文档](https://code.claude.com/docs/en/overview) 下载相关页面
- 与 Claude 对话后导出对话记录
- 将你收集的任何有参考价值的资料放入该目录

建议的目录结构：

```
reference/
├── claude_code帮助文档/
│   ├── getting started/           # 基础概念、安装、工作流
│   └── build with claude code/    # 高级功能：hooks、MCP、子代理、技能等
└── claude_code使用帮助文档/        # 补充说明文档
```

> 参考资料越充足，教程内容越准确。建议至少覆盖 Claude Code 的基础概念和核心功能。

### 5. 开始使用

在项目目录下启动 Claude Code，然后使用技能命令：

```
/write-tutorial        # 撰写新教程
/review-article        # 审查优化文章
/cover-generator       # 生成封面图
```

也可以用自然语言触发，比如"帮我写一篇关于 XXX 的教程"。

## 使用指南

### 撰写新教程

使用 `/write-tutorial` 或说"帮我写一篇教程"触发。

**工作流程：**

1. 自动确定教程序号和位置
2. 调用 `reference-searcher` 子代理检索官方参考文档，确保内容有权威依据
3. 调用 `prev-article-reader` 子代理读取上一篇教程，确保上下篇衔接
4. 生成大纲，提交给你审查
5. 逐板块撰写内容，每个板块等你确认后继续
6. 全文完成后调用 `review-depth` 子代理进行深度审查
7. 根据审查报告修改，提交最终版本

**你需要做的：**
- 审查大纲并提出修改意见
- 逐板块确认内容
- 最终审核定稿

### 审查优化文章

使用 `/review-article` 或说"帮我看看这篇文章"触发。

**工作流程：**

1. 读取上一篇教程摘要，检查连贯性
2. 调用 `review-depth` 子代理进行四维深度审查
3. 对照官方文档验证技术准确性
4. 按风格指南和排版规范进行优化
5. 保存优化版本，列出具体改动

### 生成封面图

使用 `/cover-generator` 或说"为这篇教程生成封面"触发。

**封面图规格：**
- 比例：21:9 超宽屏（适合公众号封面）
- IP 形象：手绘线描风格小猫（戴圆框眼镜、持原子权杖），黑白灰配色
- 标题：艺术字形式，位于左侧
- 背景：简约风格，不超过 3 种主色

**前置条件：**
- Python 3.8+ 已安装
- `google-genai` 和 `pillow` 已安装
- `GEMINI_API_KEY` 已配置

## 工作原理

### 技能系统

技能（Skill）是 Claude Code 的扩展能力，定义在 `.claude/skills/` 目录下。每个技能包含一个 `SKILL.md` 文件，描述了技能的触发条件、执行流程和输出规范。

| 技能 | 触发方式 | 功能 |
|------|---------|------|
| `write-tutorial` | `/write-tutorial` 或自然语言 | 完整的教程创作流水线 |
| `review-article` | `/review-article` 或自然语言 | 审查和优化已有文章 |
| `cover-generator` | `/cover-generator` 或自然语言 | 生成公众号封面图 |

### 子代理系统

子代理（Subagent）是只读的辅助代理，在教程工作流中按固定顺序调用。它们通过工具白名单（Read/Glob/Grep）和黑名单（禁止 Write/Edit/Bash）双重限制，确保只能读取信息、不能修改文件。

| 子代理 | 调用时机 | 功能 |
|--------|---------|------|
| `reference-searcher` | 撰写教程前 | 检索 `reference/` 中的官方文档，提炼核心内容 |
| `prev-article-reader` | 撰写教程前 | 读取上一篇教程，确保上下篇衔接 |
| `review-depth` | 草稿完成后 | 四维深度审查：可迁移性、原理深度、内容详实度、框架合理性 |

**调用顺序：**

```
reference-searcher → prev-article-reader → （撰写/审查）→ review-depth
```

### 写作风格

所有教程遵循统一的写作风格（详见 `.claude/reference/style-guide.md`），核心理念是：

> **让读者感觉这是一个真实的人在说话，不是一个 AI 在输出。**

具体风格特征：
- 口语化表达（"说实话"、"其实"、"我觉得"）
- 用生活化比喻解释技术概念
- 每句话单独成段，短句多、长句少
- 有个人观点和情感温度
- 核心观点反复强调，不让读者遗漏

## 排版规范

所有教程文章必须遵守：

1. 每句话单独成段，段与段之间空一行
2. 禁止使用 ASCII 方框字符（目录树结构除外）
3. 重要结论使用 `==**加粗高亮**==` 标注
4. 教程目录命名格式：`序号-教程名称/`
5. 每篇教程放在独立目录，包含正文 `.md` 文件和 `image/` 配图目录

## 常见问题

### 封面图生成失败？

检查以下几点：
1. `GEMINI_API_KEY` 是否已正确配置在 `.claude/settings.local.json` 中
2. Python 依赖是否已安装：`pip install google-genai pillow`
3. IP 形象素材是否存在：`.claude/skills/cover-generator/IP_character/IP_character.jpg`

### 教程内容不准确？

教程的准确性依赖于 `reference/` 目录中的官方文档。确保该目录下有充足且最新的参考资料，子代理会自动检索并对照。

### 如何添加新的写作风格？

编辑 `.claude/reference/style-guide.md` 文件，所有技能和子代理都会自动引用更新后的风格指南。

## 参与贡献

欢迎各种形式的贡献！

### 贡献方式

1. **提交 Issue**：报告问题、建议新功能、讨论教程选题
2. **提交 Pull Request**：修复问题、优化技能配置、改进写作风格指南
3. **贡献教程**：按照项目规范撰写新教程或优化现有教程

### 开发流程

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/your-feature`）
3. 提交修改（`git commit -m 'Add some feature'`）
4. 推送到分支（`git push origin feature/your-feature`）
5. 提交 Pull Request

### 修改技能或子代理

- 技能定义在 `.claude/skills/<技能名>/SKILL.md`
- 子代理定义在 `.claude/agents/<代理名>.md`
- 写作风格指南在 `.claude/reference/style-guide.md`
- 项目全局配置在 `CLAUDE.md`

## 开源协议

本项目基于 [MIT 协议](LICENSE) 开源。

---

如果这个项目对你有帮助，欢迎给个 Star ⭐