企业官网建设流程全解析

如果你已经厌倦了每次让 AI 干活都得把项目背景从头讲一遍，同时又希望它不只是“能改代码”，而是能主动拆需求、写方案、做审查、跑测试，那这篇指南就是写给你的。

我花了相当长一段时间把 Claude Code 从“终端里的高级聊天框”调教成了一套真正能出活的 AI 工程团队。核心思路其实很简单：把记忆、角色、技能、权限这四类配置拆开，让 Claude Code 在不同场景下调用不同身份、遵循不同规范去工作。同样是执行“帮我实现登录功能”这句话，配置前它只会给你一段可运行的半成品代码；配置后，它会先设计接口、再写实现、补测试，最后还会自己审查一遍 diff。这两者之间的差距，不是模型能力的差距，而是配置体系和工作流设计的差距。

这篇指南既适合刚从零开始接触 Claude Code 的新手，也适合那些用了几个月、总觉得 AI 不够“懂你”的开发者。我会把环境安装、CLAUDE.md 记忆体系、Subagents 角色拆分、Skills 技能包、MCP 扩展，以及一整套可复制的工程协作流程全部拆开讲，每一步都给出能直接抄作业的配置。

1. 先理解配置的目标：你是在搭团队，不是在装工具

很多教程把 Claude Code 当成一个“更聪明的 Copilot”来介绍，装上就跑，跑起来就聊。这么用当然也能干活，但你会发现它表现非常不稳定：今天让它写接口，它给你写个能跑的；明天换个项目再问，它又从零开始瞎猜。原因很简单，你没有给它建立任何项目上下文和角色边界。

我更喜欢把配置 Claude Code 理解成“搭建一支虚拟工程团队”。你给团队新成员的第一天，会做什么？介绍项目背景、告诉他技术栈和代码规范、明确他的岗位职责、给他必要的工具权限。Claude Code 的配置体系恰好一一对应：CLAUDE.md 就是项目背景介绍，Subagents 就是岗位职责说明书，Skills 就是团队共享的操作手册，settings.json 就是行政权限规定。

1.1 从“聊天框”到“工程成员”的转变

Claude Code 本质上是一个运行在终端里的 agentic AI 编程工具，它能读文件、运行命令、基于任务自主规划下一步动作。它不像聊天机器人那样只做一次回答，而是会反复“思考-执行-观察结果-再思考”，直到完成你交代的任务。

这个能力意味着，它完全可以在一个相对复杂的工程里独立承担某个环节的完整工作。但这有个前提：它必须知道项目的约束条件、代码风格、常见坑位，以及自己该在什么边界内行动。而这些信息，默认状态下它一概不知。这就是为什么说，安装只是起点，配置才是让 Claude Code 从“工具”变成“团队成员”的关键一步。

1.2 AI 工程团队的五个常规角色

我通常会在配置里建立五个虚拟角色，对应真实工程团队中的岗位：

这五个角色共享同一个底盘（Claude Code 的模型能力），但通过不同的 prompt、工具权限和输出规范，它们的“行为习惯”会明显分化。架构师倾向于先出方案再动手，审查员总是用挑刺的角度看代码，测试工程师则会自觉补上各种异常分支。配置到位之后，你更像是这些人的技术负责人，而不是他们的替代品。

1.3 配置体系的总体地图

为了让后续的实操部分不迷路，我先给出一张配置地图。Claude Code 的配置体系大致分为三层：环境层、记忆层、能力层。

• 环境层：Node.js、Git、Claude Code 本体及认证方式。
• 记忆层：CLAUDE.md 文件，包括用户级、项目级，甚至还有子目录级，用于告诉 AI“你是谁、项目长什么样、该按什么规范干活”。
• 能力层：Subagents（角色拆分）、Skills（技能包）、MCP（外部工具连接器），决定 AI 能调用什么工具、以什么身份执行任务。
• 权限层：settings.json 中的权限配置，决定哪些操作可以自动执行、哪些必须人工确认。

后面每一章，我都会按这个地图逐层展开。

2. 环境准备：Node.js、Git 与 Claude Code 的安装链路

这一章照顾的是完全从零开始的新手。如果你是老手，可以直接跳到第三节，但有几个坑我建议你扫一眼，都是我实际踩过的。

2.1 Node.js 版本管理与安装

Claude Code 官方推荐通过 npm 安装，所以 Node.js 是第一个前置依赖。我强烈建议你用 nvm（Node Version Manager）来管理 Node.js 版本，而不是直接去官网下载安装包。原因很简单：Claude Code 以及其他 AI 工程工具对 Node 版本有明确要求，项目本身可能也需要多套 Node 环境切换，nvm 能让你在不同版本之间自由切换，避免“这个工具要 Node 18，那个项目要 Node 20”的尴尬。

安装 nvm（Linux / macOS 环境）时，官方方式是执行 curl 脚本，然后把它写入 shell 配置。Windows 用户则安装 nvm-windows，注意安装路径不要带空格，否则后面很容易出问题。

nvm 装好后，建议安装并切换到 Node 20 或更高版本：

nvm install 20 nvm use 20 node -v npm -v

检查版本号能正常输出，说明 Node 环境已经就绪。这里有个常见的坑：如果你用的是 VSCode 的集成终端，nvm 安装完如果没有重启终端，nvm命令会提示找不到。别急着重装，先重启一下终端或重新加载配置文件。

2.2 Git 的安装、配置与 SSH 认证

Claude Code 在工程场景下需要频繁读取 git 状态、生成 diff、提交代码，所以 Git 是第二个硬依赖。macOS 上执行git --version如果提示不存在，会弹出提示让你安装 Command Line Tools；Ubuntu 上则执行apt install git；Windows 直接安装 Git for Windows 即可。

装完之后不要跳过配置这步，否则后面所有 git 提交都会失败，Claude Code 也会因为拿不到 git 信息而卡在很多操作上：

git config --global user.name "你的名字" git config --global user.email "你的邮箱" git config --global init.defaultBranch main

如果你需要操作远程仓库，建议顺便配置 SSH key。生成方法没啥特殊的：ssh-keygen -t ed25519 -C "你的邮箱"，然后把~/.ssh/id_ed25519.pub的内容添加到 GitHub / GitLab 的 SSH keys 里。配好之后，Claude Code 拉代码、推分支都会顺畅很多，避免每次都要输入账号密码。

2.3 Claude Code 的安装、升级与认证

Node 和 Git 就绪后，安装 Claude Code 本体就是一条命令的事：

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

全局安装完成后，执行claude --version能输出版本号，说明安装成功。如果提示claude: command not found，大概率是 npm 全局 bin 目录没有写进 PATH。可以用npm config get prefix查看全局安装路径，然后把对应的 bin 目录加到~/.bashrc或~/.zshrc里。

认证方面，直接在终端执行claude进入交互界面，它会引导你完成登录授权。如果你的使用场景是自动化脚本或团队共享环境，也可以把 Anthropic API Key 设置为环境变量ANTHROPIC_API_KEY，这样跳过交互式登录。

Claude Code 的迭代速度很快，官方几乎每周都有版本更新。升级命令是npm install -g @anthropic-ai/claude-code@latest。我建议把它纳入你的月度维护清单，因为新版通常会修复上下文处理、工具调用相关的 bug，而这些直接影响团队配置的稳定性。

2.4 首启自检清单

环境装完之后，不要急着写业务代码，先跑一遍自检：

1. node -v输出版本号；
2. git status能在项目目录正常执行；
3. claude --version输出版本号；
4. 在项目目录执行claude，输入一句“列出当前目录结构并做项目简析”，看它能否读取文件、运行命令。

我见过不少“装好了但没法用”的情况，最后排查下来都是这三件事里有一件没就绪。自检没问题，环境这一层才算真正过关。

3. 配置文件的骨架：CLAUDE.md、Settings 与多级记忆机制

环境装好之后，接下来是 Claude Code 配置体系中最核心、也最容易被低估的部分：记忆机制。这一层决定了 AI 是否“懂你的项目”，是所有角色配置和技能配置发挥作用的地基。

3.1 CLAUDE.md 项目记忆：该写什么、别写什么

CLAUDE.md 是 Claude Code 的“项目记忆文件”。每次对话启动时，它会自动读取这个文件，把其中的内容作为基础上下文。通俗点说，这就是你给虚拟团队新成员的入职培训手册。

文件分为三个层级：

• ~/.claude/CLAUDE.md：用户全局记忆，适用于你所有项目；
• .claude/CLAUDE.md：项目级记忆，放在项目根目录，被该项目的所有会话读取；
• 子目录 CLAUDE.md：可以放在特定子目录里，当 Claude Code 在该目录下工作时才会加载。

一份高质量的项目级 CLAUDE.md 应该包含四类信息：

# 项目记忆 ## 技术栈 - 前端：Vue 3 + TypeScript + Vite，状态管理使用 Pinia - 后端：Spring Boot 3 + Java 17 + Maven - 数据库：PostgreSQL 15，ORM 使用 MyBatis-Plus ## 常用命令 - 启动前端：npm run dev - 启动后端：mvn spring-boot:run - 构建产物：npm run build && mvn clean package - 运行单元测试：npm run test:unit ## 代码规范 - 前端组件统一使用 `<script setup lang="ts">`，禁止使用选项式 API - 后端禁止在 Controller 中直接操作数据库，必须经过 Service 层 - 所有对外接口返回统一的 Result 结构，禁止裸返回实体 - 数据库变更必须编写对应的增量 SQL 脚本，并放入 db/migration 目录 ## 注意事项 - 本项目使用 PostgreSQL，不要默认使用 MySQL 语法 - 支付宝沙箱环境相关配置见 docs/payment.md - 生产环境构建由 CI 负责，本地不执行发布操作

这里的关键在于“别写什么”。不要把大段业务说明、公司制度、几百行代码片段塞进 CLAUDE.md。它的定位是索引和规范，不是百科和代码库。内容太长会稀释上下文的重点，AI 反而容易忽略关键约束。写完之后定期维护，增删过时条目，像维护 README 一样维护它。

3.2 settings.json 权限与模型参数

Claude Code 的权限和运行参数在 settings.json 中配置，同样有用户级（~/.claude/settings.json）和项目级（.claude/settings.json）之分，项目级会覆盖用户级。

一个实用的基础配置是这样的：

{ "model": "opus", "permissions": { "allow": [ "Read", "Grep", "Glob", "Bash(npm run test:*)", "Bash(git status)", "Bash(git diff)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force)" ], "additionalDirectories": ["/Users/me/workspace"] } }

解释一下我的思路：model指定默认模型等级，Claude Code 支持的模型包括 Haiku、Sonnet、Opus，分别对应轻量快速、均衡、最强推理三档。日常小改动用 Sonnet，大需求让架构师角色切到 Opus。permissions.allow里我会把“读取类”操作放行，把“有副作用但属于常规操作”的命令用白名单方式放行，比如只允许运行测试相关的 npm 脚本。permissions.deny则用来兜底，防止 AI 在无人值守时执行危险命令。

这里想多说一句：权限配置最重要的不是放开，而是收紧。默认情况下，AI 每次执行 bash 命令都会询问你。如果你懒得频繁确认，可以把安全的命令放进白名单；但如果把Bash(*)全部放行，就等于允许一个会写代码的 agent 在你机器上任意执行命令。个人项目可以放松一点，团队协作和公司项目请务必保持手动确认。

3.3 多级记忆的优先级与协作方式

多级 CLAUDE.md 同时存在时，Claude Code 会按“子目录 > 项目根目录 > 用户全局”的顺序叠加读取，当同一个主题在不同层级出现冲突描述时，越具体的层级优先级越高。

用我实际工作中的例子说明：我在全局 CLAUDE.md 里写了“代码注释统一用中文”，但某个开源项目里通过项目级 CLAUDE.md 覆盖成“代码注释统一用英文”。这样我在开发该项目时，AI 会优先遵守项目级规则而不是全局规则。这个机制非常有用，它让同一套 Claude Code 可以平滑地在不同项目、不同团队风格之间切换。

但这同时也带来一个经验：全局 CLAUDE.md 只写“你自己长期不变的习惯”，比如“所有提交信息遵循 Conventional Commits 规范”。凡是和具体项目相关的信息，一律下沉到项目级配置里。很多人图省事，把项目信息写进全局配置，结果换了项目后 AI 满嘴跑火车，这属于典型的配置污染。

4. 把 AI 拆成“团队”：Subagents 与 Skills 的配置实战

记忆层解决的是“AI 懂不懂项目”的问题，能力层解决的是“AI 能不能像一支团队那样分工协作”的问题。这一章是整篇指南的高潮，也是我把 Claude Code 称为“AI 工程团队”的底气所在。

4.1 Subagents：按职责划分虚拟角色

Claude Code 的 Subagents 机制允许你在项目里定义多个带独立指令的“虚拟专用角色”。每个 Subagent 都有自己的名字、职责描述、工具权限和个性化行为约束。主对话中的 agent（称为 primary agent）会根据任务需要，自动决定是否需要调用某个 Subagent。

Subagent 的定义文件放在.claude/agents/目录下，格式是带 frontmatter 的 Markdown 文件。比如我定义的架构师：

.claude/agents/architect.md

--- name: architect description: 技术架构师。当任务涉及大型功能设计、技术选型、接口方案、模块拆分时，请先调用该角色。适合在动手写代码之前进行方案设计。 tools: Read, Grep, Glob, Write --- 你是一位有十年经验的软件架构师。接到需求后，你负责完成以下工作： 1. 分析需求的业务含义，识别模糊和缺失的信息； 2. 评估当前项目架构，确定改动影响范围； 3. 输出技术方案，包括模块划分、核心接口签名、数据库表变更； 4. 明确指出实现该功能可能踩到的坑，给出规避建议。 你的输出必须包含： - 方案概述 - 影响模块列表 - 接口定义（尽量给出方法签名或类型定义） - 实施步骤清单 - 风险和注意事项 注意：你的职责是设计，不是编码。除非任务本身是纯前端样式调整，否则不要直接写具体实现代码。

.claude/agents/code-reviewer.md

--- name: code-reviewer description: 代码审查员。当需要检查代码质量、审查 git diff、寻找 bug 和安全隐患时，优先调用该角色。适合在功能开发完成后使用。 tools: Read, Grep, Glob, Bash --- 你是一位极其严格的代码审查员。你会审查给定的代码或 diff，发现其中可能存在的功能缺陷、边界条件遗漏、性能问题和安全隐患。 审查流程： 1. 先阅读相关上下文文件，理解改动意图； 2. 逐行检查新增和修改的代码； 3. 重点关注：空指针和未定义值、并发问题、资源泄漏、SQL 注入、硬编码配置、异常被吞掉； 4. 输出分级问题列表：P0（必须修复）、P1（建议修复）、P2（可选优化）。 要求：不要夸奖代码，不要为了礼貌而降低标准。没有问题时明确说“未发现问题”。如果发现 P0 级问题，明确阻止合并。

用tools字段限制每个 Subagent 能用的工具，是让团队角色“专业化”的关键技巧。审查员不需要写代码权限，给它 Read、Grep、Glob 就足够；架构师可以给它 Write 权限让它输出设计文档；测试工程师则必须给它 Bash 权限才能运行测试。工具边界清晰了，AI 就不太容易跨角色越权干活。

4.2 Skills: 把可复用的专业能力沉淀成技能包

如果说 Subagents 定义了“谁来干活”，Skills 定义的就是“活儿怎么干”。它是 Claude Code 的 Agent Skills 机制，本质是把你经常让 AI 执行的某类专业任务，封装成一个带说明文档的技能包。当主 agent 判断当前任务匹配某个技能时，会自动加载该技能的说明作为上下文，按标准流程执行。

Skill 的文件结构是.claude/skills/<skill-name>/SKILL.md。我举一个代码审查技能的例子：

.claude/skills/frontend-review/SKILL.md

--- name: frontend-review description: 对 Vue 3 + TypeScript 项目的前端代码进行专项审查。当 diff 涉及组件、路由、状态管理或样式调整时使用。优先于通用 code-review 使用。 --- 这是一个针对 Vue 3 项目的专项审查技能。执行时遵守以下规则： 1. 检查 `<script setup>` 中是否正确使用了响应式 API，是否存在不必要的 `ref` 嵌套； 2. 检查组件的 props 是否定义了类型和默认值，禁止隐式 `any`； 3. 检查路由懒加载是否配置合理，首屏不必要的组件有无被提前加载； 4. 检查 Pinia store 中是否存在循环依赖、query 串行调用等典型问题； 5. 检查模板中是否存在大型内联函数，影响渲染性能； 6. 输出审查结果时附带文件路径和行号，并给出可操作的修改建议。

配置好 Skills 之后，你甚至可以让 Claude Code 在收到“帮我把这个页面改一下”时，自动套用前端审查技能进行检查。技能颗粒度取决于你的实际痛点：如果项目里总有组件通信混乱的毛病，就写一个组件通信专项审查；如果老有人把敏感信息写进代码，就写一个密钥扫描技能。Skill 的价值在于把“经验”固化成可重复执行的流程，而不是飘在 AI 脑中的随机行为。

4.3 MCP 扩展：让 Claude Code 接上外部工具

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，用来让 AI agent 连接外部数据和工具。配置 MCP Server 之后，Claude Code 就能访问外部系统的能力，比如读取本地文件系统、操作数据库、调用内部 API 等。

通过命令添加一个本地 MCP Server 的示例：

claude mcp add fs-tools -- npx @modelcontextprotocol/server-filesystem /Users/me/workspace

添加后用claude mcp list查看已连接的 server 列表，确保状态是 connected。MCP 的常见用处包括：连接 jira 获取需求状态、连接 Sentry 拉取线上错误、连接数据库执行只读查询。它让 Claude Code 从“只懂代码仓库”扩展到“熟悉你整个工作环境”。

这里给一句实在的提醒：MCP Server 是第三方代码，安全问题比命令行工具更值得关注。只添加你知根知底的官方或团队内部维护的 server；来历不明的 MCP 不要加，因为它的工具权限是真实作用在你系统上的。

4.4 一套开箱即用的团队配置骨架

把前面的内容汇总一下，一套基础团队配置的目录结构长这样：

. ├── .claude/ │ ├── CLAUDE.md # 项目记忆 │ ├── settings.json # 项目权限和模型设置 │ ├── agents/ │ │ ├── architect.md # 架构师角色 │ │ ├── backend.md # 后端工程师角色 │ │ ├── frontend.md # 前端工程师角色 │ │ ├── tester.md # 测试工程师角色 │ │ └── code-reviewer.md # 代码审查员角色 │ └── skills/ │ ├── frontend-review/SKILL.md │ └── unit-test-gen/SKILL.md └── ...

首次搭建时不需要一次配齐所有角色。我建议从“architect + code-reviewer”这两个角色开始，因为它们能让你的工作流立刻发生质变：开发前有人强制你思考，开发后有人强制你检查。跑顺之后，再逐步加入 tester、frontend、backend 等角色。

5. 团队协作流程设计：需求、开发、审查与测试的分工

角色和技能都配置好之后，还差最后一块拼图：工作流设计。很多人的 AI 用不好，不是因为模型不够聪明，而是因为他们只会丢一句需求让 AI 自由发挥。真正的团队协作需要节奏和制度。

5.1 需求分析阶段：让架构师先出场

接到一个新的功能需求，我的第一句话不是“帮我把这个功能做了”，而是“先让架构师分析一下”。在 Claude Code 的交互界面里，你可以这样触发：

请用 architect 角色分析以下需求，输出技术方案： “用户在小程序端可以绑定多个家庭，并切换当前家庭查看不同家庭的讯息。” 要求： 1. 识别当前项目的模块结构和数据库模型； 2. 给出数据表设计或变更建议； 3. 给出后端接口列表和前端页面改动点； 4. 标注风险和排期估算。

这样做的价值在于：AI 在没有明确方案约束时直接写代码，很容易把需求带偏。而让它先输出方案，你相当于多了个免费的架构咨询。方案不满意就继续和架构师角色反复讨论，方案确认后再进入开发阶段。这比让一个角色边设计边写代码容易控制得多。

5.2 开发和自测阶段：用规范约束产出

方案确认后，我会把方案中的实施步骤清单作为任务下发给对应角色。比如：

请按架构师输出方案的“实施步骤清单”开始实现。 约束： - 严格遵循项目中 CLAUDE.md 的代码规范； - 每个接口实现后，立即补充对应的单元测试； - 不要修改与本需求无关的代码； - 改动前先用 git status 检查工作区状态。

这里的关键词是“约束”。AI 工程团队和人一样，没有边界就会失控。每次任务都强调“只改相关代码”“每步自测”，会显著提升产出质量。特别是“不要修改无关代码”这条，能防止 AI 在实现需求时顺手把别的逻辑重构了。

5.3 代码审查与测试阶段：质量门禁

开发完成，AI 报告“功能已实现，测试已通过”之后，不要急着收工。切换 code-reviewer 角色做一次审查：

请用 code-reviewer 角色审查当前分支相对 main 分支的完整 diff。 输出问题分级清单，并针对 P0/P1 问题给出修改建议。

如果审查发现了问题，就让开发角色按建议修改，改完再让审查员复查一轮。这个过程看起来多花了时间，但从我实际项目的结果看，代码缺陷率能明显下降——AI 审查员不会累，不会因为写代码的人是自己就手下留情。

测试这一环也建议节点化：需求是“新增一个接口”就要求补接口测试；需求是“调整前端页面”就要求补组件测试。把测试要求写进每一个开发任务的 prompt 里，比事后单独发起一个“写测试”任务要自然得多。

5.4 一个完整的协作闭环示例

给你看我实际跑过的一个简化流程，方便理解整条链路是怎么串起来的：

我：请 architect 分析“增加用户注销功能”的方案。 architect 输出：数据表加注销状态字段；新增 DELETE /api/users/me 接口； 前端个人中心增加注销入口；保留 7 天冷静期；涉及用户 token 失效逻辑。 我：按方案实现。约束：不引入新的依赖，注销接口需要给 AOP 日志， 补全 Service 层单测。先看 git status 再动手。 backend 角色：实现接口、调用 AOP 日志、补充单测，报告测试通过。 我：请 code-reviewer 审查刚才的改动。 reviewer 输出：P1 问题——注销后 token 未立即失效；P2 问题——日志中 没有记录注销原因字段。 我：让 backend 修复 P1 问题，并给日志补上注销原因。 backend 修复后跑一次测试，确认通过。

一条消息链路下来，需求从方案到实现到审查到修复，全部在一个终端会话里完成。而这一整套行为模式，不是 AI 自己学会的，是前面那些角色定义、技能说明、prompt 约束共同作用下形成的结果。

6. 高频问题与调参实录

配置做完不代表万事大吉，Claude Code 在实际使用中还是会遇到不少问题。我把自己和身边人踩过的坑整理成了一份“排障手册”，按类别列出来，方便你直接搜索定位。

6.1 安装与认证类问题

Ubuntu 环境下我额外提醒一点：如果使用 nvm 安装的 Node，并且通过 SSH 连接服务器使用 Claude Code，要确认 nvm 的初始化代码在你的非交互 shell 里也能加载。很多人配置好之后，本机能跑、SSH 进去就找不到 claude 命令，多半是.bashrc里有提前 return 的逻辑导致 nvm 没加载。

6.2 上下文窗口与长任务处理

Claude Code 支持长对话，但上下文再长也有上限。当任务量很大，比如让 AI 一口气重构整个模块，它会出现“早期细节遗忘”或“越到后面越敷衍”的现象。

我的处理方式是把任务拆成多个会话，而不是让一个会话无限膨胀。具体操作是：先用 architect 角色出完整方案，把方案保存到项目文档里；然后开一个新会话，让 AI 读取方案文件，只完成其中“第二步到第四步”。每次会话的任务边界清晰，上下文里都是有效信息，产出质量自然高。

如果确实需要在超长会话中恢复之前的上下文，Claude Code 提供了claude --resume恢复历史会话的功能。不过我更建议用“文件作为跨会话记忆”：关键决策、接口约定都写进项目的 docs/ 目录，让 AI 读取。这比依赖会话缓存放心得多。

6.3 权限与安全边界

权限配置的问题通常有两种极端：一种是全部放行，结果 AI 在用户目录乱建文件、执行了不在预期内的命令；另一种是全部拦截，AI 每一步操作都要问一遍，拖慢节奏。

平衡的做法是：把“只读类工具”和“常规开发命令”加入白名单，把“有环境级副作用的操作”开除出白名单，保留人工确认。同时，对additionalDirectories字段做好限制，避免 AI 访问你不希望它碰的目录。遇到 AI 反复触发某个工具权限确认时，先停下来想一下，是“该命令确实常用需要放行”，还是“prompt 设计有问题导致 AI 偏离了任务”。多数情况是后者，放行是治标不治本。

6.4 MCP 与外部工具接入问题

MCP server 启动失败是最常见的接入问题。排查顺序是：

1. claude mcp list看连接状态，如果显示 failed，大概率是启动命令有问题；
2. 在终端单独执行 MCP server 的启动命令，看有没有报错；
3. 检查 MCP server 依赖的 CLI 工具或服务是否已安装并可用。

比如用npx方式启动的 server，第一次运行要现场下载 npm 包，如果网络环境不佳或 Node 版本不兼容，启动就会失败。遇到这种情况，先确保 Node 版本符合要求、npm 网络正常，再重新添加。

7. 我的配置心得与反共识建议

最后这部分，分享几条配置 Claude Code 过程中反直觉的判断。网上太多教程在教“怎么把配置写得又长又全”，但我实际跑下来，很多做法是错的。

7.1 配置不是越多越好，先跑通最小闭环

我第一次搭团队配置时，一口气写了九个 Subagent、十来个 Skill，目录结构相当唬人。结果真正跑需求时发现，主 agent 根本不知道何时该调用哪个角色，角色之间还经常给出互相矛盾的方案。

后来我把配置削到三个角色：architect、backend、code-reviewer。反而整个链路顺畅了。Subagent 不是越多越好，配置的每个角色都必须有明确的分工边界和触发场景。角色太多，主 agent 的选择成本急剧上升，效果就是每个角色都变得不够专业。我现在的原则是：一个角色至少要在真实任务里“救过我一次”，才值得留在配置里。

7.2 CLAUDE.md 要当代码库维护，定期重构

CLAUDE.md 最大的问题是会过时。项目技术栈换了、接口规范改了、目录结构调整了，但 CLAUDE.md 还停留在三个月前。这比没有 CLAUDE.md 更糟，因为 AI 会把过时信息当成硬约束，做出错误决策。

我现在的做法是，每次项目有结构性变化时，顺手让 Claude Code 自己帮我把 CLAUDE.md 和实际代码结构做个对照，找出不一致的地方并修正。另一个技巧是建立一个“决策日志”文件，专门记录项目中的重要技术决策和原因，CLAUDE.md 里只放一条引用链接。这样既保持了 CLAUDE.md 的简洁，信息又不会丢。

7.3 让 AI 团队真正协作的关键：接口先行

如果我只能给出一条最重要的建议，那就是：在让 AI 写代码之前，逼它先写接口和数据结构。AI 工程团队里最容易出现的问题不是“没人写代码”，而是“代码之间互相不兼容”。前端角色写出来的页面调用的接口，和后端角色实现的对不上。

接口先行能从根本上解决这个问题。方案阶段把接口签名、请求响应结构、数据结构定义清楚，后端的实现和前端的调用都基于同一份契约。团队协作这件事，不管对人也罢、对 AI 也罢，本质都是先谈清楚边界，再各自开工。

最后再分享一个实际体会：配置这套体系最大的收获，不是代码写得有多快，而是我作为“技术负责人”的思维方式被强化了。以前我打开编辑器就想赶紧写代码，现在我会先想清楚这个需求要拆成哪几步、每一步该让谁来做、质量标准是什么。Claude Code 的配置体系，某种程度上是在倒逼你用更工程化的方式思考软件交付。这个转变，比任何工具本身的效率提升都更有价值。