企业官网建设流程全解析

从第一次在终端里敲下claude，到它自己读代码、改文件、跑测试、提 PR，整个过程我只给了几句需求描述——这种体验确实会让人上瘾。但大多数人的痛点不在于“不会问问题”，而在于配置没做到位：装好了却不知道如何把 Claude Code 变成真正能干的“团队”，而不是一个只会写注释的聊天窗口。

这篇文章我把自己的实战配置过程完整拆出来，覆盖从环境安装、CLAUDE.md 规范、子代理（Subagents）、Skills 技能包到 MCP 外部工具接入的全部关键环节，目标是帮你把一个单点工具，配置成由“架构师 + 后端 + 前端 + 测试”组成的 AI 工程小队。适合刚接触 Claude Code 的初学者，也适合已经跑通基础功能、想深入做团队化配置的开发者参考。

1. 为什么说 Claude Code 能构建“AI 工程团队”

1.1 从“对话助手”到“项目协作者”

很多人一开始理解 Claude Code，会把它等同于一个“写在终端里的 ChatGPT”。这不算错，但远远不够。ChatGPT 这类对话助手擅长的是“你说一句，我答一段”，而 Claude Code 是一个能真正读写本地文件系统、执行 bash 命令、调用外部工具链的 AI Agent。差别就像“一个只会指手画脚的顾问”和“一个真的会动手改方案的同事”。

举个例子。你让它“把登录接口的超时时间改为可配置，并在配置中心加一个默认值”。一个合格的 Claude Code 配置环境下，它会自己去 grep 代码里写死的超时参数，读取相关模块，定位配置中心的加载逻辑，改完代码后跑一次测试甚至主动修复失败用例。整个过程你只需要在少数关键节点确认一下。这种“主动规划 - 动手执行 - 自查修复”的闭环，才是它被称为 agent 而不是 chat 的根本原因。

但请注意，默认安装的 Claude Code 只是“一个能干的开发者”。如果你想让它像一支团队那样分工协作——有人负责技术方案，有人专注写业务代码，有人盯质量做评审，那就必须靠配置来实现。这也是本文标题里“构建 AI 工程团队”的真正含义：不是把一个 Claude Code 变成多个进程，而是通过配置机制，让它内部具备多种角色分工。

1.2 配置机制如何“造出团队感”

Claude Code 的团队化能力来自四个核心机制，这四个机制你必须先建立整体认知：

• CLAUDE.md：相当于团队的“公司章程”。你可以把项目技术栈、代码规范、架构约束、常用命令全部写进去，每次 Claude Code 工作时都会默认读取这些规则。
• 子代理（Subagents）：在.claude/agents目录下定义固定角色，比如backend-dev、frontend-dev、code-reviewer。每个角色有自己的系统提示词、可用工具列表、甚至不同的底层模型。用@角色名就能在对话中调用它，就像在群里 @ 一个同事。
• Skills 技能包：把某个领域的高频操作打包成标准化技能，比如“数据库迁移”“单元测试生成”。Claude Code 会在合适的场景自动启用对应技能，不用你每次重复描述流程。
• MCP 服务器：通过 MCP（Model Context Protocol）接入外部工具，比如 GitHub、文件系统、数据库、浏览器自动化。这个机制决定了 AI 团队能不能触达项目外围的真实环境。

这四层配置叠加起来，效果非常接近于一个真人团队的运行方式：规范统一（CLAUDE.md）、角色明确（Subagents）、流程标准化（Skills）、工具链齐备（MCP）。下文我会逐一展开，并给出可以直接复制的配置内容。

1.3 为什么是“配置”而非“对话调教”

有一个很实际的问题：你完全可以在对话里告诉 Claude Code“你是架构师，要注重方案设计”，它确实也会照做。但对话是短时记忆，关掉会话就没了；就算不关，长时间对话里它也容易“角色混淆”。配置文件的价值在于持久和稳定——只要文件在，每个新会话启动时它都知道自己是谁、该按什么规则干活。

再深一层，配置文件还可以纳入版本管理。团队里任何成员拉下仓库，就自动获得一套统一的 AI 协作规范，不需要每个人重复去“调教”AI。这和把代码规范写进.eslintrc、把构建流程写进package.json是一个道理：一切可配置的，都应该配置化，而不是依赖口头沟通。

2. 环境准备与基础安装

2.1 安装前必须确认的三件事

很多安装失败其实不是 Claude Code 本身的问题，而是基础环境没达标。我的建议是装之前先把这三项检查一遍：

• Node.js 版本：推荐 18 或更高，我自己用的是 Node 20 LTS，实测运行非常稳定。如果你的 Node 还是 14.x、16.x，大概率会碰到兼容性问题，请先升级。
• Git：Claude Code 很多场景依赖 Git 仓库上下文（比如git diff、git log来理解改动），系统里必须已经安装并配置好 Git。
• 网络环境：安装和登录阶段需要能正常访问 npm registry 和 Anthropic 的服务。国内网络环境下下载超时比较常见，建议给 npm 配置国内镜像源，能省下不少折腾时间。

提示：如果你正在用 nvm 管理 Node 版本，安装 Claude Code 非常简单。如果没用 nvm，某些 Linux 发行版直接npm install -g时会因为全局目录权限报 EACCES 错误，后面我会专门说这个问题。

2.2 安装步骤：macOS / Linux / Windows(WSL)

macOS 和 Linux 上，一条命令就能完成全局安装：

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

装完后先别急着跑，确认一下版本号，保证安装成功：

claude --version

Windows 用户请注意：官方支持的是 WSL（Windows Subsystem for Linux）环境，不建议直接在 PowerShell / CMD 里裸跑。原因也很实际：Claude Code 要频繁执行 bash 命令和文件操作，WSL 里的 Linux 环境兼容性远好过 Windows 原生命令行。如果你还没装 WSL，建议先完成 WSL 安装，然后在 WSL 的 Ubuntu 终端里执行上面的 npm 命令。

Ubuntu 下安装后偶尔会遇到command not found，多半是 npm 全局 bin 目录不在 PATH 里。用npm prefix -g查一下全局目录，再把它的 bin 子目录加入 PATH 即可。如果已经用了 nvm，这个问题一般不会出现，nvm 会自动处理好。

2.3 登录验证与订阅说明

安装完成后在终端输入claude，首次启动会引导你进行账号登录。流程是：终端里显示一个一次性验证码，然后用浏览器打开官方登录页，完成授权后回到终端即可开始使用。

账号类型会影响你能使用的模型和配额，这里说下我自己的判断：

• Pro / Max 订阅用户：适合个人日常使用，直接在网页订阅里带着 Claude Code 权限，开箱即用。
• API 按量付费用户：适合重度使用或团队共享，按 token 量计费，灵活但成本需要关注。
• 如果你是通过 API Key 方式接入，需要提前设置ANTHROPIC_API_KEY环境变量，否则 CLI 会始终跳登录页。

登录验证成功后，可以观察一下~/.claude目录是否已生成。这个目录后续存放全局配置文件、授权记录、子代理定义等，是配置工作的主战场。

2.4 自动更新策略与版本管理

Claude Code 的更新节奏相当快，官方默认每 24 小时检查一次新版本，有更新会提示你重启生效。我用下来的体会是：不要长期停留在旧版本。很多新功能（比如新的子代理语法、Skills 市场）只在最新版可用，遇到“文档上明明有这个功能但我这里没有”的情况，十有八九是版本太老。

想手动更新也很简单：

npm update -g @anthropic-ai/claude-code

如果你在团队中使用，我反而建议关注版本的一致性。因为 CLAUDE.md、子代理配置在不同版本下解析逻辑可能略有差异，团队统一版本能减少“我这能跑你那不能跑”的尴尬。

3. 核心配置解析：从单兵到团队的钥匙

3.1 CLAUDE.md：团队的“公司章程”

CLAUDE.md 是 Claude Code 的指令核心。它分为两个层级：全局文件（~/.claude/CLAUDE.md）适用于所有项目，项目文件（项目根目录CLAUDE.md）只对当前项目生效。两个文件会一起被加载，项目文件的优先级更高。

这个文件该写什么？我的建议是，不要写“你要做一个负责任的工程师”这种空话，而是写可执行的规则。下面这份是模板，你可以直接照着改：

# 项目规范 ## 技术栈 - 后端：Python 3.11 + FastAPI + PostgreSQL - 前端：React 18 + TypeScript + Vite - 测试：pytest（后端）/ Vitest（前端） ## 架构约束 - 数据库访问必须走 repository 层，禁止在业务逻辑中直接写 SQL - 新增接口必须附带 OpenAPI 文档注释 - 所有外部 API 调用必须设置超时与重试 ## 常用命令 - 启动后端：uvicorn app.main:app --reload - 运行测试：pytest -x -q - 代码检查：ruff check . ## 工作规范 - 完成代码修改后必须运行相关测试 - 提交信息格式：<type>(<scope>): <subject> - 涉及数据库变更时，同时输出迁移脚本

注意看这份模板的重点：它给 AI 提供了判断依据。比如遇到“该不该写迁移脚本”的问题时，如果没有规范约定，Claude Code 很容易偷懒；但规范里写清楚“数据库变更必须带迁移脚本”，它就会照做。

实操心得：CLAUDE.md 不是越长越好。太长的规范反而会分散模型注意力。我建议控制在 100 行以内，只保留影响代码质量的硬性约束。写完后可以做一次“提问测试”：让它描述项目架构，看看它是否准确提取了规范里的关键技术栈与约束。

3.2 权限模型：让 AI 动手但别乱动手

默认情况下，Claude Code 每次执行 bash 命令或修改文件前都会向你请求确认。这在学习阶段很安全，但真到干活的时候你会被授权弹窗烦死。合理方案是配置权限许可（Permissions），让高频安全操作自动通过。

配置文件在~/.claude/settings.json（全局）或项目根目录.claude/settings.json（项目级）。我常用的配置长这样：

{ "permissions": { "allow": [ "Bash(npm run lint)", "Bash(npm test)", "Read(**)", "Edit(**)", "WebFetch(domain:developer.mozilla.org)", "WebFetch(domain:stackoverflow.com)" ], "deny": [ "Bash(git push *)", "Bash(rm -rf *)", "Bash(sudo *)" ], "ask": [ "Bash(*)" ] } }

这里有个关键设计：权限规则遵循deny > ask > allow的优先级。也就是说即使Bash(*)被 allow，只要Bash(git push *)在 deny 列表里，push 操作依然会强制拦截并征求你的意见。

我个人的安全策略是：读文件、改代码、跑测试这类高频且影响可控的操作直接 allow；删除、push、sudo 这类破坏面大的操作必须 deny 或 ask。把“小操作放手让 AI 干，大操作紧盯不放”作为权限配平的基本原则。

3.3 子代理：定义角色，让 AI 各司其职

子代理是构建“AI 工程团队”的核心。目录约定为.claude/agents（项目级）或~/.claude/agents（全局），每个 agent 是一个 Markdown 文件，文件名即角色名，扩展名建议.md（部分版本用.agnt，但当前稳定版以 Markdown 为主）。

一个角色文件的核心结构如下：

--- name: backend-dev description: 负责后端接口开发与数据库设计。当任务涉及 Python 代码、API 接口、数据模型时使用该角色。 tools: Read, Edit, Bash, Grep, Glob model: sonnet --- 你是一名资深后端工程师。你的职责包括： - 设计并实现 Python / FastAPI 接口 - 维护数据库模型与迁移脚本 - 对所有改动编写 pytest 测试 工作约束： - 所有数据库查询必须经过 repository 层 - 接口必须包含输入校验与错误处理 - 改动完成后先运行相关测试再交付

这里最容易被忽略的是description字段。Claude Code 是依据 description 来决定“什么时候该调用这个子代理”的。description 写得越具体，触发匹配越准。如果把backend-dev的 description 写成“负责后端开发”，它几乎什么后端任务都会匹配；而写成“当任务涉及 Python 代码、API 接口、数据模型时使用”，则能更精准地和其他角色做区分。

model字段值得单独说一下。Claude Code 主 agent 默认用的是opus系列模型（如果你账号支持），但子代理可以独立指定sonnet或haiku。这样做的好处是在不太复杂但量大的任务上（比如前端页面实现、批量写测试）用更便宜更快的模型，控制整体成本；在架构设计、复杂调试这类高难度任务上才上大模型。

子代理使用方式是在对话中 @ 角色名，比如：

@backend-dev 把用户模块的查询改成分页实现，并补上测试。

主 agent 会自动把任务转交给backend-dev，子代理执行完后再把结果交回主 agent 汇总。这个“主 agent 调度、子代理执行”的模式非常接近真实团队里的技术负责人分活逻辑。

3.4 Skills：沉淀标准流程，减少重复描述

Skills 是 Claude Code 近期更新的重要能力，所有高频、可复用的操作流程都可以封装成技能包。安装方式有两种：一种是从 Skills 市场直接装，另一种是手动创建.claude/skills目录，按固定结构组织文件。

一个标准技能包的文件结构如下：

skills/ create-migration/ SKILL.md scripts/ generate_migration.py

SKILL.md是技能说明文件，内部要写清楚技能适用场景和操作步骤：

--- name: create-migration description: 在数据库结构变更时生成 Alembic 迁移脚本。适用于模型字段新增、修改、删除的场景。 --- 当检测到数据模型变更时，按以下步骤操作： 1. 确认变更前后的模型定义差异 2. 运行 `alembic revision --autogenerate -m "描述变更内容"` 3. 检查生成的迁移文件，确保 upgrade 和 downgrade 逻辑正确 4. 运行 `alembic upgrade head` 验证迁移可执行

Skills 的触发机制和子代理类似，也是靠description做的意图匹配。模型改动场景出现时，Claude Code 会自动判断是否启用create-migration技能。如果定义了某个技能却始终不触发，优先检查 description 是否覆盖了真实触发场景的关键词。

实操心得：不要把 Skills 做得太琐碎。我见过有人把“写一个 if 语句”也做成技能，这纯属过度设计。值得技能化的是有完整流程、且你会重复执行的操作，比如“生成迁移脚本”“初始化测试环境”“发布前检查清单”。一句话能说清的事，直接写在 CLAUDE.md 里就够了。

3.5 MCP：接入外部工具链

MCP（Model Context Protocol）是 Claude Code 连接外部世界的高速通道。通过 MCP，它可以直接操作 GitHub、读取数据库、控制浏览器、调用文件系统，而不再局限于项目目录内的文件。

MCP 服务配置在.mcp.json（项目级）：

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "你的token" } }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"] }, "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } }

配好 MCP 后，Claude Code 就能执行“帮我建一个 GitHub issue，把用户反馈的问题整理进去”“把 home 页截图发给我”这类跨领域操作。在需要团队协作的场景里，GitHub MCP 配合子代理尤其好用——测试工程师角色的子代理发现问题后，可以直接通过 MCP 创建 issue，完成从“发现问题”到“录入流程”的闭环。

MCP 配置是典型“看起来复杂，用起来真香”的东西，我第一次配 Playwright MCP 也就是确认node版本没问题、然后启动命令能跑起来，后续使用完全不需要关心底层实现。

3.6 环境变量：微调模型与行为的关键开关

除了配置文件，环境变量也是重要的配置入口。常用变量有这么几个：

• ANTHROPIC_MODEL：指定默认模型，例如claude-opus-4-1，适合有特定模型偏好时使用。
• ANTHROPIC_SONNET：当子代理未指定 model 字段时，默认使用的 sonnet 模型名。
• CLAUDE_CODE_MAX_OUTPUT_TOKENS：控制单次回复最大 token 数。处理大文件或长文档时，可以适当调高，默认值偏保守。
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：设为1可以关闭非必要的遥测请求，对隐私敏感场景有帮助。

设置方式就是在 shell 里 export，或写进.bashrc/.zshrc，比如：

export ANTHROPIC_MODEL=claude-opus-4-1 export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

我自己一般不会手动设置 ANTHROPIC_MODEL，除非遇到某次任务反复需要特定模型性能才临时指定。固定死模型反而会错过版本迭代带来的能力提升。

4. 实战：把 Claude Code 配置成“三人 AI 工程团队”

4.1 团队架构设计

配置之前先想清楚“团队里有谁”。实战里我常用的是三人架构：

• tech-lead（技术负责人）：负责需求分析、技术方案设计、代码评审，是整个团队的入口角色。
• backend-dev（后端工程师）：专注 Python / FastAPI 后端实现与数据库开发。
• frontend-dev（前端工程师）：专注 React / TypeScript 页面实现与 UI 交互。

这里我推荐从两个角色起步，最多不要超过四个。角色多了以后，主 agent 的调度负担也变重，还需要花大量时间去描述角色边界。两个到三个边界清晰的角色，比十个边界模糊的角色更高效。

4.2 团队配置文件实战

先建项目根目录的CLAUDE.md，定义团队工作规则：

# AI 工程团队工作规范 ## 团队协作流程 - 接到需求后，先由 tech-lead 输出技术方案 - 技术方案确认后，backend-dev 和 frontend-dev 并行实现 - 代码完成后，必须由 tech-lead 做一次代码评审 ## 角色调用约定 - 需求分析与方案设计：@tech-lead - 后端接口与数据库相关：@backend-dev - 前端页面与交互相关：@frontend-dev - 代码评审与优化建议：@tech-lead ## 质量底线 - 后端接口改动必须附 pytest 测试 - 前端页面必须通过 TypeScript 类型检查 - 任何改动不允许破坏现有测试用例

然后在.claude/agents/下创建三个角色文件。

tech-lead.md：

--- name: tech-lead description: 负责技术方案设计、需求拆解与代码评审。当用户需要整体设计方案、评估技术选型、审查代码质量时使用该角色。 tools: Read, Grep, Glob, Bash model: opus --- 你是一名资深技术负责人。职责包括： - 将模糊需求拆解为明确的技术方案 - 评估技术选型的合理性与风险 - 对代码做质量评审，发现问题并提出改进建议 工作约束： - 技术方案必须包含改动范围、涉及模块、风险点 - 代码评审必须指出具体行号位置的问题 - 给出的建议必须结合项目实际约束，不能空谈最佳实践

backend-dev.md和frontend-dev.md按第 3.3 小节的模板扩展即可，注意分别补充各自技术栈的硬性约束。配置完成后建议跑一个简单的“团队协作测试”：

claude

然后输入：

@tech-lead 我给用户模块加一个积分功能，先出一份技术方案。方案确认后让 backend-dev 实现。

观察 Claude Code 是否依次调用 tech-lead 和 backend-dev，这是验证子代理配置是否生效最直接的方式。

4.3 用 hook 做团队“红线”

子代理管住了“角色分工”，但你还需要一套机制来卡住“流程红线”。Claude Code 提供 hook 机制，可以在特定事件前后插入自定义脚本。最常见的用法是PreToolUse钩子：当 AI 要执行某个工具时，先运行脚本检查是否合规。

比如我想确保“任何 git commit 之前必须通过测试”，可以在.claude/settings.json里加：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm test && npx tsc --noEmit" } ] } ] } }

这样 AI 每次尝试执行git commit时，都会先跑一遍全量测试和类型检查，失败的提交会被直接拦下。效果相当于给 AI 团队装了一个“CI 门禁”，而且是本地即时生效的那种。

4.4 用 -p 模式实现自动化调用

团队配置好之后，Claude Code 完全可以跑在非交互模式（-p）下，这对自动化流程特别有价值。比如写一个脚本，每晚自动让 tech-lead 审查当天的改动：

claude -p "请以 tech-lead 身份，基于 git diff 对今天的代码改动做一次完整审查，输出问题清单和修改建议" --output-format text

-p模式不需要进入交互终端，输出可以直接重定向到文件，也可以接到 CI 或聊天机器人里。我经常用它做代码审查自动化、生成提交说明、批量处理文档等场景，效果非常稳定。

5. 常见问题与排查技巧实录

5.1 安装与启动问题速查

5.2 使用中的高频坑

子代理不生效是配置中最常见的问题。排查顺序是：确认文件名和name字段一致；确认description是否覆盖了你所提任务的语义；确认对话中用了@角色名语法。还有一个容易被忽略的点——子代理文件的路径必须在当前上下文识别的范围内，全局~/.claude/agents和项目.claude/agents都会被识别，但只有项目内的agents会随仓库共享。

授权弹窗过于频繁的解决方法是在 settings.json 里补充 allow 规则。但注意不要图省事直接丢一个"Bash(*)"进去。安全性和效率的平衡点是：允许读写文件，允许跑测试和 lint，永远不要放行 rm -rf、sudo、push 等高危操作。

上下文过长导致回答混乱是长任务的普遍痛点。Claude Code 处理特大型代码库时，上下文窗口被塞满会导致遗忘早期约定。遇到这种情况，可以用/clear清空会话后通过--continue或/resume恢复关键上下文。我习惯在长时间任务里把它拆成多轮小会话，而不是一个会话硬扛到底。

MCP 服务启动失败多数是 npx 拉包太慢或网络抖动导致的。可以先手动执行对应的 npx 命令验证是否能正常启动，确认没问题后再放到.mcp.json里。如果某个 MCP 服务完全用不上，别让它留在配置里——每个 MCP 都是常驻进程资源，也会增加 Claude Code 的处理负担。

5.3 我对团队化配置的几条经验

配置工作不是一次性的，而是随着项目演进而持续调整的。我自己每隔一段时间就会根据实际使用情况做一轮“精简”：把几乎用不到的 Skills 删掉，把边界模糊的 agent 合并，把 CLAUDE.md 里不再适用的旧规范清掉。配置越贴近真实工作流，AI 团队的产出就越稳定。

如果你刚开始搭建，我的建议是：先只配置一个CLAUDE.md和两个子代理，跑手头最常做的一类需求，跑顺了再加 MCP 和 Skills。别一开始就追求“全家桶”，那只会让你的排障成本直线上升。

最后再说一个真实感受：Claude Code 配置完成后，个人开发效率的提升不只是“写代码快了一点”，而是工作方式的改变——需求拆解有 tech-lead 帮你理清边界，实现有 backend-dev 和 frontend-dev 分头干活，质量有代码评审卡住底线。它带来的不是一个更好的“编辑器”，而是一个随时在线、愿意从命令行听你指挥的“同事”。这套配置思路不是终点，等你在实际项目中跑通一轮，自然会发现哪些角色需要加强、哪些工具值得接入，到那时候你的 AI 工程团队才算真正长成了你自己的形状。