企业官网建设流程全解析

这段时间我把日常开发的重心一点一点从 IDE 的窗口挪到了命令行：跑通一版 feature、改耦合很重的老代码、翻几千行的调用链、给 CI 排错……Claude Code 的深度配置，核心目标不是把聊天界面美化，而是让你所在的开发小组真正拥有一支由 AI Agent 构成的"影子工程团队"。它不是简单的 AI 问答工具，而是一个能读仓库、写文件、执行命令、感知报错并自主迭代的 agent 系统。这篇文章不讲虚的，只聊我实际配下来的完整思路：从安装、目录结构、权限模型，到子代理分工、Skills、MCP 以及第三方模型接入，最后附一份高频问题排查清单。无论你是个人开发者想提高日常效率，还是团队负责人想统一一套 AI 工作流，都能在里面找到可以直接抄走的配置。

1. 为什么我把 Claude Code 当成团队里的一员来配置

1.1 它的本质：一个能"看见"代码库的 Agent

很多人第一次打开 Claude Code，会误以为它只是把对话框搬进了终端。这是最大的误解。普通聊天机器人只处理你贴进去的文本，而 Claude Code 的底座是一个可以感知整个工作目录的 agent：它能递归查看目录结构、读取指定文件、按条件搜索符号、定位引用关系，然后在拿到上下文后直接估算改动方案、执行修改并跑测试验证。

我用一个很直观的类比来解释：它更像你团队里那个"刚入职但学得飞快的新同事"，你要做的是给它交代背景、明确边界、提供工具，而不是替它把每一步都做完。也正因如此，它的价值高度依赖配置质量。默认状态下它像一张白纸；当你把仓库规范、命令习惯、架构约束写进配置，它才真正变成"懂你们项目的人"。

1.2 一个工程团队的雏形：主 Agent、子 Agent、MCP 工具、CI 里的无头客户端

我理解的"AI 工程团队"不是让一个 Agent 干所有活，而是多个角色协同：

• 主 Agent：负责理解你的整体指令，拆解任务，调度下面这些角色。
• 子代理（Subagents / Agents）：按职责隔离，比如架构评审、单元测试编写、文档维护、安全扫描。彼此上下文隔离，避免一个长会话把所有任务搅在一起。
• Skills：团队内部的标准化操作手册，比如"如何新增一个 API 接口""如何跑前端组件的视觉回归"。
• MCP 工具：把外部系统（数据库、Jira、监控平台、内部知识库）接进来，让 Agent 不只读代码，还能查数据、开单子、看日志。
• 无头客户端：在 CI 里用非交互模式跑定时任务、代码审查和变更日志生成。

这套组合跑起来之后，我这边最直观的感受是：例行琐事不再打断我的心流，因为可以派"团队"去干；真正需要设计决策的部分，才轮到我来做主。

1.3 适合谁和不适合谁

先泼一盆冷水。如果你是纯小白，或者只是偶尔用 AI 补几句注释，Claude Code 的配置成本对你来说可能偏高——它需要你理解环境变量、文件权限、命令执行边界，这些对完全不熟悉命令行的朋友并不友好。市面上图形化的 AI 编程插件可能更合适。

反过来，如果你已经习惯了 Git、终端和 Linux 服务器，或者你在一个有明确代码规范和发布流程的团队里，那么深度配置的回报非常明显：它能真正接入你的工程体系，而不是游离在项目之外。

2. 安装与环境准备：Ubuntu 和 VSCode 场景最容易踩的坑

2.1 先检查 Node 运行时

Claude Code 的官方渠道依赖 Node.js。它在底层用 Node 跑命令调度和文件监听，所以装机第一步不是急着下载，而是确认运行环境：

node -v npm -v

如果你的 Node 版本低于 18，建议先升级。Ubuntu 上最常见的坑是系统自带的 apt 源里 Node 版本太老，装完之后 claude 命令直接报语法错误或者缺依赖。我一般用 nvm 管理 Node 版本，这样后续升级和切换都很干净：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts nvm use --lts

这里多说一句：很多人在 Ubuntu 上卡住，不是因为 Claude Code 本身，而是因为系统里同时存在多个 Node 版本，全局安装的位置和 PATH 不一致，导致claude: command not found。装完 nvm 之后，确认which node指向的是 nvm 目录下的路径再继续。

2.2 npm 全局安装与官方脚本两种路线

环境就绪后，最简单的方式是 npm 全局安装：

npm install -g @anthropic-ai/claude-code claude --version

如果你不想在全局目录里留太多 npm 包，也可以走官方提供的一键安装脚本。脚本本质是下载并解压到用户目录，对没有 root 权限的服务器用户更友好。装完之后同样执行claude --version验证。

我建议至少把版本号看清楚。Claude Code 迭代非常快，不同版本的配置字段和 slash command 会有差异，后面你排查问题的时候，第一件事就是确认版本。你可以把版本信息写进项目的配置说明里，这样团队里任何人发现问题，能先对齐版本再讨论。

2.3 环境变量与 API 接入：别把 Key 写进 shell history

安装只是拿到了壳，真正的接入是 API 鉴权。官方默认连接 Anthropic API，你至少需要设置下面这个环境变量：

export ANTHROPIC_API_KEY="你的key"

但我不建议直接把 export 写进~/.bashrc再到处贴给别人看。更好的做法是：

• 单人开发：用 Claude Code 自带的登录流程，或者把 key 写进~/.claude/settings.json的env字段，利用配置文件权限隔离；
• 团队共享服务器：建议放 CI 的 secret 或者密钥管理服务里，让配置从环境注入，而不是入库。

关于ANTHROPIC_BASE_URL，后面接入第三方网关和本地模型时我会详细讲。这里先记住：只要你想改模型服务地址，就是改这个变量。

2.4 IDE 插件：VSCode 里装和命令行里用有什么不同

VSCode 装 Claude Code 插件，主要解决的是"看到上下文"的问题——它能把当前打开文件、选中代码、终端输出自动作为上下文带入，比手动复制粘贴省事得多。但要注意，插件本质是调用同一个后端 agent，不是另一个工具。

我的习惯是：复杂项目、涉及跨文件重构的时候，直接在 IDE 里用，因为可视化 diff 能看到改了什么；而简单任务、批量脚本、CI 巡检则用命令行非交互模式，链路更短更可控。JetBrains 系也有类似插件，如果你是 PyCharm 用户，装插件后配置逻辑完全一致，只是 UI 入口不同。这个细节值得记一下，因为网上搜"pycharm ai插件"会搜到一大堆别的工具，容易混淆。

3. 配置文件分几层？settings.json、CLAUDE.md 和 .claude 目录的分工

3.1 配置加载优先级

Claude Code 的配置不是一锅烩，而是按作用范围分层加载：

• 用户级：~/.claude/settings.json和~/.claude/CLAUDE.md，作用于当前账号所有项目；
• 项目级：.claude/settings.json和.claude/CLAUDE.md，随仓库走，团队成员共享；
• 本地覆盖：.claude/settings.local.json，不提交到 Git，只属于你本机；
• 命令级别：通过claude启动参数传入。

这套分层设计对我的意义是：通用偏好（比如默认模型、常用禁止执行的命令）放用户级；每个仓库的特殊约定（测试命令、目录结构、部署流程）放项目级；本地调试用的临时权限放 local 文件里，避免污染团队配置。

3.2 settings.json 的关键字段：权限模型、模型选择、hooks

以一个我常用的项目级配置为例：

{ "model": "claude-sonnet-4-5", "permissions": { "defaultMode": "plan", "allow": [ "Read", "Glob", "Grep", "Bash(npm run build)", "Bash(git status)" ], "deny": [ "Bash(rm -rf *)", "Write(.env)" ] }, "hooks": { "PreToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "node .claude/hooks/protect-env.js" } ] } ] } }

这里有几个值得展开的点：

• defaultMode: "plan"会让 Agent 先出方案、不直接改代码，适合做代码评审或者新人引导阶段；
• permissions.allow里列的是"我可以放心让它直接跑"的工具或命令，常见的Read/Glob/Grep这类无副作用的操作可以放开；
• permissions.deny用来硬性阻止危险动作，比如强制删除、修改密钥文件，宁可误伤，不可漏过；
• hooks是事件钩子，PreToolUse 指某个工具被调用前执行外部脚本，成功或失败可以决定是否放行该调用。

3.3 CLAUDE.md 是团队记忆，不是摆设

CLAUDE.md是大部分用户最容易低估的文件。它就像新员工入职手册：你能把项目的架构、命令、规范、历史决策都写进去，Agent 在进入项目时会优先读取并长期记忆这些内容。相比每次对话临时贴背景，把项目事实沉淀在这里，效果是质的提升。

我建议团队至少覆盖以下内容：

• 项目一句话定位和技术栈；
• 目录结构说明，尤其是"哪部分代码别乱动"；
• 常用命令：开发、测试、构建、lint、数据库迁移；
• 代码风格约定：命名、提交信息格式、分支规则；
• 已知的坑：比如某些模块必须在特定环境下编译，某些目录不要格式化。

初始版本不用追求面面俱到，让 Agent 在实际干活中暴露需求，再持续迭代 CLAUDE.md。这比一次性写几十页文档有用得多。

3.4 实战：一个后端仓库的 CLAUDE.md 骨架

我随手摘一个仓库的 CLAUDE.md 片段，你可以参考这个结构直接改：

# 项目：订单服务 ## 技术栈 - Python 3.11 / FastAPI / PostgreSQL - 所有接口必须经过 `apps/api` 目录下的路由注册 ## 常用命令 - 本地测试：`make test` - 启动开发服务：`uvicorn apps.main:app --reload` - 数据库迁移：`alembic upgrade head` ## 代码约定 - 新接口必须带 OpenAPI tags，并在 `docs/api.md` 中补一行说明 - 禁止直接修改 `migrations/versions` 下已发布的迁移文件 - 提交信息使用 `feat(scope): description` 格式 ## 注意事项 - `services/payment` 是老代码，不要在不通知负责人的情况下重构 - 本地环境变量读取 `.env.local`，不要提交 `.env`

写完之后你可以直接问 Claude Code："根据 CLAUDE.md，我现在要新增一个查询订单详情的接口，请给我完整改动计划。" 你会明显感觉到它给出的计划是贴合项目现实的，而不是泛泛而谈。

4. 用 Agents、Skills 和 MCP 搭一个最小可用"平行团队"

4.1 子代理（Subagents）：把不同职责拆开

单一会话一旦塞进太多任务，Agent 会开始"忘事"或者上下文混乱。子代理的作用就是把职责隔离。在.claude/agents/下，我用 Markdown 文件定义一个角色，比如reviewer.md：

--- name: reviewer description: 负责代码评审，检查变更是否符合项目规范、是否有明显缺陷。 tools: Read, Grep, Glob, Bash, WebSearch --- 你是团队里的资深代码评审人。拿到 diff 之后，按以下顺序检查： 1. 变更是否与任务描述一致； 2. 是否有未处理的边界条件； 3. 是否违反了 CLAUDE.md 中的代码约定； 4. 性能和安全上是否有明显风险。 最后输出：结论 + 问题列表 + 每条的严重级别（P0/P1/P2）。

Saved 之后，我在主对话里直接说"请调用 reviewer 评审我刚才的改动"，主 Agent 就会把它作为一个独立任务分发出去。因为上下文相对独立，评审逻辑不会和前面的编码任务搅在一起，输出质量会稳定很多。

团队规模扩大后，我一般会固定维护 3 到 4 个子代理：架构顾问、代码评审人、测试编写员、文档员。这些角色在团队里本来就存在，现在只是多了一份 AI 版本。

4.2 Skills：可安装、可共享的技能包

Skills 和子代理不同。子代理解决的是"谁来干"，Skills 解决的是"按什么流程干"——它是一套知识包，里面可以放操作手册、示例代码、模板文件。放在.claude/skills/下，每个技能一个目录，核心是SKILL.md。展示一个新增前端页面技能的标准结构：

.claude/skills/add-frontend-page/ ├── SKILL.md └── resources/ ├── page-template.tsx └── api-client-example.ts

SKILL.md 里描述这个技能的触发场景、执行步骤、引用哪些资源文件。当任务匹配时，主 Agent 会自动加载技能，按手册一步步执行。这和人类团队里的 SOP（标准操作流程）是一回事。

从安装角度来看，Claude Code 生态里已经出现了一些可下载的工具市场和 GitHub 工具库，可以用类似claude install-github-tool的命令拉取别人写好的技能包。但我建议先自己写两三个贴合自身项目的技能，彻底理解格式，再决定要不要用第三方的。

4.3 MCP：让 Agent 触达外部系统

MCP（Model Context Protocol）是让 Agent 和外部工具、数据源打通的协议。比如我想让 Agent 能查线上数据库只读副本，或者能往内部 Wiki 里补文档，就可以通过 MCP 把这些系统暴露给它。

配置方式在交互端有/mcp命令，也可以在.mcp.json或 settings 里维护。一个本地 stdio 传输的 MCP 服务大致是：

claude mcp add --transport stdio my-tool -- node /path/to/mcp-server.js

我更推荐把 MCP 配置写进项目级.mcp.json并提交到仓库，这样团队每个人拿到代码后，能自动同步一样的工具集。需要注意：MCP 服务的能力边界决定 Agent 的权力边界，给 Agent 接数据库之前，先在网关层把账号设成只读，这是铁律。

4.4 组合示例：评审、测试、补文档三个角色的配置

以一个最小可用的"平行团队"为例，我的分工是：

• 主 Agent：接收需求，编写功能代码；
• 评审子代理：检查代码质量和规范；
• 测试子代理：根据功能描述生成单测和边界用例；
• Skills：包含"接口文档更新模板"和"异常处理规范"两套 SOP；
• MCP：接入只读数据库和内部日志查询服务。

实际操作流程是：我向主 Agent 下达"实现某接口"指令 → 它写完代码后调用评审代理 → 评审通过后调用测试代理补测试 → 测试跑完，用文档 Skill 更新文档 → 最后把结果汇总给我。

这么一圈下来，大多数仅靠规则就能判断的活都被自动消化了，我只需要在最后看一眼 review 结论，并且处理真正需要人工决策的 P0 问题。

5. 权限与 Hook：如何让 AI 动手前先过脑子

5.1 从 plan 到全自动的权限梯度

Claude Code 的权限体系可以理解成一个梯度：

• 最严格：只让它读文件、给方案，所有写操作和命令都要你逐条确认；
• 中间档：允许一定范围内的自动操作，比如自动改代码、跑构建命令；
• 最宽松：bypassPermissions或全自动模式，Agent 可以连续执行一系列操作而不逐个弹窗。

我个人的落地经验是：交互式开发里长期使用"允许 Read/Glob/Grep，其余确认"这一档；只有当我对某类命令有十足把握时，才把它加进allow列表。比如在我维护的后端仓库里，npm run build是安全的、失败也不会有破坏性，所以我允许它自动执行；但数据库重置命令绝不放开。

如果你还在 Perplexity 里找"无限制无审核生成式 ai"，那我建议你清醒一点：真正好用的 agent 恰恰需要限制，限制越清晰，它在边界内就越自由。

5.2 Hook 的三个高价值用法：保护关键文件、强制规范、通知

用 Hook 做的事，比依赖"它自己自觉"可靠得多。这里分享三个我一直在用的场景：

第一个，保护关键文件。在 PreToolUse 阶段拦截 Write 事件，如果目标文件路径匹配.env、*.pem、migrations/下已发布的文件，就执行一个 Node 脚本，直接返回失败，阻止写入。这比我口头叮嘱"别改这个"有效太多。

第二个，强制提交信息规范。在 PostToolUse 或者用户提交前检查git commit -m参数是否匹配type(scope): subject格式，不匹配就给出示例并阻塞。这样团队里即使有人图省事，也绕不过规则。

第三个，执行结果通知。Agent 跑完长寿命令后，通过 Webhook 或者钉钉机器人把结果发到群里，适合夜间批处理任务。不需要人盯着终端，跑完看一眼手机就行。

Hook 的配置位置在 settings.json 的hooks字段。需要注意：Hook 脚本本身要写得足够健壮，不要因为脚本自己的异常把正常的 AI 流程卡死。我在脚本里都加了 try/catch，异常时默认放行并记录日志，避免 hook 变成新的"单点故障"。

5.3 无头模式在 CI 里的定时任务与审计

Claude Code 可以用非交互模式跑在服务器或 CI 里，例如：

claude -p "分析最近 50 个 commit，生成 changelog 草稿" --allowedTools "Read,Grep,Bash(git log)"

这个模式下，我会把--allowedTools收紧到最小集合，并在外部脚本里保存输入输出日志。安静模式配合输出重定向，非常适合做晚上的自动化代码巡检、依赖安全分析、变更摘要生成。

审计思路也很直接：让它在输出 JSON 时带上每条工具调用的时间、命令、文件路径，汇总成审计报告。这样即使出问题，也能回溯它到底做了什么修改、在哪一步可能引入回归。

6. 接 DeepSeek 还是继续用官方模型？第三方模型接入的可行路径

6.1 为什么要接第三方模型

很多团队会问：为什么放着官方模型不用，非要接 DeepSeek 或其他模型？原因一般有三个：

• 成本：官方高端模型在大量代码生成任务上很贵，团队想用便宜的模型跑一部分例行任务；
• 合规或隐私：部分企业要求代码不得传到海外 API，需要走内部模型或本地部署；
• 策略：团队想统一用一套中间层做模型路由和限流，不锁定单一厂商。

这里要明确一个技术前提：Claude Code 这个客户端是 Anthropic 官方工具，它默认说的是 Anthropic API 协议。而像 DeepSeek 这类模型通常提供的是 OpenAI 兼容协议，两者不能直接画等号。想接第三方，必须有一个能"翻译协议"的中间层。

6.2 通过兼容网关做转换：ANTHROPIC_BASE_URL 控制流

"claude code 接 deepseek"在社区里普遍的做法是：

• 找或自建一个网关服务（例如支持 Anthropic / OpenAI 协议互转的开源网关）；
• 在网关里配好 DeepSeek 模型的 endpoint 和 key；
• 在 Claude Code 环境里设置：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com" export ANTHROPIC_API_KEY="your-gateway-key"

只要网关返回的格式符合 Anthropic 兼容要求，Claude Code 就能正常工作。对终端用户来说，参数名不变，变的只是地址和请求转发目的地。

我实测下来的感受是：模型切换后，Claude Code 的 agent 编排能力和工具调用逻辑不会变，但 Code 生成风格、上下文遵循能力会有差异。越是复杂的多文件重构，越是考验模型本身，廉价模型可能在步骤一多之后就开始偏离计划。所以我的建议是：第三方模型适合日常小任务、注释、单测生成、文档编写；重大架构调整和复杂跨模块改动，还是切回更强的官方模型更稳。

6.3 本地部署模型的接入思路

热搜里也有"本地部署 ai""深度学习环境配置"这类词。如果你想把模型完全放在内网，思路和上面基本一致：先启动本地推理服务（例如用 vLLM 或 LM Studio 暴露一个 OpenAI 兼容端点），再在网关层转成 Anthropic 兼容格式，最后通过ANTHROPIC_BASE_URL指过去。

需要提醒的是，本地部署不仅仅是装一个推理框架的问题。显存、量化精度、并发量、上下文长度都会直接影响 agent 效果。尤其是 Claude Code 这类工具会在一次任务里携带大量代码上下文，如果本地模型上下文窗口小于 32K，很多任务会"塞不下"或者中途丢失信息。我见过一个团队在 24G 显存的机器上跑 7B 量化模型做 agent，结果是简单的文件修改还行，一旦涉及跨目录重构，模型就开始前后矛盾。

所以对本地部署，我建议你先想清楚：这个模型要承担什么级别的任务？如果只是做敏感代码库的本地审查，那小型量化模型可接受；如果要做复杂工程任务，先算清楚硬件预算再决定。

7. 高频问题排查清单与最终建议

7.1 会话越长越笨怎么处理：/compact 与任务拆分

Claude Code 在长会话里会出现"前面记得的后面忘干净"的情况，这本质是上下文窗口压力。遇到这种情况不要硬聊，直接用/compact压缩历史，或者更简单——把任务拆小。

我在实践中定了一条规则：单个会话目标必须聚焦。如果一件事横跨了 6 个文件以上还需要来回确认，我就把它拆成"先做方案"和"再改代码"两次会话。方案会话只产出计划和文件清单；代码会话拿着计划去执行。这样既减少上下文占用，又方便中途 review。

7.2 权限弹窗频繁 / 误改文件

弹窗频繁的本质是权限默认值太严，或者允许列表太窄。解决办法不是直接跳过确认，而是分类放权：凡是只读操作直接放行；凡是无副作用的构建、测试命令按需放行；凡是写操作或高危命令保留确认。

误改文件则反着来，多半是 allow 列表给得过宽。我建议在项目里放一个"高危文件清单"脚本，用 PreToolUse Hook 强制拦截。前面写过，不再赘述。

7.3 安装、鉴权与版本相关的问题

• claude: command not found：先看 Node 是否在 PATH 中，重新打开终端或执行hash -r；
• 403 / 鉴权失败：检查ANTHROPIC_API_KEY是否过期，网关模式下检查网关日志；
• 不同电脑上行为不一致：优先对比claude --version和 settings.json 是否一致，我遇到过多次"别人配了某个字段但我这版不认"的尴尬；
• 中文路径 / 特殊字符：尽量把项目放在没有中文和空格的目录下，Windows 或网络挂载盘尤其如此，某些文件监听逻辑在特殊路径下会出问题。

7.4 我的落地建议

最后聊聊我自己的体会。Claude Code 深度配置最大的收益点，不是某一个魔法参数，而是把团队的工程规则从一个"人说了算"的东西，变成一个"AI 也能遵守"的东西。当你把 CLAUDE.md、权限、Hook、子代理、Skills 都逐步搭好后，你会发现它开始真正像一个成员：知道边界，不问你重复问题，按规范干活，还能把结果汇报得清清楚楚。

我个人的做法是：每两周抽半天时间，把最近实际踩过的坑和问题沉淀进配置。比如哪个命令容易误用，就在 deny 里加一条；哪个流程反复被问，就把它写成一个 Skill。配置文件和代码库一样需要持续维护，它才是这支"AI 工程团队"真正的企业文档。