mirror of
https://github.com/awesome-skills/code-review-skill.git
synced 2026-03-22 02:19:32 +08:00
322 lines
7.5 KiB
Markdown
322 lines
7.5 KiB
Markdown
# Contributing to AI Code Review Guide
|
||
|
||
Thank you for your interest in contributing! This document provides guidelines for contributing to this Claude Code Skill project.
|
||
|
||
## Claude Code Skill 开发规范
|
||
|
||
本项目是一个 Claude Code Skill，贡献者需要遵循以下规范。
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
ai-code-review-guide/
|
||
├── SKILL.md # 必需：主文件（始终加载）
|
||
├── README.md # 项目说明文档
|
||
├── CONTRIBUTING.md # 贡献指南（本文件）
|
||
├── LICENSE # 许可证
|
||
├── reference/ # 按需加载的详细指南
|
||
│ ├── react.md
|
||
│ ├── vue.md
|
||
│ ├── rust.md
|
||
│ ├── typescript.md
|
||
│ ├── python.md
|
||
│ ├── c.md
|
||
│ ├── cpp.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
|
||
```
|
||
|
||
### Frontmatter 规范
|
||
|
||
SKILL.md 必须包含 YAML frontmatter：
|
||
|
||
```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, Java, Python, and C/C++.
|
||
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 中提问。
|