The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add Chinese (zh-CN) translation for rules/common
xingzihai3f5e042b40a9
diff --git a/rules/zh/README.md b/rules/zh/README.mdnew file mode 100644index 000000000..0793b4fde--- /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 filediff --git a/rules/zh/agents.md b/rules/zh/agents.mdnew file mode 100644index 000000000..dc75dcf4d--- /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 filediff --git a/rules/zh/code-review.md b/rules/zh/code-review.mdnew file mode 100644index 000000000..608709e9f--- /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 filediff --git a/rules/zh/coding-style.md b/rules/zh/coding-style.mdnew file mode 100644index 000000000..dd975d88a--- /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 filediff --git a/rules/zh/development-workflow.md b/rules/zh/development-workflow.mdnew file mode 100644index 000000000..610fbbace--- /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 filediff --git a/rules/zh/git-workflow.md b/rules/zh/git-workflow.mdnew file mode 100644index 000000000..15b27ed2c--- /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 filediff --git a/rules/zh/hooks.md b/rules/zh/hooks.mdnew file mode 100644index 000000000..c16bcd401--- /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 filediff --git a/rules/zh/patterns.md b/rules/zh/patterns.mdnew file mode 100644index 000000000..ef51b297c--- /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 filediff --git a/rules/zh/performance.md b/rules/zh/performance.mdnew file mode 100644index 000000000..a8d34a79b--- /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 filediff --git a/rules/zh/security.md b/rules/zh/security.mdnew file mode 100644index 000000000..1fbf01a11--- /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 filediff --git a/rules/zh/testing.md b/rules/zh/testing.mdnew file mode 100644index 000000000..c73c14914--- /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