企业官网建设流程全解析

1. 为什么单会话写代码总在真实项目里翻车

先说结论：Claude Code 能做什么，取决于你给它搭了什么样的工程骨架。它不是一个"打开编辑器写一句 prompt 等代码"的补全器，而是一套可以挂载项目记忆、自动化钩子、子智能体和 Git 隔离环境的项目级 AI 工程管理系统。适合谁？适合已经在用 Claude Code 写单文件脚本、但一进真实仓库就发现上下文断裂、变更失控、多人多 AI 冲突频发的团队开发者。

我见过太多人把 Claude Code 当聊天窗口用：新开一个会话，AI 完全不记得上周定下的目录分层、命名规范、错误码格式，你得从头解释一遍架构决策。改完代码没人审查、没人跑测试、没人记录为什么这么改。两个人加两个 AI 同时动同一个工作区，冲突像雪球一样滚。质量全靠运气，回滚全靠记忆。

这些问题的根子不在模型能力，而在缺少一套"项目全生命周期"的约束层。Claude Code 恰好提供了四块拼图：分层记忆体系（CLAUDE.md 与 rules）、事件驱动钩子、可组合的斜杠命令与子智能体、Git Worktree 原生隔离。把它们串起来，AI 才真正像一个能进团队干活的工程师，而不是一个随时失忆的临时工。

这篇按真实研发流走一遍：需求分析、隔离开发、并行评审、合并发布。每一步都给可复制的配置片段，并且把 endpoint 与 auth.json 改到 TaoToken 后的连通性验证步骤讲清楚。你照着做，能直接落到自己仓库里。

2. 接入前置：把 Claude Code 的 endpoint 与 auth.json 指向 TaoToken

在讲记忆和 Worktree 之前，得先把"路"修通。Claude Code 默认走官方端点，团队里经常遇到额度、并发、计费口径不统一的问题。把请求统一收敛到 TaoToken 的 Anthropic 兼容入口，是后面所有自动化的前提——否则钩子跑一半报 401，你根本分不清是配置错还是额度空。

TaoToken 在这里扮演的是统一 API 网关：一个 Key、一个 Base URL，模型对话、Coding Plan、控制台用量都能对上账。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api （这个不加 UTM，配置里就写它）。

Claude Code 读取凭据的位置在用户目录下的~/.claude/settings.json或项目级.claude/settings.json，认证信息则落在~/.claude/.credentials.json（部分版本走auth.json结构）。核心是三件套：Base URL、API Key、Model ID。缺一个都会在启动时报认证失败。

先拿 Key：进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面新建一个，复制出来。文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到字段对不上时以文档为准。

然后写配置。项目级.claude/settings.json里放环境变量，避免把 Key 提交进 Git：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929" } }

如果你更习惯用auth.json结构（Codex 风格或某些封装版本），对应写成：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "claude-sonnet-4-5-20250929" }

注意：ANTHROPIC_BASE_URL只写到/api，不要自己拼/v1/messages，Claude Code 会按协议补全路径。Model ID 必须和 TaoToken 控制台里列出的可用模型名完全一致，大小写、日期后缀都不能错，这是后面 404 和reading choices报错的高发点。

提示：团队协作时，把 Key 放在每个人的本地环境变量或.claude/settings.local.json（自动 gitignore），仓库里只提交不含密钥的模板文件。这样既统一了端点，又不会把凭据泄露出去。

配完先别急着上 Worktree，跑一次最小连通性验证，确认这条路是通的，再往上叠记忆和子智能体。下一节给验证命令和预期输出。

3. 可复制配置：CLAUDE.md 模板、Worktree 目录与子智能体片段

这一节是全文的骨架，全部是可复制片段。先给项目记忆，再给隔离环境，最后给子智能体。

3.1 CLAUDE.md 项目章程模板

CLAUDE.md 不是技术文档，是给 AI 的项目约束说明书。控制在 70 行以内，超过 100 行就该拆到.claude/rules/。放在项目根目录，随 Git 提交，团队共享。

# 项目：订单服务 API ## 技术栈 - 运行时：Node.js 20 + TypeScript 5.3 - 框架：Express 4.x，ORM 用 Drizzle - 包管理：pnpm（禁止 npm / yarn） - 数据库：PostgreSQL 15 ## 常用命令 - 启动开发：pnpm dev - 集成测试：pnpm test:integration - 数据库迁移：pnpm db:push - 类型检查：pnpm typecheck - 构建：pnpm build ## 项目约定 - 控制器放 src/controllers/，服务层放 src/services/ - 控制器只做参数提取和响应封装，禁止写业务逻辑 - 所有输入用 zod schema 校验 - 禁止 any，用 unknown + 类型守卫替代 - 所有文件使用命名导出，禁止默认导出 ## 禁止事项 - 不要直接改数据库 schema，统一走迁移文件 - 不要在客户端代码暴露服务端环境变量 - 不要引入超过 50KB（gzip）的新依赖，需先讨论

当它超过 100 行，按主题拆到.claude/rules/，每个文件用 YAML 头声明作用路径：

--- paths: - "src/client/**/*.tsx" - "src/client/**/*.ts" --- # 前端规则：仅对匹配路径生效 - 使用函数组件 + Hooks，禁止 class 组件 - 所有用户可见字符串走 i18n - 图片必须指定 width/height 防止 CLS

个人本地差异写进CLAUDE.local.md，它会被自动 gitignore：

# 个人本地配置（不要提交） - 我的 PostgreSQL 跑在 localhost:5433 - 本地没有 Redis，涉及缓存用内存 Map 模拟 - API 密钥从 ~/.env.local 读取

3.2 Git Worktree 目录结构

主仓库永远不直接改，所有开发在隔离 worktree 里进行。一个 worktree = 一个功能 = 一个 Claude Code 会话。

# 目录规划 /project/main → main 分支（只读，禁止直接改） /project/trees/feat-export → feat/user-export 分支 /project/trees/feat-pay → feat/payment 分支 /project/trees/fix-cache → fix/cache-bug 分支 # 创建隔离环境 cd /project/main git worktree add ../trees/feat-export -b feat/user-export # 进入并启动会话 cd ../trees/feat-export claude # 完成后合并并清理 cd /project/main git merge feat/user-export git worktree remove ../trees/feat-export

命名规范是解药：feat/<功能名>、fix/<问题简述>、refactor/<模块名>。任务完成即合并删除，保持git worktree list输出不超过 3-5 行。

3.3 子智能体配置片段

子智能体定义在.claude/agents/，每个是带 YAML 头的 Markdown。三件套（Base URL、Key、Model ID）在 settings 里已统一，子智能体只需声明自己的角色和工具权限。

--- name: security-reviewer description: 专注安全漏洞检测——OWASP Top 10、密钥泄露、注入风险 tools: Read, Grep, Glob, Bash model: claude-sonnet-4-5-20250929 --- 你是一名资深应用安全工程师。审查代码时关注： 1. 注入漏洞：SQL 注入、命令注入、XXE 2. 认证授权：JWT 验证、权限检查是否遗漏 3. 敏感数据：硬编码密钥、日志是否打印用户数据 4. 输入校验：所有用户输入是否有服务端校验 每次审查给出 CRITICAL / HIGH / MEDIUM / LOW 分级，并附修复建议。

再用斜杠命令把多个子智能体编排成流水线，放在.claude/commands/：

--- description: 全量代码审查——安全、性能、质量并行执行 argument-hint: "目标模块路径" allowed-tools: Bash, Task, Read --- 对 `$ARGUMENTS` 执行并行多维度审查： ## 第 1 步：安全审查 使用 security-reviewer 子智能体，检查 OWASP Top 10、密钥泄露、注入风险。 ## 第 2 步：性能分析 使用 performance-optimizer 子智能体，检查 N+1 查询、缓存策略、算法复杂度。 ## 第 3 步：代码质量 使用 code-reviewer 子智能体，检查命名、函数长度、嵌套深度、错误处理。 ## 第 4 步：汇总 合并三份结果，按严重程度排序，CRITICAL 和 HIGH 必须给修复建议。

使用时只需/审查 src/api/，复杂编排对用户透明。这套配置和 Worktree 配合，就是后面验证和排障的基础。

4. 验证请求：连通性检查与成功结果长什么样

配置写完必须验证，否则后面所有自动化都是空中楼阁。分两步：先验端点通不通，再验 Claude Code 会话能不能正常起。

第一步，用 curl 直接打 TaoToken 的 Anthropic 兼容端点，确认 Key 和 Base URL 有效：

curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-你的TaoToken密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-5-20250929", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'

成功时返回体里会有"content":[{"type":"text","text":"OK"}]和"stop_reason":"end_turn"。如果返回 401，说明 Key 错或没带x-api-key头；返回 404 且提示 model 不存在，说明 Model ID 和控制台列表对不上。

第二步，在项目目录起 Claude Code，用内置命令确认记忆加载和端点生效：

cd /project/trees/feat-export claude # 会话内执行 /status

/status会打印当前 Base URL、模型、以及加载了哪些 CLAUDE.md 层级。你应该看到项目根目录的 CLAUDE.md 被加载，Base URL 显示https://taotoken.net/api。如果 Base URL 还是官方地址，说明 settings.json 没被读到——检查是不是写在了错误层级，或者环境变量被 shell 覆盖。

第三步，验证记忆是否真的生效。在会话里问一句：

本项目用哪个包管理器？控制器里能不能写业务逻辑？

正确回答应该是"pnpm"和"不能，控制器只做参数提取和响应封装"。如果它答 npm 或者说可以写，说明 CLAUDE.md 没加载成功，回到/status排查层级。

第四步，验证子智能体。执行/审查 src/controllers/，观察是否并行触发多个 Task。成功时你会看到安全、性能、质量三份结果被合并成一份带分级的报告。这一步跑通，说明三件套（Base URL、Key、Model ID）和子智能体配置全部对齐。

实测下来，最容易出问题的是 Model ID 和 Base URL 的路径拼接。记住：Base URL 只到/api，Model ID 从控制台复制，别手打。验证通过后，再进 Worktree 并行开发就稳了。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错对照，遇到直接查表。

401 Unauthorized / invalid api key：最常见。原因有三：Key 复制时带了空格或换行；ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY两个变量名混用导致读取了空值；settings.json 写在了项目级但当前目录不是项目根。排查顺序：先echo $ANTHROPIC_AUTH_TOKEN看有没有值，再确认 settings.json 层级，最后用第 4 节的 curl 单独验 Key。注意 TaoToken 的 Key 走x-api-key头，别错写成Authorization: Bearer。

local proxy failed / connection refused：Claude Code 启动时报本地代理失败。这通常是环境里残留了HTTP_PROXY/HTTPS_PROXY指向一个已关闭的本地端口。检查env | grep -i proxy，把无关的代理变量清掉再启动。注意：这里说的是清理本机残留的环境变量，不是让你去配任何网络代理工具，两者完全不同。

reading choices / cannot read property 'choices'：这个报错说明返回体结构不是预期的 Anthropic 格式，多半是 Base URL 指错了端点——比如把 OpenAI 兼容路径填进了 Anthropic 配置，或者 Base URL 多写了/v1。回到 settings.json，确认ANTHROPIC_BASE_URL就是https://taotoken.net/api，不带多余路径。同时确认 Model ID 是 Anthropic 系列模型名，不是 GPT 系列。

OAuth / authentication flow failed：Claude Code 某些版本会尝试走 OAuth 登录流程，如果你已经用 API Key 认证，这个流程应该被跳过。报 OAuth 错通常是~/.claude/.credentials.json里残留了旧的 OAuth token，和新的 API Key 冲突。处理办法：备份后删除该文件，重新用 settings.json 的ANTHROPIC_AUTH_TOKEN认证。删除前先确认里面没有你还需要的其他凭据。

Worktree 里 Claude Code 读不到 CLAUDE.md：因为 CLAUDE.md 在主仓库根目录，worktree 是独立工作目录。解决办法：把 CLAUDE.md 提交进 Git，worktree 检出分支时会一并带过来；或者用符号链接指向主仓库的 CLAUDE.md。推荐前者，保证每个 worktree 的约定一致。

子智能体不触发 / Task 无响应：检查.claude/agents/下文件的 YAML 头是否合法，name和斜杠命令里引用的名字必须完全一致。另外allowed-tools里没声明Task的话，斜杠命令无法派发子智能体。

排障时如果拿不准，直接对照接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 的字段说明，比猜快得多。

6. 把接入固化进日常研发流

到这里，四块拼图已经能串成一条流水线：需求阶段用 CLAUDE.md 和 rules 约束方案输出；开发阶段用 Worktree 隔离，一个功能一个会话；评审阶段用斜杠命令并行派发安全、性能、质量子智能体；发布阶段合并回主分支并清理 worktree。每一步的端点都收敛到 TaoToken，账目和额度在控制台统一看。

几个我踩过的坑值得你避开。第一，CLAUDE.md 别贪多，50-80 行是甜点区，每多一行 AI 的注意力就被稀释一分，超 100 行立刻拆 rules。第二，Worktree 用完就删，git worktree list超过 5 行说明你在堆积分支，迟早混乱。第三，自动记忆 MEMORY.md 是补充不是替代，核心约定必须写死在 CLAUDE.md 里，因为它是确定性的，自动记忆会漂移。第四，钩子脚本先在测试分支验证再启用，写错了虽然不会让 Claude Code 停摆，但会静默失败让你误以为检查跑了。

如果你还在单会话里硬扛真实项目，建议从最小闭环开始：先写一份 70 行的 CLAUDE.md，再建一个 worktree 跑通一次功能开发，最后加一个 security-reviewer 子智能体。跑顺了再往上叠钩子和多智能体编排。需要长期跑编码和 Agent 任务的团队，可以看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 的额度方案；只想先验证模型对话效果的，直接进模型对话 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 试一轮；Key 管理和用量核对在 API Keys https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 页面完成。把端点、记忆、隔离、编排这四件事固化下来，Claude Code 才真正从补全插件变成你的工程管理操作系统。