claude-howto/zh/STYLE_GUIDE.md

风格指南

为 Claude How To 贡献内容时遵循的约定和格式规则。请按照这份指南保持内容一致、专业且易于维护。

---

目录

• 文件与文件夹命名
• 文档结构
• 标题
• 文本格式
• 列表
• 表格
• 代码块
• 链接与交叉引用
• 图表
• Emoji 用法
• YAML Frontmatter
• 图片与媒体
• 语气与文风
• 提交信息
• 作者检查清单

---

文件与文件夹命名

课程文件夹

课程文件夹使用一个 两位数字前缀，后接一个 kebab-case 描述符：

01-slash-commands/
02-memory/
03-skills/
04-subagents/
05-mcp/

这个数字反映了学习路径的顺序，从初学者到高级。

文件名

类型	约定	示例
课程 README	README.md	01-slash-commands/README.md
功能文件	kebab-case .md	code-reviewer.md, generate-api-docs.md
Shell 脚本	kebab-case .sh	format-code.sh, validate-input.sh
配置文件	标准名称	.mcp.json, settings.json
记忆文件	带作用域前缀	project-CLAUDE.md, personal-CLAUDE.md
顶层文档	UPPER_CASE .md	CATALOG.md, QUICK_REFERENCE.md, CONTRIBUTING.md
图片资源	kebab-case	pr-slash-command.png, claude-howto-logo.svg

规则

• 除顶层文档外，所有文件和文件夹名都使用 小写
• 使用连字符（-）作为单词分隔符，永远不要使用下划线或空格
• 名称要具体，但保持简洁

---

文档结构

根 README

根目录 README.md 的顺序如下：

1. Logo（使用带深色/浅色变体的 <picture> 元素）
2. H1 标题
3. 引导性引用块（一句话价值主张）
4. “为什么需要这份指南？”部分，以及对比表
5. 分隔线（---）
6. 目录
7. 功能目录
8. 快速导航
9. 学习路径
10. 功能章节
11. 快速上手
12. 最佳实践 / 故障排查
13. 参与贡献 / 许可证

课程 README

每个课程 README.md 的顺序如下：

1. H1 标题，例如 # Slash Commands
2. 简短概述段落
3. 快速参考表格（可选）
4. 架构图（Mermaid）
5. 详细章节（H2）
6. 实用示例（编号列表，4-6 个示例）
7. 最佳实践（Do's 和 Don'ts 表）
8. 故障排查
9. 相关指南 / 官方文档
10. 文档元数据页脚

功能/示例文件

单个功能文件，例如 optimize.md、pr.md：

1. YAML frontmatter（如果适用）
2. H1 标题
3. 目的 / 描述
4. 使用说明
5. 代码示例
6. 自定义提示

分隔线

使用水平分隔线（---）来分隔文档中的主要区域：

---

## New Major Section

将它们放在引导性引用块之后，以及文档中逻辑上不同的部分之间。

---

标题

层级

级别	用途	示例
# H1	页面标题，每个文档一个	# Slash Commands
## H2	主要章节	## Best Practices
### H3	子章节	### Adding a Skill
#### H4	再下一级子章节，较少使用	#### Configuration Options

规则

• 每个文档只允许一个 H1，即页面标题
• 不要跳级，不要从 H2 直接跳到 H4
• 标题要简洁，尽量控制在 2-5 个词
• 使用句首大写，只大写首字和专有名词（例外：功能名保持原样）
• 只有根 README 的章节标题 可以使用 Emoji 前缀，见 Emoji 用法

---

文本格式

强调

样式	使用时机	示例
粗体 (**text**)	关键术语、表格标签、重要概念	**Installation**:
斜体 (*text*)	技术术语首次出现、书名或文档名	*frontmatter*
Code (`text`)	文件名、命令、配置值、代码引用	`CLAUDE.md`

使用引述块做提示

对重要说明使用带粗体前缀的引述块：

> **Note**: Custom slash commands have been merged into skills since v2.0.

> **Important**: Never commit API keys or credentials.

> **Tip**: Combine memory with skills for maximum effectiveness.

支持的提示类型：Note、Important、Tip、Warning。

段落

• 保持段落简短，2-4 句为宜
• 段落之间留一个空行
• 先说重点，再补充上下文
• 解释“为什么”，不只是“是什么”

---

列表

无序列表

使用短横线（-），嵌套时使用 2 个空格缩进：

- First item
- Second item
  - Nested item
  - Another nested item
    - Deep nested (avoid going deeper than 3 levels)
- Third item

有序列表

用于顺序步骤、操作说明和排序项：

1. First step
2. Second step
   - Sub-point detail
   - Another sub-point
3. Third step

说明性列表

对键值对风格的列表，使用粗体标签：

- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops
- **Memory leaks** - find unreleased resources, circular references
- **Algorithm improvements** - suggest better algorithms or data structures

规则

• 保持一致的缩进，每层 2 个空格
• 列表前后都要空一行
• 列表项结构要平行一致，例如都用动词开头，或者都用名词开头
• 嵌套深度不要超过 3 层

---

表格

标准格式

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

常见表格模式

功能对比（3-4 列）：

| Feature | Invocation | Persistence | Best For |
|---------|-----------|------------|----------|
| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
| **Memory** | Auto-loaded | Cross-session | Long-term learning |

Do's and Don'ts：

| Do | Don't |
|----|-------|
| Use descriptive names | Use vague names |
| Keep files focused | Overload a single file |

快速参考：

| Aspect | Details |
|--------|---------|
| **Purpose** | Generate API documentation |
| **Scope** | Project-level |
| **Complexity** | Intermediate |

规则

• 当表头是行标签时，表头要加粗
• 代码源文件中的管道符尽量对齐，便于阅读（可选但推荐）
• 单元格内容要简洁；细节用链接展开
• 命令和文件路径在单元格中要使用 代码格式

---

代码块

语言标签

始终为语法高亮指定语言标签：

语言	标签	用途
Shell	bash	CLI 命令、脚本
Python	python	Python 代码
JavaScript	javascript	JS 代码
TypeScript	typescript	TS 代码
JSON	json	配置文件
YAML	yaml	Frontmatter、配置
Markdown	markdown	Markdown 示例
SQL	sql	数据库查询
Plain text	(no tag)	期望输出、目录树

约定

# Comment explaining what the command does
claude mcp add notion --transport http https://mcp.notion.com/mcp

• 在不明显的命令前添加一行 注释
• 所有示例都要做到 可直接复制粘贴
• 相关时同时提供 简单版和高级版
• 需要时要给出 期望输出，这时使用不带标签的代码块

安装示例

安装说明请使用以下模式：

# Copy files to your project
cp 01-slash-commands/*.md .claude/commands/

多步骤工作流

# Step 1: Create the directory
mkdir -p .claude/commands

# Step 2: Copy the templates
cp 01-slash-commands/*.md .claude/commands/

# Step 3: Verify installation
ls .claude/commands/

---

链接与交叉引用

内部链接（相对路径）

内部链接全部使用相对路径：

[Slash Commands](01-slash-commands/README.md)
[Skills Guide](03-skills/README.md)
[Memory Architecture](02-memory/README.md)

从课程文件夹返回根目录或兄弟目录：

[返回主指南](README.md)
[相关：Skills](03-skills/README.md)

外部链接（绝对路径）

使用完整 URL，并使用具有描述性的锚文本：

[Anthropic's official documentation](https://code.claude.com/docs/en/overview)

• 不要使用“click here”或“this link”作为锚文本
• 使用脱离上下文也能理解的描述性文字

章节锚点

链接到同一文档中的章节时，使用 GitHub 风格锚点：

[文件与文件夹命名](#文件与文件夹命名)
[作者检查清单](#作者检查清单)

相关指南模式

课程末尾要附上相关指南章节：

## Related Guides

- [Slash Commands](01-slash-commands/README.md) - 快速快捷命令
- [Memory](02-memory/README.md) - 持久上下文
- [Skills](03-skills/README.md) - 可复用能力

---

图表

Mermaid

所有图表都使用 Mermaid。支持的类型包括：

• graph TB / graph LR - 架构、层级、流程
• sequenceDiagram - 交互流程
• timeline - 时间顺序

样式约定

使用 style block 保持颜色一致：

graph TB
    A["Component A"] --> B["Component B"]
    B --> C["Component C"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#fce4ec,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

颜色调色板：

Color	Hex	Use For
Light blue	#e1f5fe	Primary components, inputs
Light pink	#fce4ec	Processing, middleware
Light green	#e8f5e9	Outputs, results
Light yellow	#fff9c4	Configuration, optional
Light purple	#f3e5f5	User-facing, UI

规则

• 节点标签使用 ["Label text"]，这样可以包含特殊字符
• 在标签中换行使用 <br/>
• 图表保持简洁，最多 10-12 个节点
• 图表下方添加简短文字说明，方便无障碍阅读
• 层级结构使用自上而下（TB），流程使用左右（LR）

---

Emoji 用法

Emoji 的使用场景

Emoji 使用要 克制且有目的，只在特定场景中出现：

场景	Emoji	示例
Root README 章节标题	分类图标	## 📚 Learning Path
Skill 等级指示	彩色圆点	🟢 Beginner, 🔵 Intermediate, 🔴 Advanced
Do's 和 Don'ts	对勾/叉号	✅ Do this, ❌ Don't do this
复杂度评级	星星	⭐⭐⭐

标准 Emoji 集合

Emoji	含义
📚	学习、指南、文档
⚡	快速上手、速查
🎯	功能、速查
🎓	学习路径
📊	统计、对比
🚀	安装、快速命令
🟢	初学者级别
🔵	中级别
🔴	高级别
✅	推荐做法
❌	避免 / 反模式
⭐	复杂度评级单位

规则

• 不要在正文或段落中使用 Emoji
• 只在根 README 的标题中使用 Emoji，不要在课程 README 中使用
• 不要添加装饰性 Emoji，每个 Emoji 都应该有意义
• Emoji 的使用要与上表保持一致

---

YAML Frontmatter

功能文件（Skills、Commands、Agents）

---
name: unique-identifier
description: What this feature does and when to use it
allowed-tools: Bash, Read, Grep
---

可选字段

---
name: my-feature
description: Brief description
argument-hint: "[file-path] [options]"
allowed-tools: Bash, Read, Grep, Write, Edit
model: opus                        # opus, sonnet, or haiku
disable-model-invocation: true     # User-only invocation
user-invocable: false              # Hidden from user menu
context: fork                      # Run in isolated subagent
agent: Explore                     # Agent type for context: fork
---

规则

• Frontmatter 放在文件最顶部
• name 字段使用 kebab-case
• description 保持为一句话
• 只包含真正需要的字段

---

图片与媒体

Logo 模式

所有以 Logo 开头的文档都使用 <picture> 元素，以支持深色/浅色模式：

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
</picture>

截图

• 存放在对应课程文件夹中，例如 01-slash-commands/pr-slash-command.png
• 使用 kebab-case 文件名
• 包含描述性的 alt 文本
• 图表优先使用 SVG，截图优先使用 PNG

规则

• 图片始终要有 alt 文本
• 控制图片文件大小，PNG 尽量小于 500KB
• 图片引用使用相对路径
• 图片存放在引用它的文档同目录，或者放在 assets/ 里供共享使用

---

语气与文风

写作风格

• 专业但亲切 - 技术准确，同时不过度堆砌术语
• 主动语态 - 说“Create a file”，不要说“一个文件应该被创建”
• 直接指令 - 说“Run this command”，不要说“你也许可以运行这个命令”
• 适合初学者 - 假设读者是 Claude Code 新手，但不是编程新手

内容原则

原则	示例
Show, don't tell	提供可运行示例，而不是抽象描述
渐进式复杂度	先简单，后面再增加深度
解释“为什么”	“Use memory for... because...” 而不只是 “Use memory for...”
可直接复制粘贴	每个代码块都应能直接粘贴使用
真实场景	使用实际场景，而不是牵强的例子

词汇

• 使用 “Claude Code”（不要写 “Claude CLI” 或 “the tool”）
• 使用 “skill”（不要写 “custom command”，这是旧术语）
• 使用 “lesson” 或 “guide” 来称呼编号章节
• 使用 “example” 来称呼单个功能文件

---

提交信息

遵循 Conventional Commits：

type(scope): description

类型

Type	Use For
feat	新功能、示例或指南
fix	Bug 修复、纠正、损坏链接
docs	文档改进
refactor	只重构、不改变行为
style	仅格式化改动
test	测试新增或修改
chore	构建、依赖、CI

作用域

使用课程名称或文件区域作为作用域：

feat(slash-commands): Add API documentation generator
docs(memory): Improve personal preferences example
fix(README): Correct table of contents link
docs(skills): Add comprehensive code review skill

---

文档元数据页脚

课程 README 以元数据块结尾：

---
**Last Updated**: March 2026
**Claude Code Version**: 2.1.97
**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5

• 使用“月份 + 年份”格式，例如 “March 2026”
• 功能变化时更新版本
• 列出所有兼容模型

---

作者检查清单

提交内容前，请确认：

• 文件/文件夹名使用 kebab-case
• 文档以 H1 标题开头，每个文件一个
• 标题层级正确，没有跳级
• 所有代码块都带语言标签
• 代码示例可直接复制粘贴
• 内部链接使用相对路径
• 外部链接使用描述性锚文本
• 表格格式正确
• Emoji 遵循标准集合（如果使用）
• Mermaid 图表使用标准配色
• 没有敏感信息，例如 API key、凭据
• YAML frontmatter 有效（如果适用）
• 图片有 alt 文本
• 段落简短且聚焦
• 相关指南章节链接到合适的课程
• 提交信息符合 conventional commits 格式