oh-my-claudecode 规则模板（Rules Templates）实战指南：项目级 `.claude/rules` 的落地、注入与定制

oh-my-claudecode 规则模板（Rules Templates）实战指南：项目级.claude/rules的落地、注入与定制

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode

导读

本文是 oh-my-claudecode 项目 templates/rules 目录的完整技术指南。该目录提供了一套开箱即用的 Markdown 规则模板（代码风格、测试、安全、性能、Git 工作流、Karpathy 编码纪律），你可以将其复制到项目根目录的.claude/rules/下，由 oh-my-claudecode 自动发现并注入到所有 Agent 的上下文中。读完本文，你将掌握规则模板的复制安装流程、六个模板的完整内容与裁剪要点、[CUSTOMIZE]标记的定制方法，以及规则注入机制的底层实现原理（基于 src/hooks/rules-injector 的源码证据）。

一、规则模板是什么

在 Claude Code 生态中，"规则"（Rules）是一类以 Markdown（或.mdc）编写的指令文件，用于约束 AI 编码助手在某个项目中的行为。oh-my-claudecode 在 templates/rules/README.md 中定义了这一约定：

This directory contains rule templates that you can copy to your project's.claude/rules/directory.

它并不是直接加载目录本身，而是提供一套可复制、可裁剪的起始模板。每个模板都针对一个具体的工程维度，且都预留了[CUSTOMIZE]标记位，让使用者把项目特有的约定填进去。模板列表如下：

这套模板的定位是"最小可行约束"：既给出强制性的工程底线（不可变、错误处理、覆盖率、密钥管理），又通过[CUSTOMIZE]留出项目适配空间，避免模板变成一刀切的教条。

二、快速上手：复制与安装

README 给出的使用流程只有四步：

1. 在项目根目录创建.claude/rules/目录；
2. 复制你需要的模板进去；
3. 针对项目进行自定义；
4. 之后.claude/rules/*.md下的规则会被自动发现并注入上下文。

README 同时给出了可直接执行的 Bash 示例：

# Copy templates to your project mkdir -p .claude/rules cp templates/rules/security.md .claude/rules/ cp templates/rules/testing.md .claude/rules/ # Customize for your project # Edit .claude/rules/security.md to add project-specific checks

从源码结构看，规则发现机制（见下文第五节）支持.md与.mdc两种扩展名，且.claude/rules只是候选目录之一——它还同时扫描.github/instructions与.cursor/rules，因此模板同样可以适配其他 AI 编码工具链。模板目录位于仓库根目录 templates/rules 下，与 hooks 相关的可执行模板（.mjs文件）则位于 templates/hooks，两者职责不同：rules是给 Agent 的指令文本，hooks是钩子脚本。

三、六个模板逐项拆解

1. coding-style.md：代码风格与不可变原则

coding-style.md 把**不可变性（Immutability）**列为 CRITICAL 级要求：永远创建新对象，绝不就地修改。模板给出了正反对照：

// WRONG: Mutation function updateUser(user, name) { user.name = name // MUTATION! return user } // CORRECT: Immutability function updateUser(user, name) { return { ...user, name } }

文件组织遵循"多小文件优于少大文件"原则：高内聚、低耦合，单文件典型 200–400 行、上限 800 行，从大组件中抽离工具函数，按特性/领域而非类型组织目录。

错误处理要求全面兜底，模板给出的 TypeScript 范式为 try/catch 中记录原始错误、向外抛出用户可读信息：

try { const result = await riskyOperation() return result } catch (error) { console.error('Operation failed:', error) throw new Error('User-friendly error message') }

输入校验推荐使用 zod 声明式 schema：

import { z } from 'zod' const schema = z.object({ email: z.string().email(), age: z.number().int().min(0).max(150) }) const validated = schema.parse(input)

最后是代码质量自检清单：函数小于 50 行、文件小于 800 行、嵌套不超过 4 层、无console.log、无硬编码值、使用不可变模式等。[CUSTOMIZE]位用于补充命名规范、文件结构与框架特有模式。

2. testing.md：TDD 工作流与 80% 覆盖率

testing.md 设定了硬性目标：最低测试覆盖率 80%，且三类测试全部要求——单元测试（单函数/工具/组件）、集成测试（API 端点、数据库操作）、端到端测试（关键用户流）。

模板强制要求TDD 六步工作流：先写测试（RED）→ 运行确认失败 → 写最小实现（GREEN）→ 运行确认通过 → 重构（IMPROVE）→ 验证覆盖率 80%+。

每个函数必须覆盖的边界用例：null/undefined 输入、空数组/空字符串、非法类型、边界值（min/max）、错误条件。测试质量清单则强调：测试相互独立（无共享状态）、测试名描述行为、外部依赖用 mock、happy path 与错误路径都测、无 flaky 测试。

值得一提的是，本仓库自身正是这一模板的实践样本：src/__tests__/与 tests 目录下存在数百个针对规则注入、路径解析、竞态与超时等边界场景的测试（如 post-tool-rules-injector.test.ts），可作为测试质量的参考范例。

3. security.md：安全清单与密钥管理

security.md 规定任何提交前必须逐项检查：无硬编码密钥（API key、密码、token）、所有用户输入已验证、SQL 注入防护（参数化查询）、XSS 防护（HTML 净化）、启用 CSRF 防护、认证/授权已验证、所有端点限流、错误消息不泄露敏感数据。

密钥管理给出正反对照——硬编码密钥是绝对的反例：

// NEVER: Hardcoded secrets const apiKey = "sk-proj-xxxxx" // ALWAYS: Environment variables const apiKey = process.env.API_KEY if (!apiKey) throw new Error('API_KEY not configured')

安全响应协议：发现问题立即停止 → 调用security-revieweragent（对应 agents/security-reviewer.md）→ 先修复 CRITICAL 问题再继续 → 轮换已暴露的密钥 → 全库排查同类问题。[CUSTOMIZE]位用于补充认证方式、授权规则、数据加密要求与合规要求（GDPR、HIPAA 等）。

4. performance.md：模型选择与上下文管理

performance.md 面向 Claude Code 特有的成本/能力权衡，给出模型选择策略：

• Haiku：约具备 Sonnet 九成能力、三倍成本节约——适用于高频调用的轻量 Agent、代码生成与探索、多智能体系统中的 worker agent；
• Sonnet：最佳编码模型——主力开发工作、编排多智能体工作流、复杂编码任务；
• Opus：最深推理——复杂架构决策、最大推理需求、研究与分析任务。

（注：上述能力描述为模板内原文表述，实际能力请以模型官方文档为准。）

上下文窗口管理：避免在上下文窗口最后 20% 的容量内执行大规模重构、跨多文件的特性实现、复杂交互的调试——这对应了本仓库对上下文膨胀问题的工程关注（参见 context-bloat-2577.test.ts 与 context-usage.mjs）。

算法效率：实现前先评估时间复杂度，避免 O(n²) 而应取 O(n log n)、选用合适的数据结构、对昂贵计算做缓存。[CUSTOMIZE]位用于补充响应时间目标、包体积上限、数据库查询上限。

5. git-workflow.md：提交格式与 PR 流程

git-workflow.md 采用Conventional Commits格式：

<type>: <description> <optional body>

类型枚举：feat, fix, refactor, docs, test, chore, perf, ci。

PR 工作流：创建 PR 前分析完整提交历史（而非只看最新提交）、用git diff [base-branch]...HEAD查看全部改动、起草完整 PR 摘要、附带含 TODO 的测试计划、新分支推送时使用-u参数。

特性实现工作流：先用planneragent 规划 → 用tdd-guideagent 走 TDD → 写完代码用code-revieweragent 评审（对应 agents/code-reviewer.md）→ 按 Conventional Commits 提交。

分支命名：feature/（新特性）、fix/（缺陷修复）、refactor/（重构）、docs/（文档变更）。[CUSTOMIZE]位用于补充分支保护规则、required reviewers、CI/CD 要求。

6. karpathy-guidelines.md：编码纪律四大原则

karpathy-guidelines.md 是从 Andrej Karpathy 对 LLM 常见编码失误的观察中提炼的行为准则，明确"宁谨慎勿求快，琐碎任务可凭判断"。

原则一：先思考再编码——不假设、不隐藏困惑、摊开权衡。实现前显式陈述假设，不确定就问；存在多种解释就并列呈现，不要默默挑选；有更简单方案就直说，必要时反对；不清楚就停下来，命名困惑点并提问。

原则二：简洁优先——解决问题的最小代码，不做投机性扩展：不加需求之外的功能、不为一次性代码造抽象、不做未被要求的"灵活性/可配置性"、不为不可能场景写错误处理。自问："资深工程师会觉得这过度复杂吗？"若是，就简化。

原则三：外科手术式改动——只动必须动的，只清理自己造成的混乱。不改写相邻代码、注释或格式；不重构没坏的东西；即使自己会用不同写法也匹配现有风格；发现无关死代码只提及、不删除。若自己的改动制造了孤儿（orphan），则清理自己造成的未用 import/变量/函数，但未经要求不删除原有死代码。检验标准：每一处改动都应能直接追溯到用户请求。

原则四：目标驱动执行——定义成功标准，循环直到验证通过。把任务改写成可验证目标："加校验"→"为非法输入写测试再让其通过"；"修 bug"→"写一个能复现的测试再让其通过"；"重构 X"→"确保前后测试都通过"。多步骤任务给出带验证点的小计划：

1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check]

模板的结论直指多智能体协作的要害：强的成功标准让 Agent 能独立闭环，弱标准（"让它能跑"）则要求人类不断澄清。

四、[CUSTOMIZE]标记：项目定制的约定位置

README 明确说明：每个模板都有[CUSTOMIZE]标记，是填写项目专属规范的位置。六份模板的定制位分别覆盖：

• coding-style：命名规范、文件结构要求、框架特有模式；
• testing：测试框架配置、mock 设置模式、E2E 场景；
• security：认证方式、授权规则、数据加密要求、合规要求；
• performance：响应时间目标、包体积上限、数据库查询上限；
• git-workflow：分支保护规则、required reviewers、CI/CD 要求；
• karpathy-guidelines：该模板本身以通用纪律为主，可补充团队的附加编码纪律。

建议的定制流程：先原样复制模板试运行一段时间，观察 Agent 行为与模板约束的偏差，再把反复出现的偏差固化为[CUSTOMIZE]下的具体条目，让规则随项目演进而不是一步到位。

五、自动发现与注入的底层实现

README 声称"规则会被自动发现并注入上下文"，其机制由 src/hooks/rules-injector 实现（由 oh-my-opencode 的 rules-injector hook 移植而来）。从源码可以梳理出完整的注入链路：

1. 项目根识别：finder.ts中的findProjectRoot从当前文件目录向上回溯，命中 constants.ts 中PROJECT_MARKERS（.git、pyproject.toml、package.json、Cargo.toml、go.mod、.venv）即视为项目根。

2. 目录与文件发现：findRuleFiles从当前文件所在目录逐级向上（直到项目根），在每个层级扫描三类规则子目录PROJECT_RULE_SUBDIRS：

['.github', 'instructions'], ['.cursor', 'rules'], ['.claude', 'rules'],

外加项目根的单文件规则.github/copilot-instructions.md，以及用户级规则目录[$CLAUDE_CONFIG_DIR|~/.claude]/rules（全局规则，通过getClaudeConfigDir解析配置目录）。

3. 文件匹配：.github/instructions目录下只接受匹配GITHUB_INSTRUCTIONS_PATTERN（/\.instructions\.md$/）的文件；其余目录接受扩展名.md与.mdc（RULE_EXTENSIONS）。

4. 距离排序与去重：calculateDistance计算规则文件与当前文件的目录层级距离，按距离升序排列（最近的规则优先、全局规则恒为最大距离排在最后），并用realpathSync解析真实路径去重，防止符号链接导致同一规则被重复注入。

5. 注入时机：TRACKED_TOOLS = ['read', 'write', 'edit', 'multiedit']表明规则在读写编辑类工具调用时被注入，另有 scripts/post-tool-rules-injector.mjs 作为工具调用后的注入钩子，与 src/hooks/rules-injector/parser.ts、matcher.ts、storage.ts 共同构成"发现 → 匹配 → 注入 → 状态存储"的完整管线。

对使用者的启示：这套机制意味着规则按目录就近生效——放在src/下的.claude/rules会优先于项目根的同名规则，而用户级全局规则永远最后兜底。因此你可以在仓库不同层级放置不同粒度的规则（如根目录放通用规范、某模块目录放该模块特例），实现"就近覆盖、全局兜底"的规则分层。

六、常见问题与最佳实践

Q1：规则没生效怎么办？检查文件名扩展名是否为.md或.mdc；确认目录名严格为.claude/rules（而非.claude/rules/子目录之外的路径，虽然递归扫描支持子目录，但目录本身必须可被扫描到）；确认项目根存在PROJECT_MARKERS之一，否则findProjectRoot返回 null，规则只会在当前文件所在目录被发现。

Q2：模板只复制一部分可以吗？可以。模板彼此独立，README 的示例就是只复制 security 与 testing 两份。建议先复制与团队痛点最相关的 1–2 份，跑通注入后再逐步加量，避免一次性给 Agent 过重的指令负担。

Q3：规则会不会互相冲突？机制上按距离排序、就近优先，距离相同的按发现顺序；[CUSTOMIZE]位就是为消除模板与项目现实之间的冲突而设。若两份规则互相矛盾，应优先修改距离更近（更具体）的那一份。

Q4：如何验证规则真的被注入？可以在.claude/rules/放入规则后，触发一次read/edit类操作，观察 Agent 上下文是否包含规则内容；结合本仓库的测试 rules-injector/finder.test.ts 可了解覆盖的典型场景（项目根识别、距离计算、全局规则、去重等）。

最佳实践总结：以karpathy-guidelines作为底层行为纪律，以git-workflow约束协作节奏，以coding-style+testing+security守住代码质量底线，以performance控制成本与上下文占用；每个项目只保留真正需要约束的维度，其余用[CUSTOMIZE]因地制宜。

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode