1. 为什么你的 CLAUDE.md 写了规则Claude Code 还是乱改文件如果你已经在用 Claude Code 写代码大概率经历过这个场景在 CLAUDE.md 里郑重写下「不要动 config/prod.env」结果某次让它重构一个模块它顺手把生产配置也改了。不是它故意违抗而是模型没有「听话」的义务——上下文一长、任务一复杂任何写在文档里的约束都可能被选择性忽略。这就是 Claude Code 工程化要解决的核心问题Prompt 是请求不是命令。你需要的是一套可复制的控制体系让「该做什么」有上下文引导「怎么做」有流程封装「绝对不许做」有代码级拦截。这套体系由三个部件组成CLAUDE.md 定义项目上下文Skills 封装可复用能力Hooks 在关键节点自动校验与拦截。这篇指南面向已经把 Claude Code 用起来、但想把它从「聪明的助手」变成「可控的工程组件」的开发者。我会给出 settings.json 与 hooks 的配置骨架、CLAUDE.md 模板、Skills 目录结构并完整演示一次从 Prompt 触发到 Hook 生效的验证流程。全程可跟做不需要你提前理解内部机制。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配置控制体系之前先确保你的 Claude Code 能正常跑起来。我用的是 TaoToken 作为模型接入层它兼容 Anthropic 的接口协议配置方式对 Claude Code 很友好。2.1 获取 API Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按项目维度创建方便后续做用量隔离和吊销。创建后立刻复制保存页面刷新后就不再完整显示。2.2 配置环境变量Claude Code 通过环境变量读取接入信息。在 shell 配置文件~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥改完执行source ~/.zshrc让配置生效。这里注意ANTHROPIC_BASE_URL只写到/api不要带多余路径否则 Claude Code 拼接请求时会 404。2.3 验证基础连通claude --version claude 用一句话说明当前目录下有哪些文件如果第二条命令能正常返回文件列表说明接入层通了。如果报 401检查 Key 是否复制完整如果报连接超时检查 BASE_URL 是否写错。这一步过了再往下做工程化配置。3. 可复制配置CLAUDE.md、Skills 与 Hooks 三件套控制体系落地到项目里就是三个目录和几份配置文件。我按「先软后硬」的顺序给骨架你可以直接抄进项目改。3.1 CLAUDE.md 模板定义项目上下文CLAUDE.md 是项目的「默认记忆」跨会话自动加载。它管的是边界和共识不是流程细节。模板如下# 项目上下文 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Fastify - 数据库PostgreSQL迁移用 Prisma ## 核心约束 - 不要修改 config/prod.env 及任何 *.prod.* 文件 - 提交前必须通过 ESLint 和 Prettier - 数据库迁移规范见 .claude/rules/database.md - 新增依赖前先说明理由不要静默安装 ## 常用命令 - 测试npm test - 构建npm run build - 本地启动npm run dev关键点是.claude/rules/database.md这种引用语法它让规则模块化按需加载避免 CLAUDE.md 无限膨胀。但你要清楚CLAUDE.md 和 Rules 都是软约束模型会尽力遵守不保证。真正的安全兜底在 Hooks。3.2 Skills 目录结构封装可靠流程CLAUDE.md 告诉模型「什么不能做」Skills 告诉它「怎么做」。一个 Skill 就是.claude/skills/下的一个 Markdown 文件带 YAML frontmatter--- name: deploy-staging description: 安全部署到 staging 环境 allowed-tools: [Bash, Read, Write, Grep] --- # 部署流程 ## 步骤 1. 运行 npm test不通过则立即停止 2. 确认当前分支为 main 3. 构建npm run build 4. 执行迁移npm run migrate:staging 5. 部署npm run deploy:staging ## 回滚条件 - 任一步骤失败立即停止并报告 - 禁止跳过测试步骤allowed-tools是工具白名单部署流程不需要浏览器工具就不给它。Skill 还能携带限定作用域的 Hooks只在执行该 Skill 时生效结束后自动清理不污染全局配置。3.3 settings.json 与 Hooks 配置骨架Hooks 是跑你写的代码的检查点注册在 settings.json 里结构是三层嵌套{ hooks: { PreToolUse: [ { matcher: Write, hooks: [ { type: command, command: .claude/hooks/protect-prod.sh } ] } ] } }第一层是事件名第二层matcher匹配工具名第三层是执行逻辑。作用域分三档~/.claude/settings.json是用户级常驻.claude/settings.json是项目级常驻.claude/settings.local.json是本地级不提交。3.4 拦截脚本保护生产配置#!/usr/bin/env bash input$(cat) file_path$(echo $input | jq -r .tool_input.file_path // empty) if [[ $file_path *prod.env* ]]; then echo {decision:deny,reason:生产环境配置文件受保护禁止写入} exit 0 fi echo {decision:allow} exit 0给脚本加执行权限chmod x .claude/hooks/protect-prod.sh。这里有个最大的坑裁决必须用exit 0加 JSON 输出。如果你用exit 1什么都不会发生Hook 形同虚设exit 2会被当成系统错误可能被绕过。只有exit 0配合{decision:deny}才是有效的策略控制。4. 验证请求从 Prompt 触发到 Hook 生效的完整流程配置写完不验证等于没写。下面走一遍完整链路确认三层都生效。4.1 验证 CLAUDE.md 加载claude 这个项目的技术栈是什么有哪些核心约束如果它能准确说出 React 18、PostgreSQL 以及「不要修改 prod.env」说明 CLAUDE.md 已被加载。这一步失败通常是文件位置不对——CLAUDE.md 要放在项目根目录或.claude/下。4.2 验证 Skill 可被调用claude 帮我部署到 staging正常情况下它会识别到deploy-stagingSkill并按步骤先跑测试。如果它自由发挥、跳过测试说明 Skill 没被识别检查 frontmatter 的name和description是否规范。4.3 验证 Hook 拦截这是最关键的一步。故意让它改生产配置claude 把 config/prod.env 里的 LOG_LEVEL 改成 debug预期结果是模型尝试调用 Write 工具 → PreToolUse Hook 触发 → 脚本返回deny→ Claude Code 显示拦截信息文件未被修改。你可以用git status确认prod.env没有变更。4.4 验证合并规则如果你注册了多个 Hook 命中同一操作它们会并行执行、自动去重然后最严格的结果胜出deny ask allow。只要有一个 deny操作就被拦截。你可以再加一个返回ask的 Hook 测试这个优先级。5. 本篇常见错排查配置过程中最容易踩的坑集中在这几处对照排查能省不少时间。Hook 不生效先确认脚本有执行权限再确认 settings.json 的 JSON 格式合法多余逗号会导致整个文件被忽略。用claude --debug能看到 Hook 是否被触发。exit 1 导致静默失效这是最高频的错误。记住裁决只认exit 0 JSON其他退出码要么无效要么被绕过。matcher 写错工具名matcher要匹配 Claude Code 内部的工具名比如Write、Edit、Bash大小写敏感。写错了 Hook 永远不触发。Skill 的 Hooks 污染全局Skill 携带的 Hooks 是临时的如果你发现它常驻了检查是不是误写进了项目级 settings.json。CLAUDE.md 太长导致指令被淹没上下文窗口是固定的注意力池塞得越多每条信息分到的注意力越少。把专项规则拆到.claude/rules/里按需引用保持主文件精简。BASE_URL 带多余路径接入层报 404 时检查ANTHROPIC_BASE_URL是否只写到/api。6. 把控制体系用起来从接入到长期编码三层体系跑通后你的 Claude Code 就从「请求式助手」变成了「可控工程组件」CLAUDE.md 定边界Skills 定流程Hooks 定底线缺一不可。软硬兼施才是完整的 AI 工程化治理。如果你还没配好接入层先去 TaoToken API Keys 创建密钥再对照 接入文档 确认环境变量写法。想先验证模型对话是否正常可以在 模型对话 里发一条测试消息。如果你打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 的额度模型更适合高频调用场景。最后分享一个实测经验Hooks 脚本里尽量用jq解析输入别用字符串截取工具调用的 JSON 结构会随版本变化硬编码匹配很容易在某次升级后失效。把拦截逻辑写成独立脚本、单独测试比塞在 settings.json 里调试高效得多。
Claude Code 工程化指南：用 CLAUDE.md、Skills 与 Hooks 搭建可复制控制体系
1. 为什么你的 CLAUDE.md 写了规则Claude Code 还是乱改文件如果你已经在用 Claude Code 写代码大概率经历过这个场景在 CLAUDE.md 里郑重写下「不要动 config/prod.env」结果某次让它重构一个模块它顺手把生产配置也改了。不是它故意违抗而是模型没有「听话」的义务——上下文一长、任务一复杂任何写在文档里的约束都可能被选择性忽略。这就是 Claude Code 工程化要解决的核心问题Prompt 是请求不是命令。你需要的是一套可复制的控制体系让「该做什么」有上下文引导「怎么做」有流程封装「绝对不许做」有代码级拦截。这套体系由三个部件组成CLAUDE.md 定义项目上下文Skills 封装可复用能力Hooks 在关键节点自动校验与拦截。这篇指南面向已经把 Claude Code 用起来、但想把它从「聪明的助手」变成「可控的工程组件」的开发者。我会给出 settings.json 与 hooks 的配置骨架、CLAUDE.md 模板、Skills 目录结构并完整演示一次从 Prompt 触发到 Hook 生效的验证流程。全程可跟做不需要你提前理解内部机制。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配置控制体系之前先确保你的 Claude Code 能正常跑起来。我用的是 TaoToken 作为模型接入层它兼容 Anthropic 的接口协议配置方式对 Claude Code 很友好。2.1 获取 API Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按项目维度创建方便后续做用量隔离和吊销。创建后立刻复制保存页面刷新后就不再完整显示。2.2 配置环境变量Claude Code 通过环境变量读取接入信息。在 shell 配置文件~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥改完执行source ~/.zshrc让配置生效。这里注意ANTHROPIC_BASE_URL只写到/api不要带多余路径否则 Claude Code 拼接请求时会 404。2.3 验证基础连通claude --version claude 用一句话说明当前目录下有哪些文件如果第二条命令能正常返回文件列表说明接入层通了。如果报 401检查 Key 是否复制完整如果报连接超时检查 BASE_URL 是否写错。这一步过了再往下做工程化配置。3. 可复制配置CLAUDE.md、Skills 与 Hooks 三件套控制体系落地到项目里就是三个目录和几份配置文件。我按「先软后硬」的顺序给骨架你可以直接抄进项目改。3.1 CLAUDE.md 模板定义项目上下文CLAUDE.md 是项目的「默认记忆」跨会话自动加载。它管的是边界和共识不是流程细节。模板如下# 项目上下文 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Fastify - 数据库PostgreSQL迁移用 Prisma ## 核心约束 - 不要修改 config/prod.env 及任何 *.prod.* 文件 - 提交前必须通过 ESLint 和 Prettier - 数据库迁移规范见 .claude/rules/database.md - 新增依赖前先说明理由不要静默安装 ## 常用命令 - 测试npm test - 构建npm run build - 本地启动npm run dev关键点是.claude/rules/database.md这种引用语法它让规则模块化按需加载避免 CLAUDE.md 无限膨胀。但你要清楚CLAUDE.md 和 Rules 都是软约束模型会尽力遵守不保证。真正的安全兜底在 Hooks。3.2 Skills 目录结构封装可靠流程CLAUDE.md 告诉模型「什么不能做」Skills 告诉它「怎么做」。一个 Skill 就是.claude/skills/下的一个 Markdown 文件带 YAML frontmatter--- name: deploy-staging description: 安全部署到 staging 环境 allowed-tools: [Bash, Read, Write, Grep] --- # 部署流程 ## 步骤 1. 运行 npm test不通过则立即停止 2. 确认当前分支为 main 3. 构建npm run build 4. 执行迁移npm run migrate:staging 5. 部署npm run deploy:staging ## 回滚条件 - 任一步骤失败立即停止并报告 - 禁止跳过测试步骤allowed-tools是工具白名单部署流程不需要浏览器工具就不给它。Skill 还能携带限定作用域的 Hooks只在执行该 Skill 时生效结束后自动清理不污染全局配置。3.3 settings.json 与 Hooks 配置骨架Hooks 是跑你写的代码的检查点注册在 settings.json 里结构是三层嵌套{ hooks: { PreToolUse: [ { matcher: Write, hooks: [ { type: command, command: .claude/hooks/protect-prod.sh } ] } ] } }第一层是事件名第二层matcher匹配工具名第三层是执行逻辑。作用域分三档~/.claude/settings.json是用户级常驻.claude/settings.json是项目级常驻.claude/settings.local.json是本地级不提交。3.4 拦截脚本保护生产配置#!/usr/bin/env bash input$(cat) file_path$(echo $input | jq -r .tool_input.file_path // empty) if [[ $file_path *prod.env* ]]; then echo {decision:deny,reason:生产环境配置文件受保护禁止写入} exit 0 fi echo {decision:allow} exit 0给脚本加执行权限chmod x .claude/hooks/protect-prod.sh。这里有个最大的坑裁决必须用exit 0加 JSON 输出。如果你用exit 1什么都不会发生Hook 形同虚设exit 2会被当成系统错误可能被绕过。只有exit 0配合{decision:deny}才是有效的策略控制。4. 验证请求从 Prompt 触发到 Hook 生效的完整流程配置写完不验证等于没写。下面走一遍完整链路确认三层都生效。4.1 验证 CLAUDE.md 加载claude 这个项目的技术栈是什么有哪些核心约束如果它能准确说出 React 18、PostgreSQL 以及「不要修改 prod.env」说明 CLAUDE.md 已被加载。这一步失败通常是文件位置不对——CLAUDE.md 要放在项目根目录或.claude/下。4.2 验证 Skill 可被调用claude 帮我部署到 staging正常情况下它会识别到deploy-stagingSkill并按步骤先跑测试。如果它自由发挥、跳过测试说明 Skill 没被识别检查 frontmatter 的name和description是否规范。4.3 验证 Hook 拦截这是最关键的一步。故意让它改生产配置claude 把 config/prod.env 里的 LOG_LEVEL 改成 debug预期结果是模型尝试调用 Write 工具 → PreToolUse Hook 触发 → 脚本返回deny→ Claude Code 显示拦截信息文件未被修改。你可以用git status确认prod.env没有变更。4.4 验证合并规则如果你注册了多个 Hook 命中同一操作它们会并行执行、自动去重然后最严格的结果胜出deny ask allow。只要有一个 deny操作就被拦截。你可以再加一个返回ask的 Hook 测试这个优先级。5. 本篇常见错排查配置过程中最容易踩的坑集中在这几处对照排查能省不少时间。Hook 不生效先确认脚本有执行权限再确认 settings.json 的 JSON 格式合法多余逗号会导致整个文件被忽略。用claude --debug能看到 Hook 是否被触发。exit 1 导致静默失效这是最高频的错误。记住裁决只认exit 0 JSON其他退出码要么无效要么被绕过。matcher 写错工具名matcher要匹配 Claude Code 内部的工具名比如Write、Edit、Bash大小写敏感。写错了 Hook 永远不触发。Skill 的 Hooks 污染全局Skill 携带的 Hooks 是临时的如果你发现它常驻了检查是不是误写进了项目级 settings.json。CLAUDE.md 太长导致指令被淹没上下文窗口是固定的注意力池塞得越多每条信息分到的注意力越少。把专项规则拆到.claude/rules/里按需引用保持主文件精简。BASE_URL 带多余路径接入层报 404 时检查ANTHROPIC_BASE_URL是否只写到/api。6. 把控制体系用起来从接入到长期编码三层体系跑通后你的 Claude Code 就从「请求式助手」变成了「可控工程组件」CLAUDE.md 定边界Skills 定流程Hooks 定底线缺一不可。软硬兼施才是完整的 AI 工程化治理。如果你还没配好接入层先去 TaoToken API Keys 创建密钥再对照 接入文档 确认环境变量写法。想先验证模型对话是否正常可以在 模型对话 里发一条测试消息。如果你打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 的额度模型更适合高频调用场景。最后分享一个实测经验Hooks 脚本里尽量用jq解析输入别用字符串截取工具调用的 JSON 结构会随版本变化硬编码匹配很容易在某次升级后失效。把拦截逻辑写成独立脚本、单独测试比塞在 settings.json 里调试高效得多。