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

关于本项目

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

贡献类型

1. 新示例或新模板

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

2. 文档改进

3. 功能指南

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

4. Bug 报告

报告你遇到的问题：

5. 反馈与建议

帮助我们改进这份指南：

快速开始

1. Fork 并克隆

git clone YOUR_REPO
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 风格

代码示例

文档写作

JSON/YAML

图表

Commit 规范

使用 conventional commit 格式：

type(scope): description

[optional body]

类型包括：

示例：

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

提交前检查

清单

本地测试

# 运行所有 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 报告

请包含：

功能请求

请包含：

文档问题

请包含：

项目政策

敏感信息

代码质量

知识产权

获取帮助

认可

贡献者会被收录在：

安全

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

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

行为准则

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

简要来说：

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

许可证

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

有问题？

感谢你的贡献！