破解CLAUDE.md上下文瓶颈之条件化规则系统

如果把所有的规则都塞进 CLAUDE.md 这一个文件里，时间久了肯定会遇到“内存告急”的问题。想象一下，你只是让 AI 写一个简单的前端按钮，它却被迫在脑子里过一遍数据库怎么迁移、服务器怎么配置等一堆完全用不上的信息。这些无关的“杂音”不仅会分散 AI 的注意力，让它变笨、效率下降，甚至还会导致它产生幻觉，或者干脆忘了你交代的前端要求。

为了解决这个痛点，.claude/rules/ 目录应运而生。它的作用，就是把以前那本“大而全的厚重说明书”，变成了一个“按需取用的模块化工具箱”。

这么做有两个最大的好处：

第一是“分门别类，专人专管”。你可以把庞大的规则库拆分成多个小文件，比如前端规范、数据库规范、测试规范等。每个文件只专注自己那一亩三分地，以后想找或者改某条规则，再也不用在几千行的代码里大海捞针了。

第二是“按需激活，绝不浪费”。你可以在每个规则文件的开头加一段配置，告诉 AI 这条规则在什么时候生效。比如，只有当 AI 碰到数据库相关的文件时，数据库规范才会被加载到它的记忆里；如果 AI 只是在写前端代码，那数据库规范就会安静地躺在硬盘里，完全不占用宝贵的记忆空间（Token）。这样，AI 就能把全部注意力集中在当前真正要做的事情上。

示例

数据库规范

预先将数据库规范写入文件 .claude/rules/database.md

数据库与 Prisma 规范

1. Schema 设计原则

命名规范：模型名使用 PascalCase（如 UserProfile），字段名使用 camelCase。
主键：统一使用 id 字段，类型为 String @default(cuid())。
时间戳：必须包含 createdAt DateTime @default(now()) 和 updatedAt DateTime @updatedAt。
软删除：核心业务表必须包含 deletedAt DateTime? 字段，禁止物理删除。

2. 迁移规范

每次修改 Schema 后，必须运行 npx prisma migrate dev 生成迁移文件。
禁止手动修改 migrations 目录下已生成的 SQL 文件。
破坏性变更（如删除列）必须在 PR 描述中显式声明。

3. 查询性能

禁止在循环中执行数据库查询（N+1 问题），必须使用 include 或 select 进行关联查询。
对于高频查询的过滤字段，必须添加 @@index。

然后在 CLAUDE.md 写入：

<!- - .claude/rules/database.md - - > - - -
-----------------------------------------------

paths:

- "prisma/schema.prisma"
- "prisma/migrations/**/*.sql"
- "**/*.sql"

---

这让当处理编辑到 paths 定义所涵盖的文件时，就会也才会加载 database.md 的规范。

API 接口规范

预先将 API 接口规范写入文件 .claude/rules/api.md

Next.js API 路由规范

1. 响应格式

所有 API 必须返回统一的 JSON 结构：{ code: number, message: string, data?: any }。
成功响应使用 HTTP 200，创建成功使用 201。
错误响应必须抛出标准的 AppError 类，禁止直接 res.status(500).send('Error')。

2. 参数校验

所有 POST/PUT 请求的 Body 必须使用 zod 进行校验。
校验失败直接返回 400，并附带具体的错误信息。

3. 鉴权与中间件

涉及用户隐私或写操作的接口，必须在函数开头调用 await auth() 验证登录状态。
禁止在 API 路由中硬编码任何 Secret 或 Token。

然后在 CLAUDE.md 写入：

<!- - .claude/rules/api.md - - > - - -
------------------------------------------

paths:

- "app/api/**/*.ts"
- "pages/api/**/*.ts"

---

在 OpenCode 中，没有与 Claude Code 的 paths 字段完全对应的、用于根据文件路径自动加载规则的内置语法。不过，OpenCode 有更强大的以下两种组合策略来实现相同甚至更灵活的效果：

策略一：在 AGENTS.md 中定义按需加载规则

这是最推荐的做法。你可以在项目根目录的 AGENTS.md 文件中，明确告诉 AI 在遇到特定文件路径时，主动读取对应的规则文件。

创建规则文件：将你的测试规则保存为 .opencode/rules/testing.md。
在 AGENTS.md 中声明：在 AGENTS.md 中添加如下指令，指导 AI 按需加载。

外部文件加载

当处理以下路径的文件时，请务必先使用 Read 工具加载对应的规则文件：`**/*.test.ts`, `**/*.spec.ts`, `tests/**` -> 加载 `.opencode/rules/testing.md`⚠️ 注意：不要预先加载所有规则文件，仅在任务相关时按需加载。加载后，文件内容视为强制指令。

这种方式将路径匹配的逻辑交给了 AI，并利用了“按需懒加载”来节省 Token。

策略二：为特定 Agent 配置专属规则

如果你希望某个 Agent 专门负责测试相关任务，并始终遵循测试规则，可以创建一个自定义 Agent，并在其配置中引用规则。

创建自定义 Agent：在 ~/.config/opencode/agents/ 目录下创建一个新文件，例如 test-agent.md。
在 Agent 配置中引用规则：在该文件的 Frontmatter 或内容中，通过 instructions 字段引用你的测试规则文件。

---

name: test-agent
description: 专门负责编写和审查测试代码的 Agent
instructions:
- .opencode/rules/testing.md

---

这样，当你通过 @test-agent 调用它时，它会始终加载并遵循 testing.md 中的规则，而无需在 AGENTS.md 中配置路径匹配。

另外，OpenCode 完全兼容 Claude Code 的规则文件。如果你的项目已有 .claude/rules/testing.md，OpenCode 会自动将其作为回退规则加载，无需立即迁移。

示例