企业官网建设流程全解析

1. 为什么纯 Agent 工具需要重新理解上下文

Claude Code 和很多人印象里的“代码生成器”不是一类东西。你给它一句“帮我写个登录接口”，它当然能写，但这不是它的主战场。它更像一个坐在你旁边、能读你仓库、能跑命令、能连续追问的工程搭档。这个定位差异直接决定了：上下文给得对不对，比提示词写得漂不漂亮重要得多。

我见过太多人把 Claude Code 当补全工具用，结果抱怨“它老是改错文件”“它记不住我上一轮说的约束”。问题往往不在模型，而在于你把一个 Agent 塞进了单轮问答的壳子里。Agent 的工作方式是：先理解项目结构，再规划步骤，然后调用工具（读文件、写文件、执行命令），最后根据结果继续推进。它每一步都依赖你提供的上下文边界。

这里有个关键概念叫token 预算。Claude Code 每次请求能带的内容是有限的，你的 CLAUDE.md、当前打开的文件、历史对话、工具返回结果，全都在抢这块预算。如果你把整个仓库一股脑塞进去，真正重要的约束反而被挤掉了。所以官方实践里反复强调：用 Markdown 做分层，把“永远要遵守的规则”和“这次任务相关的信息”分开。

适合谁看这篇？如果你已经在用 Claude Code 做真实仓库开发，或者正准备把它接进团队工作流，那这篇就是给你写的。我会给出一套可复制的 CLAUDE.md 分层模板、上下文裁剪配置，以及一次端到端验证动作。全程围绕“纯 Agent 工具”这个前提，不讲虚的。

先明确一个判断标准：当你的 CLAUDE.md 超过 200 行还没分层时，Claude Code 的表现就会开始不稳定。这不是玄学，是 token 分配的问题。下面我从项目结构开始拆。

2. TaoToken 前置：把 Claude Code 接到可用端点

Claude Code 本身是个客户端，它需要一个兼容的 API 端点来跑模型。官方端点之外，很多团队会用 TaoToken 这类聚合服务来统一管理 key 和模型路由。这里我不展开注册流程，只讲接入 Claude Code 需要准备的三件套：Base URL、API Key、Model ID。这三样缺一个，Claude Code 都起不来。

TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数。你在 Claude Code 里配置的时候，Base URL 就填这个。API Key 去控制台生成，路径是https://taotoken.net/console，生成后复制出来，别截图，直接存进环境变量。

Model ID 这块要看你用哪个模型。Claude Code 默认走 Anthropic 的模型命名，比如claude-sonnet-4-20250514这种格式。如果你在 TaoToken 上用的是别的模型，得确认它支持 Anthropic 的 messages 接口格式。不支持的话，Claude Code 会报reading choices之类的解析错误，这个后面排障章节会细讲。

配置方式有两种。第一种是环境变量，适合临时测试：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key" export ANTHROPIC_MODEL="claude-sonnet-4-20250514"

第二种是写进 Claude Code 的 settings 文件，适合长期使用。路径通常在~/.claude/settings.json，内容长这样：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

注意ANTHROPIC_BASE_URL后面不要加/v1，Claude Code 会自己拼路径。加了反而会 404。这个坑我踩过，当时排查了半小时，最后发现是多写了一段。

如果你用的是 Claude Code 的 coding plan 模式，也就是让它长时间跑编码任务，那还需要确认你的 key 有足够的额度。Coding Plan 的入口在https://taotoken.net/coding-plan，适合那种“让它自己跑一晚上重构”的场景。普通对话和调试用 API Keys 就够了。

配置完之后，先别急着开项目。在空目录里跑一次claude命令，看它能不能正常启动并响应。如果启动就报local proxy failed，说明 Base URL 没通，检查网络和地址拼写。如果启动成功但一发消息就报 401，那是 key 的问题。这两个错误后面会单独讲。

3. 可复制配置：CLAUDE.md 分层模板与裁剪参数

这一节是核心。Claude Code 读 CLAUDE.md 的方式是：从当前工作目录往上找，找到第一个就停。所以你可以做分层——项目根目录放全局规则，子目录放模块规则。但很多人不知道的是，Claude Code 只会自动加载根目录的 CLAUDE.md，子目录的需要你在对话里显式引用，或者用@语法带进来。

先给一套我实测下来比较稳的分层模板。根目录的CLAUDE.md控制在 80 行以内，只放三类东西：项目定位、技术栈约束、Agent 行为边界。

# 项目上下文 ## 项目定位 这是一个 NestJS + Prisma 的后端服务，对外提供 REST API。 主要模块：auth、user、order。数据库 PostgreSQL。 ## 技术栈约束 - 语言：TypeScript strict 模式 - 框架：NestJS 10.x - ORM：Prisma 5.x - 校验：class-validator - 测试：Jest + Supertest ## Agent 行为边界 - 修改文件前必须先读该文件当前内容 - 不要自动执行数据库 migration，只生成 SQL 让我确认 - 新增依赖前先问我 - 每次改动后运行 `pnpm test` 并贴出结果 - 不要碰 `src/legacy/` 目录 ## 常用命令 - 启动：`pnpm start:dev` - 测试：`pnpm test` - 类型检查：`pnpm typecheck`

这份模板的关键在于“Agent 行为边界”这一段。纯 Agent 工具最大的风险是它太主动，你不划边界，它可能改一堆你不想动的文件。把边界写清楚，比写十句“请小心”有用。

子目录的 CLAUDE.md 按模块拆。比如src/order/CLAUDE.md：

# Order 模块上下文 ## 职责 处理订单创建、状态流转、退款。 ## 关键约束 - 订单状态机定义在 `order.status.ts`，不要绕过它直接改 status 字段 - 金额计算统一用 `Money` 值对象，禁止裸 number 运算 - 所有写操作必须走 `OrderRepository`，不要在 service 里直接调 prisma ## 相关文件 - `order.service.ts`：业务逻辑 - `order.repository.ts`：数据访问 - `order.status.ts`：状态机

然后在对话里这样引用：@src/order/CLAUDE.md 帮我加一个取消订单的接口。Claude Code 会把这份子上下文加载进来，但不会污染根上下文。

接下来是上下文裁剪配置。Claude Code 支持在 settings 里配context相关参数，控制它自动读取哪些文件、忽略哪些。这个配置能显著降低 token 消耗：

{ "context": { "ignorePatterns": [ "**/node_modules/**", "**/dist/**", "**/*.lock", "**/coverage/**", "**/.git/**" ], "maxFileSize": 50000, "autoReadLimit": 20 } }

ignorePatterns是必须配的。不配的话，Claude Code 在搜索文件时可能把node_modules里的东西也扫进来，token 瞬间爆炸。maxFileSize限制单个文件读取上限，超过 50KB 的文件它只读头部。autoReadLimit控制自动读取的文件数量，默认别调太高，20 个够用了。

还有一个技巧：用.claudeignore文件。语法和.gitignore一样，放在项目根目录。Claude Code 会优先读这个文件来决定忽略哪些路径。我一般会把*.generated.ts、migrations/、fixtures/这些放进去。

配置完之后，你可以用claude --print-context这个命令看它实际加载了哪些内容。这个命令会输出当前上下文的 token 估算和文件列表。如果发现某个不该进来的文件进来了，就去检查 ignore 配置。

4. 验证请求：一次端到端 Agent 任务复现

配置写完不验证等于没写。这一节我带你在一个真实仓库里跑一次完整任务，从发指令到看结果，把每一步的预期输出说清楚。

假设你的项目结构是这样的：

my-app/ ├── CLAUDE.md ├── .claudeignore ├── package.json ├── src/ │ ├── auth/ │ │ ├── CLAUDE.md │ │ └── auth.service.ts │ └── user/ │ ├── CLAUDE.md │ └── user.service.ts └── prisma/ └── schema.prisma

第一步，启动 Claude Code。在项目根目录执行claude，它会自动加载根目录的 CLAUDE.md。你会看到它打印出“Loaded project context from CLAUDE.md”之类的提示。如果没有这个提示，说明文件没被识别，检查文件名大小写。

第二步，发一个带子上下文的指令：

@src/user/CLAUDE.md 阅读 user.service.ts，找出所有直接调用 prisma 的地方，列出来并说明为什么应该走 repository。

预期行为：Claude Code 会先读src/user/CLAUDE.md，再读user.service.ts，然后输出一个列表。它不会直接改代码，因为根 CLAUDE.md 里写了“修改文件前必须先读该文件当前内容”，而且这个指令本身是分析型的。

第三步，让它执行一个修改任务：

把 user.service.ts 里直接调 prisma 的地方改成走 UserRepository，改完后运行 pnpm test。

这时候观察它的工具调用顺序：先读文件 → 生成修改 → 写文件 → 执行pnpm test→ 贴出测试结果。如果测试失败，它会根据报错继续修。这就是纯 Agent 工具的工作方式——它不是一次性输出代码，而是“读-改-测”循环。

第四步，验证 token 预算。在对话里输入/context，Claude Code 会显示当前上下文的占用情况。你应该看到类似这样的输出：

Context usage: - System prompt: 1,200 tokens - CLAUDE.md: 800 tokens - Conversation: 3,500 tokens - Files: 5,200 tokens - Total: 10,700 / 200,000 tokens

如果 Files 那一项特别高，说明有不该加载的文件进来了，回去检查.claudeignore。如果 Conversation 涨得很快，说明你在一个会话里塞了太多不相关的任务，该开新会话了。

第五步，验证工具调用边界。故意发一个越界指令：

帮我执行 prisma migrate deploy。

预期行为：Claude Code 会拒绝，并引用 CLAUDE.md 里的“不要自动执行数据库 migration”。如果它真的执行了，说明你的边界规则没写清楚，或者它没加载到。这时候去检查根 CLAUDE.md 的“Agent 行为边界”段落是否在文件前 80 行内——太靠后可能被截断。

这一套跑下来，你就有了一个可复现的验证流程。每次改完 CLAUDE.md 或 ignore 配置，都跑一遍这五步，确保行为符合预期。

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

接入和配置过程中，有几个报错几乎人人都会遇到。我把它们和对应的排查路径列出来，你对着改就行。

401 Unauthorized。这个最直接，key 不对或没传。先确认ANTHROPIC_API_KEY环境变量有没有生效，在终端里echo $ANTHROPIC_API_KEY看输出。如果是空的，说明 export 没成功，或者你写在了 settings.json 但格式错了。settings.json 里的 key 必须在env对象下面，不能直接放顶层。还有一种情况是 key 复制时带了空格，肉眼看不出来，重新复制一次。

local proxy failed。这个报错通常出现在启动阶段，意思是 Claude Code 连不上你配的 Base URL。排查顺序：第一，确认ANTHROPIC_BASE_URL是https://taotoken.net/api，结尾没有斜杠，没有/v1。第二，在终端里curl https://taotoken.net/api看能不能通。第三，如果你在公司网络里，确认没有额外的网络策略拦截。这个报错和 key 无关，纯粹是地址问题。

reading choices 相关报错。完整报错可能是Error reading choices: unexpected response format之类。这个说明端点返回的 JSON 结构不是 Claude Code 期望的 Anthropic messages 格式。原因通常是 Model ID 填错了，或者你用的模型不支持 Anthropic 接口。解决方法是确认 Model ID 是 Anthropic 命名格式，比如claude-sonnet-4-20250514。如果你在 TaoToken 上用的是别的模型，去https://taotoken.net/doc查一下它支持哪些接口格式。

OAuth 相关报错。如果你看到OAuth token expired或failed to refresh token，说明你用的是 OAuth 登录方式而不是 API Key。Claude Code 支持两种认证：OAuth 和 API Key。用 TaoToken 的话，走 API Key 就行，不需要 OAuth。去 settings.json 里把 OAuth 相关的配置删掉，只留ANTHROPIC_API_KEY。

上下文超限报错。报错信息里会带context length exceeded或too many tokens。这时候不是去调大限制，而是去裁剪。检查.claudeignore有没有漏掉大文件，检查当前会话是不是开了太久。Claude Code 的会话历史是累积的，开一整天不关，token 肯定爆。养成习惯：一个任务一个会话，做完就/clear。

工具调用被拒绝但你没写规则。有时候 Claude Code 会自己“觉得”某个操作危险然后拒绝。这是它的安全机制，不是你配置的问题。如果你确认这个操作是安全的，可以在对话里明确说“我授权你执行这个操作”。但更好的做法是提前在 CLAUDE.md 里写清楚哪些操作是允许的，减少来回确认。

这几个错误覆盖了 90% 的接入问题。剩下的 10% 通常是环境差异，比如 Windows 下的路径问题、Node 版本不兼容等。遇到的时候先看完整报错，别只看最后一行。

6. 语义一致 CTA：把配置落到日常开发流

配置跑通之后，接下来就是把它变成日常习惯。我自己的做法是：每个新项目初始化时，先花 20 分钟写 CLAUDE.md 和.claudeignore，后面能省下大量来回沟通的时间。这 20 分钟的投入产出比极高。

具体来说，项目初始化时做三件事。第一，写根 CLAUDE.md，控制在 80 行内，重点写 Agent 行为边界。第二，写.claudeignore，把node_modules、dist、coverage、*.lock全排除。第三，在 settings.json 里配好 Base URL、Key、Model ID 三件套。这三件事做完，Claude Code 就能在项目里稳定工作了。

日常使用中，我建议按任务类型分会话。分析型任务（读代码、找问题）一个会话，修改型任务（改代码、跑测试）另一个会话。不要在一个会话里既分析又修改又部署，上下文会乱。Claude Code 的/clear命令可以清空当前会话历史，但保留 CLAUDE.md 的加载。这个命令很实用，做完一个任务就清一次。

如果你要让它跑长时间的编码任务，比如重构一个模块，用 Coding Plan 模式。入口在https://taotoken.net/coding-plan，这个模式下的上下文管理策略和普通对话不同，它会自动做任务分解和进度跟踪。适合那种“我下班了让它自己跑”的场景，但前提是你的 CLAUDE.md 边界写得足够清楚，不然它可能改出你意想不到的东西。

模型选择上，日常调试用轻量模型就够了，复杂重构再切到强模型。切换方式就是改ANTHROPIC_MODEL环境变量，或者在对话里用/model命令。TaoToken 的模型列表在https://taotoken.net/doc里能查到，选支持 Anthropic messages 格式的就行。

最后说一个我踩过的坑：不要把所有规则都堆在根 CLAUDE.md 里。我一开始图省事，把 auth、user、order 三个模块的规则全写在一起，结果根文件 300 多行，Claude Code 加载后反而经常忽略后面的规则。后来拆成根 + 子目录两层，每个文件都不超过 100 行，表现立刻稳定了。分层不是为了好看，是为了让 token 预算花在刀刃上。

你现在就可以打开自己的项目，按第 3 节的模板写一份 CLAUDE.md，然后跑第 4 节的五步验证。跑完你会对“纯 Agent 工具”这个词有完全不一样的理解。