mirror of
https://github.com/awesome-skills/code-review-skill.git
synced 2026-03-22 02:19:32 +08:00
docs: 更新贡献指南，添加 Claude Code Skill 开发规范
新增内容： - Frontmatter 规范（name、description、allowed-tools） - 命名约定（kebab-case、64字符限制） - Description 写法规范（功能陈述 + Use when 触发条件） - Progressive Disclosure 原则和文件职责划分 - 文件引用规范（Markdown 链接格式） - Skill 设计原则（单一职责、版本管理、内容质量） - 常见问题解答
This commit is contained in:
Tu Shaokun
399
CONTRIBUTING.md
399
CONTRIBUTING.md
@@ -1,102 +1,319 @@
|
||||
# Contributing to AI Code Review Guide
|
||||
|
||||
Thank you for your interest in contributing! This document provides guidelines for contributing to this project.
|
||||
Thank you for your interest in contributing! This document provides guidelines for contributing to this Claude Code Skill project.
|
||||
|
||||
## How to Contribute
|
||||
## Claude Code Skill 开发规范
|
||||
|
||||
### Reporting Issues
|
||||
本项目是一个 Claude Code Skill，贡献者需要遵循以下规范。
|
||||
|
||||
- Use GitHub Issues to report bugs or suggest enhancements
|
||||
- Provide clear descriptions and examples
|
||||
- Include relevant code snippets when applicable
|
||||
|
||||
### Submitting Changes
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/your-feature`)
|
||||
3. Make your changes
|
||||
4. Commit with clear messages (`git commit -m "Add: description"`)
|
||||
5. Push to your fork (`git push origin feature/your-feature`)
|
||||
6. Open a Pull Request
|
||||
|
||||
## Contribution Types
|
||||
|
||||
### Adding New Language Support
|
||||
|
||||
When adding a new programming language:
|
||||
|
||||
1. Add a new section in `SKILL.md` with:
|
||||
- Language-specific review patterns
|
||||
- Common anti-patterns with ❌/✅ examples
|
||||
- A review checklist
|
||||
|
||||
2. Add corresponding entries in `references/common-bugs-checklist.md`
|
||||
|
||||
3. Format:
|
||||
```markdown
|
||||
### [Language] Code Review
|
||||
|
||||
```[language]
|
||||
// ❌ Bad pattern
|
||||
code example
|
||||
|
||||
// ✅ Good pattern
|
||||
code example
|
||||
```
|
||||
|
||||
#### [Language] Review Checklist
|
||||
- [ ] Check item 1
|
||||
- [ ] Check item 2
|
||||
```
|
||||
|
||||
### Adding Framework Patterns
|
||||
|
||||
When adding framework-specific patterns:
|
||||
|
||||
1. Ensure you reference official documentation
|
||||
2. Include version numbers (e.g., "React 19", "Vue 3.4+")
|
||||
3. Provide working code examples
|
||||
4. Add corresponding checklist items
|
||||
|
||||
### Improving Existing Content
|
||||
|
||||
- Fix typos or grammatical errors
|
||||
- Update outdated patterns
|
||||
- Add more edge cases
|
||||
- Improve code examples
|
||||
|
||||
## Code Example Guidelines
|
||||
|
||||
### Format
|
||||
|
||||
- Use ❌ for anti-patterns
|
||||
- Use ✅ for recommended patterns
|
||||
- Include comments explaining why
|
||||
|
||||
### Quality
|
||||
|
||||
- Examples should be realistic, not contrived
|
||||
- Show both the problem and the solution
|
||||
- Keep examples focused and minimal
|
||||
|
||||
## Commit Message Format
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
Type: Short description
|
||||
|
||||
Longer description if needed
|
||||
|
||||
- Detail 1
|
||||
- Detail 2
|
||||
ai-code-review-guide/
|
||||
├── SKILL.md # 必需：主文件（始终加载）
|
||||
├── README.md # 项目说明文档
|
||||
├── CONTRIBUTING.md # 贡献指南（本文件）
|
||||
├── LICENSE # 许可证
|
||||
├── reference/ # 按需加载的详细指南
|
||||
│ ├── react.md
|
||||
│ ├── vue.md
|
||||
│ ├── rust.md
|
||||
│ ├── typescript.md
|
||||
│ ├── python.md
|
||||
│ ├── common-bugs-checklist.md
|
||||
│ ├── security-review-guide.md
|
||||
│ └── code-review-best-practices.md
|
||||
├── assets/ # 模板和快速参考
|
||||
│ ├── review-checklist.md
|
||||
│ └── pr-review-template.md
|
||||
└── scripts/ # 工具脚本
|
||||
└── pr-analyzer.py
|
||||
```
|
||||
|
||||
Types:
|
||||
- `Add`: New feature or content
|
||||
- `Fix`: Bug fix or correction
|
||||
- `Update`: Update existing content
|
||||
- `Refactor`: Restructure without changing behavior
|
||||
- `Docs`: Documentation only changes
|
||||
### Frontmatter 规范
|
||||
|
||||
## Questions?
|
||||
SKILL.md 必须包含 YAML frontmatter：
|
||||
|
||||
Feel free to open an issue for any questions about contributing.
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: |
|
||||
功能描述。触发条件说明。
|
||||
Use when [具体使用场景]。
|
||||
allowed-tools: ["Read", "Grep", "Glob"] # 可选：限制工具访问
|
||||
---
|
||||
```
|
||||
|
||||
#### 必需字段
|
||||
|
||||
| 字段 | 说明 | 约束 |
|
||||
|------|------|------|
|
||||
| `name` | Skill 标识符 | 小写字母、数字、连字符；最多 64 字符 |
|
||||
| `description` | 功能和激活条件 | 最多 1024 字符；必须包含 "Use when" |
|
||||
|
||||
#### 可选字段
|
||||
|
||||
| 字段 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `allowed-tools` | 限制工具访问 | `["Read", "Grep", "Glob"]` |
|
||||
|
||||
### 命名约定
|
||||
|
||||
**Skill 名称规则**：
|
||||
- 仅使用小写字母、数字和连字符（kebab-case）
|
||||
- 最多 64 个字符
|
||||
- 避免下划线或大写字母
|
||||
|
||||
```
|
||||
✅ 正确：code-review-excellence, typescript-advanced-types
|
||||
❌ 错误：CodeReview, code_review, TYPESCRIPT
|
||||
```
|
||||
|
||||
**文件命名规则**：
|
||||
- reference 文件使用小写：`react.md`, `vue.md`
|
||||
- 多词文件使用连字符：`common-bugs-checklist.md`
|
||||
|
||||
### Description 写法规范
|
||||
|
||||
Description 必须包含两部分：
|
||||
|
||||
1. **功能陈述**：具体说明 Skill 能做什么
|
||||
2. **触发条件**：以 "Use when" 开头，说明何时激活
|
||||
|
||||
```yaml
|
||||
# ✅ 正确示例
|
||||
description: |
|
||||
Provides comprehensive code review guidance for React 19, Vue 3, Rust,
|
||||
TypeScript, and Python. Helps catch bugs, improve code quality, and
|
||||
give constructive feedback.
|
||||
Use when reviewing pull requests, conducting PR reviews, establishing
|
||||
review standards, or mentoring developers through code reviews.
|
||||
|
||||
# ❌ 错误示例（太模糊，缺少触发条件）
|
||||
description: |
|
||||
Helps with code review.
|
||||
```
|
||||
|
||||
### Progressive Disclosure（渐进式披露）
|
||||
|
||||
Claude 只在需要时加载支持文件，不会一次性加载所有内容。
|
||||
|
||||
#### 文件职责划分
|
||||
|
||||
| 文件 | 加载时机 | 内容 |
|
||||
|------|----------|------|
|
||||
| `SKILL.md` | 始终加载 | 核心原则、快速索引、何时使用 |
|
||||
| `reference/*.md` | 按需加载 | 语言/框架的详细指南 |
|
||||
| `assets/*.md` | 明确需要时 | 模板、清单 |
|
||||
| `scripts/*.py` | 明确指引时 | 工具脚本 |
|
||||
|
||||
#### 内容组织原则
|
||||
|
||||
**SKILL.md**（~200 行以内）：
|
||||
- 简述：2-3 句话说明用途
|
||||
- 核心原则和方法论
|
||||
- 语言/框架索引表（链接到 reference/）
|
||||
- 何时使用此 Skill
|
||||
|
||||
**reference/*.md**（详细内容）：
|
||||
- 完整的代码示例
|
||||
- 所有最佳实践
|
||||
- Review Checklist
|
||||
- 边界情况和陷阱
|
||||
|
||||
### 文件引用规范
|
||||
|
||||
在 SKILL.md 中引用其他文件时：
|
||||
|
||||
```markdown
|
||||
# ✅ 正确：使用 Markdown 链接格式
|
||||
| **React** | [React Guide](reference/react.md) | Hooks, React 19, RSC |
|
||||
| **Vue 3** | [Vue Guide](reference/vue.md) | Composition API |
|
||||
|
||||
详见 [React Guide](reference/react.md) 获取完整指南。
|
||||
|
||||
# ❌ 错误：使用代码块格式
|
||||
参考 `reference/react.md` 文件。
|
||||
```
|
||||
|
||||
**路径规则**：
|
||||
- 使用相对路径（相对于 Skill 目录）
|
||||
- 使用正斜杠 `/`，不使用反斜杠
|
||||
- 不需要 `./` 前缀
|
||||
|
||||
---
|
||||
|
||||
## 贡献类型
|
||||
|
||||
### 添加新语言支持
|
||||
|
||||
1. 在 `reference/` 目录创建新文件（如 `go.md`）
|
||||
2. 遵循以下结构：
|
||||
|
||||
```markdown
|
||||
# [Language] Code Review Guide
|
||||
|
||||
> 简短描述，一句话说明覆盖内容。
|
||||
|
||||
## 目录
|
||||
- [主题1](#主题1)
|
||||
- [主题2](#主题2)
|
||||
- [Review Checklist](#review-checklist)
|
||||
|
||||
---
|
||||
|
||||
## 主题1
|
||||
|
||||
### 子主题
|
||||
|
||||
```[language]
|
||||
// ❌ Bad pattern - 说明为什么不好
|
||||
bad_code_example()
|
||||
|
||||
// ✅ Good pattern - 说明为什么好
|
||||
good_code_example()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Review Checklist
|
||||
|
||||
### 类别1
|
||||
- [ ] 检查项 1
|
||||
- [ ] 检查项 2
|
||||
```
|
||||
|
||||
3. 在 `SKILL.md` 的索引表中添加链接
|
||||
4. 更新 `README.md` 的统计信息
|
||||
|
||||
### 添加框架模式
|
||||
|
||||
1. 确保引用官方文档
|
||||
2. 包含版本号（如 "React 19", "Vue 3.5+"）
|
||||
3. 提供可运行的代码示例
|
||||
4. 添加对应的 checklist 项
|
||||
|
||||
### 改进现有内容
|
||||
|
||||
- 修复拼写或语法错误
|
||||
- 更新过时的模式（注明版本变化）
|
||||
- 添加边界情况示例
|
||||
- 改进代码示例的清晰度
|
||||
|
||||
---
|
||||
|
||||
## 代码示例规范
|
||||
|
||||
### 格式要求
|
||||
|
||||
```markdown
|
||||
// ❌ 问题描述 - 解释为什么这样做不好
|
||||
problematic_code()
|
||||
|
||||
// ✅ 推荐做法 - 解释为什么这样做更好
|
||||
recommended_code()
|
||||
```
|
||||
|
||||
### 质量标准
|
||||
|
||||
- 示例应基于真实场景，避免人为构造
|
||||
- 同时展示问题和解决方案
|
||||
- 保持示例简洁聚焦
|
||||
- 包含必要的上下文（import 语句等）
|
||||
|
||||
---
|
||||
|
||||
## 提交流程
|
||||
|
||||
### Issue 报告
|
||||
|
||||
- 使用 GitHub Issues 报告问题或建议
|
||||
- 提供清晰的描述和示例
|
||||
- 标注相关的语言/框架
|
||||
|
||||
### Pull Request 流程
|
||||
|
||||
1. Fork 仓库
|
||||
2. 创建功能分支：`git checkout -b feature/add-go-support`
|
||||
3. 进行修改
|
||||
4. 提交（见下文 commit 格式）
|
||||
5. 推送到 fork：`git push origin feature/add-go-support`
|
||||
6. 创建 Pull Request
|
||||
|
||||
### Commit 消息格式
|
||||
|
||||
```
|
||||
类型: 简短描述
|
||||
|
||||
详细说明（如需要）
|
||||
|
||||
- 具体变更 1
|
||||
- 具体变更 2
|
||||
```
|
||||
|
||||
**类型**：
|
||||
- `feat`: 新功能或新内容
|
||||
- `fix`: 修复错误
|
||||
- `docs`: 仅文档变更
|
||||
- `refactor`: 重构（不改变功能）
|
||||
- `chore`: 维护性工作
|
||||
|
||||
**示例**：
|
||||
```
|
||||
feat: 添加 Go 语言代码审查指南
|
||||
|
||||
- 新增 reference/go.md
|
||||
- 覆盖错误处理、并发、接口设计
|
||||
- 更新 SKILL.md 索引表
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill 设计原则
|
||||
|
||||
### 单一职责
|
||||
|
||||
每个 Skill 专注一个核心能力。本 Skill 专注于**代码审查**，不应扩展到：
|
||||
- 代码生成
|
||||
- 项目初始化
|
||||
- 部署配置
|
||||
|
||||
### 版本管理
|
||||
|
||||
- 在 reference 文件中标注框架/语言版本
|
||||
- 更新时在 commit 中说明版本变化
|
||||
- 过时内容应更新而非删除（除非完全废弃）
|
||||
|
||||
### 内容质量
|
||||
|
||||
- 所有建议应有依据（官方文档、最佳实践）
|
||||
- 避免主观偏好（如代码风格），专注于客观问题
|
||||
- 优先覆盖常见陷阱和安全问题
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何测试我的更改？
|
||||
|
||||
将修改后的 Skill 复制到 `~/.claude/skills/` 目录，然后在 Claude Code 中测试：
|
||||
```bash
|
||||
cp -r ai-code-review-guide ~/.claude/skills/code-review-excellence
|
||||
```
|
||||
|
||||
### Q: 我应该更新 SKILL.md 还是 reference 文件？
|
||||
|
||||
- **SKILL.md**：只修改索引表或核心原则
|
||||
- **reference/*.md**：添加/更新具体的语言或框架内容
|
||||
|
||||
### Q: 如何处理过时的内容？
|
||||
|
||||
1. 标注版本变化（如 "React 18 → React 19"）
|
||||
2. 保留旧版本内容（如果仍有用户使用）
|
||||
3. 在 checklist 中更新相关项
|
||||
|
||||
---
|
||||
|
||||
## 问题咨询
|
||||
|
||||
如有任何问题，欢迎在 GitHub Issues 中提问。
|
||||
|
||||
Reference in New Issue
Block a user