<picture>
  <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
</picture>

# 为 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 并克隆
```bash
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto
```

### 2. 创建分支
使用能说明用途的分支名：
```bash
git checkout -b add/feature-name
git checkout -b fix/issue-description
git checkout -b docs/improvement-area
```

### 3. 配置开发环境

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

**必需依赖：**

```bash
# 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
```

**验证配置：**

```bash
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 信息清晰且有描述性

### 本地测试
```bash
# 运行所有 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](SECURITY.md) 获取漏洞报告流程。

## 行为准则

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

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

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

## 许可证

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

## 有问题？

- 查看 [README.md](README.md)
- 阅读 [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md)
- 查看已有示例
- 发起 issue 讨论

感谢你的贡献！
