1. 为什么 CI/CD 里的 Claude 总是“时灵时不灵”如果你已经在本地用 Claude Code 写代码大概率遇到过这种落差本地会话里它像个靠谱同事一进 CI/CD 流水线就开始飘——同样的仓库这次它按规范改了测试下次它把package.json里的脚本名记错这次它老老实实跑 lint下次它直接跳过检查提交。问题不在模型本身而在于流水线里的 Claude 每次都是“失忆”的它不知道你们团队的命名约定不知道构建命令是pnpm build还是npm run build:prod更不知道哪些目录碰不得。我试过把项目约定一股脑塞进 CI 的 prompt 里结果是 prompt 越写越长维护成本比代码还高而且改一处要同步好几个 workflow 文件。后来换成一套分层骨架CLAUDE.md 固化项目约定Skills 封装重复任务Hooks 卡住关键节点再配合 TaoToken 统一 Key/API 通道才做到一次配置、多环境复用。这篇就把这套骨架拆开给出可直接复制的settings.json与config.toml以及从本地跑通到流水线验证的完整动作。适合谁已经在用 Claude Code、想把 AI 审查接进 GitHub Actions 或 GitLab CI 的开发者被“AI 每次会话都要重新解释项目背景”折磨过的团队以及想让 AI 在流水线里稳定发挥、而不是靠运气的人。核心检索词先摆出来claude 使用技巧、CLAUDE.md、Skills、Hooks、CI/CD。这五个词就是整篇骨架的五个支点下面逐个落地。2. TaoToken 前置统一 Key 与 API 通道在讲配置之前先把“通道”这件事解决掉。CI/CD 里最烦的是密钥管理本地一套 Key流水线一套 Key换模型又要换 endpoint。TaoToken 的作用是把这些收敛成一个入口——你拿一个 Key就能在本地和流水线里走同一条 API 通道模型对话、编码任务都从这儿过。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM直接填进配置里。具体动作分三步。第一步去控制台建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 建完在 API Keys 页面能看到https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二步本地把它写进环境变量别硬编码进仓库。第三步流水线里用 Secrets 注入同名变量这样本地和 CI 读的是同一个名字配置不用改。注意Key 只放环境变量或 CI Secrets永远不要提交进 git。CI 里用${{ secrets.TAOTOKEN_API_KEY }}这种引用方式本地用.env并加进.gitignore。如果你只是想先验证模型通不通可以直接用模型对话页面试一句https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期跑编码和 Agent 任务的话Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。通道打通后Claude Code 的配置里只需要指向这个 base URL本地和流水线共用一份逻辑。3. 可复制配置CLAUDE.md Skills Hooks 三件套这一节是骨架的核心三块配置各司其职CLAUDE.md 管“规则”Skills 管“能力”Hooks 管“强制”。先给目录结构再逐个给可复制内容。repo/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── rules/ │ │ └── backend-api.md │ └── skills/ │ └── code-review/ │ └── SKILL.md ├── .github/ │ └── workflows/ │ └── claude-review.yml └── config.toml3.1 CLAUDE.md写给 AI 看的项目说明书CLAUDE.md 会在每次会话开始时自动加载相当于给 AI 一份跨会话的“长期记忆”。官方建议控制在 200 行以内每条规则要具体可执行别写“正确使用 JavaScript 特性”这种模糊话要写“禁止使用 var 声明变量”。# 项目约定 ## 项目概览 - 技术栈TypeScript Node 20 pnpm - 架构monorepopackages/ 下按领域拆分 - 包管理器pnpm禁止使用 npm 或 yarn ## 代码规范 - YOU MUST 使用 2 空格缩进 - IMPORTANT 禁止使用 var统一 const/let - 命名组件 PascalCase工具函数 camelCase常量 UPPER_SNAKE_CASE - 提交信息遵循 Conventional Commits ## 常用命令 - 安装pnpm install - 构建pnpm build - 测试pnpm test - 单测pnpm test -- file - Lintpnpm lint ## 行为规则 - 修改代码前先跑 pnpm test 确认基线 - 不要改动 packages/legacy/ 下的历史代码除非明确要求 - 新增依赖前先说明理由 ## 已知隐患 - packages/core 的 init 顺序不能调换否则会循环依赖 - 测试环境变量必须从 .env.test 读取不要硬编码 ## 工作流 - 分支feature/*、fix/*、chore/* - PR 必须通过 lint test 才能合并大型项目可以拆分把后端 API 规范放.claude/rules/backend-api.md在主文件里用import引进来这样规则只在处理对应目录时加载省上下文。3.2 Skills把重复任务封装成技能包Skills 是把复杂工作流、提示词打包在一起的“技能包”。和 CLAUDE.md 的建议性指令不同Skills 是完整封装的能力能定义多步骤计划。比如“深度代码审查”这种每次都要重复描述的任务封装一次就够了。--- name: code-review description: 对指定文件或 PR 做深度代码审查覆盖安全、性能、风格 --- # 深度代码审查流程 ## 步骤 1. 读取目标文件或 diff列出改动范围 2. 按以下维度逐项检查 - 安全注入、越权、敏感信息硬编码 - 性能N1 查询、不必要的循环、内存泄漏 - 风格是否符合 CLAUDE.md 中的命名与缩进约定 - 测试新增逻辑是否有对应测试 3. 对每个问题给出文件:行号、问题描述、修复建议 4. 输出结构化报告按严重程度排序 ## 输出格式 - 严重必须修 - 建议可选 - 通过项简要列出放在.claude/skills/code-review/SKILL.md之后在会话里直接调用这个 skill不用每次重写审查提示词。3.3 Hooks在关键节点强制卡住Hooks 绑定在 Claude Code 生命周期的特定节点上保证动作每次都执行是确定性的控制。最常用的是PreToolUse和PostToolUse。比如每次文件编辑后自动跑 ESLint配置写在.claude/settings.json{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: pnpm lint --fix $CLAUDE_FILE_PATHS } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \[hook] 即将执行: $CLAUDE_TOOL_INPUT\ .claude/audit.log } ] } ] } }PostToolUse在编辑后自动 lintPreToolUse在跑 Bash 前记审计日志。这样即使 CLAUDE.md 里的规则在长对话中被压缩忽略Hooks 依然会执行。3.4 config.toml统一 API 通道把 TaoToken 的通道写进config.toml本地和流水线共用[api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 timeout_seconds 120 [behavior] auto_load_claude_md true skills_dir .claude/skills hooks_config .claude/settings.jsonapi_key_env指向环境变量名本地.env和 CI Secrets 都用TAOTOKEN_API_KEY配置零改动。4. 验证请求从本地跑通到流水线配置写完不算完得验证它真的生效。分两步本地先跑通再进流水线。4.1 本地验证先确认环境变量读到了export TAOTOKEN_API_KEY你的Key echo $TAOTOKEN_API_KEY | head -c 8然后跑一次最小请求确认通道通curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到content字段带OK说明 Key 和通道都正常。接着在项目里启动 Claude Code观察它是否自动加载了 CLAUDE.md——随便问一句“本项目的构建命令是什么”它应该答pnpm build而不是猜npm run build。再验证 Hook故意改一个文件看.claude/audit.log有没有新增记录lint 有没有自动跑。如果日志为空说明 Hook 没触发回去检查settings.json的 matcher 是否匹配。4.2 流水线验证把审查接进 GitHub Actions用 Headless 模式跑name: Claude Code Review on: pull_request: types: [opened, synchronize] jobs: claude-review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run Claude Review env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} run: | npx -y anthropic-ai/claude-code -p \ 读取 CLAUDE.md 与 .claude/skills/code-review/SKILL.md对本 PR 的 diff 执行深度代码审查输出结构化报告 \ --output-format json review.json - name: Post Comment uses: actions/github-scriptv7 with: script: | const fs require(fs); const review JSON.parse(fs.readFileSync(review.json, utf8)); github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: review.result || 审查完成无阻塞问题 });关键点TAOTOKEN_API_KEY从 Secrets 注入和本地同名-p是 Headless 模式适合 CIprompt 里显式让它读 CLAUDE.md 和 SKILL.md保证规则和技能都生效。PR 打开或更新时触发审查结果自动贴回 PR 评论。跑通后你会看到PR 里出现一条结构化评论按严重程度列出问题而不是一句“看起来不错”。5. 本篇常见错排查配置骨架搭起来后踩坑基本集中在这几处逐个对照。Hook 不触发最常见是matcher写错。Edit|Write是正则大小写敏感如果你用的是其他工具名得改成对应的。另外settings.json必须在.claude/目录下放错位置不生效。CLAUDE.md 没被加载确认文件名大小写完全一致CLAUDE.md不是claude.md且放在仓库根目录。如果用了import被引用的文件路径要相对主文件正确否则静默失败。CI 里报 401九成是 Secrets 名字对不上。本地用TAOTOKEN_API_KEYCI 里secrets.TAOTOKEN_API_KEY必须同名。另外检查 workflow 里有没有把 env 传进 run 步骤只在 job 级别定义 env 有时不会自动透传。Skill 调用不到SKILL.md的 frontmatter 里name和目录名要一致description要写清楚触发场景。目录结构必须是.claude/skills/name/SKILL.md少一层都不行。长对话后规则失效这是 CLAUDE.md 的建议性本质决定的上下文压缩后可能被忽略。解决办法是把关键检查下沉到 Hooks用确定性执行兜底或者用/compact手动压缩、/context查看占用及时/clear重开。幻觉陷入失败循环果断重启/clear清空 session把试错清单明确告诉 AI 避免重蹈覆辙。多用git commit便于回滚Altm 进 Plan 模式只做规划不改代码。6. 一次配置多环境复用这套骨架的价值在于分层CLAUDE.md 是基础层定义核心标准Hooks 是执行层强制自动化检查Skills 和 CI/CD 是流程层封装复杂审查任务。三层各管一段互不越界。回到开头那个问题——为什么 CI 里的 Claude 时灵时不灵因为之前把所有期望都压在 prompt 上而 prompt 是易失的。现在规则进了 CLAUDE.md强制动作进了 Hooks重复任务进了 Skills通道收敛到 TaoToken 一个 Key本地和流水线读同一份配置。你要做的只是维护这几个文件而不是每次改 workflow 都重新解释一遍项目。最后留个实用习惯别全指望 AI。人还是要看路子走对了没有对走偏的及时纠偏。良好的代码命名规范对 AI 理解项目帮助极大命名清晰的项目AI 的审查质量会明显高一截。配置跑通后先让它审几个小 PR 观察输出质量稳定了再放开到主分支。