企业官网建设流程全解析

1. 从“有用的工具”到“团队成员”：我先给 Claude Code 定了四个角色

先说结论：Claude Code 不是一个普通的代码补全插件，它是一个跑在终端里、能独立阅读工程、修改文件、执行命令、然后自己验证结果的 agentic 编程工具。如果说 Copilot 是副驾驶，Claude Code 更像是你直接雇了一个刚入职、能力很强但偶尔需要盯着点的远程工程师——你给它任务，它会自己拆解、执行、汇报，甚至在你睡着的时候把 PR 开好。

但工具再强，用不好也是一堆摆设。我在实际用了一周之后发现，大多数人的问题不是“Claude Code 不好用”，而是根本没有给它建立正确的工作上下文和权限边界。默认状态下的 Claude Code 就像一个新来的同事，有潜力但不知道你们团队的代码规范、目录结构、测试习惯，也不知道哪些事情可以自己拍板、哪些必须请示。这篇配置指南，核心就是解决这个问题：怎么把 Claude Code 从“一个能写代码的终端工具”，配置成“一个合格的 AI 工程团队成员”。

我的做法是先给它定四个角色，再围绕这四个角色做配置：

• 熟悉业务的结对工程师：懂项目结构，知道代码放哪、测试怎么跑、规范是什么。
• 严格的代码审查者：能指出问题、给出修改建议，而不是只会夸“代码写得很好”。
• 高效的工具调用者：能查文档、调接口、操作 Git，必要时还能自己写脚本。
• 守规矩的执行者：权限边界清晰，不会在你没同意的情况下乱改文件、乱跑命令。

整篇指南会围绕这四个角色展开。内容会覆盖安装、CLAUDE.md 记忆体系配置、权限模式、Skills 技能扩展、Subagents 子代理分工、Hooks 自动化这几个核心模块，全部都是我在 Ubuntu 和 Windows 11 上实测过的配置方案，并配有可直接抄作业的配置示例。适合已经用过一点 Claude Code、但觉得效果不稳定的朋友，也适合刚装完发现“这玩意怎么不听指挥”的新手。

2. 安装与接入：先把“人”招进来，再谈培养

2.1 安装与认证：官方渠道最省心

Claude Code 的安装路径很清晰，官方推荐使用 npm 全局安装，这是目前兼容性最好、升级最方便的方式。前提是你本机有 Node.js 18 以上版本，没有的话先去装一个 LTS 版本，这里不展开。安装命令只有一条：

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

装完之后跑一下claude --version，能正常输出版本号就说明安装成功。然后是认证，在终端里输入claude，第一次启动会引导你完成 login 流程，通常是跳转浏览器完成授权。这里有第一个关键注意事项：很多朋友在服务器上安装时没有浏览器可用，导致认证卡住。我的建议是本地电脑安装好并认证完成后，直接同步~/.claude目录到服务器，或者使用 API Key 方式登录——在终端里用/login命令可以切换认证方式，API Key 适合 CI/CD 场景，但要注意 Key 的权限尽量限制在项目范围。

VSCode 用户建议再装一个 Claude Code 官方扩展，这样可以在编辑器里直接开一个集成终端跑 Claude Code，AI 修改的代码会实时反映在编辑器界面里，审查 diff 的时候体验比单独开终端好很多。我个人强烈建议“编辑器 + 终端”组合使用，因为 Claude Code 的强项之一是全局感知，它能看到整个项目而非单个文件，这正是它区别于普通插件的核心能力。

2.2 先跑通一个最小任务，再开始深度配置

装好之后不要急着做复杂配置，先找一个简单的任务验证基本流程。我建议拿一个你熟悉的、规模较小的开源项目做测试，让它“解释一下这个项目的核心架构，并指出三个可以优化的点”。这里有两个目的：第一，确认 Claude Code 能否正确读取项目结构；第二，观察它的默认行为模式——它会在什么情况下读文件、什么情况下停下来提问，这些行为预判在后续配置中非常重要。

这一步踩坑率不低，最常见的现象是 Claude Code 对项目完全“无感”，回答很泛泛。原因往往不是工具问题，而是项目里缺少上下文。Claude Code 默认会读取当前目录下的文件，但它不会自己“猜”你的业务规则，你需要在配置层面主动喂给它。这就引出了整个深度配置里最重要的一环——CLAUDE.md。

3. 干“团队”的活，先建“团队”的记忆：CLAUDE.md 才是灵魂

3.1 CLAUDE.md 的本质：把你的经验固化给 AI

如果说 Claude Code 是新入职的工程师，那 CLAUDE.md 就是你们团队的新人手册。这个文件决定了一个最关键的问题：AI 是“懂行地干活”还是“瞎猜着干活”。它支持全局和项目两级配置，全局配置文件在~/.claude/CLAUDE.md，项目级配置文件在项目根目录的CLAUDE.md。两套配置会自动合并，项目级优先级更高。

为什么这个文件如此重要？因为 Claude Code 的上下文窗口虽然大，但它不会每次任务都从头读一遍整个项目。CLAUDE.md 实际上起到的是“压缩后的长期记忆”作用，相当于告诉它：这个项目是什么、结构怎么组织、有哪些约定俗成的规则、你希望它用什么方式工作。没有这个文件，它每次都是“裸奔”状态，很多行为就会显得“不聪明”甚至“闯祸”。

我的建议是 CLAUDE.md 至少包含以下板块——项目概述与目标、技术栈与关键依赖、目录结构说明、开发与测试命令、代码规范与命名约定、禁止事项与权限边界。一个我实际使用的模板如下：

# 项目概述 这是一个基于 FastAPI 的电商后端服务，核心功能包括用户认证、商品管理、订单处理。 技术栈：Python 3.11 + FastAPI + SQLAlchemy + PostgreSQL + Redis # 目录结构说明 - app/api/ 路由层，按业务模块划分 - app/services/ 业务逻辑层，核心逻辑禁止写在路由里 - app/models/ ORM模型，使用 SQLAlchemy 2.0 风格 - tests/ 测试目录，使用 pytest # 开发与测试命令 - 启动开发服务：uvicorn app.main:app --reload - 跑全部测试：pytest tests/ -v - 跑单个测试：pytest tests/test_user_api.py -v # 代码规范 - Python 代码使用 black + isort 格式化 - 类型注解必须完整，public 函数必须有 docstring - 所有 API 响应遵循统一的 {code, message, data} 结构 # 禁止事项 - 不要直接修改 database/migrations 下的迁移文件 - 不要引入新的第三方库，除非先和项目负责人确认 - 不要在 services 层直接使用 SQLAlchemy Session 对象

你可以看到，最后一条“禁止事项”极其关键，Claude Code 这个工具的特点是它会主动做一些“合理但不合适”的事情，比如看到缺库就自动给你装一个。把边界写清楚，能省去大量盯它干活的时间。

3.2 用 CLAUDE.md 培养“团队风格”，而不是千人千面的万能 AI

实际测下来，CLAUDE.md 撰写的好坏，直接决定 Claude Code 的输出质量上限。我见过一个朋友的项目，CLAUDE.md 写了两千多字，事无巨细地描述了各种规范，结果 AI 干活反而变得非常慢，遇到任何小问题都要停下来反复确认。后来我帮他瘦身，只保留了关键信息，效率立刻提升了一个档次。

这套方法论很像管理一个真实的团队：规则太多会拖垮执行力，规则太少会失控。我的实践结论有几点：第一，命令要具体到可执行，比如不要写“要规范命名”，要写“用户相关的 Service 文件必须命名为 user_service.py”；第二，原则性规则只留最重要的 3 到 5 条，其他都是噪音；第三，把 CLAUDE.md 当作活文档，随着项目演进持续迭代，不要一次写完就再也不管。我自己每次做完一个比较大的功能，都会回头看一眼 CLAUDE.md，把新学到的项目特殊约定补充进去，这样 Claude Code 会“越用越懂你”。

这里再分享一个进阶技巧：CLAUDE.md 里可以用/指令格式定义项目专属命令，比如/test表示运行测试并输出摘要，/review表示让 Claude Code 以代码审查者身份检查当前改动。这些自定义指令本质上是在“培养团队默契”，让 AI 的行为模式高度可预期。

4. 权限与模式配置：决定你的 AI 工程师是“实习生”还是“正式员工”

4.1 理解三种工作模式，别让它“什么活都接”

Claude Code 默认情况下对文件修改和命令执行有很强的自我保护意识，比如修改文件前会询问确认、执行危险命令时会警告。但如果你每次都手动确认，效率会大打折扣。所以我用下来觉得，真正要做到好用，核心在于科学地设置权限，也就是它能不能动文件、要不要问过你再动手、能不能自动重试。

Claude Code 内置了几种权限模式，我在实践中常用的有三种：

• 默认模式：每次修改文件都会请求确认，适合不熟悉的项目或排查问题阶段。
• 自动接受文件编辑模式（acceptEdits）：AI 修改文件前不再逐一确认，只管改，改完给你看 diff。适合功能开发期、测试代码这类低风险场景。
• 全自动模式（bypassPermissions）：AI 可以自由改文件、运行命令，全程几乎不需要你干预。适合跑批量重构、修 lint、补测试这类明确任务，但风险也最高，强烈不建议在没把握的情况下使用。

具体切换方式是在对话中输入/permissions命令，选择对应的权限级别。我个人的建议配置是：最外层项目设置里关闭全自动，只打开 acceptEdits，然后针对个别明确可信的操作（比如运行pytest、git add/commit）单独设置允许规则。这样既保留了效率，又不至于失控。

这里有一个不少人都踩过的坑——Claude Code 运行命令和改文件是两套独立权限。你可以在配置里允许它 “执行测试命令”，同时禁止 “直接改数据库模型”。我见过有人在设置里为了省事直接全开，结果 AI 跑偏了还自动把代码提交了，虽然能撤回，但心态很受影响。

4.2 用 settings.json 精细控制，比口头约定更可靠

权限控制的终极方式是项目级配置文件.claude/settings.json。这个文件允许你按具体规则定义哪些操作可以自动执行、哪些必须人工确认，还支持按文件路径设置 allow 和 deny 规则。比如我现在的常用配置是：

{ "permissions": { "allow": [ "pytest tests/*.py", "git status", "git diff", "npm test" ], "deny": [ "rm -rf *", "git push --force" ], "fileEdit": { "allow": ["src/**", "tests/**"], "deny": ["database/migrations/**", "secrets/**", "*.lock"] } } }

这套配置的核心思路不是“禁止一切”，而是“把低风险的路径放开，把高风险路径锁死”。比如src和tests是我希望 AI 自由发挥的领域，而迁移文件和锁文件则是定义了“碰都不能碰”的红线。实际体验下来，这种精细化的权限控制比“一刀切”更符合真实工作流——既能快速干活，又不需要在关键节点提心吊胆。

另外有个实用小技巧：如果你发现某个权限配置不生效，先检查两个 settings 文件的合并顺序。Claude Code 会依次合并~/.claude/settings.json（用户级）、.claude/settings.json（项目级）、当前会话的/permissions设置，后者的优先级更高。排查问题的时候先确定是哪个层级拦住了。

5. 团队分工的进阶配置：Skills、Subagents 与 Hooks

5.1 Skills：把“特长”安装到你的 AI 工程师身上

如果说 CLAUDE.md 是新人手册，Skills 就是岗位技能包。Claude Code 的 Skills 目录允许你把特定的工作流程封装成文件夹，放到.claude/skills/下，AI 在处理匹配任务时就会主动加载这个技能包。安装方式主要两种：从官方 Skill 仓库下载，或者自己手写。社区里已经有不少现成的 Skills，比如“Code Reviewer”（代码审查）、“React Component Generator”（React 组件生成）、“Git 提交信息规范化”等。

我自己写过一个“单元测试专家”的 Skill，效果非常好。实际上它在.claude/skills/test-writer/SKILL.md里定义了一套写测试的流程：先读被测模块，分析依赖和边界条件，再设计测试用例，最后按照项目已有的测试风格生成test_*.py文件，运行测试并把失败信息反馈回来。配置好这个 Skill 之后，我只需要说“给 auth_service 写单元测试”，Claude Code 就会自动加载这个技能流程，不再是一通乱写。手动创建 Skill 的目录结构也很简单：

.claude/skills/test-writer/ ├── SKILL.md # 技能的主描述文件，定义触发条件与执行流程 └── reference.md # 可选，技能相关的补充参考文档

对于想快速上手的朋友，我的建议是先装社区里成熟的 Skills，用一段实际任务验证效果，再模仿它的结构自己写。一开始别贪多，装太多 Skill 会让 Claude Code 在任务触发时产生选择困难，反而拖慢速度。

5.2 Subagents：给不同职责配上独立的“虚拟员工”

再进一步，Subagents 机制可以让你真正意义上组建一支“AI 工程团队”。每个 Subagent 相当于一个拥有独立系统提示词、独立工具权限的 Claude 实例——你可以同时创建架构师、前端工程师、测试工程师、代码审查员，它们各司其职，在一个会话里协同完成任务。我用得最多的是让“主 Agent 负责拆解任务”，然后分发给“测试工程师”、“重构工程师”等子代理并行处理，效率提升极其明显。

Subagent 定义放在.claude/agents/目录下，每个以.md结尾的文件对应一个 Agent。举一个我正在用的例子：

--- name: code-reviewer description: 专门的代码审查员，用于审查代码改动并给出结构化反馈。 tools: Read, Grep, Glob, Bash model: claude-sonnet-4-20250514 --- 你是一位严格的代码审查专家。收到审查请求后，请按以下流程执行： 1. 读取目标文件的完整内容，结合项目 CLAUDE.md 中的规范进行评估。 2. 重点关注：安全性、边界条件、性能隐患、命名规范、测试覆盖。 3. 检查变更范围，指出现有逻辑中被破坏的调用方。 4. 输出格式：按“问题严重程度”分组列出问题，每个问题附带行号、原因与修改建议。

实际使用中我发现，给 Subagent 设定一个清晰的description非常重要，它决定了主 Agent 什么时候会把这个任务委派下去。描述写得越具体，任务分发的准确率越高。而tools字段则控制了该 Subagent 的“手脚”，审查类角色不应该被赋予 Write 权限——它负责提意见，不负责直接改代码，这个边界能让工作流更可控。

几个角色搭配建议：你可以配置一个frontend-dev（专攻 React/Vue 组件开发）、一个backend-dev（专攻 API 设计与数据库）、一个test-engineer（专写测试）、一个code-reviewer（专门挑刺）。当主 Agent 收到“实现用户登录功能”这么一个大任务时，它会自动拆解成前端、后端、测试、审查四块，分发给对应的 Subagent 执行。这种模式下，Claude Code 从一个“写代码的 AI”真正变成了“带团队的 AI”。

5.3 Hooks：让团队“自觉地”遵守流程

Hooks 是容易被忽略但非常给力的一大特性。它允许在特定事件触发时执行自定义脚本——比如在 Claude Code 每次修改代码之前自动跑一遍 lint，在生成 diff 之后自动补充文档，或者在任务完成之后自动发送通知。这个特性本质上是在给 AI 工程师立规矩，“写代码前先检查格式、提交前先跑测试”这些团队规范，从靠自觉变成靠机制。

我目前的一个实用配置是：在PreToolUse阶段拦截 Git 提交命令，自动运行项目的测试套件；在Stop阶段自动更新项目的 CHANGELOG。配置写在.claude/settings.json里：

{ "hooks": { "PreToolUse": [ { "matcher": "Git*", "hooks": [ { "type": "command", "command": "npm test -- --silent && echo '测试通过，允许提交' || echo '测试失败，阻止提交'" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "node .claude/scripts/update_changelog.js" } ] } ] } }

这里有两个注意事项：第一，hook 命令的执行结果会影响主流程，比如PreToolUse中返回非零退出码，会直接阻止 AI 继续操作，所以脚本务必写得稳妥；第二，hook 脚本要考虑到多环境兼容，建议用 Node 或 Python 写而不是依赖 bash 特有的指令，不然在 Windows 上就会有兼容性问题。我折腾下来，hook 稳定性至关重要——脚本本身出错，比 AI 不守规矩更让人头疼。

6. MCP 与外部工具链：把手伸长，能对接多少系统就对接多少

6.1 MCP 到底是什么，值得配吗

现在很多人在聊 MCP（Model Context Protocol），这个词听起来很唬人，本质上它就是一个标准化的“接口协议”，让 Claude Code 能像调用本地工具一样去操作外部系统——比如查公司内部的 API 文档、操作 GitHub 仓库、读写 Notion 文档、查询数据库。它解决的核心痛点是：Claude Code 的能力边界不再局限于终端文件和命令，而是可以接入整个软件生态。

我配置 MCP 的第一感受是“AI 突然有了完整的工作台”。之前它写完代码要等我把改动推到远端，或者让我手动查文档；配上 GitHub MCP、数据库 MCP 之后，它可以自己拉取 Issue、查看 PR 状态、连上只读数据库验证数据模型。不过真心建议从“少而精”开始——每个 MCP Server 都会占用上下文空间，接入太多无用的服务，Claude Code 的思考速度会明显下降，而且可能出现工具选择混乱。

6.2 一个实用的 MCP 配置示例

MCP 配置通常写在项目级.mcp.json文件里，我目前长期启用的是 GitHub 和本地文档检索两类。以下是一个简化的真实配置：

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "你的token" } }, "docs-search": { "command": "python", "args": ["./.claude/mcp/docs-search.py"] } } }

GitHub MCP 的用途非常直接：当你本地代码和远端 Issue 联动时，AI 可以不离开终端就获取 Issue 详情、创建 PR、查看 CI 状态，省去了大量切换窗口的时间。本地文档检索则是我针对公司内部技术文档写的轻量脚本，核心逻辑是用正则或简单文本匹配，把相关文档片段返回给 Claude Code，本质上是给它的“知识库”扩容。

配置 MCP 最常见的问题是环境变量和路径。npx版本需要本机网络正常，Python 脚本则要保证依赖完整，任何一个环节报错，Claude Code 都会直接提示“MCP server connection failed”，而这个错误往往不是你改改 JSON 就能解决的，得去服务端排查。建议在接 MCP 之前先用命令行单独测试 Server 能否启动，再配置给 Claude Code。

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

这部分是我在实际使用中遇到最多、也最容易被官方文档忽略的高频问题，逐一整理出来供参考，每一种都有对应的排查思路和解决方案。

第一条和第三条出现频率最高。关于命令找不到，本质是 npm 全局目录不在 shell 的查找路径里，遇到时先执行npm root -g看输出，再把对应的 bin 目录加进PATH，国内环境还要注意 Node 是否用的 nvm 多版本管理，版本切换后全局包会“消失”也是同一个原因。关于配置不生效，记住 Claude Code 的上下文加载机制——只读根目录下的 CLAUDE.md 和 .claude 目录，不会递归读取子目录下的配置，把配置文件放错位置是最常见的人为失误。

在稳定性方面还有两个实测心得：第一，尽量在前 10 轮对话内完成主要任务，越往后的对话 Claude Code 越容易产生“偷懒行为”——比如只给出修改建议而不真正动手，这时我会果断/clear开会新会话，同时把核心任务描述写得更精准；第二，遇到大任务一定拆解成小步骤逐个执行，让 AI 每完成一个步骤就汇报一次结果，这能极大降低出错概率。最后提一下卸载，npm uninstall -g @anthropic-ai/claude-code可以卸载程序本体，但~/.claude目录里会有配置和认证信息，不打算再使用的话记得一并清理干净。

8. 最后再分享一个我踩过之后觉得最值钱的配置习惯

说了这么多，如果你只能记住一件事，我希望是这个习惯：每次给 Claude Code 布置任务前，先用 30 秒想清楚三件事——这个任务的交付物是什么、边界范围在哪里、验收标准是什么。绝大多数“AI 不听话”的案例，根源不是工具笨，而是任务描述太模糊。Claude Code 是一个能力很强但高度依赖指示的“员工”，你把话说得越清楚，它干得就越漂亮。

不妨把你日常工作中最常重复的一个开发任务，试着用上文的方式完整地配置一遍：CLAUDE.md 补上项目背景和规范、settings.json 设好权限边界、再写一个 50 行的 Skill 封装你的工作流。这套“配置思维”一旦建立起来，Claude Code 就不再是那个只会写代码的终端工具，而是真正融入了你工程节奏的团队成员。配置的过程本身，也是在逼着你把“团队如何协作”这件事想得更明白。