Claude 项目架构文档约束代码生成：CLAUDE.md 与 Rules 的 Prompt 策略配置指南

1. 为什么架构文档写了等于没写很多团队都遇到过这个场景架构文档在 Confluence 里躺了半年新人照着写代码还是把数据库调用塞进 ControllerAI 补全更是放飞自我生成的代码跟项目分层毫无关系。问题不在于文档写得不好而在于文档和代码生成之间缺了一条“执行链路”。Claude Code 提供了一条相对完整的链路CLAUDE.md 负责全局上下文Rules 负责路径级约束Hooks 负责确定性拦截。三者配合能把“架构文档”从装饰品变成方向盘。我试过在一个中型 Node.js 仓库里把这三层配齐生成代码的架构违规率从大约三成降到接近零代价是前期花了两小时梳理规则。这篇内容聚焦一件事怎么把项目架构文档翻译成 Claude 能执行的约束覆盖 CLAUDE.md 骨架、Rules 配置片段、Hooks 触发时机以及一次真实仓库里的验证动作。适合已经在用 Claude Code 做日常开发、但发现生成代码总“跑偏”的工程师。如果你还没配过任何约束从零开始也能跟做。核心检索词先明确CLAUDE.md 是每次会话自动加载的项目记忆文件Rules 是按文件路径按需注入的规则片段Hooks 是在工具调用前后执行的确定性脚本。三者分工不同混用会浪费上下文预算。2. 前置准备TaoToken 接入与项目初始化在配置约束之前得先让 Claude Code 能稳定跑起来。我用的是 TaoToken 作为模型接入层它兼容 Anthropic 的接口协议配置方式跟官方一致省去了自己维护密钥轮换的麻烦。第一步拿到 API Key。访问 https://taotoken.net/api-keys 创建一个密钥复制保存。注意这个 Key 只在创建时完整显示一次。第二步配置环境变量。在项目根目录或 shell 配置里设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥如果你用的是 Claude Code CLI它会自动读取这两个变量。想确认接入是否正常可以先用模型对话页面发一条测试消息https://taotoken.net/models 能正常返回就说明链路通了。第三步初始化项目约束目录。在仓库根目录执行mkdir -p .claude/rules .claude/hooks touch CLAUDE.md到这里前置就完成了。接下来所有配置都围绕这三个位置展开。需要提醒的是CLAUDE.md 和 .claude/rules/ 建议提交到 Git团队共享个人偏好放 CLAUDE.local.md不要提交。3. 可复制配置CLAUDE.md 骨架与 Rules 分层写法3.1 CLAUDE.md 骨架控制在 50 行内CLAUDE.md 的每一行都在消耗注意力预算。系统提示词本身已经占了约 50 条指令留给 CLAUDE.md 的可靠槽位大约 100 到 150 条。写太多模型会均匀忽略所有规则。下面是我实测下来比较稳的骨架# 项目宪法 ## 技术硬约束 - Node.js 22 LTS禁止阻塞事件循环的同步写法 - PostgreSQL 15禁止引入 MySQL 驱动 - 禁止用 any 绕过类型检查用 unknown 类型守卫 ## 架构边界 - src/api/ → 只处理 HTTP 请求响应禁止直接操作数据库 - src/domain/ → 核心业务逻辑禁止依赖外部服务 - src/infra/ → 基础设施适配禁止包含业务决策 ## 高频命令 pnpm test # 运行测试 pnpm lint # ESLint 检查 pnpm type-check # TypeScript 检查 ## 禁止事项附替代方案 - 禁止 // ts-ignore改用 // ts-expect-error 并附说明 - 禁止在 domain 层用 console.log改用 /utils/logger关键原则每加一条新规则就删一条旧的。强调词要克制使用IMPORTANT:和NEVER留给真正不可跳过的约束滥用会让权重失效。3.2 Rules 路径分域配置Rules 放在 .claude/rules/ 下通过 frontmatter 的 paths 字段匹配文件路径只在 Claude 读取匹配文件时注入。这意味着规则出现在“决策点”附近注意力权重更高。.claude/rules/api-layer.md--- paths: - src/api/**/*.ts description: API 层开发规范 --- # API 层规则 1. 只负责请求解析、参数校验、响应封装 2. 禁止直接调用 Repository必须通过 Service 层中转 3. 错误响应统一使用 src/api/errors.ts 的 ApiError 类 ## 正确示例 typescript Post(/users) async createUser(req: Request): PromiseResponse { const validated await userSchema.parseAsync(req.body); const result await userService.create(validated); return this.ok(result); }错误示例会被 Hooks 拦截Post(/users) async createUser(req: Request): PromiseResponse { const user await userRepository.save(req.body); return this.ok(user); }.claude/rules/domain-layer.md markdown --- paths: - src/domain/**/*.ts description: 领域层开发规范 --- # 领域层规则 1. 只包含业务逻辑禁止 import 任何 infra 或 api 模块 2. 禁止使用 console统一用 /utils/logger 3. 所有对外暴露的函数必须有显式返回类型Rules 的触发机制要注意它通过 Read 工具触发。如果 Claude 编辑文件前没有先读取内容规则不会加载。所以工作流上要保证“先读后写”。规则一旦注入本次会话持续生效。3.3 Hooks 确定性拦截配置Hooks 在系统提示词之外执行不占注意力预算且是确定性的——不依赖模型判断。适合放“一次都不能违反”的硬约束。.claude/hooks/architecture_guard.py#!/usr/bin/env python3 import sys from pathlib import Path def enforce(file_path: str, content: str) - bool: path str(Path(file_path)) if src/api/ in path: low content.lower() if repository in low and service not in low: print(架构违规API 层直接引用 Repository) print(修正通过 Service 层中转) return False if src/domain/ in path: if console.log in content or console.error in content: print(架构违规领域层使用 console) print(修正import { logger } from /utils/logger) return False return True if __name__ __main__: file_path sys.argv[1] if len(sys.argv) 1 else content sys.stdin.read() sys.exit(0 if enforce(file_path, content) else 2).claude/settings.local.json里注册 Hook{ hooks: { PreToolUse: [ { matcher: Edit|Write, command: python .claude/hooks/architecture_guard.py $CODEC_FILE_PATH } ] } }退出码 2 会阻断整个编辑操作。这就是 Hooks 和 CLAUDE.md 的本质区别前者是护栏后者是建议。4. 验证请求在真实仓库触发一次生成配置写完不算完得验证它真的生效。下面是我在一个真实仓库里的验证流程。第一步确认 CLAUDE.md 被加载。启动 Claude Code 后执行/context检查输出里 CLAUDE.md 的内容是否出现在会话起始位置。如果没出现说明文件路径不对或格式有问题。第二步触发一次路径规则。给 Claude 一个明确任务在 src/api/ 下新增一个 GET /orders 接口返回订单列表观察日志里是否有规则注入事件。正常情况下Claude 读取 src/api/ 下的文件时api-layer.md 会被注入到 tool result 的 system-reminder 块中。第三步检查生成结果是否符合约束。重点看三点是否通过 Service 层调用数据、错误处理是否用了 ApiError、返回类型是否显式声明。第四步故意触发一次 Hooks 拦截。让 Claude 生成一段违规代码在 src/api/orders.ts 里直接调用 orderRepository.findAll()预期结果是 Hooks 返回退出码 2终端打印“架构违规API 层直接引用 Repository”编辑被阻断。如果没被拦截检查 settings.local.json 的 matcher 是否写对以及脚本是否有执行权限。一次成功的验证输出大概长这样[Claude Code] 会话启动 CLAUDE.md: 46 行已加载 规则: 2 条路径分域规则待命 [用户请求] 在 src/api/ 新增 GET /orders [规则注入] api-layer.md 已加载 [代码生成] 通过 Service 层调用使用 ApiError [验证] 架构分层符合命名符合5. 本篇常见错排查CLAUDE.md 越长越好相反。系统提示词已占约 50 条指令CLAUDE.md 每多一行其他行被遵循的概率就下降。控制在 50 到 200 行低频知识挪到 Rules 或 Skills。Rules 的 paths 不生效规则靠 Read 工具触发。如果 Claude 直接编辑没先读文件规则不会加载。确保工作流是“先读后写”或者用 Hooks 兜底。Hooks 和 CLAUDE.md 规则重复怎么办判断标准很简单这条规则能不能容忍偶尔违反能容忍放 CLAUDE.md不能容忍放 Hooks。Hooks 是确定性的CLAUDE.md 是指导性的。Hook 脚本报权限错误执行chmod x .claude/hooks/architecture_guard.py。另外确认 settings.local.json 里的路径是相对项目根目录的。规则注入后 token 消耗暴涨社区有报告 11 条规则文件在 30 次工具调用中消耗约 93,000 tokens。规则文件保持简短每条控制在 200 行内只放真正的模块特定约束。生成代码仍然违反架构检查是不是把硬约束写在了 CLAUDE.md 里。模型对长上下文顶部的规则注意力衰减最严重硬约束必须下沉到 Hooks。6. 把约束系统跑起来配置这套东西的核心思路是把架构文档拆成三层全局的放 CLAUDE.md路径相关的放 Rules不可违反的放 Hooks。三者各司其职不要混用。如果你还在调接入层先去 https://taotoken.net/api-keys 拿 Key接入文档在 https://taotoken.net/doc 里面有完整的接口说明。想先验证模型行为是否符合预期可以用模型对话页面快速试https://taotoken.net/models 。长期做编码和 Agent 任务的建议直接上 Coding Plan省去每次手动配环境的麻烦https://taotoken.net/coding-plan 。最后留一个实用技巧每次改完 CLAUDE.md 或 Rules跑一次/context看加载情况再故意触发一次 Hooks 拦截确认护栏还在。约束系统跟代码一样需要定期回归验证不然某次重构后规则悄悄失效了你都不知道。