From 5dc60a5243aab90b3fecb4db7d02b6e8d6143b16 Mon Sep 17 00:00:00 2001 From: konstapukarifastnetfi Date: Sun, 7 Jun 2026 08:25:56 +0300 Subject: [PATCH] fix: retire rules/zh from the always-loaded default rules install (#2170) rules/zh shipped ~17KB of Chinese rule text into the auto-loaded rules tree of every default install (rules-core installs the bare 'rules' path with defaultInstall: true), with no paths: frontmatter gating. The content had also drifted behind both rules/common and the maintained translations in docs/zh-CN/rules/common (e.g. zh/coding-style.md 48 lines vs the 52-line docs/zh-CN copy), and 'zh' was already dropped from the installer's language help in favor of the gated docs-zh-cn locale module (--locale zh-CN). - move rules/zh/code-review.md to docs/zh-CN/rules/common/code-review.md: the only file with no counterpart in the maintained locale tree (fills a zh-CN parity gap with rules/common/code-review.md) - delete the remaining 10 rules/zh files, all older duplicates of docs/zh-CN/rules/common content - update trae-install test to assert the rules tree via rules/web instead Not addressed here: rules/README.md (~5.5KB of installer docs) still ships into the auto-loaded tree via the bare 'rules' module path; filtering README files from rule-tree expansion is a separate decision --- .../zh-CN/rules/common}/code-review.md | 0 rules/zh/README.md | 108 ------------------ rules/zh/agents.md | 50 -------- rules/zh/coding-style.md | 48 -------- rules/zh/development-workflow.md | 44 ------- 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 ----- tests/lib/install-targets.test.js | 6 - tests/scripts/trae-install.test.js | 4 +- 13 files changed, 2 insertions(+), 456 deletions(-) rename {rules/zh => docs/zh-CN/rules/common}/code-review.md (100%) delete mode 100644 rules/zh/README.md delete mode 100644 rules/zh/agents.md delete mode 100644 rules/zh/coding-style.md delete mode 100644 rules/zh/development-workflow.md delete mode 100644 rules/zh/git-workflow.md delete mode 100644 rules/zh/hooks.md delete mode 100644 rules/zh/patterns.md delete mode 100644 rules/zh/performance.md delete mode 100644 rules/zh/security.md delete mode 100644 rules/zh/testing.md diff --git a/rules/zh/code-review.md b/docs/zh-CN/rules/common/code-review.md similarity index 100% rename from rules/zh/code-review.md rename to docs/zh-CN/rules/common/code-review.md diff --git a/rules/zh/README.md b/rules/zh/README.md deleted file mode 100644 index 35baaf64..00000000 --- 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.md deleted file mode 100644 index 3723d4b4..00000000 --- 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.md deleted file mode 100644 index e20a609e..00000000 --- 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.md deleted file mode 100644 index f0aa9785..00000000 --- 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.md deleted file mode 100644 index 50a4217f..00000000 --- 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.md deleted file mode 100644 index e66383bc..00000000 --- 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.md deleted file mode 100644 index e39f245e..00000000 --- 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.md deleted file mode 100644 index 11a2911c..00000000 --- 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.md deleted file mode 100644 index 3956a481..00000000 --- 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.md deleted file mode 100644 index cb899fa7..00000000 --- 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.js index f59afd8e..8d039f93 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.js index 77dde617..167b913a 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);