Claude How To 内容风格指南从命名规范到 Markdown 自动化校验【免费下载链接】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-howtoClaude How Toclaude-howto是一个可视化、示例驱动的 Claude Code 教程仓库覆盖斜杠命令、Memory、Skills、Subagents、MCP、Hooks 等十大模块。其 STYLE_GUIDE.md 为所有贡献内容定义了统一的内容规范文件命名、文档骨架、标题与排版、表格与代码块、链接与交叉引用、Mermaid 图表、Emoji 边界、YAML frontmatter、语气与提交信息。阅读本文后你将完整掌握该仓库的内容写作约定并能结合 scripts/ 目录下的校验脚本与 pre-commit 配置理解每条规范是如何被自动化验证落地的。文件与目录命名规范风格指南对仓库的文件系统布局有明确约定这也是仓库根目录结构能被工具脚本识别的前提。课程目录两位数字前缀 kebab-case课程目录使用两位数字编号前缀加短横线小写描述词01-slash-commands/ 02-memory/ 03-skills/ 04-subagents/ 05-mcp/编号反映从入门到进阶的学习路径顺序。这一约定并非仅靠人工遵守交叉引用校验脚本会强制检查01-*到10-*的每一个编号目录都必须包含README.md见 scripts/check_cross_references.py#L95-L101缺失即报错missing README.md。文件命名对照表类型约定示例课程 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顶层文档大写.mdCATALOG.md、QUICK_REFERENCE.md、CONTRIBUTING.md图片资源kebab-casepr-slash-command.png、claude-howto-logo.svg对应仓库中的真实示例01-slash-commands/commit.md、02-memory/project-CLAUDE.md、06-hooks/format-code.sh、05-mcp/github-mcp.json 均严格遵循该表。三条硬性规则所有文件和目录名使用小写README.md、CATALOG.md等顶层文档除外使用连字符-作为单词分隔符禁止下划线或空格名称要描述性强且简洁。文档结构模板风格指南把文档分为三类并各自规定了严格的章节顺序。根 README 的 13 段顺序根目录 README.md 遵循以下顺序Logopicture元素含深色/浅色两套变体H1 标题引言 blockquote一句话价值主张Why This Guide? 章节含对比表格水平分割线---目录Table of Contents功能目录Feature Catalog快速导航学习路径Learning Path各功能章节Getting Started最佳实践 / 故障排查贡献 / 许可课程 README 的 10 段顺序每个课程的README.md遵循以下顺序H1 标题如# Slash Commands简短概述段落快速参考表可选架构图Mermaid详细章节H2实战示例编号4–6 个最佳实践Dos and Donts 表格故障排查Troubleshooting相关指南 / 官方文档文档元数据页脚01-slash-commands/README.md 即为遵循该骨架的实例Logopicture开头、H1 标题、Overview 概述、Built-in Commands Reference 表格、后续深入章节依次展开。功能/示例文件的顺序单个功能文件如optimize.md、pr.md按以下顺序组织YAML frontmatter如适用H1 标题用途/描述使用说明代码示例定制建议章节分隔符使用水平分割线---分隔文档的主要区域位置在引言 blockquote 之后以及逻辑上相互独立的部分之间--- ## New Major Section标题与文本格式标题层级层级用途示例#H1页面标题每篇文档仅一个# Slash Commands##H2主要章节## Best Practices###H3子章节### Adding a Skill####H4孙章节少用#### Configuration Options标题规则每篇文档只有一个 H1——仅用于页面标题禁止跳级——不能从 H2 直接跳到 H4标题要简短——目标 2–5 个词使用 sentence case——仅首词和专有名词大写例外功能名保持原样Emoji 前缀只允许出现在根 README 的章节标题上详见 Emoji 使用章节。这一条与自动化校验直接相关交叉引用校验脚本在生成锚点时会剥离 Emoji 字符并保留前导连字符以兼容## Learning Path这类带 Emoji 的标题锚点形如#-learning-path具体逻辑见 scripts/check_cross_references.py#L29-L50 中的heading_to_anchor()函数——它先移除 Emoji、变体选择符、零宽连接符等字符再小写化、去标点、空格转连字符、去除尾部连字符。也就是说标题里带 Emoji 不会破坏锚点链接但前提是使用仓库约定的标准 Emoji 集。强调样式样式使用场景示例加粗**text**关键术语、表格标签、重要概念**Installation**:斜体*text*技术术语首次出现、书籍/文档标题*frontmatter*行内代码text文件名、命令、配置值、代码引用CLAUDE.md用 Blockquote 做 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。段落段落保持简短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 层。表格标准格式与三种常用模式功能对比表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 |表格规则当第一列是行标签时加粗表头源码中管道符对齐非必须但推荐单元格内容简洁细节用链接承载单元格内的命令和文件路径用行内代码格式。表格单元格中的管道符必须转义——这是一条被自动化校验强制执行的规则。渲染校验脚本 scripts/check_markdown_rendering.py#L141-L183 中的rule_unescaped_pipe_in_table会统计每一行未被转义的|数量若与表头不一致例如[color|default]这类裸管道符写进了单元格就报unescaped-pipe-in-table错误修复方式是将字面量管道符写作\|。此外rule_backtick_in_inline_codeL117-L138会捕获单反引号行内代码内再套字面反引号这一渲染陷阱源自历史 PR #114 的真实缺陷模式规范写法是双反引号加空格text。代码块语言标签所有代码块必须带语言标签语言标签适用ShellbashCLI 命令、脚本PythonpythonPython 代码JavaScriptjavascriptJS 代码TypeScripttypescriptTS 代码JSONjson配置文件YAMLyamlfrontmatter、配置MarkdownmarkdownMarkdown 示例SQLsql数据库查询纯文本无标签预期输出、目录树代码块惯例# 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/代码块闭合同样被自动化检查覆盖scripts/check_cross_references.py#L91-L93 会统计文件内位于行首的三反引号围栏数量出现奇数个未闭合即报unmatched code fences。链接与交叉引用内部链接相对路径所有内部链接使用相对路径[Slash Commands](https://link.gitcode.com/i/dd9b61b4a4a2c915f29c4ffb25bd8fd7) [Skills Guide](https://link.gitcode.com/i/d842ed4182087d555845f07ff75bfb0a) [Memory Architecture](https://link.gitcode.com/i/c140e660dfff7430c0e05f8484e52efa)从课程目录回到根目录或兄弟目录[Back to main guide](https://link.gitcode.com/i/ff12086662b0fc7df3ba4a35475ebf41) Related: Skills外部链接使用完整 URL 且锚文本必须有描述性例如指向 Anthropic 官方 Claude Code 文档。规则是永远不要用 click here 或 this link 作为锚文本锚文本必须脱离上下文也能读懂含义。章节锚点使用 GitHub 风格的锚点[Feature Catalog](#-feature-catalog) [Best Practices](#best-practices)相关指南模式——课程结尾统一收束为相关指南小节## Related Guides - [Slash Commands](https://link.gitcode.com/i/dd9b61b4a4a2c915f29c4ffb25bd8fd7) - Quick shortcuts - [Memory](https://link.gitcode.com/i/5d3f64cc66302d10c2da08432d7a56be) - Persistent context - [Skills](https://link.gitcode.com/i/d842ed4182087d555845f07ff75bfb0a) - Reusable capabilities链接规范的自动化执行风格指南中内部链接必须可解析、锚点必须对应真实标题两条规则由 scripts/check_cross_references.py 整体实现其校验逻辑可归纳为相对.md链接正则提取所有.md链接解析为绝对路径后要求a必须落在仓库根目录之内b文件必须真实存在否则报broken cross-referenceL72-L78页内锚点提取所有#anchor链接与文档全部标题经heading_to_anchor()生成的锚点集合比对不匹配则报broken anchorL80-L89扫描前预处理先用strip_code_blocks()剥离围栏代码块和行内代码L53-L59避免文档示例里的伪链接造成误报——这与风格指南代码块内可以写示例链接的隐含约定相呼应目录结构兜底01-*至10-*每个编号课程目录必须含README.mdL95-L101。外部 URL 则由 scripts/check_links.py 并发检查可达性内置对徽章域名、占位域名、示例域名的跳过规则L23-L49。值得注意的是它对 pre-commit 阶段采取宽松策略发现死链会报告但不阻断提交只有设置LINK_CHECK_STRICT1CI 中使用才强制失败L124-L130。Mermaid 图表与标准色板风格指南要求所有图表统一使用 Mermaid支持的类型为graph TB/graph LR——架构、层级、流程sequenceDiagram——交互流程timeline——时间序列。样式约定与标准色板使用 style 块应用统一配色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颜色十六进制用途浅蓝#e1f5fe主要组件、输入浅粉#fce4ec处理、中间件浅绿#e8f5e9输出、结果浅黄#fff9c4配置、可选浅紫#f3e5f5用户界面、UI图表规则节点标签使用[Label text]形式支持特殊字符标签内换行用br/保持图表简洁最多 10–12 个节点图下方加一句简短文字描述兼顾可访问性层级图用自上而下TB工作流用自左而右LR。这些语法并非仅靠人工把关。scripts/check_mermaid.py 会用正则mermaid\n(.*?)抽取每个 Markdown 文件中的全部图表块逐一写入临时.mmd文件并调用 mermaid-cli 的mmdc渲染器做真实语法校验L44-L70渲染失败即按文件 块序号报出具体错误若本机未安装mmdc则打印警告后跳过L17-L21而 CI 环境通过MERMAID_PUPPETEER_NO_SANDBOX环境变量注入 Puppeteer 的--no-sandbox参数以适配 Linux 无头环境L26-L36。Emoji 使用边界风格指南对 Emoji 采取稀疏且有目的的策略仅允许出现在特定上下文中上下文Emoji示例根 README 章节标题分类图标## Learning Path技能等级指示彩色圆点 入门、 进阶、 高级Dos and Donts对勾/叉号✅ 推荐、❌ 反模式复杂度评级星号⭐⭐⭐标准 Emoji 集Emoji含义学习、指南、文档⚡快速上手、快速参考功能、快速参考学习路径统计、对比安装、快捷命令入门级别中级级别高级级别✅推荐实践❌避免/反模式⭐复杂度评级单位规则正文段落中永远不使用 Emoji仅在根 README 的标题中使用 Emoji课程 README 不用不加装饰性 Emoji——每个 Emoji 都必须承载语义用法与上表保持一致。这条规范解释了为何锚点校验函数要专门处理 Emoji 剥离标题中的 、 等 Emoji 会被 GitHub 锚点规则丢弃并留下前导连字符仓库的锚点生成逻辑heading_to_anchor()与之逐位对齐保证 TOC 与正文锚点链接不会失效。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-invocable: false # 从用户菜单隐藏 context: fork # 在隔离子代理中运行 agent: Explore # context: fork 时的代理类型 ---规则frontmatter 放在文件最顶部name字段使用kebab-casedescription限制为一句话只写需要的字段不堆砌。仓库中的真实功能文件均可在此约定下找到对应物例如 04-subagents/code-reviewer.md 和 03-skills/refactor/SKILL.md。frontmatter 的 YAML 合法性还由 pre-commit 的check-yaml钩子--allow-multiple-documents参数允许 frontmatter 分隔兜底校验见 .pre-commit-config.yaml#L39-L55。图片与媒体Logo 的picture模式所有以 Logo 开头的文档使用picture元素实现深色/浅色模式自适应各课程 README 与 STYLE_GUIDE.md 自身开头均以此开头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截图存放在所属课程目录中如01-slash-commands/pr-slash-command.png真实文件见 01-slash-commands/pr-slash-command.png文件名使用 kebab-case提供描述性 alt 文本架构图优先 SVG界面截图用 PNG。规则图片必须提供 alt 文本控制图片体积PNG 小于 500KB——pre-commit 的check-added-large-files钩子将上限设为 1000KB.pre-commit-config.yaml#L51-L53比风格指南的推荐值更宽松写作时仍应以 500KB 为目标图片引用使用相对路径图片放在引用它的文档同目录共享图片放assets/。语气与文风写作风格专业但亲切——技术准确但不堆砌术语主动语态——写 Create a file不写 A file should be created直接祈使——写 Run this command不写 You might want to run this command面向初学者——默认读者熟悉编程但不熟悉 Claude Code。内容原则原则示例Show, dont tell给可运行的示例而非抽象描述渐进式复杂度先简单后在后续章节加深解释为什么写用 memory 是为了……因为……而不只是用 memory 是为了……可直接复制粘贴每个代码块粘贴后必须能直接工作真实场景用实用场景不用牵强造的例子术语表用 Claude Code不用 Claude CLI 或 the tool用 skill不用 custom command——那是遗留术语编号章节称为 lesson 或 guide单个功能文件称为 example。提交信息Conventional Commits提交信息遵循 Conventional Commits 规范type(scope): descriptionType 取值Type用途feat新功能、新示例或新指南fix缺陷修复、勘误、断链修复docs文档改进refactor不改变行为的重构style仅格式化变更test测试新增或变更chore构建、依赖、CIScope 取值以课程名或文件区域作为 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文档元数据页脚课程 README 以元数据块收尾--- **Last Updated**: July 29, 2026 **Claude Code Version**: 2.1.220 **Compatible Models**: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5日期用月 日 年格式如 May 20, 2026功能变更时同步更新版本号列出全部兼容模型。注意适用前提本风格指南标注的基准是 Claude Code 2.1.2202026 年 7 月 29 日而仓库根 README.md 的版本徽章显示仓库整体已同步至更新的 2.x 版本——引用具体命令行为时以各课程 README 中标注的版本号如v2.1.212、v2.1.216为准。作者自检清单与自动化校验链提交前 16 项自检风格指南为作者提供了提交前核对清单文件/目录名使用 kebab-case文档以 H1 标题开头每文件一个标题层级正确无跳级所有代码块带语言标签代码示例可直接复制粘贴运行内部链接使用相对路径外部链接有描述性锚文本表格格式正确Emoji 符合标准集如果用到Mermaid 图表使用标准色板不含敏感信息API 密钥、凭据YAML frontmatter 合法如适用图片有 alt 文本段落简短聚焦相关指南小节链接到相关课程提交信息符合 Conventional Commits 格式规范如何被 pre-commit 与 CI 强制执行上述清单并非停留在纸面。.pre-commit-config.yaml 把风格指南的每一类约束都接到了钩子上CONTRIBUTING.md 明确写道All five checks must pass before a PR will be accepted五项文档检查全部通过PR 才会被接受。本地环境搭建与钩子构成如下# Python 工具链uv 是项目包管理器 pip install uv uv venv source .venv/bin/activate uv pip install -r scripts/requirements-dev.txt # Markdown linterNode.js npm install -g markdownlint-cli # Mermaid 图表校验器Node.js npm install -g mermaid-js/mermaid-cli # 安装并激活 pre-commit uv pip install pre-commit pre-commit install # 验证环境 pre-commit run --all-files文档质量相关的钩子与风格指南章节的对应关系钩子校验脚本/工具对应的风格指南章节markdown-lintmarkdownlint --config .markdownlint.json排版细节列表/标题/空格cross-referencesscripts/check_cross_references.py命名规范、链接与交叉引用mermaid-syntaxscripts/check_mermaid.pyMermaid 图表link-checkscripts/check_links.py外部链接可达性markdown-renderingscripts/check_markdown_rendering.py表格管道转义、行内代码反引号、代码围栏闭合其中 .markdownlint.json 采用默认全关、按需开启策略仅启用 10 条与风格指南强相关的规则MD009、MD010行尾空格与硬制表符、MD011连续空行、MD014命令应写成行内代码、MD018/MD019/MD037ATX 标题两侧空格规范、MD038/MD039行内代码/强调符内部空格、MD047文件以单个换行结尾。这与风格指南段落间空行列表前后空行标题简短等排版条款一一对应。此外 scripts/check_markdown_rendering.py 以规则注册表形式组织四条渲染规则L226-L231文件头部注释给出了扩展方式新增规则时写一个(file_path, content) - list[str]函数、追加到RULES列表并在scripts/tests/下补充测试夹具——风格指南的渲染类条款因此是可持续扩展的工程资产而非一次性约定。配置中还有一个多语言细节除主文档外的越南语vi/与日语ja/翻译目录也分别挂了 markdown-lint、交叉引用、Mermaid、链接检查钩子.pre-commit-config.yaml#L115-L181意味着风格指南的约束被同步施加到各语言版本目录如 vi/、ja/、zh/、uk/上保证多语言内容遵循同一套排版与链接规范。小结Claude How To 的风格指南本质上是一份可执行的内容规范它用表格化、清单化的方式把命名、结构、排版、图表、Emoji、frontmatter、语气和提交信息约定成文再借助 scripts/ 下的四个校验脚本与 pre-commit 配置 把关键条款变成提交门禁。对贡献者而言记住三件事即可落地一是对照本文的模板与表格写作二是提交前跑pre-commit run --all-files三是用作者清单做最后核对。这样产出的内容与仓库现有的十门课程、多语言版本在观感和可维护性上保持一致。【免费下载链接】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），仅供参考 
长河君 · 2026/9/10 6:51:11 · 阅读 1.2k Claude How To 内容风格指南：从命名规范到 Markdown 自动化校验
Claude How To 内容风格指南从命名规范到 Markdown 自动化校验【免费下载链接】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-howtoClaude How Toclaude-howto是一个可视化、示例驱动的 Claude Code 教程仓库覆盖斜杠命令、Memory、Skills、Subagents、MCP、Hooks 等十大模块。其 STYLE_GUIDE.md 为所有贡献内容定义了统一的内容规范文件命名、文档骨架、标题与排版、表格与代码块、链接与交叉引用、Mermaid 图表、Emoji 边界、YAML frontmatter、语气与提交信息。阅读本文后你将完整掌握该仓库的内容写作约定并能结合 scripts/ 目录下的校验脚本与 pre-commit 配置理解每条规范是如何被自动化验证落地的。文件与目录命名规范风格指南对仓库的文件系统布局有明确约定这也是仓库根目录结构能被工具脚本识别的前提。课程目录两位数字前缀 kebab-case课程目录使用两位数字编号前缀加短横线小写描述词01-slash-commands/ 02-memory/ 03-skills/ 04-subagents/ 05-mcp/编号反映从入门到进阶的学习路径顺序。这一约定并非仅靠人工遵守交叉引用校验脚本会强制检查01-*到10-*的每一个编号目录都必须包含README.md见 scripts/check_cross_references.py#L95-L101缺失即报错missing README.md。文件命名对照表类型约定示例课程 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顶层文档大写.mdCATALOG.md、QUICK_REFERENCE.md、CONTRIBUTING.md图片资源kebab-casepr-slash-command.png、claude-howto-logo.svg对应仓库中的真实示例01-slash-commands/commit.md、02-memory/project-CLAUDE.md、06-hooks/format-code.sh、05-mcp/github-mcp.json 均严格遵循该表。三条硬性规则所有文件和目录名使用小写README.md、CATALOG.md等顶层文档除外使用连字符-作为单词分隔符禁止下划线或空格名称要描述性强且简洁。文档结构模板风格指南把文档分为三类并各自规定了严格的章节顺序。根 README 的 13 段顺序根目录 README.md 遵循以下顺序Logopicture元素含深色/浅色两套变体H1 标题引言 blockquote一句话价值主张Why This Guide? 章节含对比表格水平分割线---目录Table of Contents功能目录Feature Catalog快速导航学习路径Learning Path各功能章节Getting Started最佳实践 / 故障排查贡献 / 许可课程 README 的 10 段顺序每个课程的README.md遵循以下顺序H1 标题如# Slash Commands简短概述段落快速参考表可选架构图Mermaid详细章节H2实战示例编号4–6 个最佳实践Dos and Donts 表格故障排查Troubleshooting相关指南 / 官方文档文档元数据页脚01-slash-commands/README.md 即为遵循该骨架的实例Logopicture开头、H1 标题、Overview 概述、Built-in Commands Reference 表格、后续深入章节依次展开。功能/示例文件的顺序单个功能文件如optimize.md、pr.md按以下顺序组织YAML frontmatter如适用H1 标题用途/描述使用说明代码示例定制建议章节分隔符使用水平分割线---分隔文档的主要区域位置在引言 blockquote 之后以及逻辑上相互独立的部分之间--- ## New Major Section标题与文本格式标题层级层级用途示例#H1页面标题每篇文档仅一个# Slash Commands##H2主要章节## Best Practices###H3子章节### Adding a Skill####H4孙章节少用#### Configuration Options标题规则每篇文档只有一个 H1——仅用于页面标题禁止跳级——不能从 H2 直接跳到 H4标题要简短——目标 2–5 个词使用 sentence case——仅首词和专有名词大写例外功能名保持原样Emoji 前缀只允许出现在根 README 的章节标题上详见 Emoji 使用章节。这一条与自动化校验直接相关交叉引用校验脚本在生成锚点时会剥离 Emoji 字符并保留前导连字符以兼容## Learning Path这类带 Emoji 的标题锚点形如#-learning-path具体逻辑见 scripts/check_cross_references.py#L29-L50 中的heading_to_anchor()函数——它先移除 Emoji、变体选择符、零宽连接符等字符再小写化、去标点、空格转连字符、去除尾部连字符。也就是说标题里带 Emoji 不会破坏锚点链接但前提是使用仓库约定的标准 Emoji 集。强调样式样式使用场景示例加粗**text**关键术语、表格标签、重要概念**Installation**:斜体*text*技术术语首次出现、书籍/文档标题*frontmatter*行内代码text文件名、命令、配置值、代码引用CLAUDE.md用 Blockquote 做 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。段落段落保持简短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 层。表格标准格式与三种常用模式功能对比表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 |表格规则当第一列是行标签时加粗表头源码中管道符对齐非必须但推荐单元格内容简洁细节用链接承载单元格内的命令和文件路径用行内代码格式。表格单元格中的管道符必须转义——这是一条被自动化校验强制执行的规则。渲染校验脚本 scripts/check_markdown_rendering.py#L141-L183 中的rule_unescaped_pipe_in_table会统计每一行未被转义的|数量若与表头不一致例如[color|default]这类裸管道符写进了单元格就报unescaped-pipe-in-table错误修复方式是将字面量管道符写作\|。此外rule_backtick_in_inline_codeL117-L138会捕获单反引号行内代码内再套字面反引号这一渲染陷阱源自历史 PR #114 的真实缺陷模式规范写法是双反引号加空格text。代码块语言标签所有代码块必须带语言标签语言标签适用ShellbashCLI 命令、脚本PythonpythonPython 代码JavaScriptjavascriptJS 代码TypeScripttypescriptTS 代码JSONjson配置文件YAMLyamlfrontmatter、配置MarkdownmarkdownMarkdown 示例SQLsql数据库查询纯文本无标签预期输出、目录树代码块惯例# 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/代码块闭合同样被自动化检查覆盖scripts/check_cross_references.py#L91-L93 会统计文件内位于行首的三反引号围栏数量出现奇数个未闭合即报unmatched code fences。链接与交叉引用内部链接相对路径所有内部链接使用相对路径[Slash Commands](https://link.gitcode.com/i/dd9b61b4a4a2c915f29c4ffb25bd8fd7) [Skills Guide](https://link.gitcode.com/i/d842ed4182087d555845f07ff75bfb0a) [Memory Architecture](https://link.gitcode.com/i/c140e660dfff7430c0e05f8484e52efa)从课程目录回到根目录或兄弟目录[Back to main guide](https://link.gitcode.com/i/ff12086662b0fc7df3ba4a35475ebf41) Related: Skills外部链接使用完整 URL 且锚文本必须有描述性例如指向 Anthropic 官方 Claude Code 文档。规则是永远不要用 click here 或 this link 作为锚文本锚文本必须脱离上下文也能读懂含义。章节锚点使用 GitHub 风格的锚点[Feature Catalog](#-feature-catalog) [Best Practices](#best-practices)相关指南模式——课程结尾统一收束为相关指南小节## Related Guides - [Slash Commands](https://link.gitcode.com/i/dd9b61b4a4a2c915f29c4ffb25bd8fd7) - Quick shortcuts - [Memory](https://link.gitcode.com/i/5d3f64cc66302d10c2da08432d7a56be) - Persistent context - [Skills](https://link.gitcode.com/i/d842ed4182087d555845f07ff75bfb0a) - Reusable capabilities链接规范的自动化执行风格指南中内部链接必须可解析、锚点必须对应真实标题两条规则由 scripts/check_cross_references.py 整体实现其校验逻辑可归纳为相对.md链接正则提取所有.md链接解析为绝对路径后要求a必须落在仓库根目录之内b文件必须真实存在否则报broken cross-referenceL72-L78页内锚点提取所有#anchor链接与文档全部标题经heading_to_anchor()生成的锚点集合比对不匹配则报broken anchorL80-L89扫描前预处理先用strip_code_blocks()剥离围栏代码块和行内代码L53-L59避免文档示例里的伪链接造成误报——这与风格指南代码块内可以写示例链接的隐含约定相呼应目录结构兜底01-*至10-*每个编号课程目录必须含README.mdL95-L101。外部 URL 则由 scripts/check_links.py 并发检查可达性内置对徽章域名、占位域名、示例域名的跳过规则L23-L49。值得注意的是它对 pre-commit 阶段采取宽松策略发现死链会报告但不阻断提交只有设置LINK_CHECK_STRICT1CI 中使用才强制失败L124-L130。Mermaid 图表与标准色板风格指南要求所有图表统一使用 Mermaid支持的类型为graph TB/graph LR——架构、层级、流程sequenceDiagram——交互流程timeline——时间序列。样式约定与标准色板使用 style 块应用统一配色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颜色十六进制用途浅蓝#e1f5fe主要组件、输入浅粉#fce4ec处理、中间件浅绿#e8f5e9输出、结果浅黄#fff9c4配置、可选浅紫#f3e5f5用户界面、UI图表规则节点标签使用[Label text]形式支持特殊字符标签内换行用br/保持图表简洁最多 10–12 个节点图下方加一句简短文字描述兼顾可访问性层级图用自上而下TB工作流用自左而右LR。这些语法并非仅靠人工把关。scripts/check_mermaid.py 会用正则mermaid\n(.*?)抽取每个 Markdown 文件中的全部图表块逐一写入临时.mmd文件并调用 mermaid-cli 的mmdc渲染器做真实语法校验L44-L70渲染失败即按文件 块序号报出具体错误若本机未安装mmdc则打印警告后跳过L17-L21而 CI 环境通过MERMAID_PUPPETEER_NO_SANDBOX环境变量注入 Puppeteer 的--no-sandbox参数以适配 Linux 无头环境L26-L36。Emoji 使用边界风格指南对 Emoji 采取稀疏且有目的的策略仅允许出现在特定上下文中上下文Emoji示例根 README 章节标题分类图标## Learning Path技能等级指示彩色圆点 入门、 进阶、 高级Dos and Donts对勾/叉号✅ 推荐、❌ 反模式复杂度评级星号⭐⭐⭐标准 Emoji 集Emoji含义学习、指南、文档⚡快速上手、快速参考功能、快速参考学习路径统计、对比安装、快捷命令入门级别中级级别高级级别✅推荐实践❌避免/反模式⭐复杂度评级单位规则正文段落中永远不使用 Emoji仅在根 README 的标题中使用 Emoji课程 README 不用不加装饰性 Emoji——每个 Emoji 都必须承载语义用法与上表保持一致。这条规范解释了为何锚点校验函数要专门处理 Emoji 剥离标题中的 、 等 Emoji 会被 GitHub 锚点规则丢弃并留下前导连字符仓库的锚点生成逻辑heading_to_anchor()与之逐位对齐保证 TOC 与正文锚点链接不会失效。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-invocable: false # 从用户菜单隐藏 context: fork # 在隔离子代理中运行 agent: Explore # context: fork 时的代理类型 ---规则frontmatter 放在文件最顶部name字段使用kebab-casedescription限制为一句话只写需要的字段不堆砌。仓库中的真实功能文件均可在此约定下找到对应物例如 04-subagents/code-reviewer.md 和 03-skills/refactor/SKILL.md。frontmatter 的 YAML 合法性还由 pre-commit 的check-yaml钩子--allow-multiple-documents参数允许 frontmatter 分隔兜底校验见 .pre-commit-config.yaml#L39-L55。图片与媒体Logo 的picture模式所有以 Logo 开头的文档使用picture元素实现深色/浅色模式自适应各课程 README 与 STYLE_GUIDE.md 自身开头均以此开头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截图存放在所属课程目录中如01-slash-commands/pr-slash-command.png真实文件见 01-slash-commands/pr-slash-command.png文件名使用 kebab-case提供描述性 alt 文本架构图优先 SVG界面截图用 PNG。规则图片必须提供 alt 文本控制图片体积PNG 小于 500KB——pre-commit 的check-added-large-files钩子将上限设为 1000KB.pre-commit-config.yaml#L51-L53比风格指南的推荐值更宽松写作时仍应以 500KB 为目标图片引用使用相对路径图片放在引用它的文档同目录共享图片放assets/。语气与文风写作风格专业但亲切——技术准确但不堆砌术语主动语态——写 Create a file不写 A file should be created直接祈使——写 Run this command不写 You might want to run this command面向初学者——默认读者熟悉编程但不熟悉 Claude Code。内容原则原则示例Show, dont tell给可运行的示例而非抽象描述渐进式复杂度先简单后在后续章节加深解释为什么写用 memory 是为了……因为……而不只是用 memory 是为了……可直接复制粘贴每个代码块粘贴后必须能直接工作真实场景用实用场景不用牵强造的例子术语表用 Claude Code不用 Claude CLI 或 the tool用 skill不用 custom command——那是遗留术语编号章节称为 lesson 或 guide单个功能文件称为 example。提交信息Conventional Commits提交信息遵循 Conventional Commits 规范type(scope): descriptionType 取值Type用途feat新功能、新示例或新指南fix缺陷修复、勘误、断链修复docs文档改进refactor不改变行为的重构style仅格式化变更test测试新增或变更chore构建、依赖、CIScope 取值以课程名或文件区域作为 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文档元数据页脚课程 README 以元数据块收尾--- **Last Updated**: July 29, 2026 **Claude Code Version**: 2.1.220 **Compatible Models**: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5日期用月 日 年格式如 May 20, 2026功能变更时同步更新版本号列出全部兼容模型。注意适用前提本风格指南标注的基准是 Claude Code 2.1.2202026 年 7 月 29 日而仓库根 README.md 的版本徽章显示仓库整体已同步至更新的 2.x 版本——引用具体命令行为时以各课程 README 中标注的版本号如v2.1.212、v2.1.216为准。作者自检清单与自动化校验链提交前 16 项自检风格指南为作者提供了提交前核对清单文件/目录名使用 kebab-case文档以 H1 标题开头每文件一个标题层级正确无跳级所有代码块带语言标签代码示例可直接复制粘贴运行内部链接使用相对路径外部链接有描述性锚文本表格格式正确Emoji 符合标准集如果用到Mermaid 图表使用标准色板不含敏感信息API 密钥、凭据YAML frontmatter 合法如适用图片有 alt 文本段落简短聚焦相关指南小节链接到相关课程提交信息符合 Conventional Commits 格式规范如何被 pre-commit 与 CI 强制执行上述清单并非停留在纸面。.pre-commit-config.yaml 把风格指南的每一类约束都接到了钩子上CONTRIBUTING.md 明确写道All five checks must pass before a PR will be accepted五项文档检查全部通过PR 才会被接受。本地环境搭建与钩子构成如下# Python 工具链uv 是项目包管理器 pip install uv uv venv source .venv/bin/activate uv pip install -r scripts/requirements-dev.txt # Markdown linterNode.js npm install -g markdownlint-cli # Mermaid 图表校验器Node.js npm install -g mermaid-js/mermaid-cli # 安装并激活 pre-commit uv pip install pre-commit pre-commit install # 验证环境 pre-commit run --all-files文档质量相关的钩子与风格指南章节的对应关系钩子校验脚本/工具对应的风格指南章节markdown-lintmarkdownlint --config .markdownlint.json排版细节列表/标题/空格cross-referencesscripts/check_cross_references.py命名规范、链接与交叉引用mermaid-syntaxscripts/check_mermaid.pyMermaid 图表link-checkscripts/check_links.py外部链接可达性markdown-renderingscripts/check_markdown_rendering.py表格管道转义、行内代码反引号、代码围栏闭合其中 .markdownlint.json 采用默认全关、按需开启策略仅启用 10 条与风格指南强相关的规则MD009、MD010行尾空格与硬制表符、MD011连续空行、MD014命令应写成行内代码、MD018/MD019/MD037ATX 标题两侧空格规范、MD038/MD039行内代码/强调符内部空格、MD047文件以单个换行结尾。这与风格指南段落间空行列表前后空行标题简短等排版条款一一对应。此外 scripts/check_markdown_rendering.py 以规则注册表形式组织四条渲染规则L226-L231文件头部注释给出了扩展方式新增规则时写一个(file_path, content) - list[str]函数、追加到RULES列表并在scripts/tests/下补充测试夹具——风格指南的渲染类条款因此是可持续扩展的工程资产而非一次性约定。配置中还有一个多语言细节除主文档外的越南语vi/与日语ja/翻译目录也分别挂了 markdown-lint、交叉引用、Mermaid、链接检查钩子.pre-commit-config.yaml#L115-L181意味着风格指南的约束被同步施加到各语言版本目录如 vi/、ja/、zh/、uk/上保证多语言内容遵循同一套排版与链接规范。小结Claude How To 的风格指南本质上是一份可执行的内容规范它用表格化、清单化的方式把命名、结构、排版、图表、Emoji、frontmatter、语气和提交信息约定成文再借助 scripts/ 下的四个校验脚本与 pre-commit 配置 把关键条款变成提交门禁。对贡献者而言记住三件事即可落地一是对照本文的模板与表格写作二是提交前跑pre-commit run --all-files三是用作者清单做最后核对。这样产出的内容与仓库现有的十门课程、多语言版本在观感和可维护性上保持一致。【免费下载链接】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），仅供参考