The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: retire rules/zh from the always-loaded default rules install (#2170)
konstapukarifastnetfi5dc60a5243aa
diff --git a/rules/zh/code-review.md b/docs/zh-CN/rules/common/code-review.mdsimilarity index 100%rename from rules/zh/code-review.mdrename to docs/zh-CN/rules/common/code-review.mddiff --git a/rules/zh/README.md b/rules/zh/README.mddeleted file mode 100644index 35baaf646..000000000--- a/rules/zh/README.md+++ /dev/null@@ -1,108 +0,0 @@-# 规则--## 结构--规则按**通用**层和**语言特定**目录组织:--```-rules/-├── common/ # 语言无关的原则(始终安装)-│ ├── coding-style.md-│ ├── git-workflow.md-│ ├── testing.md-│ ├── performance.md-│ ├── patterns.md-│ ├── hooks.md-│ ├── agents.md-│ ├── security.md-│ ├── code-review.md-│ └── development-workflow.md-├── zh/ # 中文翻译版本-│ ├── coding-style.md-│ ├── git-workflow.md-│ ├── testing.md-│ ├── performance.md-│ ├── patterns.md-│ ├── hooks.md-│ ├── agents.md-│ ├── security.md-│ ├── code-review.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-# 创建目标目录-mkdir -p ~/.claude/rules--# 安装通用规则(所有项目必需)-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/` 中可能被语言特定文件覆盖的规则会被标记:--> **语言说明**:此规则可能会被语言特定规则覆盖;对于某些语言,该模式可能并不符合惯用写法。diff --git a/rules/zh/agents.md b/rules/zh/agents.mddeleted file mode 100644index 3723d4b46..000000000--- a/rules/zh/agents.md+++ /dev/null@@ -1,50 +0,0 @@-# 代理编排--## 可用代理--位于 `~/.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-```--## 多视角分析--对于复杂问题,使用分角色子代理:-- 事实审查者-- 高级工程师-- 安全专家-- 一致性审查者-- 冗余检查者diff --git a/rules/zh/coding-style.md b/rules/zh/coding-style.mddeleted file mode 100644index e20a609ef..000000000--- a/rules/zh/coding-style.md+++ /dev/null@@ -1,48 +0,0 @@-# 编码风格--## 不可变性(关键)--始终创建新对象,永远不要修改现有对象:--```-// 伪代码-错误: modify(original, field, value) → 就地修改 original-正确: update(original, field, value) → 返回带有更改的新副本-```--原理:不可变数据防止隐藏的副作用,使调试更容易,并启用安全的并发。--## 文件组织--多个小文件 > 少量大文件:-- 高内聚,低耦合-- 典型 200-400 行,最多 800 行-- 从大模块中提取工具函数-- 按功能/领域组织,而非按类型--## 错误处理--始终全面处理错误:-- 在每一层显式处理错误-- 在面向 UI 的代码中提供用户友好的错误消息-- 在服务器端记录详细的错误上下文-- 永远不要静默吞掉错误--## 输入验证--始终在系统边界验证:-- 处理前验证所有用户输入-- 在可用的情况下使用基于模式的验证-- 快速失败并给出清晰的错误消息-- 永远不要信任外部数据(API 响应、用户输入、文件内容)--## 代码质量检查清单--在标记工作完成前:-- [ ] 代码可读且命名良好-- [ ] 函数很小(<50 行)-- [ ] 文件聚焦(<800 行)-- [ ] 没有深层嵌套(>4 层)-- [ ] 正确的错误处理-- [ ] 没有硬编码值(使用常量或配置)-- [ ] 没有变更(使用不可变模式)diff --git a/rules/zh/development-workflow.md b/rules/zh/development-workflow.mddeleted file mode 100644index f0aa97851..000000000--- a/rules/zh/development-workflow.md+++ /dev/null@@ -1,44 +0,0 @@-# 开发工作流--> 此文件扩展 [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 流程--5. **审查前检查**- - 验证所有自动化检查(CI/CD)已通过- - 解决任何合并冲突- - 确保分支已与目标分支同步- - 仅在这些检查通过后请求审查diff --git a/rules/zh/git-workflow.md b/rules/zh/git-workflow.mddeleted file mode 100644index 50a4217f2..000000000--- a/rules/zh/git-workflow.md+++ /dev/null@@ -1,24 +0,0 @@-# 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)。diff --git a/rules/zh/hooks.md b/rules/zh/hooks.mddeleted file mode 100644index e66383bc6..000000000--- a/rules/zh/hooks.md+++ /dev/null@@ -1,30 +0,0 @@-# 钩子系统--## 钩子类型--- **PreToolUse**:工具执行前(验证、参数修改)-- **PostToolUse**:工具执行后(自动格式化、检查)-- **Stop**:会话结束时(最终验证)--## 自动接受权限--谨慎使用:-- 为可信、定义明确的计划启用-- 探索性工作时禁用-- 永远不要使用 dangerously-skip-permissions 标志-- 改为在 `~/.claude.json` 中配置 `allowedTools`--## TodoWrite 最佳实践--使用 TodoWrite 工具:-- 跟踪多步骤任务的进度-- 验证对指令的理解-- 启用实时引导-- 显示细粒度的实现步骤--待办列表揭示:-- 顺序错误的步骤-- 缺失的项目-- 多余的不必要项目-- 错误的粒度-- 误解的需求diff --git a/rules/zh/patterns.md b/rules/zh/patterns.mddeleted file mode 100644index e39f245e4..000000000--- a/rules/zh/patterns.md+++ /dev/null@@ -1,31 +0,0 @@-# 常用模式--## 骨架项目--实现新功能时:-1. 搜索久经考验的骨架项目-2. 使用并行代理评估选项:- - 安全性评估- - 可扩展性分析- - 相关性评分- - 实现规划-3. 克隆最佳匹配作为基础-4. 在经验证的结构内迭代--## 设计模式--### 仓储模式--将数据访问封装在一致的接口后面:-- 定义标准操作:findAll、findById、create、update、delete-- 具体实现处理存储细节(数据库、API、文件等)-- 业务逻辑依赖抽象接口,而非存储机制-- 便于轻松切换数据源,并简化使用模拟的测试--### API 响应格式--对所有 API 响应使用一致的信封:-- 包含成功/状态指示器-- 包含数据负载(错误时可为空)-- 包含错误消息字段(成功时可为空)-- 包含分页响应的元数据(total、page、limit)diff --git a/rules/zh/performance.md b/rules/zh/performance.mddeleted file mode 100644index 11a2911c1..000000000--- a/rules/zh/performance.md+++ /dev/null@@ -1,55 +0,0 @@-# 性能优化--## 模型选择策略--**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. 每次修复后验证diff --git a/rules/zh/security.md b/rules/zh/security.mddeleted file mode 100644index 3956a481c..000000000--- a/rules/zh/security.md+++ /dev/null@@ -1,29 +0,0 @@-# 安全指南--## 强制安全检查--在任何提交之前:-- [ ] 无硬编码密钥(API 密钥、密码、令牌)-- [ ] 所有用户输入已验证-- [ ] SQL 注入防护(参数化查询)-- [ ] XSS 防护(净化 HTML)-- [ ] CSRF 保护已启用-- [ ] 认证/授权已验证-- [ ] 所有端点启用速率限制-- [ ] 错误消息不泄露敏感数据--## 密钥管理--- 永远不要在源代码中硬编码密钥-- 始终使用环境变量或密钥管理器-- 启动时验证所需的密钥是否存在-- 轮换任何可能已暴露的密钥--## 安全响应协议--如果发现安全问题:-1. 立即停止-2. 使用 **security-reviewer** 代理-3. 在继续之前修复关键问题-4. 轮换任何已暴露的密钥-5. 审查整个代码库中的类似问题diff --git a/rules/zh/testing.md b/rules/zh/testing.mddeleted file mode 100644index cb899fa74..000000000--- a/rules/zh/testing.md+++ /dev/null@@ -1,29 +0,0 @@-# 测试要求--## 最低测试覆盖率:80%--测试类型(全部必需):-1. **单元测试** - 单个函数、工具、组件-2. **集成测试** - API 端点、数据库操作-3. **E2E 测试** - 关键用户流程(框架根据语言选择)--## 测试驱动开发--强制工作流:-1. 先写测试(RED)-2. 运行测试 - 应该失败-3. 编写最小实现(GREEN)-4. 运行测试 - 应该通过-5. 重构(IMPROVE)-6. 验证覆盖率(80%+)--## 测试失败排查--1. 使用 **tdd-guide** 代理-2. 检查测试隔离-3. 验证模拟是否正确-4. 修复实现,而非测试(除非测试有误)--## 代理支持--- **tdd-guide** - 主动用于新功能,强制先写测试diff --git a/tests/lib/install-targets.test.js b/tests/lib/install-targets.test.jsindex f59afd8ed..8d039f93d 100644--- a/tests/lib/install-targets.test.js+++ b/tests/lib/install-targets.test.js@@ -206,12 +206,6 @@ function runTests() {)),'Should not install Cursor README docs as runtime rule files');- assert.ok(- !plan.operations.some(operation => (- normalizedRelativePath(operation.sourceRelativePath) === 'rules/zh/README.md'- )),- 'Should not flatten localized README docs into Cursor rule files'- );})) passed++; else failed++;if (test('does not install root AGENTS.md into Cursor nested context', () => {diff --git a/tests/scripts/trae-install.test.js b/tests/scripts/trae-install.test.jsindex 77dde617b..167b913a3 100644--- a/tests/scripts/trae-install.test.js+++ b/tests/scripts/trae-install.test.js@@ -113,11 +113,11 @@ function runTests() {assert.ok(manifestLines.includes('skills/skill-comply/pyproject.toml'));assert.ok(manifestLines.includes('rules/common/code-review.md'));assert.ok(manifestLines.includes('rules/python/coding-style.md'));- assert.ok(manifestLines.includes('rules/zh/README.md'));+ assert.ok(manifestLines.includes('rules/web/performance.md'));assert.ok(fs.existsSync(path.join(projectRoot, '.trae', 'skills', 'skill-comply', 'pyproject.toml')));assert.ok(fs.existsSync(path.join(projectRoot, '.trae', 'rules', 'python', 'coding-style.md')));- assert.ok(fs.existsSync(path.join(projectRoot, '.trae', 'rules', 'zh', 'README.md')));+ assert.ok(fs.existsSync(path.join(projectRoot, '.trae', 'rules', 'web', 'performance.md')));} finally {cleanup(homeDir);cleanup(projectRoot);