Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
356 lines (258 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

356 lines (258 loc) · 10.5 KB
Raw

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，贡献者需要遵循以下规范。

目录结构

code-review-skill/
├── SKILL.md                    # Required: main file (always loaded)
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── reference/                  # On-demand language/framework guides
│   ├── react.md                # React 19 / Next.js / TanStack Query v5
│   ├── vue.md                  # Vue 3.5 Composition API
│   ├── angular.md              # Angular 17+, Signals, Standalone, RxJS
│   ├── svelte.md               # Svelte 5 / SvelteKit, runes, SSR boundary
│   ├── rust.md                 # Ownership, async, unsafe, cancellation
│   ├── typescript.md           # Type safety, generics, strict mode
│   ├── nestjs.md               # NestJS DI, modules, Guards/Pipes, DTOs
│   ├── python.md               # Type hints, async, testing
│   ├── django.md               # Django / DRF, N+1, serializers, async views
│   ├── fastapi.md              # FastAPI, Depends, Pydantic v2, async
│   ├── java.md                 # Java 17/21, Spring Boot 3, virtual threads
│   ├── kotlin.md               # Kotlin / Android, coroutines, Flow, Compose
│   ├── swift.md                # Swift 5.9+/6, SwiftUI, concurrency, optionals
│   ├── go.md                   # Error handling, goroutines, context
│   ├── csharp.md               # C# / .NET 8, async, EF Core, ASP.NET Core
│   ├── php.md                  # PHP 8.x, types, PDO, security, Composer
│   ├── c.md                    # Memory safety, UB, error handling
│   ├── cpp.md                  # RAII, move semantics, exception safety
│   ├── zig.md                  # Allocators, error unions, comptime, C interop
│   ├── qt.md                   # Object model, signals/slots, GUI perf
│   ├── css-less-sass.md        # Variables, responsive, performance
│   ├── architecture-review-guide.md  # SOLID, anti-patterns, coupling
│   ├── performance-review-guide.md   # Web Vitals, N+1, complexity
│   ├── security-review-guide.md      # OWASP Top 10, JWT, validation
│   ├── common-bugs-checklist.md      # Quick-reference bug patterns
│   ├── code-quality-universal.md      # Language-agnostic quality anti-patterns
│   ├── code-review-best-practices.md # Communication & process
│   └── cross-cutting/               # Language-agnostic cross-cutting patterns
│       ├── sql-injection-prevention.md # Parameterized queries, 6 languages
│       ├── xss-prevention.md           # Output encoding, CSP, 5 frameworks
│       ├── n-plus-one-queries.md       # N+1 queries, eager loading, 5 languages
│       ├── error-handling-principles.md # Error handling principles, 7 languages
│       └── async-concurrency-patterns.md # Concurrency patterns, 7 languages
├── assets/                     # Templates and quick reference
│   ├── review-checklist.md
│   └── pr-review-template.md
└── scripts/
    └── pr-analyzer.py          # PR complexity analyzer

Frontmatter 规范

SKILL.md 必须包含 YAML frontmatter：

---
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-skill, typescript-advanced-types
❌ 错误：CodeReview, code_review, TYPESCRIPT

文件命名规则：

  • reference 文件使用小写：react.md, vue.md
  • 多词文件使用连字符：common-bugs-checklist.md

Description 写法规范

Description 必须包含两部分：

  1. 功能陈述：具体说明 Skill 能做什么
  2. 触发条件：以 "Use when" 开头，说明何时激活
# ✅ 正确示例
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 链接格式
| **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 目录）
  • 使用正斜杠 /，不使用反斜杠
  • 不需要 ./ 前缀

约定（Conventions）

严重级别（severity）：审查意见统一使用 SKILL.md「Technique 4」的标记方案，三档由红到绿表示优先级：

  • 🔴 [blocking] - 合并前必须修复
  • 🟡 [important] - 应当修复，有异议可讨论
  • 🟢 [nit] - 可选优化，不阻塞合并

新增 reference 指南时请沿用这套标记，不要自创等价的名称（如 critical/warning/suggestion）。

语言策略：现有指南是中英混合的——部分通篇中文，部分（如 fastapi.md、php.md）以英文为主。新增内容时跟随同一领域既有指南的语言：改某个指南就用它的语言；新建指南可自行选择中文或英文，但单个文件内部保持一致。

贡献类型

添加新语言支持

  1. 在 reference/ 目录创建新文件（如 go.md）
  2. 遵循以下结构：
# [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 中测试：

cp -r code-review-skill ~/.claude/skills/code-review-skill

Q: 我应该更新 SKILL.md 还是 reference 文件？

  • SKILL.md：只修改索引表或核心原则
  • reference/*.md：添加/更新具体的语言或框架内容

Q: 如何处理过时的内容？

  1. 标注版本变化（如 "React 18 → React 19"）
  2. 保留旧版本内容（如果仍有用户使用）
  3. 在 checklist 中更新相关项

问题咨询

如有任何问题，欢迎在 GitHub Issues 中提问。