1. 每次新会话都要重新交代背景问题到底出在哪如果你正在用 Claude Code 做中大型项目大概率经历过这个场景新开一个会话第一件事不是写代码而是先打一段项目说明书——这是 Node.js 项目用的 Prisma Express测试框架是 Jest别动 package-lock.json别碰 .env 文件API 响应统一用{ data, error, meta }结构……重复到第十次的时候你会开始怀疑自己是不是在训练一个每天失忆的实习生。更崩溃的是某次 Claude 帮你改完一个接口顺手把package-lock.json优化了一下600 多行 diffreview 的时候你差点以为看错了仓库。它不是故意的但每次都得人肉盯着自动化又变回了人工 review。这个问题的根源在于大多数人用 Claude Code 还停留在对话式编程阶段。每次新开会话上下文清零、规则清零、约束清零。你以为在跟一个越来越懂你的搭档合作实际上每次都是从零开始。Claude Code 其实内置了一套完整的扩展机制来解决这个问题——Hooks、Skills、Agents 三层配置协同。Hooks 管不能做什么Skills 管应该怎么做Agents 管谁来做。把这三层配好你的 Claude Code 就从需要手把手带的实习生变成自带 SOP 的高级工程师。这篇文章面向需要反复交代上下文的中大型项目开发者目标是让每次会话开箱即用。我会给出可直接复制的settings.json配置片段、完整的目录结构、验证动作以及如何把 endpoint 与鉴权统一改到 TaoToken 通道让 Hooks、Skills、Agents 三层配置真正跑起来。全程不需要写业务代码全是配置。2. 三层协同前先把 Claude Code 的请求通道接到 TaoToken在配置 Hooks、Skills、Agents 之前有一个前置动作必须先做把 Claude Code 的请求 endpoint 和鉴权统一到 TaoToken。原因很直接——三层配置跑起来之后Subagent 会大量并发调用模型Hooks 里的 prompt 类型判断也会额外发起请求如果通道不统一你会在多个 key、多个 endpoint 之间来回切换排查问题时根本分不清是哪一层出的错。TaoToken 在这里扮演的是统一接入通道的角色一个 API Key、一个 Base URLClaude Code 主会话、Subagent、Hooks 里的 LLM 判断全部走同一条链路。这样你在看日志、算成本、排查 401 的时候只需要盯一个地方。2.1 获取 API Key 与确认 Base URL先到 TaoToken 控制台创建 API Key。地址是https://taotoken.net/api-keys登录后点创建复制出来的 key 形如sk-xxxxxxxx。这个 key 只显示一次建议直接存进密码管理器。Base URL 统一用https://taotoken.net/api注意这个地址不带任何查询参数是纯粹的 API 入口。官网首页是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台、文档、模型对话入口都在上面能找到。如果你还没决定用哪个模型可以先到模型对话页面https://taotoken.net/models试一下确认模型 ID 再写进配置。Claude Code 场景下常用的模型 ID 需要和你账号下可用的保持一致写错模型 ID 会直接报model not found。2.2 环境变量方式接入推荐Claude Code 读取环境变量的优先级高于配置文件所以最省事的做法是在 shell 里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 export ANTHROPIC_MODEL你的模型ID把这三行写进~/.zshrc或~/.bashrcsource一下。这样每次开终端都自动生效Claude Code 启动时直接读到。注意ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY的区别前者用于自定义 endpoint 的 Bearer 鉴权后者是官方直连时用的。走 TaoToken 通道时用ANTHROPIC_AUTH_TOKEN写错了会出现鉴权失败。2.3 settings.json 方式接入团队共享如果你希望团队里每个人克隆仓库后开箱即用可以把通道配置写进项目的.claude/settings.json。但 key 不能提交到 git所以正确做法是settings.json 里只写 Base URL 和模型 IDkey 通过环境变量注入。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: 你的模型ID } }然后每个人在自己的~/.zshrc里放ANTHROPIC_AUTH_TOKEN。这样仓库里没有敏感信息通道又是统一的。2.4 验证通道是否打通配置完先别急着写 Hooks用一条最小请求验证通道curl https://taotoken.net/api/v1/messages \ -H Authorization: Bearer $ANTHROPIC_AUTH_TOKEN \ -H Content-Type: application/json \ -d { model: $ANTHROPIC_MODEL, max_tokens: 64, messages: [{role: user, content: reply with ok}] }返回里能看到content字段和正常的usage说明通道通了。如果返回 401先检查 key 有没有复制完整、有没有多余空格如果返回model not found去模型对话页面确认模型 ID 拼写。这一步做完后面 Hooks 里的 prompt 判断、Subagent 的并发调用全部走这条通道不用再单独配。3. 可复制的 settings.jsonHooks 让 Claude 自己守规矩通道打通后进入正题。Hooks 的核心思想很简单在 Claude 执行特定操作的前后自动触发你定义的逻辑。用过 Git 的 pre-commit hook 或者 Spring 的 AOP概念一模一样。3.1 九种事件覆盖完整生命周期事件触发时机核心用途PreToolUse工具执行前拦截危险操作、修改输入参数PostToolUse工具执行后自动格式化、跑 linterUserPromptSubmit用户提交 prompt 时注入上下文、安全警告Stop主 Agent 准备停止时检查是否跑了测试/buildSubagentStop子 Agent 准备停止时验证子任务完成度SessionStart会话开始时加载环境变量、设置项目上下文SessionEnd会话结束时清理临时文件、记录日志PreCompact上下文压缩前保留关键信息不被丢弃Notification通知发送时桌面提醒权限请求、空闲提示每个事件支持两种 Hook 类型command执行 Shell 脚本适合确定性检查默认超时 60 秒prompt让 LLM 做判断适合需要语义理解的场景默认超时 30 秒仅 PreToolUse、PostToolUse、Stop、SubagentStop、UserPromptSubmit 支持。Matcher 决定这个 Hook 监听哪些工具Write精确匹配Read|Write|Edit匹配多个*匹配所有mcp__.*__delete.*正则匹配。3.2 完整 settings.json 配置Node.js 项目这是我在生产项目里实际使用的配置直接放在.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: 你的模型ID }, hooks: { SessionStart: [ { matcher: *, hooks: [ { type: command, command: echo \[session] branch$(git branch --show-current) node$(node -v)\ exit 0 } ] } ], PreToolUse: [ { matcher: Write|Edit, hooks: [ { type: prompt, prompt: File path: $TOOL_INPUT.file_path. Verify: 1) Not .env or credentials 2) Not package-lock.json/yarn.lock 3) No path traversal (..). Return approve or deny. } ] } ], PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx prettier --write \$TOOL_INPUT.file_path\ 2/dev/null; npx eslint --fix \$TOOL_INPUT.file_path\ 2/dev/null; exit 0 } ] } ], Stop: [ { matcher: *, hooks: [ { type: prompt, prompt: Review transcript. If code was modified, verify: 1) Tests were run 2) Build succeeded 3) All user questions answered. Return approve or block with reason. } ] } ], Notification: [ { matcher: permission_prompt|idle_prompt, hooks: [ { type: command, command: osascript -e display notification \Claude needs attention\ with title \Claude Code\ 2/dev/null; exit 0 } ] } ] }, permissions: { allow: [Edit, Write, Bash(npm test:*), Bash(npm run build:*)], deny: [Bash(rm -rf:*), Bash(git push --force:*)] } }这套配置做了四件事写文件前用 LLM 检查是否碰敏感文件写文件后自动跑 Prettier ESLint结束前验证测试和构建等待时弹桌面通知。3.3 三个必踩的坑坑一改了配置没反应。Hooks 在会话启动时加载改完settings.json必须退出并重启会话。调试用claude --debug能看到 Hook 的注册和执行日志。坑二以为 Hook 按顺序执行。所有匹配的 Hooks 并行执行不保证顺序不能假设 Hook A 的输出被 Hook B 读到。需要链式处理就在一个 Hook 内部用;串联命令或者通过临时文件在 PreToolUse → PostToolUse 之间传状态。坑三Hook 脚本忘了exit 0。command 类型退出码 0 表示成功2 表示阻断stderr 反馈给 Claude其他非零码是非阻断错误。脚本可能失败但不想阻断流程记得兜底exit 0。4. Skills 与 Agents把经验沉淀成知识包把角色拆成并行团队Hooks 解决了守规矩但应该怎么做和谁来做还得靠 Skills 和 Agents。4.1 Skills 的三级渐进式加载CLAUDE.md 能解决每次交代项目背景但它是全量加载的写多了会吃掉上下文窗口。Skills 按需加载只在需要时把相关知识注入上下文。它的三级加载机制是设计上最聪明的地方Level 1 是 Metadataname description始终在上下文中约 100 words让 Claude 知道有这个 Skill 可用。Level 2 是 SKILL.md bodySkill 触发时才加载建议 1500-2000 words。Level 3 是 Bundled Resourcesscripts/ references/ assets/Claude 按需读取没有大小限制。这意味着你可以注册 50 个 Skills但只有被触发时它的 body 才占上下文Metadata 这层成本几乎可忽略。目录结构skill-name/ ├── SKILL.md # 必须YAML frontmatter Markdown body ├── scripts/ # 可执行脚本确定性任务 ├── references/ # 按需加载的参考文档 └── assets/ # 模板、图片等资源文件4.2 自定义 Skill 示例测试生成器放在.claude/skills/gen-test/SKILL.md--- name: gen-test description: This skill should be used when the user asks to generate tests, write tests for, add test coverage, or create unit tests. Generates tests following project conventions. disable-model-invocation: true --- # Test Generator Generate tests for the file at $ARGUMENTS. ## Process 1. Read the source file and understand its exports 2. Check existing test patterns in [examples/](examples/) 3. Follow the projects testing conventions: - Use Jest/Vitest for unit tests - Use real code, minimize mocks - One behavior per test - Clear test names describing behavior 4. Place test file in appropriate __tests__/ directory 5. Run tests to verify they pass ## Reference Examples - **examples/unit-test.ts** - Standard unit test pattern - **examples/integration-test.ts** - API integration test pattern几个关键设计disable-model-invocation: true让只有用户显式调用才触发防止 Claude 自作主张具体步骤放 bodyLevel 2示例代码放examples/Level 3按需读取$ARGUMENTS是动态占位符用户输入/gen-test src/services/user.ts时替换为文件路径。Skills 还支持动态上下文注入!command语法会在 Skill 加载前执行命令并替换输出## Current State - Branch: !git branch --show-current - Status: !git status --short这样 Claude 拿到的是实时项目状态不是静态文档。4.3 Agents把角色拆成并行团队Agents 是你手下的虚拟团队成员每个有自己的角色定位、工具权限和思维模型。放在.claude/agents/code-reviewer.md--- name: code-reviewer description: Use this agent when code changes are complete and need review. model: sonnet color: blue tools: [Read, Grep, Glob] --- You are an expert code reviewer specializing in identifying bugs, security issues, and code quality problems. **Your Core Responsibilities:** 1. Review all changed files for correctness 2. Check for security vulnerabilities (OWASP Top 10) 3. Verify error handling completeness 4. Assess code readability and maintainability **Output Format:** - **Summary**: 2-3 sentences on overall quality - **Issues**: Grouped by severity with file:line references - **Verdict**: Approved / Changes Requested关键配置model: sonnet是性价比最优选择tools: [Read, Grep, Glob]遵守最小权限原则Reviewer 只需要读代码。模型选择策略机械实现改 1-2 个文件spec 明确用 haiku快且便宜集成判断多文件协调、接口设计用 sonnet架构设计、复杂 Code Review 用 opus不确定时用 inherit 继承主 Agent 模型。Subagent 并行派发的前提2 个以上独立任务无共享状态每个任务可独立理解Agent 之间不会编辑同一文件。满足这三条Claude 会自动分派到不同 Subagent每个在独立工作空间执行完成后返回 DONE、DONE_WITH_CONCERNS、NEEDS_CONTEXT、BLOCKED 四种状态之一。坑一以为 Subagent 自动继承主 Agent 上下文。这是最常见的误解。Subagent 启动时是干净上下文不会自动获得你之前聊了半小时的会话历史。你需要在派发时把 Subagent 需要知道的所有信息写进 task 描述。这是刻意设计避免上下文污染。坑二给 Agent 太多工具权限。只负责 Review 的 Agent 不需要 Write 和 Bash。工具越多Agent 越容易发挥创造力做你没要求的事。5. 验证请求与常见报错排查配置写完必须验证。这一节给出验证动作和真实报错对照。5.1 验证 Hooks 是否生效重启 Claude Code 会话后用/hooks命令查看已加载的 Hooks 列表。如果列表为空说明settings.json路径不对或 JSON 语法错误。用claude --debug启动日志里会打印每个 Hook 的注册信息。触发一次 Write 操作观察 PostToolUse 是否跑了 Prettier。如果文件没被格式化检查$TOOL_INPUT.file_path是否被正确替换——不同版本的变量名可能不同用claude --debug看实际传入的参数。5.2 验证 Skills 是否被识别在会话里输入/看命令补全列表自定义 Skill 应该出现在里面。如果没出现检查 SKILL.md 的 frontmatter 格式——name和description是必填YAML 缩进错了会导致整个 Skill 加载失败。5.3 验证 Agents 是否可派发输入code-reviewer看是否能唤起。如果 description 写得泛泛Claude 可能永远不会主动派发。必须用第三人称加具体触发短语把触发场景写死。5.4 真实报错对照表报错原因解决401 Unauthorizedkey 错误或未注入检查ANTHROPIC_AUTH_TOKEN是否导出有无多余空格model not found模型 ID 拼写错误去模型对话页面确认可用模型 IDlocal proxy failedBase URL 写错或网络不通确认ANTHROPIC_BASE_URL为https://taotoken.net/apireading choices 报错响应格式解析失败检查是否误用了 OpenAI 格式的 endpointOAuth 相关报错误用了官方登录态走 TaoToken 通道时清掉官方 OAuth 缓存Hook 不执行未重启会话退出并重启 Claude CodeSkill 不触发description 太泛改成第三人称加具体触发短语排查顺序建议先确认通道curl 最小请求再确认 Hooks 加载/hooks再确认 Skills 识别/补全最后确认 Agents 派发唤起。一层一层来不要跳。6. 把三层配置真正用起来从今天开始的三步走回到开头那个场景每次开新会话都要重复交代背景、手动盯着 Claude 别碰 lock 文件、改完代码不知道该不该跑测试。这些问题的本质是——你在用一个有记忆能力的工具却没给它建立记忆。CLAUDE.md 是它的长期记忆Skills 是它的专业技能库Hooks 是它的行为准则Agents 是它的团队分工。把这四样配好Claude Code 才算真正上岗。我的建议是分三步走今天先写一个 CLAUDE.md30 分钟明天配好 Hooks 的settings.json20 分钟后天按需写第一个 Skill30 分钟。不用一步到位但别在对话式编程阶段停太久。通道层面把 endpoint 和鉴权统一到 TaoToken 之后主会话、Subagent、Hooks 里的 LLM 判断全部走一条链路排查问题时只需要盯一个地方。API Key 在https://taotoken.net/api-keys创建接入文档在https://taotoken.net/doc模型对话在https://taotoken.net/models长期编码和 Agent 场景可以看 Coding Planhttps://taotoken.net/coding-plan。配好之后你会发现新开会话的第一句话不再是这是一个 Node.js 项目而是直接进入正题。这才是 Claude Code 该有的样子。