claude-howto/zh/CONTRIBUTING.md

为 Claude How To 贡献内容

感谢你愿意为这个项目做出贡献。这份指南会帮助你更高效地参与协作。

关于本项目

Claude How To 是一份面向 Claude Code 的可视化、以示例驱动的学习指南。我们提供：

• Mermaid 图表，解释各项功能的工作方式
• 可直接投入使用的模板，你可以马上复制到项目中
• 带上下文和最佳实践的真实案例
• 从入门到进阶的渐进式学习路径

贡献类型

1. 新示例或新模板

为已有功能补充示例，例如 slash commands、skills、hooks 等：

• 可直接复制粘贴的代码
• 清楚说明工作原理
• 使用场景与收益
• 排障提示

2. 文档改进

• 澄清容易混淆的内容
• 修复拼写和语法问题
• 补充缺失信息
• 优化代码示例

3. 功能指南

为新的 Claude Code 功能编写指南：

• 分步骤教程
• 架构图
• 常见模式和反模式
• 真实工作流

4. Bug 报告

报告你遇到的问题：

• 你原本期望发生什么
• 实际发生了什么
• 复现步骤
• 相关的 Claude Code 版本和操作系统

5. 反馈与建议

帮助我们改进这份指南：

• 建议更好的解释方式
• 指出覆盖不足的地方
• 推荐新章节或重组结构

快速开始

1. Fork 并克隆

git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto

2. 创建分支

使用能说明用途的分支名：

git checkout -b add/feature-name
git checkout -b fix/issue-description
git checkout -b docs/improvement-area

3. 配置开发环境

pre-commit hooks 会在本地、每次提交前运行与 CI 相同的检查。PR 被接受前，下面四项检查都必须通过。

必需依赖：

# Python 工具链（uv 是本项目的包管理器）
pip install uv
uv venv
source .venv/bin/activate
uv pip install -r scripts/requirements-dev.txt

# Markdown lint 工具（Node.js）
npm install -g markdownlint-cli

# Mermaid 图表校验器（Node.js）
npm install -g @mermaid-js/mermaid-cli

# 安装 pre-commit 并启用 hooks
uv pip install pre-commit
pre-commit install

验证配置：

pre-commit run --all-files

每次提交都会运行这些 hooks：

Hook	检查内容
markdown-lint	Markdown 格式和结构
cross-references	相对链接、锚点、代码围栏
mermaid-syntax	所有 ```mermaid 代码块是否可正确解析
link-check	外部 URL 是否可访问
build-epub	.md 变更时 EPUB 是否能无错误生成

目录结构

├── 01-slash-commands/      # 用户手动触发的快捷命令
├── 02-memory/              # 持久上下文示例
├── 03-skills/              # 可复用能力
├── 04-subagents/           # 专门化 AI 助手
├── 05-mcp/                 # Model Context Protocol 示例
├── 06-hooks/               # 事件驱动自动化
├── 07-plugins/             # 打包功能集合
├── 08-checkpoints/         # 会话快照
├── 09-advanced-features/   # 规划、思考、后台任务
├── 10-cli/                 # CLI 参考
├── scripts/                # 构建与工具脚本
└── README.md            # 主指南

如何贡献示例

添加 Slash Command

1. 在 01-slash-commands/ 中创建一个 .md 文件
2. 包含：
   • 清晰说明用途
   • 使用场景
   • 安装说明
   • 使用示例
   • 自定义技巧
3. 更新 01-slash-commands/README.md

添加 Skill

1. 在 03-skills/ 中创建一个目录
2. 包含：
   • SKILL.md - 主文档
   • scripts/ - 如有需要可放辅助脚本
   • templates/ - 提示词模板
   • README 中的示例用法
3. 更新 03-skills/README.md

添加 Subagent

1. 在 04-subagents/ 中创建一个 .md 文件
2. 包含：
   • agent 的目标和能力
   • 系统提示词结构
   • 示例使用场景
   • 集成示例
3. 更新 04-subagents/README.md

添加 MCP 配置

1. 在 05-mcp/ 中创建一个 .json 文件
2. 包含：
   • 配置说明
   • 所需环境变量
   • 配置步骤
   • 使用示例
3. 更新 05-mcp/README.md

添加 Hook

1. 在 06-hooks/ 中创建一个 .sh 文件
2. 包含：
   • shebang 和说明
   • 逻辑清晰的注释
   • 错误处理
   • 安全考虑
3. 更新 06-hooks/README.md

编写规范

Markdown 风格

• 使用清晰的标题层级（章节用 H2，小节用 H3）
• 段落保持简短且聚焦
• 列表用项目符号
• 代码块要标明语言
• 各章节之间保留空行

代码示例

• 示例要能直接复制粘贴
• 为不明显的逻辑添加注释
• 同时提供简单版和进阶版
• 展示真实使用场景
• 标出可能的坑

文档写作

• 解释“为什么”，而不只是“是什么”
• 包含前置条件
• 添加排障章节
• 链接相关主题
• 保持对初学者友好

JSON/YAML

• 统一缩进风格（2 或 4 个空格）
• 为配置添加注释
• 包含验证示例

图表

• 尽量使用 Mermaid
• 保持图表简洁易读
• 在图表下方补充说明
• 链接到相关章节

Commit 规范

使用 conventional commit 格式：

type(scope): description

[optional body]

类型包括：

• feat：新功能或新示例
• fix：修复或更正
• docs：文档变更
• refactor：代码重构
• style：格式调整
• test：新增或修改测试
• chore：构建、依赖等

示例：

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 已更新（本地和根目录）
• 不包含敏感信息（API key、凭据）
• 示例经过测试并可运行
• 链接已验证且正确
• 文件权限正确（脚本可执行）
• Commit 信息清晰且有描述性

本地测试

# 运行所有 pre-commit 检查（与 CI 相同）
pre-commit run --all-files

# 查看改动
git diff

Pull Request 流程

1. 创建带有清晰说明的 PR：

   • 这次提交做了什么？
   • 为什么需要它？
   • 是否有关联 issue？

2. 补充相关细节：

   • 新功能？请说明使用场景
   • 文档？请说明改进点
   • 示例？展示前后对比

3. 关联 issue：

   • 使用 Closes #123 自动关闭相关 issue

4. 耐心等待审查：

   • 维护者可能会提出改进建议
   • 根据反馈迭代
   • 最终决定由维护者负责

Code Review 流程

审查者会检查：

• 准确性：描述是否与实际一致？
• 质量：是否达到生产可用？
• 一致性：是否符合项目模式？
• 文档：是否清晰完整？
• 安全性：是否存在漏洞？

报告问题

Bug 报告

请包含：

• Claude Code 版本
• 操作系统
• 复现步骤
• 预期行为
• 实际行为
• 如有必要，附上截图

功能请求

请包含：

• 使用场景或要解决的问题
• 建议方案
• 你考虑过的替代方案
• 额外上下文

文档问题

请包含：

• 哪里令人困惑或缺失
• 建议如何改进
• 示例或参考资料

项目政策

敏感信息

• 永远不要提交 API key、token 或凭据
• 示例中使用占位符
• 为配置文件提供 .env.example
• 文档中说明所需环境变量

代码质量

• 示例要聚焦且易读
• 避免过度设计
• 对不明显的逻辑添加注释
• 提交前充分测试

知识产权

• 原创内容归作者所有
• 项目采用教育用途许可证
• 尊重已有版权
• 需要时注明来源

获取帮助

• 提问：在 GitHub Issues 中发起 discussion
• 通用帮助：先查看现有文档
• 开发帮助：参考类似示例
• Code Review：在 PR 中 @ 维护者

认可

贡献者会被收录在：

• README.md 的 Contributors 部分
• GitHub contributors 页面
• Commit 历史

安全

在贡献示例和文档时，请遵守安全编码实践：

• 绝不要硬编码密钥或 API key - 使用环境变量
• 提示安全影响 - 标出潜在风险
• 使用安全默认值 - 默认启用安全功能
• 验证输入 - 展示正确的输入校验和清理方式
• 加入安全提示 - 记录安全注意事项

如遇安全问题，请参见 SECURITY.md 获取漏洞报告流程。

行为准则

我们承诺打造一个热情且包容的社区。请阅读 CODE_OF_CONDUCT.md 查看完整社区标准。

简要来说：

• 保持尊重和包容
• 愉快地接受反馈
• 帮助他人成长和学习
• 避免骚扰或歧视
• 向维护者报告问题

所有贡献者都应遵守这份准则，并以善意和尊重对待彼此。

许可证

为本项目贡献内容，即表示你同意你的贡献将按 MIT License 许可。详情见 LICENSE 文件。

有问题？

• 查看 README.md
• 阅读 LEARNING-ROADMAP.md
• 查看已有示例
• 发起 issue 讨论

感谢你的贡献！