From b5148f184ae4065c7f2b4d833c07af9a52890617 Mon Sep 17 00:00:00 2001 From: xingzihai <1315258019@qq.com> Date: Thu, 26 Mar 2026 00:59:46 +0000 Subject: [PATCH 1/5] feat(rules): add code-review.md rule to common rules - Add comprehensive code review standards for all languages - Define when to review (after code changes, before commits) - Include security review triggers and severity levels - Reference relevant agents (code-reviewer, security-reviewer, etc.) - Add review checklist covering security, quality, and performance - Define approval criteria (Approve/Warning/Block) This rule complements the existing code-reviewer agent by providing clear guidelines on when and how to conduct code reviews. --- rules/common/code-review.md | 116 ++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 rules/common/code-review.md diff --git a/rules/common/code-review.md b/rules/common/code-review.md new file mode 100644 index 00000000..e2364b07 --- /dev/null +++ b/rules/common/code-review.md @@ -0,0 +1,116 @@ +# Code Review Standards + +## Purpose + +Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews. + +## When to Review + +**MANDATORY review triggers:** + +- After writing or modifying code +- Before any commit to shared branches +- When security-sensitive code is changed (auth, payments, user data) +- When architectural changes are made +- Before merging pull requests + +## Review Checklist + +Before marking code complete: + +- [ ] Code is readable and well-named +- [ ] Functions are focused (<50 lines) +- [ ] Files are cohesive (<800 lines) +- [ ] No deep nesting (>4 levels) +- [ ] Errors are handled explicitly +- [ ] No hardcoded secrets or credentials +- [ ] No console.log or debug statements +- [ ] Tests exist for new functionality +- [ ] Test coverage meets 80% minimum + +## Security Review Triggers + +**STOP and use security-reviewer agent when:** + +- Authentication or authorization code +- User input handling +- Database queries +- File system operations +- External API calls +- Cryptographic operations +- Payment or financial code + +## Review Severity Levels + +| Level | Meaning | Action | +|-------|---------|--------| +| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge | +| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge | +| MEDIUM | Maintainability concern | **INFO** - Consider fixing | +| LOW | Style or minor suggestion | **NOTE** - Optional | + +## Agent Usage + +Use these agents for code review: + +| Agent | Purpose | +|-------|---------| +| **code-reviewer** | General code quality, patterns, best practices | +| **security-reviewer** | Security vulnerabilities, OWASP Top 10 | +| **typescript-reviewer** | TypeScript/JavaScript specific issues | +| **python-reviewer** | Python specific issues | +| **go-reviewer** | Go specific issues | +| **rust-reviewer** | Rust specific issues | + +## Review Workflow + +``` +1. Run git diff to understand changes +2. Check security checklist first +3. Review code quality checklist +4. Run relevant tests +5. Verify coverage >= 80% +6. Use appropriate agent for detailed review +``` + +## Common Issues to Catch + +### Security + +- Hardcoded credentials (API keys, passwords, tokens) +- SQL injection (string concatenation in queries) +- XSS vulnerabilities (unescaped user input) +- Path traversal (unsanitized file paths) +- CSRF protection missing +- Authentication bypasses + +### Code Quality + +- Large functions (>50 lines) - split into smaller +- Large files (>800 lines) - extract modules +- Deep nesting (>4 levels) - use early returns +- Missing error handling - handle explicitly +- Mutation patterns - prefer immutable operations +- Missing tests - add test coverage + +### Performance + +- N+1 queries - use JOINs or batching +- Missing pagination - add LIMIT to queries +- Unbounded queries - add constraints +- Missing caching - cache expensive operations + +## Approval Criteria + +- **Approve**: No CRITICAL or HIGH issues +- **Warning**: Only HIGH issues (merge with caution) +- **Block**: CRITICAL issues found + +## Integration with Other Rules + +This rule works with: + +- [testing.md](testing.md) - Test coverage requirements +- [security.md](security.md) - Security checklist +- [git-workflow.md](git-workflow.md) - Commit standards +- [agents.md](agents.md) - Agent delegation \ No newline at end of file From 3f5e042b40a9d0799ae7ce6027eed8999ff32410 Mon Sep 17 00:00:00 2001 From: xingzihai <1315258019@qq.com> Date: Thu, 26 Mar 2026 01:38:39 +0000 Subject: [PATCH 2/5] feat: add Chinese (zh-CN) translation for rules/common - Add rules/zh/ directory with complete Chinese translations - Translate all 10 common rule files: - coding-style.md - security.md - testing.md - git-workflow.md - performance.md - patterns.md - hooks.md - agents.md - development-workflow.md - code-review.md - Add README.md for the zh directory explaining structure and installation - Maintain consistent formatting with original English versions - Keep technical terms and code examples in English where appropriate --- rules/zh/README.md | 102 +++++++++++++++++++++++++++ rules/zh/agents.md | 50 +++++++++++++ rules/zh/code-review.md | 116 +++++++++++++++++++++++++++++++ rules/zh/coding-style.md | 48 +++++++++++++ rules/zh/development-workflow.md | 38 ++++++++++ rules/zh/git-workflow.md | 24 +++++++ rules/zh/hooks.md | 30 ++++++++ rules/zh/patterns.md | 31 +++++++++ rules/zh/performance.md | 55 +++++++++++++++ rules/zh/security.md | 29 ++++++++ rules/zh/testing.md | 29 ++++++++ 11 files changed, 552 insertions(+) create mode 100644 rules/zh/README.md create mode 100644 rules/zh/agents.md create mode 100644 rules/zh/code-review.md create mode 100644 rules/zh/coding-style.md create mode 100644 rules/zh/development-workflow.md create mode 100644 rules/zh/git-workflow.md create mode 100644 rules/zh/hooks.md create mode 100644 rules/zh/patterns.md create mode 100644 rules/zh/performance.md create mode 100644 rules/zh/security.md create mode 100644 rules/zh/testing.md diff --git a/rules/zh/README.md b/rules/zh/README.md new file mode 100644 index 00000000..0793b4fd --- /dev/null +++ b/rules/zh/README.md @@ -0,0 +1,102 @@ +# 规则 + +## 结构 + +规则按**通用**层和**语言特定**目录组织： + +``` +rules/ +├── common/ # 语言无关的原则（始终安装） +│ ├── coding-style.md +│ ├── git-workflow.md +│ ├── testing.md +│ ├── performance.md +│ ├── patterns.md +│ ├── hooks.md +│ ├── agents.md +│ └── security.md +├── zh/ # 中文翻译版本 +│ ├── coding-style.md +│ ├── git-workflow.md +│ ├── testing.md +│ ├── performance.md +│ ├── patterns.md +│ ├── hooks.md +│ ├── agents.md +│ ├── security.md +│ └── development-workflow.md +├── typescript/ # TypeScript/JavaScript 特定 +├── python/ # Python 特定 +├── golang/ # Go 特定 +├── swift/ # Swift 特定 +└── php/ # PHP 特定 +``` + +- **common/** 包含通用原则 — 无语言特定的代码示例。 +- **zh/** 包含 common 目录的中文翻译版本。 +- **语言目录** 扩展通用规则，包含框架特定的模式、工具和代码示例。每个文件引用其对应的通用版本。 + +## 安装 + +### 选项 1：安装脚本（推荐） + +```bash +# 安装通用 + 一个或多个语言特定的规则集 +./install.sh typescript +./install.sh python +./install.sh golang +./install.sh swift +./install.sh php + +# 同时安装多种语言 +./install.sh typescript python +``` + +### 选项 2：手动安装 + +> **重要提示：** 复制整个目录 — 不要使用 `/*` 展开。 +> 通用和语言特定目录包含同名文件。 +> 将它们展开到一个目录会导致语言特定文件覆盖通用规则， +> 并破坏语言特定文件使用的 `../common/` 相对引用。 + +```bash +# 安装通用规则（所有项目必需） +cp -r rules/common ~/.claude/rules/common + +# 安装中文翻译版本（可选） +cp -r rules/zh ~/.claude/rules/zh + +# 根据项目技术栈安装语言特定规则 +cp -r rules/typescript ~/.claude/rules/typescript +cp -r rules/python ~/.claude/rules/python +cp -r rules/golang ~/.claude/rules/golang +cp -r rules/swift ~/.claude/rules/swift +cp -r rules/php ~/.claude/rules/php +``` + +## 规则 vs 技能 + +- **规则** 定义广泛适用的标准、约定和检查清单（如"80% 测试覆盖率"、"禁止硬编码密钥"）。 +- **技能**（`skills/` 目录）为特定任务提供深入、可操作的参考材料（如 `python-patterns`、`golang-testing`）。 + +语言特定的规则文件在适当的地方引用相关技能。规则告诉你*做什么*；技能告诉你*怎么做*。 + +## 规则优先级 + +当语言特定规则与通用规则冲突时，**语言特定规则优先**（特定覆盖通用）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。 + +- `rules/common/` 定义适用于所有项目的通用默认值。 +- `rules/golang/`、`rules/python/`、`rules/swift/`、`rules/php/`、`rules/typescript/` 等在语言习惯不同时覆盖这些默认值。 +- `rules/zh/` 是通用规则的中文翻译，与英文版本内容一致。 + +### 示例 + +`common/coding-style.md` 推荐不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点： + +> 惯用的 Go 使用指针接收器进行结构体变更 — 参见 [common/coding-style.md](../common/coding-style.md) 了解通用原则，但这里首选符合 Go 习惯的变更方式。 + +### 带覆盖说明的通用规则 + +`rules/common/` 中可能被语言特定文件覆盖的规则会标记： + +> **语言说明**：此规则可能被语言特定规则覆盖，对于某些语言，该模式可能不是惯用的。 \ No newline at end of file diff --git a/rules/zh/agents.md b/rules/zh/agents.md new file mode 100644 index 00000000..dc75dcf4 --- /dev/null +++ b/rules/zh/agents.md @@ -0,0 +1,50 @@ +# 代理编排 + +## 可用代理 + +位于 `~/.claude/agents/`： + +| 代理 | 用途 | 何时使用 | +|-------|---------|------------| +| planner | 实现规划 | 复杂功能、重构 | +| architect | 系统设计 | 架构决策 | +| tdd-guide | 测试驱动开发 | 新功能、bug 修复 | +| code-reviewer | 代码审查 | 编写代码后 | +| security-reviewer | 安全分析 | 提交前 | +| build-error-resolver | 修复构建错误 | 构建失败时 | +| e2e-runner | E2E 测试 | 关键用户流程 | +| refactor-cleaner | 死代码清理 | 代码维护 | +| doc-updater | 文档 | 更新文档 | +| rust-reviewer | Rust 代码审查 | Rust 项目 | + +## 立即使用代理 + +无需用户提示： +1. 复杂功能请求 - 使用 **planner** 代理 +2. 刚编写/修改的代码 - 使用 **code-reviewer** 代理 +3. Bug 修复或新功能 - 使用 **tdd-guide** 代理 +4. 架构决策 - 使用 **architect** 代理 + +## 并行任务执行 + +对独立操作始终使用并行 Task 执行： + +```markdown +# 好：并行执行 +同时启动 3 个代理： +1. 代理 1：认证模块安全分析 +2. 代理 2：缓存系统性能审查 +3. 代理 3：工具类型检查 + +# 坏：不必要的顺序 +先代理 1，然后代理 2，然后代理 3 +``` + +## 多视角分析 + +对于复杂问题，使用分角色子代理： +- 事实审查者 +- 高级工程师 +- 安全专家 +- 一致性审查者 +- 冗余检查者 \ No newline at end of file diff --git a/rules/zh/code-review.md b/rules/zh/code-review.md new file mode 100644 index 00000000..608709e9 --- /dev/null +++ b/rules/zh/code-review.md @@ -0,0 +1,116 @@ +# 代码审查标准 + +## 目的 + +代码审查确保代码合并前的质量、安全性和可维护性。此规则定义何时以及如何进行代码审查。 + +## 何时审查 + +**强制审查触发条件：** + +- 编写或修改代码后 +- 提交到共享分支之前 +- 更改安全敏感代码时（认证、支付、用户数据） +- 进行架构更改时 +- 合并 pull request 之前 + +## 审查检查清单 + +在标记代码完成之前： + +- [ ] 代码可读且命名良好 +- [ ] 函数聚焦（<50 行） +- [ ] 文件内聚（<800 行） +- [ ] 无深层嵌套（>4 层） +- [ ] 错误显式处理 +- [ ] 无硬编码密钥或凭据 +- [ ] 无 console.log 或调试语句 +- [ ] 新功能有测试 +- [ ] 测试覆盖率满足 80% 最低要求 + +## 安全审查触发条件 + +**停止并使用 security-reviewer 代理当：** + +- 认证或授权代码 +- 用户输入处理 +- 数据库查询 +- 文件系统操作 +- 外部 API 调用 +- 加密操作 +- 支付或金融代码 + +## 审查严重级别 + +| 级别 | 含义 | 行动 | +|-------|---------|--------| +| CRITICAL（关键） | 安全漏洞或数据丢失风险 | **阻止** - 合并前必须修复 | +| HIGH（高） | Bug 或重大质量问题 | **警告** - 合并前应修复 | +| MEDIUM（中） | 可维护性问题 | **信息** - 考虑修复 | +| LOW（低） | 风格或次要建议 | **注意** - 可选 | + +## 代理使用 + +使用这些代理进行代码审查： + +| 代理 | 用途 | +|-------|--------| +| **code-reviewer** | 通用代码质量、模式、最佳实践 | +| **security-reviewer** | 安全漏洞、OWASP Top 10 | +| **typescript-reviewer** | TypeScript/JavaScript 特定问题 | +| **python-reviewer** | Python 特定问题 | +| **go-reviewer** | Go 特定问题 | +| **rust-reviewer** | Rust 特定问题 | + +## 审查工作流 + +``` +1. 运行 git diff 了解更改 +2. 先检查安全检查清单 +3. 审查代码质量检查清单 +4. 运行相关测试 +5. 验证覆盖率 >= 80% +6. 使用适当的代理进行详细审查 +``` + +## 常见问题捕获 + +### 安全 + +- 硬编码凭据（API 密钥、密码、令牌） +- SQL 注入（查询中的字符串拼接） +- XSS 漏洞（未转义的用户输入） +- 路径遍历（未净化的文件路径） +- CSRF 保护缺失 +- 认证绕过 + +### 代码质量 + +- 大函数（>50 行）- 拆分为更小的 +- 大文件（>800 行）- 提取模块 +- 深层嵌套（>4 层）- 使用提前返回 +- 缺少错误处理 - 显式处理 +- 变更模式 - 优先使用不可变操作 +- 缺少测试 - 添加测试覆盖 + +### 性能 + +- N+1 查询 - 使用 JOIN 或批处理 +- 缺少分页 - 给查询添加 LIMIT +- 无界查询 - 添加约束 +- 缺少缓存 - 缓存昂贵操作 + +## 批准标准 + +- **批准**：无关键或高优先级问题 +- **警告**：仅有高优先级问题（谨慎合并） +- **阻止**：发现关键问题 + +## 与其他规则的集成 + +此规则与以下规则配合： + +- [testing.md](testing.md) - 测试覆盖率要求 +- [security.md](security.md) - 安全检查清单 +- [git-workflow.md](git-workflow.md) - 提交标准 +- [agents.md](agents.md) - 代理委托 \ No newline at end of file diff --git a/rules/zh/coding-style.md b/rules/zh/coding-style.md new file mode 100644 index 00000000..dd975d88 --- /dev/null +++ b/rules/zh/coding-style.md @@ -0,0 +1,48 @@ +# 编码风格 + +## 不可变性（关键） + +始终创建新对象，永远不要修改现有对象： + +``` +// 伪代码 +错误: modify(original, field, value) → 就地修改 original +正确: update(original, field, value) → 返回带有更改的新副本 +``` + +原理：不可变数据防止隐藏的副作用，使调试更容易，并启用安全的并发。 + +## 文件组织 + +多个小文件 > 少量大文件： +- 高内聚，低耦合 +- 典型 200-400 行，最多 800 行 +- 从大模块中提取工具函数 +- 按功能/领域组织，而非按类型 + +## 错误处理 + +始终全面处理错误： +- 在每一层显式处理错误 +- 在面向 UI 的代码中提供用户友好的错误消息 +- 在服务器端记录详细的错误上下文 +- 永远不要静默吞掉错误 + +## 输入验证 + +始终在系统边界验证： +- 处理前验证所有用户输入 +- 在可用的情况下使用基于模式的验证 +- 快速失败并给出清晰的错误消息 +- 永远不要信任外部数据（API 响应、用户输入、文件内容） + +## 代码质量检查清单 + +在标记工作完成前： +- [ ] 代码可读且命名良好 +- [ ] 函数很小（<50 行） +- [ ] 文件聚焦（<800 行） +- [ ] 没有深层嵌套（>4 层） +- [ ] 正确的错误处理 +- [ ] 没有硬编码值（使用常量或配置） +- [ ] 没有变更（使用不可变模式） \ No newline at end of file diff --git a/rules/zh/development-workflow.md b/rules/zh/development-workflow.md new file mode 100644 index 00000000..610fbbac --- /dev/null +++ b/rules/zh/development-workflow.md @@ -0,0 +1,38 @@ +# 开发工作流 + +> 此文件扩展 [common/git-workflow.md](./git-workflow.md)，包含 git 操作之前的完整功能开发流程。 + +功能实现工作流描述了开发管道：研究、规划、TDD、代码审查，然后提交到 git。 + +## 功能实现工作流 + +0. **研究与重用** _(任何新实现前必需)_ + - **GitHub 代码搜索优先：** 在编写任何新代码之前，运行 `gh search repos` 和 `gh search code` 查找现有实现、模板和模式。 + - **库文档其次：** 使用 Context7 或主要供应商文档确认 API 行为、包使用和版本特定细节。 + - **仅当前两者不足时使用 Exa：** 在 GitHub 搜索和主要文档之后，使用 Exa 进行更广泛的网络研究或发现。 + - **检查包注册表：** 在编写工具代码之前搜索 npm、PyPI、crates.io 和其他注册表。首选久经考验的库而非手工编写的解决方案。 + - **搜索可适配的实现：** 寻找解决问题 80%+ 且可以分支、移植或包装的开源项目。 + - 当满足需求时，优先采用或移植经验证的方法而非从头编写新代码。 + +1. **先规划** + - 使用 **planner** 代理创建实现计划 + - 编码前生成规划文档：PRD、架构、系统设计、技术文档、任务列表 + - 识别依赖和风险 + - 分解为阶段 + +2. **TDD 方法** + - 使用 **tdd-guide** 代理 + - 先写测试（RED） + - 实现以通过测试（GREEN） + - 重构（IMPROVE） + - 验证 80%+ 覆盖率 + +3. **代码审查** + - 编写代码后立即使用 **code-reviewer** 代理 + - 解决关键和高优先级问题 + - 尽可能修复中优先级问题 + +4. **提交与推送** + - 详细的提交消息 + - 遵循约定式提交格式 + - 参见 [git-workflow.md](./git-workflow.md) 了解提交消息格式和 PR 流程 \ No newline at end of file diff --git a/rules/zh/git-workflow.md b/rules/zh/git-workflow.md new file mode 100644 index 00000000..15b27ed2 --- /dev/null +++ b/rules/zh/git-workflow.md @@ -0,0 +1,24 @@ +# Git 工作流 + +## 提交消息格式 +``` +<类型>: <描述> + +<可选正文> +``` + +类型：feat, fix, refactor, docs, test, chore, perf, ci + +注意：通过 ~/.claude/settings.json 全局禁用归属。 + +## Pull Request 工作流 + +创建 PR 时： +1. 分析完整提交历史（不仅是最新提交） +2. 使用 `git diff [base-branch]...HEAD` 查看所有更改 +3. 起草全面的 PR 摘要 +4. 包含带有 TODO 的测试计划 +5. 如果是新分支，使用 `-u` 标志推送 + +> 对于 git 操作之前的完整开发流程（规划、TDD、代码审查）， +> 参见 [development-workflow.md](./development-workflow.md)。 \ No newline at end of file diff --git a/rules/zh/hooks.md b/rules/zh/hooks.md new file mode 100644 index 00000000..c16bcd40 --- /dev/null +++ b/rules/zh/hooks.md @@ -0,0 +1,30 @@ +# 钩子系统 + +## 钩子类型 + +- **PreToolUse**：工具执行前（验证、参数修改） +- **PostToolUse**：工具执行后（自动格式化、检查） +- **Stop**：会话结束时（最终验证） + +## 自动接受权限 + +谨慎使用： +- 为可信、定义明确的计划启用 +- 探索性工作时禁用 +- 永远不要使用 dangerously-skip-permissions 标志 +- 改为在 `~/.claude.json` 中配置 `allowedTools` + +## TodoWrite 最佳实践 + +使用 TodoWrite 工具： +- 跟踪多步骤任务的进度 +- 验证对指令的理解 +- 启用实时引导 +- 显示细粒度的实现步骤 + +待办列表揭示： +- 顺序错误的步骤 +- 缺失的项目 +- 多余的不必要项目 +- 错误的粒度 +- 误解的需求 \ No newline at end of file diff --git a/rules/zh/patterns.md b/rules/zh/patterns.md new file mode 100644 index 00000000..ef51b297 --- /dev/null +++ b/rules/zh/patterns.md @@ -0,0 +1,31 @@ +# 常用模式 + +## 骨架项目 + +实现新功能时： +1. 搜索久经考验的骨架项目 +2. 使用并行代理评估选项： + - 安全性评估 + - 可扩展性分析 + - 相关性评分 + - 实现规划 +3. 克隆最佳匹配作为基础 +4. 在经验证的结构内迭代 + +## 设计模式 + +### 仓储模式 + +将数据访问封装在一致的接口后面： +- 定义标准操作：findAll、findById、create、update、delete +- 具体实现处理存储细节（数据库、API、文件等） +- 业务逻辑依赖抽象接口，而非存储机制 +- 便于轻松切换数据源，并简化使用模拟的测试 + +### API 响应格式 + +对所有 API 响应使用一致的信封： +- 包含成功/状态指示器 +- 包含数据负载（错误时可为空） +- 包含错误消息字段（成功时可为空） +- 包含分页响应的元数据（total、page、limit） \ No newline at end of file diff --git a/rules/zh/performance.md b/rules/zh/performance.md new file mode 100644 index 00000000..a8d34a79 --- /dev/null +++ b/rules/zh/performance.md @@ -0,0 +1,55 @@ +# 性能优化 + +## 模型选择策略 + +**Haiku 4.5**（Sonnet 90% 的能力，3 倍成本节省）： +- 频繁调用的轻量级代理 +- 结对编程和代码生成 +- 多代理系统中的工作者代理 + +**Sonnet 4.6**（最佳编码模型）： +- 主要开发工作 +- 编排多代理工作流 +- 复杂编码任务 + +**Opus 4.5**（最深度推理）： +- 复杂架构决策 +- 最大推理需求 +- 研究和分析任务 + +## 上下文窗口管理 + +避免在上下文窗口的最后 20% 进行以下操作： +- 大规模重构 +- 跨多个文件的功能实现 +- 调试复杂交互 + +上下文敏感度较低的任务： +- 单文件编辑 +- 独立工具创建 +- 文档更新 +- 简单 bug 修复 + +## 扩展思考 + 规划模式 + +扩展思考默认启用，为内部推理保留最多 31,999 个 token。 + +通过以下方式控制扩展思考： +- **切换**：Option+T（macOS）/ Alt+T（Windows/Linux） +- **配置**：在 `~/.claude/settings.json` 中设置 `alwaysThinkingEnabled` +- **预算上限**：`export MAX_THINKING_TOKENS=10000` +- **详细模式**：Ctrl+O 查看思考输出 + +对于需要深度推理的复杂任务： +1. 确保扩展思考已启用（默认开启） +2. 启用**规划模式**进行结构化方法 +3. 使用多轮审查进行彻底分析 +4. 使用分角色子代理获得多样化视角 + +## 构建排查 + +如果构建失败： +1. 使用 **build-error-resolver** 代理 +2. 分析错误消息 +3. 增量修复 +4. 每次修复后验证 \ No newline at end of file diff --git a/rules/zh/security.md b/rules/zh/security.md new file mode 100644 index 00000000..1fbf01a1 --- /dev/null +++ b/rules/zh/security.md @@ -0,0 +1,29 @@ +# 安全指南 + +## 强制安全检查 + +在任何提交之前： +- [ ] 无硬编码密钥（API 密钥、密码、令牌） +- [ ] 所有用户输入已验证 +- [ ] SQL 注入防护（参数化查询） +- [ ] XSS 防护（净化 HTML） +- [ ] CSRF 保护已启用 +- [ ] 认证/授权已验证 +- [ ] 所有端点启用速率限制 +- [ ] 错误消息不泄露敏感数据 + +## 密钥管理 + +- 永远不要在源代码中硬编码密钥 +- 始终使用环境变量或密钥管理器 +- 启动时验证所需的密钥是否存在 +- 轮换任何可能已暴露的密钥 + +## 安全响应协议 + +如果发现安全问题： +1. 立即停止 +2. 使用 **security-reviewer** 代理 +3. 在继续之前修复关键问题 +4. 轮换任何已暴露的密钥 +5. 审查整个代码库中的类似问题 \ No newline at end of file diff --git a/rules/zh/testing.md b/rules/zh/testing.md new file mode 100644 index 00000000..c73c1491 --- /dev/null +++ b/rules/zh/testing.md @@ -0,0 +1,29 @@ +# 测试要求 + +## 最低测试覆盖率：80% + +测试类型（全部必需）： +1. **单元测试** - 单个函数、工具、组件 +2. **集成测试** - API 端点、数据库操作 +3. **E2E 测试** - 关键用户流程（框架根据语言选择） + +## 测试驱动开发 + +强制工作流： +1. 先写测试（RED） +2. 运行测试 - 应该失败 +3. 编写最小实现（GREEN） +4. 运行测试 - 应该通过 +5. 重构（IMPROVE） +6. 验证覆盖率（80%+） + +## 测试失败排查 + +1. 使用 **tdd-guide** 代理 +2. 检查测试隔离 +3. 验证模拟是否正确 +4. 修复实现，而非测试（除非测试有误） + +## 代理支持 + +- **tdd-guide** - 主动用于新功能，强制先写测试 \ No newline at end of file From c146fae2ceeca995dfb6590718733339aeeb215e Mon Sep 17 00:00:00 2001 From: xingzihai <1315258019@qq.com> Date: Thu, 26 Mar 2026 02:28:02 +0000 Subject: [PATCH 3/5] docs: add comprehensive Skill Development Guide - Add docs/SKILL-DEVELOPMENT-GUIDE.md with detailed guidance on creating skills - Update CONTRIBUTING.md with enhanced skills section linking to the new guide - Covers skill architecture, categories, best practices, testing, and examples The new guide provides: - What skills are and when they activate - Skill file structure and format - Step-by-step skill creation tutorial - Writing effective skill content - Common patterns and anti-patterns - Testing and validation checklist - Complete examples gallery --- CONTRIBUTING.md | 55 +- docs/SKILL-DEVELOPMENT-GUIDE.md | 906 ++++++++++++++++++++++++++++++++ 2 files changed, 949 insertions(+), 12 deletions(-) create mode 100644 docs/SKILL-DEVELOPMENT-GUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7b99c3a..dd956663 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,6 +73,13 @@ git add . && git commit -m "feat: add my-skill" && git push -u origin feat/my-co Skills are knowledge modules that Claude Code loads based on context. +> **📚 Comprehensive Guide:** For detailed guidance on creating effective skills, see [Skill Development Guide](docs/SKILL-DEVELOPMENT-GUIDE.md). It covers: +> - Skill architecture and categories +> - Writing effective content with examples +> - Best practices and common patterns +> - Testing and validation +> - Complete examples gallery + ### Directory Structure ``` @@ -86,7 +93,7 @@ skills/ ```markdown --- name: your-skill-name -description: Brief description shown in skill list +description: Brief description shown in skill list and used for auto-activation origin: ECC --- @@ -94,6 +101,10 @@ origin: ECC Brief overview of what this skill covers. +## When to Activate + +Describe scenarios where Claude should use this skill. This is critical for auto-activation. + ## Core Concepts Explain key patterns and guidelines. @@ -107,33 +118,53 @@ function example() { } \`\`\` +## Anti-Patterns + +Show what NOT to do with examples. + ## Best Practices - Actionable guidelines - Do's and don'ts - Common pitfalls to avoid -## When to Use +## Related Skills -Describe scenarios where this skill applies. +Link to complementary skills (e.g., `related-skill-1`, `related-skill-2`). ``` +### Skill Categories + +| Category | Purpose | Examples | +|----------|---------|----------| +| **Language Standards** | Idioms, conventions, best practices | `python-patterns`, `golang-patterns` | +| **Framework Patterns** | Framework-specific guidance | `django-patterns`, `nextjs-patterns` | +| **Workflow** | Step-by-step processes | `tdd-workflow`, `refactoring-workflow` | +| **Domain Knowledge** | Specialized domains | `security-review`, `api-design` | +| **Tool Integration** | Tool/library usage | `docker-patterns`, `supabase-patterns` | + ### Skill Checklist -- [ ] Focused on one domain/technology -- [ ] Includes practical code examples -- [ ] Under 500 lines +- [ ] Focused on one domain/technology (not too broad) +- [ ] Includes "When to Activate" section for auto-activation +- [ ] Includes practical, copy-pasteable code examples +- [ ] Shows anti-patterns (what NOT to do) +- [ ] Under 500 lines (800 max) - [ ] Uses clear section headers - [ ] Tested with Claude Code +- [ ] Links to related skills +- [ ] No sensitive data (API keys, tokens, paths) ### Example Skills -| Skill | Purpose | -|-------|---------| -| `coding-standards/` | TypeScript/JavaScript patterns | -| `frontend-patterns/` | React and Next.js best practices | -| `backend-patterns/` | API and database patterns | -| `security-review/` | Security checklist | +| Skill | Category | Purpose | +|-------|----------|---------| +| `coding-standards/` | Language Standards | TypeScript/JavaScript patterns | +| `frontend-patterns/` | Framework Patterns | React and Next.js best practices | +| `backend-patterns/` | Framework Patterns | API and database patterns | +| `security-review/` | Domain Knowledge | Security checklist | +| `tdd-workflow/` | Workflow | Test-driven development process | +| `project-guidelines-example/` | Template | Project-specific skill template | --- diff --git a/docs/SKILL-DEVELOPMENT-GUIDE.md b/docs/SKILL-DEVELOPMENT-GUIDE.md new file mode 100644 index 00000000..6a5b123c --- /dev/null +++ b/docs/SKILL-DEVELOPMENT-GUIDE.md @@ -0,0 +1,906 @@ +# Skill Development Guide + +A comprehensive guide to creating effective skills for Everything Claude Code (ECC). + +## Table of Contents + +- [What Are Skills?](#what-are-skills) +- [Skill Architecture](#skill-architecture) +- [Creating Your First Skill](#creating-your-first-skill) +- [Skill Categories](#skill-categories) +- [Writing Effective Skill Content](#writing-effective-skill-content) +- [Best Practices](#best-practices) +- [Common Patterns](#common-patterns) +- [Testing Your Skill](#testing-your-skill) +- [Submitting Your Skill](#submitting-your-skill) +- [Examples Gallery](#examples-gallery) + +--- + +## What Are Skills? + +Skills are **knowledge modules** that Claude Code loads based on context. They provide: + +- **Domain expertise**: Framework patterns, language idioms, best practices +- **Workflow definitions**: Step-by-step processes for common tasks +- **Reference material**: Code snippets, checklists, decision trees +- **Context injection**: Activate when specific conditions are met + +Unlike **agents** (specialized subassistants) or **commands** (user-triggered actions), skills are passive knowledge that Claude Code references when relevant. + +### When Skills Activate + +Skills activate when: +- The user's task matches the skill's domain +- Claude Code detects relevant context +- A command references a skill +- An agent needs domain knowledge + +### Skill vs Agent vs Command + +| Component | Purpose | Activation | +|-----------|---------|------------| +| **Skill** | Knowledge repository | Context-based (automatic) | +| **Agent** | Task executor | Explicit delegation | +| **Command** | User action | User-invoked (`/command`) | +| **Hook** | Automation | Event-triggered | +| **Rule** | Always-on guidelines | Always active | + +--- + +## Skill Architecture + +### File Structure + +``` +skills/ +└── your-skill-name/ + ├── SKILL.md # Required: Main skill definition + ├── examples/ # Optional: Code examples + │ ├── basic.ts + │ └── advanced.ts + └── references/ # Optional: External references + └── links.md +``` + +### SKILL.md Format + +```markdown +--- +name: skill-name +description: Brief description shown in skill list and used for auto-activation +origin: ECC +--- + +# Skill Title + +Brief overview of what this skill covers. + +## When to Activate + +Describe scenarios where Claude should use this skill. + +## Core Concepts + +Main patterns and guidelines. + +## Code Examples + +\`\`\`typescript +// Practical, tested examples +\`\`\` + +## Best Practices + +- Actionable guidelines +- Do's and don'ts + +## Related Skills + +Link to complementary skills. +``` + +### YAML Frontmatter Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Lowercase, hyphenated identifier (e.g., `react-patterns`) | +| `description` | Yes | One-line description for skill list and auto-activation | +| `origin` | No | Source identifier (e.g., `ECC`, `community`, project name) | +| `tags` | No | Array of tags for categorization | +| `version` | No | Skill version for tracking updates | + +--- + +## Creating Your First Skill + +### Step 1: Choose a Focus + +Good skills are **focused and actionable**: + +| ✅ Good Focus | ❌ Too Broad | +|---------------|--------------| +| `react-hook-patterns` | `react` | +| `postgresql-indexing` | `databases` | +| `pytest-fixtures` | `python-testing` | +| `nextjs-app-router` | `nextjs` | + +### Step 2: Create the Directory + +```bash +mkdir -p skills/your-skill-name +``` + +### Step 3: Write SKILL.md + +Here's a minimal template: + +```markdown +--- +name: your-skill-name +description: Brief description of when to use this skill +--- + +# Your Skill Title + +Brief overview (1-2 sentences). + +## When to Activate + +- Scenario 1 +- Scenario 2 +- Scenario 3 + +## Core Concepts + +### Concept 1 + +Explanation with examples. + +### Concept 2 + +Another pattern with code. + +## Code Examples + +\`\`\`typescript +// Practical example +\`\`\` + +## Best Practices + +- Do this +- Avoid that + +## Related Skills + +- `related-skill-1` +- `related-skill-2` +``` + +### Step 4: Add Content + +Write content that Claude can **immediately use**: + +- ✅ Copy-pasteable code examples +- ✅ Clear decision trees +- ✅ Checklists for verification +- ❌ Vague explanations without examples +- ❌ Long prose without actionable guidance + +--- + +## Skill Categories + +### Language Standards + +Focus on idiomatic code, naming conventions, and language-specific patterns. + +**Examples:** `python-patterns`, `golang-patterns`, `typescript-standards` + +```markdown +--- +name: python-patterns +description: Python idioms, best practices, and patterns for clean, idiomatic code. +--- + +# Python Patterns + +## When to Activate + +- Writing Python code +- Refactoring Python modules +- Python code review + +## Core Concepts + +### Context Managers + +\`\`\`python +# Always use context managers for resources +with open('file.txt') as f: + content = f.read() +\`\`\` +``` + +### Framework Patterns + +Focus on framework-specific conventions, common patterns, and anti-patterns. + +**Examples:** `django-patterns`, `nextjs-patterns`, `springboot-patterns` + +```markdown +--- +name: django-patterns +description: Django best practices for models, views, URLs, and templates. +--- + +# Django Patterns + +## When to Activate + +- Building Django applications +- Creating models and views +- Django URL configuration +``` + +### Workflow Skills + +Define step-by-step processes for common development tasks. + +**Examples:** `tdd-workflow`, `code-review-workflow`, `deployment-checklist` + +```markdown +--- +name: code-review-workflow +description: Systematic code review process for quality and security. +--- + +# Code Review Workflow + +## Steps + +1. **Understand Context** - Read PR description and linked issues +2. **Check Tests** - Verify test coverage and quality +3. **Review Logic** - Analyze implementation for correctness +4. **Check Security** - Look for vulnerabilities +5. **Verify Style** - Ensure code follows conventions +``` + +### Domain Knowledge + +Specialized knowledge for specific domains (security, performance, etc.). + +**Examples:** `security-review`, `performance-optimization`, `api-design` + +```markdown +--- +name: api-design +description: REST and GraphQL API design patterns, versioning, and best practices. +--- + +# API Design Patterns + +## RESTful Conventions + +| Method | Endpoint | Purpose | +|--------|----------|---------| +| GET | /resources | List all | +| GET | /resources/:id | Get one | +| POST | /resources | Create | +``` + +### Tool Integration + +Guidance for using specific tools, libraries, or services. + +**Examples:** `supabase-patterns`, `docker-patterns`, `mcp-server-patterns` + +--- + +## Writing Effective Skill Content + +### 1. Start with "When to Activate" + +This section is **critical** for auto-activation. Be specific: + +```markdown +## When to Activate + +- Creating new React components +- Refactoring existing components +- Debugging React state issues +- Reviewing React code for best practices +``` + +### 2. Use "Show, Don't Tell" + +Bad: +```markdown +## Error Handling + +Always handle errors properly in async functions. +``` + +Good: +```markdown +## Error Handling + +\`\`\`typescript +async function fetchData(url: string) { + try { + const response = await fetch(url) + + if (!response.ok) { + throw new Error(\`HTTP \${response.status}: \${response.statusText}\`) + } + + return await response.json() + } catch (error) { + console.error('Fetch failed:', error) + throw new Error('Failed to fetch data') + } +} +\`\`\` + +### Key Points + +- Check \`response.ok\` before parsing +- Log errors for debugging +- Re-throw with user-friendly message +``` + +### 3. Include Anti-Patterns + +Show what NOT to do: + +```markdown +## Anti-Patterns + +### ❌ Direct State Mutation + +\`\`\`typescript +// NEVER do this +user.name = 'New Name' +items.push(newItem) +\`\`\` + +### ✅ Immutable Updates + +\`\`\`typescript +// ALWAYS do this +const updatedUser = { ...user, name: 'New Name' } +const updatedItems = [...items, newItem] +\`\`\` +``` + +### 4. Provide Checklists + +Checklists are actionable and easy to follow: + +```markdown +## Pre-Deployment Checklist + +- [ ] All tests passing +- [ ] No console.log in production code +- [ ] Environment variables documented +- [ ] Secrets not hardcoded +- [ ] Error handling complete +- [ ] Input validation in place +``` + +### 5. Use Decision Trees + +For complex decisions: + +```markdown +## Choosing the Right Approach + +\`\`\` +Need to fetch data? +├── Single request → use fetch directly +├── Multiple independent → Promise.all() +├── Multiple dependent → await sequentially +└── With caching → use SWR or React Query +\`\`\` +``` + +--- + +## Best Practices + +### DO + +| Practice | Example | +|----------|---------| +| **Be specific** | "Use \`useCallback\` for event handlers passed to child components" | +| **Show examples** | Include copy-pasteable code | +| **Explain WHY** | "Immutability prevents unexpected side effects in React state" | +| **Link related skills** | "See also: \`react-performance\`" | +| **Keep focused** | One skill = one domain/concept | +| **Use sections** | Clear headers for easy scanning | + +### DON'T + +| Practice | Why It's Bad | +|----------|--------------| +| **Be vague** | "Write good code" - not actionable | +| **Long prose** | Hard to parse, better as code | +| **Cover too much** | "Python, Django, and Flask patterns" - too broad | +| **Skip examples** | Theory without practice is less useful | +| **Ignore anti-patterns** | Learning what NOT to do is valuable | + +### Content Guidelines + +1. **Length**: 200-500 lines typical, 800 lines maximum +2. **Code blocks**: Include language identifier +3. **Headers**: Use `##` and `###` hierarchy +4. **Lists**: Use `-` for unordered, `1.` for ordered +5. **Tables**: For comparisons and references + +--- + +## Common Patterns + +### Pattern 1: Standards Skill + +```markdown +--- +name: language-standards +description: Coding standards and best practices for [language]. +--- + +# [Language] Coding Standards + +## When to Activate + +- Writing [language] code +- Code review +- Setting up linting + +## Naming Conventions + +| Element | Convention | Example | +|---------|------------|---------| +| Variables | camelCase | userName | +| Constants | SCREAMING_SNAKE | MAX_RETRY | +| Functions | camelCase | fetchUser | +| Classes | PascalCase | UserService | + +## Code Examples + +[Include practical examples] + +## Linting Setup + +[Include configuration] + +## Related Skills + +- `language-testing` +- `language-security` +``` + +### Pattern 2: Workflow Skill + +```markdown +--- +name: task-workflow +description: Step-by-step workflow for [task]. +--- + +# [Task] Workflow + +## When to Activate + +- [Trigger 1] +- [Trigger 2] + +## Prerequisites + +- [Requirement 1] +- [Requirement 2] + +## Steps + +### Step 1: [Name] + +[Description] + +\`\`\`bash +[Commands] +\`\`\` + +### Step 2: [Name] + +[Description] + +## Verification + +- [ ] [Check 1] +- [ ] [Check 2] + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| [Issue] | [Fix] | +``` + +### Pattern 3: Reference Skill + +```markdown +--- +name: api-reference +description: Quick reference for [API/Library]. +--- + +# [API/Library] Reference + +## When to Activate + +- Using [API/Library] +- Looking up [API/Library] syntax + +## Common Operations + +### Operation 1 + +\`\`\`typescript +// Basic usage +\`\`\` + +### Operation 2 + +\`\`\`typescript +// Advanced usage +\`\`\` + +## Configuration + +[Include config examples] + +## Error Handling + +[Include error patterns] +``` + +--- + +## Testing Your Skill + +### Local Testing + +1. **Copy to Claude Code skills directory**: + ```bash + cp -r skills/your-skill-name ~/.claude/skills/ + ``` + +2. **Test with Claude Code**: + ``` + You: "I need to [task that should trigger your skill]" + + Claude should reference your skill's patterns. + ``` + +3. **Verify activation**: + - Ask Claude to explain a concept from your skill + - Check if it uses your examples and patterns + - Ensure it follows your guidelines + +### Validation Checklist + +- [ ] **YAML frontmatter valid** - No syntax errors +- [ ] **Name follows convention** - lowercase-with-hyphens +- [ ] **Description is clear** - Tells when to use +- [ ] **Examples work** - Code compiles and runs +- [ ] **Links valid** - Related skills exist +- [ ] **No sensitive data** - No API keys, tokens, paths + +### Code Example Testing + +Test all code examples: + +```bash +# For TypeScript +npx tsc --noEmit examples/*.ts + +# For Python +python -m py_compile examples/*.py + +# For Go +go build ./examples/... +``` + +--- + +## Submitting Your Skill + +### 1. Fork and Clone + +```bash +gh repo fork affaan-m/everything-claude-code --clone +cd everything-claude-code +``` + +### 2. Create Branch + +```bash +git checkout -b feat/skill-your-skill-name +``` + +### 3. Add Your Skill + +```bash +mkdir -p skills/your-skill-name +# Create SKILL.md +``` + +### 4. Validate + +```bash +# Check YAML frontmatter +head -10 skills/your-skill-name/SKILL.md + +# Verify structure +ls -la skills/your-skill-name/ + +# Run tests if available +npm test +``` + +### 5. Commit and Push + +```bash +git add skills/your-skill-name/ +git commit -m "feat(skills): add your-skill-name skill" +git push -u origin feat/skill-your-skill-name +``` + +### 6. Create Pull Request + +Use this PR template: + +```markdown +## Summary + +Brief description of the skill and why it's valuable. + +## Skill Type + +- [ ] Language standards +- [ ] Framework patterns +- [ ] Workflow +- [ ] Domain knowledge +- [ ] Tool integration + +## Testing + +How I tested this skill locally. + +## Checklist + +- [ ] YAML frontmatter valid +- [ ] Code examples tested +- [ ] Follows skill guidelines +- [ ] No sensitive data +- [ ] Clear activation triggers +``` + +--- + +## Examples Gallery + +### Example 1: Language Standards + +**File:** `skills/rust-patterns/SKILL.md` + +```markdown +--- +name: rust-patterns +description: Rust idioms, ownership patterns, and best practices for safe, idiomatic code. +origin: ECC +--- + +# Rust Patterns + +## When to Activate + +- Writing Rust code +- Handling ownership and borrowing +- Error handling with Result/Option +- Implementing traits + +## Ownership Patterns + +### Borrowing Rules + +\`\`\`rust +// ✅ CORRECT: Borrow when you don't need ownership +fn process_data(data: &str) -> usize { + data.len() +} + +// ✅ CORRECT: Take ownership when you need to modify or consume +fn consume_data(data: Vec) -> String { + String::from_utf8(data).unwrap() +} +\`\`\` + +## Error Handling + +### Result Pattern + +\`\`\`rust +use thiserror::Error; + +#[derive(Error, Debug)] +pub enum AppError { + #[error("IO error: {0}")] + Io(#[from] std::io::Error), + + #[error("Parse error: {0}")] + Parse(#[from] std::num::ParseIntError), +} + +pub type AppResult = Result; +\`\`\` + +## Related Skills + +- `rust-testing` +- `rust-security` +``` + +### Example 2: Framework Patterns + +**File:** `skills/fastapi-patterns/SKILL.md` + +```markdown +--- +name: fastapi-patterns +description: FastAPI patterns for routing, dependency injection, validation, and async operations. +origin: ECC +--- + +# FastAPI Patterns + +## When to Activate + +- Building FastAPI applications +- Creating API endpoints +- Implementing dependency injection +- Handling async database operations + +## Project Structure + +\`\`\` +app/ +├── main.py # FastAPI app entry point +├── routers/ # Route handlers +│ ├── users.py +│ └── items.py +├── models/ # Pydantic models +│ ├── user.py +│ └── item.py +├── services/ # Business logic +│ └── user_service.py +└── dependencies.py # Shared dependencies +\`\`\` + +## Dependency Injection + +\`\`\`python +from fastapi import Depends +from sqlalchemy.ext.asyncio import AsyncSession + +async def get_db() -> AsyncSession: + async with AsyncSessionLocal() as session: + yield session + +@router.get("/users/{user_id}") +async def get_user( + user_id: int, + db: AsyncSession = Depends(get_db) +): + # Use db session + pass +\`\`\` + +## Related Skills + +- `python-patterns` +- `pydantic-validation` +``` + +### Example 3: Workflow Skill + +**File:** `skills/refactoring-workflow/SKILL.md` + +```markdown +--- +name: refactoring-workflow +description: Systematic refactoring workflow for improving code quality without changing behavior. +origin: ECC +--- + +# Refactoring Workflow + +## When to Activate + +- Improving code structure +- Reducing technical debt +- Simplifying complex code +- Extracting reusable components + +## Prerequisites + +- All tests passing +- Git working directory clean +- Feature branch created + +## Workflow Steps + +### Step 1: Identify Refactoring Target + +- Look for code smells (long methods, duplicate code, large classes) +- Check test coverage for target area +- Document current behavior + +### Step 2: Ensure Tests Exist + +\`\`\`bash +# Run tests to verify current behavior +npm test + +# Check coverage for target files +npm run test:coverage +\`\`\` + +### Step 3: Make Small Changes + +- One refactoring at a time +- Run tests after each change +- Commit frequently + +### Step 4: Verify Behavior Unchanged + +\`\`\`bash +# Run full test suite +npm test + +# Run E2E tests +npm run test:e2e +\`\`\` + +## Common Refactorings + +| Smell | Refactoring | +|-------|-------------| +| Long method | Extract method | +| Duplicate code | Extract to shared function | +| Large class | Extract class | +| Long parameter list | Introduce parameter object | + +## Checklist + +- [ ] Tests exist for target code +- [ ] Made small, focused changes +- [ ] Tests pass after each change +- [ ] Behavior unchanged +- [ ] Committed with clear message +``` + +--- + +## Additional Resources + +- [CONTRIBUTING.md](../CONTRIBUTING.md) - General contribution guidelines +- [project-guidelines-example](../skills/project-guidelines-example/SKILL.md) - Project-specific skill template +- [coding-standards](../skills/coding-standards/SKILL.md) - Example of standards skill +- [tdd-workflow](../skills/tdd-workflow/SKILL.md) - Example of workflow skill +- [security-review](../skills/security-review/SKILL.md) - Example of domain knowledge skill + +--- + +**Remember**: A good skill is focused, actionable, and immediately useful. Write skills you'd want to use yourself. \ No newline at end of file From da74f85c10c540129ddf7ba6a4f2cb314b8bde80 Mon Sep 17 00:00:00 2001 From: xingzihai <1315258019@qq.com> Date: Thu, 26 Mar 2026 04:37:08 +0000 Subject: [PATCH 4/5] fix: address review feedback from PR #929 - Add missing code-review.md and development-workflow.md to zh/README.md directory listing - Add mkdir -p command before copy in manual install instructions - Fix TypeScript test command path in SKILL-DEVELOPMENT-GUIDE.md - Add Anti-Patterns section to SKILL.md template - Add Template category to Skill Categories table in CONTRIBUTING.md - Add Pre-Review Requirements section to code-review.md (both en and zh) - Add Pre-Review Checks step to development-workflow.md (both en and zh) - Add trailing newlines to all files that were missing them --- CONTRIBUTING.md | 1 + docs/SKILL-DEVELOPMENT-GUIDE.md | 14 +++++++++----- rules/common/code-review.md | 10 +++++++++- rules/common/development-workflow.md | 6 ++++++ rules/zh/README.md | 10 ++++++++-- rules/zh/agents.md | 2 +- rules/zh/code-review.md | 10 +++++++++- rules/zh/coding-style.md | 2 +- rules/zh/development-workflow.md | 8 +++++++- rules/zh/git-workflow.md | 2 +- rules/zh/hooks.md | 2 +- rules/zh/patterns.md | 2 +- rules/zh/performance.md | 2 +- rules/zh/security.md | 2 +- rules/zh/testing.md | 2 +- 15 files changed, 57 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd956663..bf5db0a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -142,6 +142,7 @@ Link to complementary skills (e.g., `related-skill-1`, `related-skill-2`). | **Workflow** | Step-by-step processes | `tdd-workflow`, `refactoring-workflow` | | **Domain Knowledge** | Specialized domains | `security-review`, `api-design` | | **Tool Integration** | Tool/library usage | `docker-patterns`, `supabase-patterns` | +| **Template** | Project-specific skill templates | `project-guidelines-example` | ### Skill Checklist diff --git a/docs/SKILL-DEVELOPMENT-GUIDE.md b/docs/SKILL-DEVELOPMENT-GUIDE.md index 6a5b123c..a772c868 100644 --- a/docs/SKILL-DEVELOPMENT-GUIDE.md +++ b/docs/SKILL-DEVELOPMENT-GUIDE.md @@ -90,6 +90,10 @@ Main patterns and guidelines. // Practical, tested examples \`\`\` +## Anti-Patterns + +Show what NOT to do with concrete examples. + ## Best Practices - Actionable guidelines @@ -602,14 +606,14 @@ description: Quick reference for [API/Library]. Test all code examples: ```bash -# For TypeScript -npx tsc --noEmit examples/*.ts +# For TypeScript (run from inside the skill directory or specify the path) +npx tsc --noEmit skills/your-skill-name/examples/*.ts # For Python -python -m py_compile examples/*.py +python -m py_compile skills/your-skill-name/examples/*.py # For Go -go build ./examples/... +go build ./skills/your-skill-name/examples/... ``` --- @@ -903,4 +907,4 @@ npm run test:e2e --- -**Remember**: A good skill is focused, actionable, and immediately useful. Write skills you'd want to use yourself. \ No newline at end of file +**Remember**: A good skill is focused, actionable, and immediately useful. Write skills you'd want to use yourself. diff --git a/rules/common/code-review.md b/rules/common/code-review.md index e2364b07..d79ba9bf 100644 --- a/rules/common/code-review.md +++ b/rules/common/code-review.md @@ -14,6 +14,14 @@ Code review ensures quality, security, and maintainability before code is merged - When architectural changes are made - Before merging pull requests +**Pre-Review Requirements:** + +Before requesting review, ensure: + +- All automated checks (CI/CD) are passing +- Merge conflicts are resolved +- Branch is up to date with target branch + ## Review Checklist Before marking code complete: @@ -113,4 +121,4 @@ This rule works with: - [testing.md](testing.md) - Test coverage requirements - [security.md](security.md) - Security checklist - [git-workflow.md](git-workflow.md) - Commit standards -- [agents.md](agents.md) - Agent delegation \ No newline at end of file +- [agents.md](agents.md) - Agent delegation diff --git a/rules/common/development-workflow.md b/rules/common/development-workflow.md index d97c1b1d..ae070be2 100644 --- a/rules/common/development-workflow.md +++ b/rules/common/development-workflow.md @@ -36,3 +36,9 @@ The Feature Implementation Workflow describes the development pipeline: research - Detailed commit messages - Follow conventional commits format - See [git-workflow.md](./git-workflow.md) for commit message format and PR process + +5. **Pre-Review Checks** + - Verify all automated checks (CI/CD) are passing + - Resolve any merge conflicts + - Ensure branch is up to date with target branch + - Only request review after these checks pass diff --git a/rules/zh/README.md b/rules/zh/README.md index 0793b4fd..34f71910 100644 --- a/rules/zh/README.md +++ b/rules/zh/README.md @@ -14,7 +14,9 @@ rules/ │ ├── patterns.md │ ├── hooks.md │ ├── agents.md -│ └── security.md +│ ├── security.md +│ ├── code-review.md +│ └── development-workflow.md ├── zh/ # 中文翻译版本 │ ├── coding-style.md │ ├── git-workflow.md @@ -24,6 +26,7 @@ rules/ │ ├── hooks.md │ ├── agents.md │ ├── security.md +│ ├── code-review.md │ └── development-workflow.md ├── typescript/ # TypeScript/JavaScript 特定 ├── python/ # Python 特定 @@ -60,6 +63,9 @@ rules/ > 并破坏语言特定文件使用的 `../common/` 相对引用。 ```bash +# 创建目标目录 +mkdir -p ~/.claude/rules + # 安装通用规则（所有项目必需） cp -r rules/common ~/.claude/rules/common @@ -99,4 +105,4 @@ cp -r rules/php ~/.claude/rules/php `rules/common/` 中可能被语言特定文件覆盖的规则会标记： -> **语言说明**：此规则可能被语言特定规则覆盖，对于某些语言，该模式可能不是惯用的。 \ No newline at end of file +> **语言说明**：此规则可能被语言特定规则覆盖，对于某些语言，该模式可能不是惯用的。 diff --git a/rules/zh/agents.md b/rules/zh/agents.md index dc75dcf4..3723d4b4 100644 --- a/rules/zh/agents.md +++ b/rules/zh/agents.md @@ -47,4 +47,4 @@ - 高级工程师 - 安全专家 - 一致性审查者 -- 冗余检查者 \ No newline at end of file +- 冗余检查者 diff --git a/rules/zh/code-review.md b/rules/zh/code-review.md index 608709e9..bb4c228c 100644 --- a/rules/zh/code-review.md +++ b/rules/zh/code-review.md @@ -14,6 +14,14 @@ - 进行架构更改时 - 合并 pull request 之前 +**审查前要求：** + +在请求审查之前，确保： + +- 所有自动化检查（CI/CD）已通过 +- 合并冲突已解决 +- 分支已与目标分支同步 + ## 审查检查清单 在标记代码完成之前： @@ -113,4 +121,4 @@ - [testing.md](testing.md) - 测试覆盖率要求 - [security.md](security.md) - 安全检查清单 - [git-workflow.md](git-workflow.md) - 提交标准 -- [agents.md](agents.md) - 代理委托 \ No newline at end of file +- [agents.md](agents.md) - 代理委托 diff --git a/rules/zh/coding-style.md b/rules/zh/coding-style.md index dd975d88..e20a609e 100644 --- a/rules/zh/coding-style.md +++ b/rules/zh/coding-style.md @@ -45,4 +45,4 @@ - [ ] 没有深层嵌套（>4 层） - [ ] 正确的错误处理 - [ ] 没有硬编码值（使用常量或配置） -- [ ] 没有变更（使用不可变模式） \ No newline at end of file +- [ ] 没有变更（使用不可变模式） diff --git a/rules/zh/development-workflow.md b/rules/zh/development-workflow.md index 610fbbac..f0aa9785 100644 --- a/rules/zh/development-workflow.md +++ b/rules/zh/development-workflow.md @@ -35,4 +35,10 @@ 4. **提交与推送** - 详细的提交消息 - 遵循约定式提交格式 - - 参见 [git-workflow.md](./git-workflow.md) 了解提交消息格式和 PR 流程 \ No newline at end of file + - 参见 [git-workflow.md](./git-workflow.md) 了解提交消息格式和 PR 流程 + +5. **审查前检查** + - 验证所有自动化检查（CI/CD）已通过 + - 解决任何合并冲突 + - 确保分支已与目标分支同步 + - 仅在这些检查通过后请求审查 diff --git a/rules/zh/git-workflow.md b/rules/zh/git-workflow.md index 15b27ed2..50a4217f 100644 --- a/rules/zh/git-workflow.md +++ b/rules/zh/git-workflow.md @@ -21,4 +21,4 @@ 5. 如果是新分支，使用 `-u` 标志推送 > 对于 git 操作之前的完整开发流程（规划、TDD、代码审查）， -> 参见 [development-workflow.md](./development-workflow.md)。 \ No newline at end of file +> 参见 [development-workflow.md](./development-workflow.md)。 diff --git a/rules/zh/hooks.md b/rules/zh/hooks.md index c16bcd40..e66383bc 100644 --- a/rules/zh/hooks.md +++ b/rules/zh/hooks.md @@ -27,4 +27,4 @@ - 缺失的项目 - 多余的不必要项目 - 错误的粒度 -- 误解的需求 \ No newline at end of file +- 误解的需求 diff --git a/rules/zh/patterns.md b/rules/zh/patterns.md index ef51b297..e39f245e 100644 --- a/rules/zh/patterns.md +++ b/rules/zh/patterns.md @@ -28,4 +28,4 @@ - 包含成功/状态指示器 - 包含数据负载（错误时可为空） - 包含错误消息字段（成功时可为空） -- 包含分页响应的元数据（total、page、limit） \ No newline at end of file +- 包含分页响应的元数据（total、page、limit） diff --git a/rules/zh/performance.md b/rules/zh/performance.md index a8d34a79..11a2911c 100644 --- a/rules/zh/performance.md +++ b/rules/zh/performance.md @@ -52,4 +52,4 @@ 1. 使用 **build-error-resolver** 代理 2. 分析错误消息 3. 增量修复 -4. 每次修复后验证 \ No newline at end of file +4. 每次修复后验证 diff --git a/rules/zh/security.md b/rules/zh/security.md index 1fbf01a1..3956a481 100644 --- a/rules/zh/security.md +++ b/rules/zh/security.md @@ -26,4 +26,4 @@ 2. 使用 **security-reviewer** 代理 3. 在继续之前修复关键问题 4. 轮换任何已暴露的密钥 -5. 审查整个代码库中的类似问题 \ No newline at end of file +5. 审查整个代码库中的类似问题 diff --git a/rules/zh/testing.md b/rules/zh/testing.md index c73c1491..cb899fa7 100644 --- a/rules/zh/testing.md +++ b/rules/zh/testing.md @@ -26,4 +26,4 @@ ## 代理支持 -- **tdd-guide** - 主动用于新功能，强制先写测试 \ No newline at end of file +- **tdd-guide** - 主动用于新功能，强制先写测试 From e815f0d05c0bce41d1f19f57fe27c21de2292c2b Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Sat, 28 Mar 2026 20:23:34 -0400 Subject: [PATCH 5/5] fix(docs): resolve skill guide review issues --- docs/SKILL-DEVELOPMENT-GUIDE.md | 15 ++++++++++++--- rules/zh/README.md | 4 ++-- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/SKILL-DEVELOPMENT-GUIDE.md b/docs/SKILL-DEVELOPMENT-GUIDE.md index a772c868..cbf5e3c8 100644 --- a/docs/SKILL-DEVELOPMENT-GUIDE.md +++ b/docs/SKILL-DEVELOPMENT-GUIDE.md @@ -606,14 +606,23 @@ description: Quick reference for [API/Library]. Test all code examples: ```bash -# For TypeScript (run from inside the skill directory or specify the path) +# From the repo root npx tsc --noEmit skills/your-skill-name/examples/*.ts -# For Python +# Or from inside the skill directory +npx tsc --noEmit examples/*.ts + +# From the repo root python -m py_compile skills/your-skill-name/examples/*.py -# For Go +# Or from inside the skill directory +python -m py_compile examples/*.py + +# From the repo root go build ./skills/your-skill-name/examples/... + +# Or from inside the skill directory +go build ./examples/... ``` --- diff --git a/rules/zh/README.md b/rules/zh/README.md index 34f71910..35baaf64 100644 --- a/rules/zh/README.md +++ b/rules/zh/README.md @@ -103,6 +103,6 @@ cp -r rules/php ~/.claude/rules/php ### 带覆盖说明的通用规则 -`rules/common/` 中可能被语言特定文件覆盖的规则会标记： +`rules/common/` 中可能被语言特定文件覆盖的规则会被标记： -> **语言说明**：此规则可能被语言特定规则覆盖，对于某些语言，该模式可能不是惯用的。 +> **语言说明**：此规则可能会被语言特定规则覆盖；对于某些语言，该模式可能并不符合惯用写法。