Claude How To 风格指南解析为 Claude Code 教程仓库建立可维护的文档写作规范【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto导读Claude How To 是一个以视觉化、示例驱动方式讲解 Claude Code 的开源教程仓库其全部产出物都是 Markdown 文档编号模块01-到10-。为了让几十个文档保持一致性、专业性、易维护仓库在 STYLE_GUIDE.md 中沉淀了一套完整、可执行的写作规范并配套了自动校验脚本。本篇将以该风格指南为主体结合仓库中的校验脚本、测试用例与各模块真实文档系统拆解这套规范——读完你既能直接上手为 Claude How To 贡献内容也能把这套规范 自动化校验的方法论复用到自己的文档工程中。文章基于仓库当前内容撰写其中版本信息与命令行为以仓库实际文件为准。一、文件与目录命名规范课程目录命名教程模块目录使用两位数字前缀 kebab-case 描述符01-slash-commands/ 02-memory/ 03-skills/ 04-subagents/ 05-mcp/数字前缀体现学习路径的顺序从入门到进阶。这一点在 CLAUDE.md 中被列为硬性规则——01-…10-是教程模块数字前缀 学习顺序不是字母序禁止重排。文件命名对照表类型约定示例课程 READMEREADME.md01-slash-commands/README.md功能文件Kebab-case.mdcode-reviewer.md、generate-api-docs.mdShell 脚本Kebab-case.shformat-code.sh、validate-input.sh配置文件标准命名.mcp.json、settings.json记忆文件带作用域前缀project-CLAUDE.md、personal-CLAUDE.md顶层文档UPPER_CASE.mdCATALOG.md、QUICK_REFERENCE.md、CONTRIBUTING.md图片资源Kebab-casepr-slash-command.png、claude-howto-logo.svg命名规则所有文件与目录名使用小写顶层文档如README.md、CATALOG.md除外使用连字符-作为单词分隔符绝不使用下划线或空格名称保持描述性但简洁。仓库实践03-skills/下的功能目录如code-review-specialist/、blog-draft/、doc-generator/均遵循小写 连字符02-memory/下的记忆文件确实以作用域前缀命名directory-api-CLAUDE.md、project-CLAUDE.md。二、文档结构规范风格指南为三类文档分别定义了固定结构顺序保证所有读者在任何文档中都能快速定位信息。根 README 的结构顺序Logopicture元素含 dark/light 两套变体H1 标题引言块引用一行价值主张为什么选择本指南章节含对比表格水平线---目录功能目录Feature Catalog快速导航学习路径各功能章节开始使用最佳实践 / 故障排查贡献 / 许可证课程 README 的结构顺序H1 标题如# Slash Commands简短概述段落快速参考表格可选架构图Mermaid详细章节H2实操示例编号列表4–6 个示例最佳实践Dos and Donts 表格故障排查相关指南 / 官方文档文档元数据页脚以 01-slash-commands/README.md 为实例它以pictureLogo 开头随后是# Slash Commands标题、Overview、Built-in Commands 快速参考表、两条 Mermaid 架构图Command Architecture、Command Lifecycle、编号的可用命令示例/optimize到/unit-test-expand共 8 个、Best Practices 的 Dos and Donts 表格、Troubleshooting、Related Guides最后以**Last Updated**元数据页脚收尾——完全复刻了上述顺序。功能/示例文件的结构单个功能文件如optimize.md、pr.mdYAML frontmatter如适用H1 标题用途 / 描述使用说明代码示例定制技巧章节分隔线使用水平线---分隔文档的主要区域--- ## New Major Section放置位置引言块引用之后以及逻辑上相互独立的部分之间。三、标题层级规范层级对照级别用途示例#H1页面标题每文档仅一个# Slash Commands##H2主要章节## Best Practices###H3子章节### Adding a Skill####H4子-子章节很少用#### Configuration Options标题规则每文档只有一个 H1——仅限页面标题绝不跳级——不要从 H2 直接跳到 H4标题保持简洁——尽量控制在 2–5 个词使用 sentence case——只有首词和专有名词大写例外功能名称保持原样仅在根 README 的章节标题上添加 Emoji 前缀详见 Emoji 章节。仓库对标题锚点的处理有代码级保障校验脚本 scripts/check_cross_references.py 中的heading_to_anchor()函数会按 GitHub 的锚点生成算法剥离 Emoji 与特殊标点、保留 Unicode 字母如越南语变音符号、转小写、空格换连字符、去除首尾连字符把每个标题转换为合法锚点并逐条核对文档内#anchor链接是否命中真实标题从而杜绝锚点失效 404。四、文本格式规范强调样式样式何时使用示例加粗**text**关键术语、表格中的行标签、重要概念**Installation**:斜体*text*技术术语首次出现、书名/文档名*frontmatter*代码text文件名、命令、配置值、代码引用CLAUDE.md引用块Callout使用带加粗前缀的块引用承载重要提示 **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.支持的 Callout 类型Note、Important、Tip、Warning。仓库文档大量使用这一约定例如 01-slash-commands/README.md 中的 Why/cdmatters 引用块以及 03-skills/README.md 中关于.claude/commands/迁移的 Note。段落规范段落保持简短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 |Dos and Donts| Do | Dont | |----|-------| | Use descriptive names | Use vague names | | Keep files focused | Overload a single file |快速参考| Aspect | Details | |--------|---------| | **Purpose** | Generate API documentation | | **Scope** | Project-level | | **Complexity** | Intermediate |规则当第一列是行标签时表头单元格使用加粗源码中对齐竖线提升可读性可选但推荐单元格内容保持简洁细节用链接承载单元格内的命令与文件路径使用code formatting。自动化校验未转义竖线表格是最容易渲染变形的语法。仓库用 scripts/check_markdown_rendering.py 中的rule_unescaped_pipe_in_table规则做机器检查它以表头行的列数未转义竖线计数为基准逐一核对每一行若某行未转义竖线数不同例如[color|default]中裸露的|即报错并提示用\|转义。对应测试 scripts/tests/test_check_markdown_rendering.py 同时覆盖了正反两例| a | b | c |与三列表头不匹配会被标记而| [color\|default] | b |转义后通过单元格内联代码中的竖线a \| b也视为合法。七、代码块规范语言标签所有代码块必须声明语言标签以启用语法高亮语言标签用途ShellbashCLI 命令、脚本PythonpythonPython 代码JavaScriptjavascriptJS 代码TypeScripttypescriptTS 代码JSONjson配置文件YAMLyamlFrontmatter、配置MarkdownmarkdownMarkdown 示例SQLsql数据库查询纯文本无标签预期输出、目录树这一约定在 CLAUDE.md 中被列为硬规则代码围栏必须声明语言bash、python、json……否则交叉引用检查会失败。约定# 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/渲染校验反引号与围栏Markdown 的渲染正确性同样由脚本把关。rule_backtick_in_inline_code专门捕捉内联代码里又含反引号的经典 bug仓库曾在 PR #114 中出现!command这种写法——它按 CommonMark 内联代码语义从左到右消费代码跨度任何残留的反引号都被视为结构不匹配规范写法是双反引号 空格的!command 惯用法。rule_unmatched_fence则统计文件中的三重反引号围栏数量奇数即报错。这两条规则都会跳过围栏代码块内部避免误报对应的正向/负向测试用例含块引用内围栏场景在scripts/tests/test_check_markdown_rendering.py中一应俱全。八、链接与交叉引用内部链接相对路径所有内部链接使用相对路径[Slash Commands](https://link.gitcode.com/i/849b34eeb1056d5d065668418b5879f9) [Skills Guide](https://link.gitcode.com/i/2beea1f6557093067dfcf2a1b31ed6fe) [Memory Architecture](https://link.gitcode.com/i/7bc8007ee8d1bbe201096fbe361fd1e5)从课程目录返回根目录或访问同级目录[Back to main guide](https://link.gitcode.com/i/c5d9afe6364fbdc63e742dd9067bed94) Related: Skills外部链接绝对 URL使用完整 URL 与描述性锚文本[Anthropics official documentation](https://code.claude.com/docs/en/overview)绝不用 click here 或 this link 作为锚文本锚文本脱离上下文也应自明。章节锚点站内锚点使用 GitHub 风格[Feature Catalog](#-feature-catalog) [Best Practices](#best-practices)相关指南模式课程文档以相关指南章节收尾## Related Guides - Slash Commands - Quick shortcuts - Memory - Persistent context - Skills - Reusable capabilities例如 03-skills/README.md 末尾的 Additional Resources 就并列链接了 01-slash-commands/README.md、02-memory/README.md、04-subagents/README.md、05-mcp/README.md、06-hooks/README.md。交叉引用的机器校验仓库将链接不失效变成可验证的硬约束scripts/check_cross_references.py 会遍历仓库内所有.md文件排除.venv、node_modules、.git、blog-posts、openspec、prompts、.agents等目录完成三件事相对.md链接必须能解析把text解析为真实文件不存在即报broken cross-reference且链接必须停留在仓库根目录之内页内锚点必须匹配真实标题用heading_to_anchor()生成合法锚点集合后逐一核对代码围栏必须成对奇数个即报错。此外它还强制校验01-到10-编号目录都必须有README.md。在扫描时脚本会先剥离围栏代码块与内联代码避免把示例中的链接误判为真实引用。九、图表规范Mermaid支持类型graph TB/graph LR— 架构、层级、流程sequenceDiagram— 交互流程timeline— 时间线序列样式约定与调色板用 style 块施加统一配色标准调色板颜色Hex用途浅蓝#e1f5fe主要组件、输入浅粉#fce4ec处理、中间件浅绿#e8f5e9输出、结果浅黄#fff9c4配置、可选浅紫#f3e5f5面向用户、UI这套配色在仓库文档中随处可见例如 02-memory/README.md 的 Memory Discovery Behavior 图用浅粉Managed Policy、浅紫User、浅蓝Project、浅绿Local区分四级记忆作用域语义与调色板定义一一对应。仓库 CHANGELOG 也记录过对五色stroke/color属性的统一修正。规则节点标签使用[Label text]支持特殊字符标签内换行用br/图表保持简洁最多 10–12 个节点图下附简短文字描述以提升可访问性层级结构用自上而下TB工作流用从左到右LR。仓库对 Mermaid 的校验有两层scripts/check_mermaid.py检查语法EPUB 构建脚本 scripts/build_epub.py 会渲染 Mermaid需要本地mmdcCLICLAUDE.md 明确指出EPUB 构建失败通常就是 Mermaid 无效或mmdc缺失。十、Emoji 使用规范Emoji 的使用原则是稀少且有目的——只在特定上下文出现上下文Emoji示例根 README 章节标题分类图标## Learning Path技能等级指示彩色圆点 入门、 中级、 高级Dos and Donts对勾/叉号✅ 这样做、❌ 别这样做复杂度评级星号⭐⭐⭐标准 Emoji 集Emoji含义学习、指南、文档⚡开始使用、快速参考功能、快速参考学习路径统计、对比安装、快捷命令入门级中级高级✅推荐实践❌避免 / 反模式⭐复杂度评级单位规则正文或段落中绝不使用 Emoji只在根 README 的标题中使用 Emoji课程 README 不行不加装饰性 Emoji——每个 Emoji 必须承载含义使用与上表保持一致。heading_to_anchor()专门处理了含 Emoji 标题的锚点生成它会剥离 Emoji 等符号含辅助平面字符、Dingbats、变体选择符、零宽连接符再按规则转成锚点因此## Learning Path这类标题的锚点#-learning-path保留前导连字符也能被正确校验。十一、YAML Frontmatter功能文件技能、命令、Agent--- 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-casedescription保持一句话只包含必要字段。仓库的真实技能文件就是这些字段的活教材03-skills/code-review-specialist/SKILL.md 的 frontmatter 用name: code-review-specialist加一句含触发条件的长descriptionUse when users ask to review code, analyze code quality, evaluate pull requests...03-skills/README.md 还补充了disallowed-tools、effort、background、shell、hooks、paths等更多可选字段及完整取值说明——例如disable-model-invocation: true用于/commit、/deploy这类有副作用的命令防止 Claude 自行触发user-invocable: false用于纯背景知识类技能。十二、图片与媒体Logo 模式所有以 Logo 开头的文档使用picture元素以支持 dark/light 模式picture source media(prefers-color-scheme: dark) srcsetresources/logos/claude-howto-logo-dark.svg img altClaude How To srcresources/logos/claude-howto-logo.svg /picture仓库根目录提供了 claude-howto-logo.svg 与 claude-howto-logo.png多套矢量资产集中存放在 assets/logo/logo-full.svg、logo-mark.svg、logo-wordmark.svg等英文与各语言版 README 均以该picture模式开头。截图存放在对应课程目录如01-slash-commands/pr-slash-command.png使用 kebab-case 文件名包含描述性 alt 文本图表优先 SVG截图优先 PNG。规则图片必须提供 alt 文本图片文件体积合理PNG 500KB图片引用使用相对路径图片存放在引用它的文档同目录或放入共享的assets/目录。十三、语气与声音写作风格专业但平易近人——技术准确避免术语堆砌主动语态——Create a file 而不是 A file should be created直接指令——Run this command 而不是 You might want to run this command对新手友好——假定读者刚接触 Claude Code但并非编程新手。内容原则原则示例展示而非说教提供可运行的示例而不是抽象描述渐进式难度先简单后续章节再加深解释为什么Use memory for... because... 而不只是 Use memory for...可直接复制每个代码块粘贴即用真实场景使用实际场景而非刻意构造的示例词汇表使用 Claude Code不要用 Claude CLI 或 the tool使用 skill不要用 custom command——旧术语自定义斜杠命令已并入 skill见 01-slash-commands/README.md 的迁移说明用 lesson 或 guide 指代编号课程模块用 example 指代单个功能文件。十四、提交信息规范遵循 Conventional Commits 格式type(scope): description类型类型用途feat新功能、示例或指南fixBug 修复、勘误、失效链接docs文档改进refactor不改变行为的重构style仅格式修改test新增或修改测试chore构建、依赖、CI范围用课程名或文件区域作为 scopefeat(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这与 CLAUDE.md 的硬规则一致提交格式type(scope): subjectscope 匹配模块目录名。仓库 CHANGELOG 本身就是这套规范的执行记录。十五、文档元数据页脚课程 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功能变化时更新版本号列出所有兼容模型。仓库实际文档的页脚更为完整例如 03-skills/code-review-specialist/SKILL.md 的页脚包含Last Updated、Claude Code Version、Sources与Compatible Models四部分。有趣的是当前仓库各文档页脚的版本号并不统一如 01-slash-commands/README.md 记录为 2.1.235其余文档为 2.1.220这也说明元数据维护需要与作者检查清单配合避免漂移。十六、作者检查清单与自动化保障提交前检查清单文件/目录名使用 kebab-case文档以 H1 标题开头每文件一个标题层级正确无跳级所有代码块都有语言标签代码示例可复制粘贴内部链接使用相对路径外部链接使用描述性锚文本表格格式正确Emoji 遵循标准集如使用Mermaid 图使用标准调色板无敏感信息API 密钥、凭据YAML frontmatter 有效如适用图片有 alt 文本段落简短聚焦相关指南章节链接到对应课程提交信息符合 conventional commits 格式把检查清单变成自动化的机器Claude How To 的核心思路是人工清单 机器校验双保险。仓库在 scripts/ 下集中放置校验工具CLAUDE.md 明确其定位scripts/中的脚本仅用于校验文档与构建 EPUB并列出质量门禁命令# Quality gate (also runs on commit via pre-commit hooks) pre-commit run --all-files # Tests pytest scripts/tests/ -vPre-commit 会在.md变更上运行 5 项文档检查markdown-lint、cross-references、mermaid-syntax、link-check、markdown-rendering全部通过才允许提交。其中scripts/check_markdown_rendering.py 实现 4 条渲染规则内联代码反引号、表格未转义竖线、游离的$ARGUMENTS占位符、不成对围栏并明确排除.venv、node_modules、blog-posts、prompts、.claude等非教程输出目录scripts/check_cross_references.py 负责链接、锚点与围栏的交叉校验每条规则都有配套的正向/负向测试见 scripts/tests/test_check_markdown_rendering.py——例如$ARGUMENTS出现在裸正文中会被标记而在内联代码或围栏内通过$5 today、$1,000这类正文货币金额则被刻意排除$N与货币在语法上无法区分。多语言文档的一致性仓库包含ja/、uk/、vi/、zh/四个翻译目录uk/STYLE_GUIDE.md 正是本文所依据的乌克兰语版本其头部携带 i18n 注释i18n-source、i18n-source-sha、i18n-date用于追踪与英文源的同步状态。翻译同步由 scripts/sync_translations.py 负责而 scripts/check_markdown_rendering.py 的测试明确断言其扫描范围覆盖ja、uk、vi、zh四个翻译目录——这意味着风格规范不是英文独有的而是整个仓库所有语言的共同标准。网页构建脚本 scripts/build_website.py 也把STYLE_GUIDE.md映射为 Style Guide 页面标题。结语从命名、结构、语法细节到提交信息Claude How To 的风格指南回答了一个文档工程的核心问题当内容创作者众多、语言版本众多、产出物庞大时如何保证一致性、专业性、易维护三者兼得。它的方法论可以提炼为三点用模板固定骨架——根 README、课程 README、功能文件各有固定结构顺序读者与贡献者都无需猜测用规则约束细节——kebab-case、sentence case、语言标签、标准调色板、受限 Emoji 集、Conventional Commits每一条都具体到可直接执行用脚本兜底人工——渲染正确性与交叉引用不再是自觉而是 pre-commit 质量门禁与 pytest 测试的硬性输出让规范从建议变成事实。如果你正在维护 Claude Code 教程、技术博客或企业知识库可以直接复用这份规范与其校验脚本的设计思路先定义结构与命名约定再为 Markdown 的机械性错误编写规则与测试最后接入 CI——这样你的文档体系也能像 Claude How To 一样在持续增长中保持一致的质感与可检索性。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考