企业官网建设流程全解析

装完 Claude Code 之后第一次正经用它干活，我让它给一个老项目加登录模块。它读了一遍代码，给了我一个看起来很合理的方案，然后告诉我"这个改动比较大，建议分步执行"。我追了一句"那你现在开始改吧"，它回"好的"，然后只改了第一处就停下来等确认。那一刻我意识到，Claude Code 不是一个人，它是一张白纸——你给它多少上下文，它就干多少活；你给它怎样的规则，它就用怎样的方式干活。工具本身只是起点，真正决定产出上限的，是你把它配置成了什么样。

很多人装完 Claude Code 就把它当成终端里的聊天框，问一句答一句，用两天就搁置了。这不是工具不行，而是只完成了 10% 的配置工作。一个真正能扛事的"AI 工程团队"，不是装一个 CLI 就有的，它需要你把工具当人用：交代项目背景、划清权限边界、接好外部系统、分配好角色。这篇文章就是围绕"深度配置"展开的，目标是让 Claude Code 从"能回答问题的终端工具"变成"由架构师、编码员、审查者组成的虚拟小队"。过程会涉及环境准备、两套核心配置、MCP 扩展、多 Agent 协作，以及我踩过的一些坑。适合刚入门但不想停留在玩具级用法的开发者，也适合已经用了一段时间但总觉得"差点意思"的人。

1. 装好 Claude Code 只是开始：环境里那些容易被忽视的硬要求

先别急着配各种花活，环境这关过不去，后面全是白搭。我在给两台新机器装 Claude Code 的时候，分别踩了 Node 版本和全局目录权限的坑，这里一起说清楚。

1.1 Node.js 18+：为什么版本下限如此关键

Claude Code 是跑在 Node.js 运行时上的 CLI 工具，官方对 Node 的版本要求是 18 以上。这个下限不是随便定的，它涉及工具本身的依赖生态——很多现代 npm 包已经放弃对 16 及以下版本的支持，Claude Code 用到的 API 也大量依赖 18 才有的原生能力。版本不够的话，装的时候不会立刻报错，但运行阶段会出现各种诡异的异常，最常见的是一条 engine 警告直接卡住安装：

npm ERR! engine Unsupported engine npm ERR! engine node: wanted: >=18 ("current: 16.20.2")

很多发行版自带的 Node 版本特别老，Ubuntu 20.04 默认源里的 Node 还在 10.x 徘徊，直接装必然踩这个坑。我的建议是不要走系统包管理器去装 Node，一来版本太旧，二来权限管理混乱。用 nvm 是更省心的方案：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v

这里有个细节容易忽略：nvm 切换 Node 版本后，全局安装的包并不会跟着迁移，因为不同版本的全局目录是隔离的。如果你之前已经用系统 Node 装过一些全局工具，切到 nvm 之后需要重新安装。所以我现在的习惯是，新机器到手先装 nvm，再用 nvm 装 Node，然后再装 Claude Code，顺序不能反。

1.2 Ubuntu 与 Windows 下不同的安装姿势

环境就绪后，安装本身并不复杂：

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

但 Ubuntu 下经常遇到一个问题：npm 全局安装目录没有当前用户的写权限，安装命令报一堆 EACCES 错误。很多人第一反应是加 sudo，这能装成功，但后续会有麻烦——以 root 身份安装的全局包，普通用户执行时经常遇到权限错乱。正规做法是调整 npm 的全局目录，把它的归属权放到当前用户下：

mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

这样 npm 全局包默认装到当前用户目录，再执行 Claude Code 的安装命令就不需要 sudo 了。

Windows 用户我的建议是优先用 WSL。不是说原生 Windows 跑不了，实际上官方对 Windows 也有支持，但 Claude Code 内部会大量调用 shell 命令和 Unix 风格的脚本，在 PowerShell 里跑经常要处理路径转换、命令兼容这些问题。WSL 里配上 Ubuntu 发行版，再用 nvm 装 Node，整个体验跟 Linux 一致，少踩很多坑。

装完之后用一个命令验证：claude --version。能正常输出版本号，说明核心安装没问题。

1.3 Git 和 Shell：不装好它们，Agent 干不了活

Claude Code 不是一个只会聊天的大模型，它是一个 agent，意味着它要动你的代码。它生成 commit message 前要读 git diff，代码报错时要看当前分支和文件状态，甚至能帮你创建分支、提交代码。这些场景全部依赖 Git。机器上没配 Git 的话，它很多核心能力就直接退化了——不是"少一个功能"的程度，而是整个工作流断了一条腿。

我遇到过一台环境很干净的服务器，Claude Code 装好后让它分析代码，它说"无法获取 git 信息"，接着生成的一堆建议都偏差很大，因为缺失了变更历史这个关键上下文。所以事前配好 Git、配好 SSH key、能正常访问你的远端仓库，这些是让 Claude Code 高效工作的前提。同样的逻辑适用于 Shell——bash 或 zsh 都行，但一定要保证基本命令在 PATH 里。

补充一点：如果机器的网络环境走的是代理，记得让 npm 和 git 的代理配置保持一致，否则 npm 装包正常、git 拉取超时，Claude Code 在执行跨仓库任务时一样会卡。

1.4 账号类型与服务可用性确认

Claude Code 的登录方式主要有两类：一是直接用 Claude 账号（Pro/Max 订阅）登录，二是用 Anthropic API 的 Key。前者适合个人开发者在终端交互式使用，后者更适合脚本化、自动化场景。

首次登录直接跑claude，它会引导你打开浏览器完成认证。想用 API Key 的话，设置环境变量ANTHROPIC_API_KEY即可，命令行验证登录状态用/status。

还有一件事需要提前确认：Claude Code 对使用区域有明确的服务限制，官方支援列表是动态调整的。如果安装或登录时遇到 "Claude Code might not be available in your country" 这类提示，说明当前网络环境不在官方支持范围内。这不是安装命令的问题，也不是配置参数能解决的，务必以 Anthropic 官网的最新说明为准，确认自己的使用场景合规后再继续。

2. 两套核心配置：CLAUDE.md 与 settings.json 的分工

很多人的配置水平停留在"装好就用"，但 Claude Code 真正的深度配置，核心就是两个文件：一个负责告诉它"项目是什么样的"，一个负责规定"它能用什么、怎么用"。把这两者的边界理清，配置体系的骨架就立住了。

2.1 CLAUDE.md：给 AI 团队的"项目交接文档"

CLAUDE.md 是 Claude Code 每次启动时自动读取的项目记忆文件。你可以把它理解成给新人开发者的 onboarding 文档——一个刚入职的工程师，拿到一份写清楚的交接文档，能快速进入状态；没有文档，他只能一点点猜。Claude Code 也一样，它不会主动知道你项目的技术栈是什么、构建命令是什么、代码规范有哪些，这些全靠 CLAUDE.md 告诉它。

我的模板一般包含五块内容：

# 项目：订单系统 ## 技术栈 - 后端：Java 17 + Spring Boot 3 - 前端：Vue 3 + TypeScript - 数据库：MySQL 8 ## 常用命令 - 本地启动：./mvnw spring-boot:run - 单元测试：./mvnw test - 前端构建：npm run build ## 架构约定 - 所有对外接口统一走 /api/v1 前缀 - 数据库操作必须走 Mapper 层，禁止在 Service 里直接写 SQL - 新增依赖前先说明理由 ## 常见任务示例 - 新增接口：Controller → Service → Mapper → SQL 脚本 → 接口文档注释 - 修改表结构：先出变更脚本，再改实体类，最后更新 README ## 注意事项 - 不要在代码里硬编码密钥，统一走配置中心 - 日志用 slf4j，不要用 System.out

这里有个关键点：写 CLAUDE.md 不是写作文，是写给"执行者"的操作手册。它不需要文采，需要结构化。字段越清晰，Claude Code 在规划任务时就越容易命中正确路径。实测下来，一份好的 CLAUDE.md 能让产出的代码风格和项目现有代码高度一致，这比任何提示词都管用。

除了项目根目录的 CLAUDE.md，用户目录下的~/.claude/CLAUDE.md也会被读取，负责存放跨项目的通用偏好——比如你习惯用 2 空格缩进、不喜欢生成复杂的注释、提交信息偏好英文还是中文。两者不冲突，项目级内容优先级更高。

2.2 settings.json：权限、模型、钩子的总开关

CLAUDE.md 解决"知道什么"的问题，settings.json 解决"能做什么"的问题。这个文件控制着 Claude Code 的权限边界、默认模型、工具调用规则，甚至可以在工具调用前后挂载自动化钩子。

settings.json 有两个层级：用户级放在~/.claude/settings.json，项目级放在.claude/settings.json。项目级配置会覆盖用户级的同名配置，适用场景是把某套权限策略绑定到特定仓库，避免团队协作时互相影响。

核心配置结构长这样：

{ "permissions": { "allow": [ "Read(README.md)", "Bash(npm run build)", "Bash(git status)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force)" ], "ask": [ "Bash(rm *)", "Bash(git reset --hard)" ] }, "model": "claude-sonnet-4-20250514", "hooks": { "PreToolUse": [ { "matcher": "Bash(git push)", "hook": true } ] } }

权限字段有三个级别：allow 直接放行、deny 直接拒绝、ask 每次都弹确认。我见过不少人的做法是把权限全开，觉得"反正它也不会乱来"，这是很危险的。Claude Code 的高效建立在它能自由执行命令之上，但"自由"不等于"无界"。特别是涉及删除、强推、修改权限这类危险操作，留一道人工确认的关卡很有必要。它更像给团队成员发门禁卡——办公区随便走，机房和财务室要有授权。

模型选择上，日常编码场景我推荐用 Sonnet 系列，速度快、性价比高；复杂的架构设计或大规模重构再切到 Opus 系列，思考深度更强。不用固定死，我习惯在settings.json里按项目默认设置，需要临时切换时直接在会话中输入/model换。

2.3 环境变量与密钥：别把 token 写进配置库

配置里最容易翻车的是密钥管理。有些人图省事，把 API Key 直接写进 settings.json 或者项目配置文件里，然后整个仓库被推到远端——这种事故我见过不只一次。API Key 一旦泄露，轻则额度被盗刷，重则造成数据安全问题。

正确的做法是通过环境变量注入。在~/.bashrc或~/.zshrc里加：

export ANTHROPIC_API_KEY="your-api-key-here"

或者用 direnv 这类工具做项目级的环境变量管理，让密钥只在当前项目目录下生效，不进版本库。Claude Code 对环境变量的支持很完善，ANTHROPIC_MODEL、ANTHROPIC_BASE_URL、ANTHROPIC_SMALL_FAST_MODEL等常用变量都可以在运行时动态指定，完全不依赖硬编码。

顺带提醒，.gitignore里一定要把.claude/settings.json（如果里面放了敏感信息）、.env、*.local这些文件排除掉。哪怕现在没有放密钥，养成习惯总是好的。

2.4 生效顺序：改完不生效的第一排查方向

配置改完没生效，这是最高频的疑问。排查顺序其实就三条链路。

第一，确认配置层级。项目级 settings.json 会覆盖用户级配置，如果两边字段冲突，以项目级为准。我遇到过有人在用户级配置了模型，但项目级 settings.json 里有一个旧的 model 字段，导致切换模型永远不生效。

第二，确认是否重启。Claude Code 启动时会读一次配置，会话运行中改配置不会热更新。改完文件需要完全退出重进，而不是新开一个对话。

第三，确认文件位置。Claude Code 的配置文件路径在不同版本之间有差异，拿不准的时候在会话里用/config命令打开配置管理界面，可视化修改比手工改路径靠谱得多。

3. 接入 MCP 与拆分角色：从"一个助手"到"一支团队"

前面的配置解决的是"工具规不规范"的问题，这一章解决的是"团队怎么建立"的问题。深度配置的终极形态，是把 Claude Code 从单个助手改造成多个角色协作的工程团队，这里的关键技术是 MCP 和子代理机制。

3.1 MCP 对 Claude Code 的意义：工具即能力边界

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，你可以粗暴地理解成给 Claude Code 装 USB 接口——没有接口时它只能操作本地文件和终端命令，插上不同的外设就能解锁不同的能力。

以官方文档为例，接入 GitHub MCP 服务器后，Claude Code 就能直接操作 issue、PR、repo 等资源；接入数据库 MCP 后，它能用自然语言查询数据库内容；接入 Playwright MCP 后，它甚至能控制浏览器做端到端测试。没有 MCP 的 Claude Code 是一个只能待在终端里的编码工具，接上 MCP 的 Claude Code 是一个能触达整个研发链路的操作者，差距就是这么大。

MCP 服务器本质上是独立的进程，通过 JSON-RPC 与 Claude Code 通信。这个设计的好处是生态开放，任何团队都可以开发自己的 MCP 服务器，包装内部系统、私有工具，让 Claude Code 变成"什么都能干"的 agent。这也是它能当"工程团队"用的底层基础。

3.2 动手接入 MCP：filesystem 与 GitHub 这两个必须会

接入 MCP 的命令很直接：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects claude mcp add github -- npx -y @modelcontextprotocol/server-github

第一条把 filesystem 服务器接到 Claude Code 上，并允许它访问~/projects目录；第二条接上 GitHub 服务器，让它在有 token 的情况下操作仓库资源。运行claude mcp list可以查看当前已接入的服务器，启动 Claude Code 后也可以直接用/mcp命令管理。

我常用的一套 MCP 组合长这样：

这里有一个实战层面的建议：MCP 不是接得越多越好。每个 MCP 服务器都会占用上下文窗口和系统资源，接入 10 个不常用的服务器，反而会稀释 Claude Code 对核心任务的注意力。先接必需的，跑通过一个场景再加下一个，按需扩展。

3.3 用子代理拆角色：架构师、编码员、审查者的协作方式

很多人不知道 Claude Code 支持子代理机制，子代理可以在一个会话中并行协作,每个代理有独立的任务描述、工具权限和行为模式。这是"构建 AI 工程团队"的关键——不是多个终端各跑一个 Claude，而是在同一个会话里，拆出多个角色各司其职。

我在.claude/agents/目录下定义了三个角色：

architect.md——架构师，负责总体设计和方案评审：

--- name: architect description: 负责架构设计和技术方案评审，输出高层次的系统设计文档 tools: Read, Grep, Glob, Bash --- 你是一名资深软件架构师。接到需求后，先阅读项目现有架构说明和技术栈， 再输出技术方案，方案必须包括：模块拆解、数据模型设计、接口设计、 风险点评估。输出的方案需要简洁、可执行，不要写废话。

coder.md——编码员，负责具体模块实现：

--- name: coder description: 负责具体功能开发，按照架构方案实现代码 tools: Read, Edit, MultiEdit, Write, Bash --- 你是一名资深后端工程师。开工前先确认需求文档和技术方案， 严格按照架构师的设计方案编码，代码风格与项目现有代码保持一致。 每个模块完成后，要运行对应测试确认逻辑正确。

reviewer.md——审查员，负责代码审查和安全检查：

--- name: reviewer description: 负责代码审查，检查安全性、性能和可维护性 tools: Read, Grep, Glob, Bash --- 你是一名严格的高级代码审查员。审查代码时重点关注： 安全问题、性能隐患、边界条件、可维护性。发现问题直接指出， 并给出最小化的修改建议，不要重写整个文件，除非有充分理由。

实际使用中，主线程会先接需求，梳理后分发给架构师产出方案，方案经我确认后交给编码员实现，最后丢给审查员过一遍。整个过程在同一个会话里完成，Claude Code 会自动做上下文的传递。这套机制跑顺之后，产出质量比我直接用 Claude Code 一把梭高出一大截——因为每个角色都有明确边界，不会出现"既要写方案又要写代码最后两头都糊"的情况。

3.4 把团队流程固化：自定义指令与 Workflow

角色拆好之后，还需要把协作流程固化下来，否则每次开工都要重新解释一遍谁干什么。我推荐把重复性的任务流程做成自定义指令，放在.claude/commands/目录下。

比如创建一个new-feature.md自定义命令：

--- description: 新功能开发流程：架构设计 → 编码实现 → 代码审查 --- 请按以下流程处理新功能开发： 1. 先调用 architect 子代理，基于项目技术栈和现有架构，输出技术方案 2. 将方案整理成文档，列出模块拆解、数据模型、接口设计和风险点 3. 方案确认后，调用 coder 子代理按方案实现代码 4. 调用 reviewer 子代理审查代码，突出问题点 5. 输出审查报告和修改建议

这样在 Claude Code 会话中输入/new-feature，它就会自动按流程走完整个开发周期。我建议每个团队根据自己的研发流程，逐步沉淀 3~5 个这样的自定义命令，比任何提示词模板都好用。

再进一步，可以配合 settings.json 里的 hooks 机制做自动化。比如配置一个 PreToolUse 钩子，在每次执行git commit前自动跑一遍代码格式化或单元测试，把质量控制前置。

4. 调试路径与高频坑位：一次真实排查过程复盘

配置和使用过程中不可能不踩坑。这一章不列一堆理论，我用一次真实的排查过程来说清楚 Claude Code 遇到问题时，应该怎么一步步找到原因并解决。

4.1 遇到问题先看日志：--debug 输出怎么读

有一次我在一个 Ubuntu 服务器上跑一个批处理任务，Claude Code 执行到一半突然卡住，既不报错也不继续，终端只剩一个光标在闪。我的第一反应是"模型卡了"或者"网络断了"，但这些都是猜测，要确认必须看日志。

Claude Code 提供了调试模式：

claude --debug --verbose

--debug会输出完整的调试信息，--verbose会打印更细的交互过程。那次运行后，日志里出现了一行关键提示，显示某个工具的调用等待超时，然后自动重试了一次又超时。问题不在模型，而在于这次任务涉及从外部服务拉取数据，外部服务的响应时间太长，Claude Code 的工具调用有超时阈值，一旦超过它就会停下来。

日志是排查的第一步，也是最重要的一步。很多人遇到问题就凭感觉改配置，不如先花两分钟看看日志里到底报了什么。日志文件位于~/.claude/logs/，也可以在会话中用/debug来切换调试输出。

4.2 被权限拦路：工具调用拒绝后的处理思路

另一个很典型的问题是，Claude Code 在需要执行某个命令时被权限拦下来。常见现象是它反复尝试执行某个操作，但每次都被拒，然后陷入循环——这个场景大多数人可能都见过。

我的处理思路是：不要急着给它开全权限，先想一下这个操作是不是真的合理。之前的 settings.json 里我配置了Bash(git reset --hard)需要询问，结果有一次它确实需要执行这个命令，一直卡在确认环节。我当时有两个选择：一是临时允许，二是调整命令策略。我选的是在 ask 列表里保留它，但修改了命令的具体匹配规则，让交互式确认只在极端危险操作时弹出。

这里想强调一个原则：权限配置的粒度取"够用"不取"全放"。每当 Claude Code 被拦下，先判断这个命令是不是任务必需的、是不是可逆的。可逆且低频的命令，比如删临时文件，可以放行；不可逆且影响面大的命令，保留确认步骤。时间久了，你可以慢慢积累出一套贴合自己使用习惯的权限清单。

4.3 配置不生效与上下文过长：两个容易反复踩的点

配置不生效的原因在第二章提过，这里说另一个高频问题——上下文过长。

有一次我用 Claude Code 分析一个大型前端项目，让它在 20 多个文件里找路由配置的问题。任务进行到一半时，它开始答非所问，甚至把之前已经确认过的事情又拿出来重新问。我看了下对话历史，发现上下文窗口已经被塞满了——每次读文件都在累积 token，越到后面可用空间越少，它的"短期记忆"被挤占得所剩无几。

处理办法：用/compact命令压缩对话历史，或者直接开一个新会话、把必要的上下文通过 CLAUDE.md 文件带过去。更高效的做法是把大任务拆成小批次执行，不要试图在一个会话里让 Claude Code 完成所有事。它能高效处理的是一个明确、有边界的任务，而不是一个"包含所有信息的巨型任务"。

4.4 让产出质量上一个台阶：提问与任务拆分的改造

这一节不给 100 条提示词模板，只讲一个我反复验证过的方法论：Claude Code 的表现上限，很大程度取决于你给它下发的任务质量。同一个项目，两种下法，产出天差地别。

第一种下法："帮我优化一下这个项目的代码。"

第二种下法："请先阅读src/modules/下所有模块的代码，输出一个文件清单，标注每个文件的职责和数据流向。然后基于这个清单，找出依赖关系最复杂的 3 个模块，分别说明它们的循环依赖问题，最后按影响范围从大到小给出重构建议。"

看得出来，第二种下法把"优化"这个大词拆成了可执行的动作：读代码、列清单、找问题、排序、给建议。这不是什么高级技巧，而是把任务拆分成 Claude Code 能执行的子任务。它本质上是个高效的执行者，不是读心者——你交代得越具体，它执行得越准。

我现在的习惯是，每次下发任务前先在脑内过一遍：这件事拆成哪几步？每一步的输入输出是什么？大概要读哪些文件？把这些信息写进任务描述里，然后才交给 Claude Code 执行。带着这套方法去用，你会发现它的产出质量会有一个明显的提升。

最后再分享一个我个人的体会：Claude Code 这类工具，真正拉开差距的不是谁先装上，而是谁把它配置得更贴合自己的项目和节奏。我花在维护 CLAUDE.md 和子代理配置上的时间，省下的是每次会话里反复解释项目背景的时间，这笔账怎么算都不亏。如果你现在刚装好 Claude Code，建议从写一份项目 CLAUDE.md 开始，写完再跑一个任务试试，对比下前后的差异，你会回来感谢自己的。