# 风格指南 > 为 Claude How To 贡献内容时遵循的约定和格式规则。请按照这份指南保持内容一致、专业且易于维护。 --- ## 目录 - [文件与文件夹命名](#文件与文件夹命名) - [文档结构](#文档结构) - [标题](#标题) - [文本格式](#文本格式) - [列表](#列表) - [表格](#表格) - [代码块](#代码块) - [链接与交叉引用](#链接与交叉引用) - [图表](#图表) - [Emoji 用法](#emoji-用法) - [YAML Frontmatter](#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（使用带深色/浅色变体的 `` 元素） 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. 自定义提示 ### 分隔线 使用水平分隔线（`---`）来分隔文档中的主要区域： ```markdown --- ## New Major Section ``` 将它们放在引导性引用块之后，以及文档中逻辑上不同的部分之间。 --- ## 标题 ### 层级 | 级别 | 用途 | 示例 | |-------|-----|---------| | `#` H1 | 页面标题，每个文档一个 | `# Slash Commands` | | `##` H2 | 主要章节 | `## Best Practices` | | `###` H3 | 子章节 | `### Adding a Skill` | | `####` H4 | 再下一级子章节，较少使用 | `#### Configuration Options` | ### 规则 - **每个文档只允许一个 H1**，即页面标题 - **不要跳级**，不要从 H2 直接跳到 H4 - **标题要简洁**，尽量控制在 2-5 个词 - **使用句首大写**，只大写首字和专有名词（例外：功能名保持原样） - **只有根 README 的章节标题** 可以使用 Emoji 前缀，见 [Emoji 用法](#emoji-用法) --- ## 文本格式 ### 强调 | 样式 | 使用时机 | 示例 | |-------|------------|---------| | **粗体** (`**text**`) | 关键术语、表格标签、重要概念 | `**Installation**:` | | *斜体* (`*text*`) | 技术术语首次出现、书名或文档名 | `*frontmatter*` | | `Code` (`` `text` ``) | 文件名、命令、配置值、代码引用 | `` `CLAUDE.md` `` | ### 使用引述块做提示 对重要说明使用带粗体前缀的引述块： ```markdown > **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 个空格缩进： ```markdown - First item - Second item - Nested item - Another nested item - Deep nested (avoid going deeper than 3 levels) - Third item ``` ### 有序列表 用于顺序步骤、操作说明和排序项： ```markdown 1. First step 2. Second step - Sub-point detail - Another sub-point 3. Third step ``` ### 说明性列表 对键值对风格的列表，使用粗体标签： ```markdown - **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 层 --- ## 表格 ### 标准格式 ```markdown | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Data | Data | Data | ``` ### 常见表格模式 **功能对比（3-4 列）：** ```markdown | 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：** ```markdown | Do | Don't | |----|-------| | Use descriptive names | Use vague names | | Keep files focused | Overload a single file | ``` **快速参考：** ```markdown | 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) | 期望输出、目录树 | ### 约定 ```bash # Comment explaining what the command does claude mcp add notion --transport http https://mcp.notion.com/mcp ``` - 在不明显的命令前添加一行 **注释** - 所有示例都要做到 **可直接复制粘贴** - 相关时同时提供 **简单版和高级版** - 需要时要给出 **期望输出**，这时使用不带标签的代码块 ### 安装示例 安装说明请使用以下模式： ```bash # Copy files to your project cp 01-slash-commands/*.md .claude/commands/ ``` ### 多步骤工作流 ```bash # 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/ ``` --- ## 链接与交叉引用 ### 内部链接（相对路径） 内部链接全部使用相对路径： ```markdown [Slash Commands](01-slash-commands/README.md) [Skills Guide](03-skills/README.md) [Memory Architecture](02-memory/README.md) ``` 从课程文件夹返回根目录或兄弟目录： ```markdown [返回主指南](README.md) [相关：Skills](03-skills/README.md) ``` ### 外部链接（绝对路径） 使用完整 URL，并使用具有描述性的锚文本： ```markdown [Anthropic's official documentation](https://code.claude.com/docs/en/overview) ``` - 不要使用“click here”或“this link”作为锚文本 - 使用脱离上下文也能理解的描述性文字 ### 章节锚点 链接到同一文档中的章节时，使用 GitHub 风格锚点： ```markdown [文件与文件夹命名](#文件与文件夹命名) [作者检查清单](#作者检查清单) ``` ### 相关指南模式 课程末尾要附上相关指南章节： ```markdown ## 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 保持颜色一致： ```mermaid 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"]`，这样可以包含特殊字符 - 在标签中换行使用 `
` - 图表保持简洁，最多 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） ```yaml --- name: unique-identifier description: What this feature does and when to use it allowed-tools: Bash, Read, Grep --- ``` ### 可选字段 ```yaml --- 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 开头的文档都使用 `` 元素，以支持深色/浅色模式： ```html ``` ### 截图 - 存放在对应课程文件夹中，例如 `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](https://www.conventionalcommits.org/)： ``` 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 以元数据块结尾： ```markdown --- **Last Updated**: August 2026 **Claude Code Version**: 2.1.245 **Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 ``` - 使用“月份 + 年份”格式，例如 “August 2026” - 使用当前同步运行捕获的版本号，而非此处示例中显示的值 - 功能变化时更新版本 - 列出所有兼容模型 --- ## 作者检查清单 提交内容前，请确认： - [ ] 文件/文件夹名使用 kebab-case - [ ] 文档以 H1 标题开头，每个文件一个 - [ ] 标题层级正确，没有跳级 - [ ] 所有代码块都带语言标签 - [ ] 代码示例可直接复制粘贴 - [ ] 内部链接使用相对路径 - [ ] 外部链接使用描述性锚文本 - [ ] 表格格式正确 - [ ] Emoji 遵循标准集合（如果使用） - [ ] Mermaid 图表使用标准配色 - [ ] 没有敏感信息，例如 API key、凭据 - [ ] YAML frontmatter 有效（如果适用） - [ ] 图片有 alt 文本 - [ ] 段落简短且聚焦 - [ ] 相关指南章节链接到合适的课程 - [ ] 提交信息符合 conventional commits 格式 --- **最后更新**: 2026 年 8 月 25 日 **Claude Code 版本**: 2.1.245 **来源**: - https://code.claude.com/docs/en/overview