企业官网建设流程全解析

写在前面：本文基于我近半年持续落地 Claude Code 的真实踩坑经验，前后两个账号每月投入 40 刀，算是交了不少学费。

最开始我也只是把 Claude Code 当成普通聊天机器人来使用，但是很快就发现各种问题：会话上下文越来越杂乱，接入的工具越多效果反而越差，规则写得越来越长，模型却时常无视。花了不少时间深挖 Claude Code 的底层逻辑之后，才找到这些问题的根源。

想要快速理解它，我习惯把 Claude Code 拆解成六层架构来看，每一层各司其职：

1. CLAUDE.md / rules / memory：承载长期上下文，定义项目基础约定

2. Tools / MCP：赋予动作能力，告诉模型它可以执行哪些操作

3. Skills：按需加载的工作方法论，定义处理任务的流程

4. Hooks：强制行为拦截，不依赖模型自主判断执行

5. Subagents：具备隔离上下文的独立工作单元，实现受控自治

6. Verifiers：验证闭环，保障结果可校验、可回滚、可审计

这六层是联动的，单独优化某一层，很容易在其他层面引发新问题。CLAUDE.md 内容写得过长，会直接污染上下文；工具堆砌过多，模型容易出现选择混乱；Subagent 无限制创建，任务状态会发生漂移；如果跳过验证环节，后续出问题很难定位故障点。

底层运行机制：Agent 循环

Claude Code 的核心就是一套持续迭代的代理循环：

收集上下文 → 采取行动 → 验证结果 →（任务完成 或 返回收集阶段）

整个循环会读取 CLAUDE.md、Skills、Memory 作为基础输入，同时由 Hooks、权限沙箱、MCP/Tools 约束行为边界。

长期实践下来我发现，绝大多数卡点，并不是模型推理能力不足。更多情况是传入了错误的上下文，或是任务缺少清晰的判定标准，就算模型执行了操作，也无法判断结果对错，更无法回滚。

基于这套架构，我总结了五个排查诊断维度，遇到异常可以逐层定位：

- 上下文层：确定常驻信息与按需加载信息，载体为 CLAUDE.md、rules、memory、skills

- 动作层：管控模型可用能力，包含内置工具、MCP、插件

- 控制层：约束、审计、阻断高危动作，依托权限、沙箱、Hooks

- 隔离层：对任务做上下文与权限隔离，使用 Subagent、worktree、独立会话

- 验证层：判定任务可信完成，依靠测试、lint、截图、日志、CI

结果不稳定优先排查上下文加载逻辑；自动化行为失控，检查控制层配置；长会话质量衰减，大多是中间输出污染上下文，新建会话往往比反复调试提示词更高效。

厘清核心概念边界，避免混用

很多人在落地时会混淆这几组概念，这里简单区分各自定位：

- CLAUDE.md：项目级持久契约，存放会话必须遵守的约束、边界与禁止项。误区：把它写成完整团队知识库。

- .claude/rules/：按路径、语言划分的局部规则。误区：所有规则全部堆入根目录 CLAUDE.md。

- 内置工具：读写文件、执行命令、检索等原生能力。误区：所有能力都塞进 shell 调用。

- MCP：外部系统接入协议，连接 GitHub、数据库、监控平台等。误区：一次性接入过多服务，工具定义挤占上下文。

- Plugin：打包分发载体，可打包 Skills、Hooks、MCP。误区：将 Plugin 当成底层运行原语。

- Skill：按需加载的领域知识与工作流包。误区：把 Skill 同时做成百科全书和部署脚本。

- Hook：生命周期拦截脚本，强制执行规则。误区：用 Hook 替代所有模型推理判断。

- Subagent：隔离上下文的独立工作单元。误区：无限制并行调用，造成治理失控。

一句话区分：需要新增动作能力，用 Tool/MCP；需要标准化工作流程，用 Skill；需要隔离任务环境，启用 Subagent；需要硬性审计约束，配置 Hook；想要跨项目复用整套配置，打包成 Plugin。

上下文工程：最核心的系统约束

大部分场景下，瓶颈不在于上下文窗口上限，而是上下文噪音太多，有效信息被冗余内容淹没。

Claude Code 200K 的上下文窗口并不是全部都能拿来处理业务，会有固定开销占用：

- 固定开销（15-20K tokens）：系统指令、Skill 描述、MCP 工具定义、LSP 状态。MCP 是最大隐形消耗项，单个 MCP Server 通常包含 20~30 个工具定义，接入 5 个服务，仅工具描述就会占用 25K tokens。

- 半固定内容（5-10K tokens）：CLAUDE.md、memory

- 动态可用区域（160-180K tokens）：对话历史、文件内容、工具返回结果

上下文分层最佳实践

- 常驻：CLAUDE.md，只保留项目契约、构建命令、硬性禁止项，参考官方范例，控制在 2.5K tokens 左右

- 按路径加载：rules，存放语言、目录、文件类型相关局部规范

- 按需加载：Skills，业务工作流与领域知识，详细文档放到附属文件，不塞进主 SKILL.md

- 隔离加载：Subagents，处理大规模代码检索、并行调研任务

- 不入上下文：Hooks，确定性脚本、审计、阻断逻辑

配套操作习惯：

使用 /context 实时查看 token 占用，不要等到自动压缩之后补救；切换任务优先 /clear ，同一任务进入新阶段使用 /compact 。并且在 CLAUDE.md 中定义压缩优先级，规定压缩时优先保留架构决策、文件变更、验证状态、待办与回滚方案，工具输出仅保留是否通过的结论，交由算法自动压缩很容易丢失关键设计约定。

另外还有一个容易忽略的开销：工具输出。执行测试、git 查询等命令会一次性输出海量日志，全部进入上下文会快速挤占空间。RTK（Rust Token Killer）可以在输出交给模型之前自动过滤冗余信息，只保留核心结论，例如只返回测试通过数量，丢弃数千行详细单条测试日志，减少上下文噪声。

上下文自动压缩还有一个隐藏陷阱：默认策略会优先删除早期文件内容、工具输出，连带之前确定的架构决策一起丢失。时隔一段时间继续开发，模型会遗忘前期约定，莫名产生 bug。除了自定义压缩指令，还有一个稳妥方案：在开启新会话前，让 Claude 生成 HANDOFF.md，记录当前进度、尝试过的方案、可行方案与死胡同、下一步计划。新会话直接读取这份交接文档，不再依赖压缩摘要。

Plan Mode：把探索和执行拆开

Plan Mode 的核心思想是只读探索与实际执行分离。探索阶段仅做分析，不改动任何文件，目标方案确认之后，再执行修改操作。

1. 探索阶段：只读操作，澄清目标边界，输出完整方案

2. 确认阶段：人工校验方案合理性

3. 执行阶段：落地代码修改

处理大型重构、模块迁移这类高风险改动时，这套模式可以避免模型在错误假设上持续投入大量工作量。进阶玩法可以多实例互审：一个 Agent 输出方案，另一个 Agent 扮演高级工程师做方案评审。

Skills 设计：不是提示词模板库

Skill 是按需加载的工作流，描述常驻上下文，完整内容仅在触发时加载。一个合格的 Skill 需要明确触发场景、完整步骤、输入输出、终止条件；存在副作用的 Skill，需要设置 disable-model-invocation: true ，禁止模型自动调用。

推荐目录结构：

plaintext

.claude/skills/

└── incident-triage/

├── SKILL.md

├── runbook.md

├── examples.md

└── scripts/

└── collect-context.sh

常见三类 Skill：

1. 检查清单型：质量门禁，例如发布前校验编译、测试、版本、更新日志

2. 工作流型：标准化高危操作，自带备份、试运行、回滚步骤，比如配置迁移

3. 领域专家型：故障诊断框架，固定证据收集路径与根因判断矩阵

Skill 描述文字要精简，减少常驻 token 消耗。同时区分调用频率：高频任务允许自动触发；低频任务关闭自动调用，手动触发；极少使用的内容，直接移出 Skill，写在项目文档中。

Skill 反模式

描述过于宽泛、正文堆砌大量文档、单个 Skill 包揽多种任务、带风险操作允许模型自动调用。

工具设计：面向 Agent 的工具，和面向人的 API 不一样

给 Agent 设计工具，核心目标是让模型选对、用好，而不是单纯实现功能。

- 命名：增加前缀区分系统，例如 github_pr_、sentry_error_

- 参数：使用明确字段，避免模糊 id

- 返回值：只返回支撑决策的信息，过滤冗余原始字段

- 规模：单一职责，边界清晰，默认精简输出

从 Claude Code 团队工具迭代中可以学到：不要靠标记文本格式、参数 flag 让模型主动暂停询问，稳定性很差。更好的做法是单独封装 AskUserQuestion 工具，模型需要确认信息时，必须显式调用该工具触发暂停，逻辑更加可靠。

同时也要懂得克制，不是所有场景都适合新增工具。本地 shell 可稳定执行、仅需要静态知识、更适合 Skill 约束，或是还没有验证稳定性的场景，都不建议新增 Tool。

Hooks：将确定性逻辑从模型手里收回

Hooks 是生命周期的拦截脚本，用来执行模型不可靠完成的强制校验，不要用来处理复杂语义推理业务。

适合场景：保护文件拦截、修改后自动 lint、会话启动注入环境信息、任务完成推送通知。

不适合：大量文本推理、长时间业务流程、复杂权衡决策。

简单示例配置：

json

{

"hooks": {

"PostToolUse": [

{

"matcher": "Edit",

"pattern": "*.rs",

"hooks": [

{

"type": "command",

"command": "cargo check 2>&1 | head -30",

"statusMessage": "Running cargo check..."

}

]

}

]

}

}

Hooks 可以在代码编辑完成后立刻执行编译检查，提前捕获错误。注意截断命令输出，避免 Hook 日志反过来污染上下文。

Hooks、Skills、CLAUDE.md 三者可以形成组合约束：CLAUDE.md 定义交付标准，Skill 规定操作步骤，Hook 在关键节点强制校验阻断。

Subagents：核心价值是隔离，不只是并行

Subagent 是独立 Claude 实例，拥有独立上下文窗口、可限制可用工具，执行完毕后返回摘要结果。像大规模代码扫描、测试执行这类会产生大量输出的任务，交给子代理处理，主线上下文不会被海量日志挤占。

Claude Code 内置三类子代理：Explore（只读代码检索，低成本模型）、Plan（方案调研）、通用代理，也支持自定义。

配置要点：

- 限制可用工具，最小权限原则

- 根据任务选择模型：探索使用低成本模型，代码审查使用高能力模型

- 设置最大轮次，防止无限执行

- 文件修改场景使用 worktree 隔离文件系统

Subagent 常见反模式

子代理权限和主会话完全一致、输出格式不固定、子任务之间强依赖共享状态。

Prompt 缓存：Claude Code 底层核心

整套 Claude Code 的架构，很大程度围绕 Prompt 缓存设计。高缓存命中率不仅降低成本，还能放宽速率限制。缓存是前缀匹配机制，固定内容放在前文，动态内容放在末尾。

推荐 Prompt 顺序：

1. System Prompt（静态，锁定）

2. Tool Definitions（静态，锁定）

3. Chat History（动态后置）

4. 当前用户输入（末尾）

破坏缓存的坑：系统提示内加入时间戳、随机打乱工具定义、会话中途增删 MCP 服务。动态信息不要修改系统 Prompt，放到用户消息中传入。

缓存按模型隔离，Opus 的缓存无法复用给 Haiku。需要切换模型时，优先使用 Subagent 做任务交接。

上下文压缩 Compaction

当上下文接近上限，系统会 fork 当前会话，把历史对话交给模型生成摘要，保留系统提示、工具定义，释放 token 空间。压缩使用缓存，成本很低。

Plan Mode 的实现细节很巧妙：没有切换工具集（会破坏缓存），而是做成模型可调用的工具，模型自主判断进入规划模式。

延迟加载 defer_loading 机制：大量 MCP 工具不会一次性传入完整 schema，先传入轻量占位描述，模型选中工具之后，再加载完整定义，保证缓存前缀稳定。

Verifier：没有验证闭环，就谈不上工程化 Agent

模型返回“任务完成”不代表交付合格，必须建立验证体系，保证结果可核验、可回滚、可审计。

- 底层：命令退出码、类型检查、单元测试、lint

- 中层：集成测试、合约测试、截图比对、冒烟测试

- 高层：生产日志、监控指标、人工检查清单

在 CLAUDE.md、Skill 中提前明确验收标准，定义 Done 的条件。

实用内置命令清单

plaintext

/context # 查看 token 消耗，定位 MCP、文件读取开销

/clear # 清空会话

/compact # 压缩会话，保留关键信息

/mcp # MCP 服务管理，查看工具数量与消耗

/hooks # Hooks 管理入口

/permissions # 权限白名单管理

/sandbox # 沙箱配置

/model # 切换模型

/rewind # 回退会话至检查点

/insight # 分析会话，提炼规则写入 CLAUDE.md

还有 claude --continue 恢复历史会话、 --worktree 创建隔离工作树等 CLI 参数，适合自动化、CI 场景。

怎么写一份合格的 CLAUDE.md

CLAUDE.md 是你和 Claude 的协作契约，不是项目百科。不要一次性写满，先用起来，重复遇到同类问题时，再补充规则。

✅ 适合写入：构建测试命令、目录模块边界、编码规范、环境坑、禁止操作列表、压缩保留规则

❌ 不适合写入：长篇背景、完整 API 文档、显而易见的信息、低频领域知识（放到 Skills）

模板示例：

markdown

# Project Contract

## Build And Test

- Install: `pnpm install`

- Dev: `pnpm dev`

- Test: `pnpm test`

- Typecheck: `pnpm typecheck`

- Lint: `pnpm lint`

## Architecture Boundaries

- HTTP handlers live in `src/http/handlers/`

- Domain logic lives in `src/domain/`

- Do not put persistence logic in handlers

- Shared types live in `src/contracts/`

## Coding Conventions

- Prefer pure functions in domain layer

- Do not introduce new global state without explicit justification

- Reuse existing error types from `src/errors/`

## Safety Rails

## NEVER

- Modify `.env`, lockfiles, or CI secrets without explicit approval

- Remove feature flags without searching all call sites

- Commit without running tests

## ALWAYS

- Show diff before committing

- Update CHANGELOG for user-facing changes

## Verification

- Backend changes: `make test` + `make lint`

- API changes: update contract tests under `tests/contracts/`

- UI changes: capture before/after screenshots

## Compact Instructions

Preserve:

1. Architecture decisions (NEVER summarize)

2. Modified files and key changes

3. Current verification status (pass/fail commands)

4. Open risks, TODOs, rollback notes

小技巧：每次纠正 Claude 的错误之后，可以让模型直接更新 CLAUDE.md，规避同类问题重复出现，定期手动清理过时规则。

落地经验总结

我在开发开源终端项目 Kaku（Rust+Lua，内置AI能力）的过程中，踩了大量混合语言项目下 Claude Code 的坑，沉淀了两点重要感悟。

环境透明优先：Claude Code 直接调用本地 shell、git、包管理器，一旦环境状态不透明，模型就会开始猜测，可靠性大幅下降。推荐增加 doctor 命令，在任务启动前输出完整环境健康报告。CLI 设计 init/reset 这类语义明确的子命令，收敛状态，再开放编辑能力。

Hooks 也可以按文件类型做差异化配置，不同语言绑定对应的语法、编译检查，编辑后立刻校验。

完整项目目录参考，按需裁剪：

plaintext

Project/

├── CLAUDE.md

├── .claude/

│ ├── rules/

│ ├── skills/

│ ├── agents/

│ └── settings.json

└── docs/

落地反模式汇总

反模式 现象 修复方案

CLAUDE.md 充当知识库 上下文被稀释，关键指令失效 仅保留契约，资料拆分到 Skill/rules

Skill 大杂烩 触发不稳定，工作流冲突 一个 Skill 只负责一类任务

工具过多、描述模糊 模型选错工具，挤占上下文 合并重叠工具，命名分层

缺少验证闭环 模型自认为完成，结果不可信 给任务绑定 Verifier 验收标准

无边界自治 多代理并行失控，难以止损 最小权限，限制 maxTurns

任务全部堆在主会话 有效上下文被日志污染 重型探索交给 Subagent，及时清理会话

我把这套配置检查逻辑封装成开源 Skill 项目 tw93/waza，可以一键扫描 Claude Code 配置问题，执行 /health 输出优化优先级报告。

claude plugin marketplace add tw93/waza

claude plugin install health@waza

结语

使用 Claude Code，一般会经历三个成长阶段：

1. 工具使用者：只会基础操作，有帮助但是提升有限

2. 流程优化者：开始编写 CLAUDE.md、Skills，效率明显提升

3. 系统设计者：懂得在约束下构建 Agent 自治系统，效率产生质变

有一句话值得反复思考：如果连你自己都无法清晰定义「任务完成的标准」，那这个任务就不适合直接交给 Agent 自主执行。验证标准本身，就是 Agent 工程落地的第一道门槛。

以上是我半年深度实践后的总结，里面还有很多值得深挖的细节，欢迎技术同行一起交流探讨。

如果你想要系统学习 AI Agent 工程落地、前沿部署相关知识，可以参考我长期维护的站点：

- FDE学习站：https://cs-wude-fde-learning.pages.dev/

- 产品项目站：https://cs-wude-product.pages.dev/