企业官网建设流程全解析

如果你和我一样，每天在终端和编辑器之间来回切换，你一定试过把一大段代码复制到网页对话框里，问“这段代码哪里有问题”。我过去也这么干，直到开始用claude-code，这个习惯彻底改了。它是一个跑在终端里的 AI 编程代理，不是简单的聊天机器人，而是能直接读你仓库、改你文件、执行命令、跑测试的“结对程序员”。这篇文章我会从安装配置、项目记忆、权限控制、MCP 扩展，到一次真实的 Bug 排查复盘，再把踩过的坑和技巧整理出来，希望能帮你少走弯路。

1. Claude Code 是个什么工具，为什么能提高开发效率

先说清楚定位：claude-code是 Anthropic 官方推出的命令行 AI 编程工具，本质上是一个运行在终端里的 Agent。你给它一个任务，它自己规划步骤、调用工具（读文件、搜索、编辑、执行命令）、最终给出可验证的结果。它跟我以前用过的所有“AI 补全插件”最大的区别是：它真的有手有脚，能直接把改动落在代码里。

我第一次用的时候其实挺震撼的。进入一个老项目的目录，输入一句“帮我看看这个项目的模块划分和入口流程”，它不是凭空给你一段泛泛而谈，而是真的去ls、cat、grep，把关键文件打开，然后基于实际代码内容回答。这种感觉像突然多了一个熟悉代码库的同事，而不是一个只能聊天的资料库。

1.1 它和网页版/IDE 插件最大的区别

很多人问：那和网页版 Claude、或者 Cursor、Copilot 这类 IDE 工具有什么区别？我自己的体感是这样：

网页版 AI 的核心问题是缺少真实上下文。你粘贴一段代码进去，它只能基于这段代码和你补的描述猜测，一旦问题跨文件、跨模块、牵扯历史逻辑，网页版就很容易“一本正经地胡说八道”。而且你没法让它真的去执行命令跑测试，它只能“建议”你跑，最后动手的还是你自己。

IDE 插件更进了一步，尤其是 Cursor 这类工具，可以索引整个仓库。但它们的落点还是“编辑器”——你和 AI 的交互更多发生在补全、对话框、Diff 面板里，中间隔着一层编辑器抽象，有时候反而增加认知负担。而且 IDE 插件通常需要 GUI 环境，在服务器上、在 CI 流水线里或者纯终端工作流下就不太方便。

claude-code恰好补上了这个空档：它完全以终端为家，当前目录就是工作目录，所有操作都围绕真实文件系统展开。它可以直接修改源码、创建测试文件、跑pnpm test看结果、根据报错继续修，直到任务闭环。它不依赖某个特定编辑器，你在任何环境——本地、远程服务器、容器、CI——都能用同一套方式工作。这在日常开发里是巨大的便利，因为你不需要把 AI 工具“接入”你的工作流，它本身就是工作流的一部分。

1.2 适合哪些场景和人群

用了一段时间后，我总结出它最擅长的四类场景：

第一，老项目调研。接手一个没文档、没注释的项目，让它先读代码、梳理模块、找出入口和依赖关系，效率极高。这比我肉眼翻代码至少快一个数量级。

第二，跨文件 Bug 修复。比如一个报错在接口层，根因却在数据层，中间隔着好几层调用。它能顺着调用链一路查下去，而不是只看报错堆栈那一行。

第三，批量重构和测试补齐。给一个明确的重构目标，它可以在多个文件里执行模式统一的修改；让它给模块补单元测试，它会把边界情况也考虑进去。

第四，需要自动化的场景。给 CI 里配置一个任务，让它用无人值守模式跑代码修复和静态检查，是一个很实用的玩法。

但也有不适合的人群和场景。如果你是编程新手，连 diff 都看不懂、不知道 AI 改的代码会不会引爆线上问题，那我建议你先别把它当成“自动写码机”来用。它更像一个水平不错但需要你审查的初级工程师——你的代码审查能力决定了协作质量。对于高度依赖特定黑话、领域规则极强、或者一次改动涉及几十个文件的超大重构，我也更倾向于把它拆成多步周任务，而不是一次性丢给它。

2. 首次安装与项目接入的完整流程

安装和接入这一步不复杂，但有几个细节会卡人，尤其是第一次用的朋友。我把完整过程写下来，按步骤操作基本不会出问题。

2.1 环境依赖与 npm 安装

claude-code是一个 npm 包，所以本机需要提前装好 Node.js 和 npm。我自己的环境是 Node.js 20，实际用下来 18 及以上都可以，太老的版本会报依赖不兼容。

全局安装命令很简单：

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

装完检查版本：

claude --version

能打印出版本号就说明装好了。如果你之前装过旧版本，建议用同一命令升级，它会把本地配置保留下来。

有几个安装时容易遇到的问题我顺手说一下。如果 npm 全局安装目录没有写权限，你可能需要配置 npm 的 prefix 或者用 sudo，但我不推荐直接 sudo 装 npm 包，权限问题后续会一直纠缠你。更稳妥的做法是调整 npm 全局目录到用户目录下。另外，如果国内网络环境安装缓慢，可以先把 npm registry 切到镜像源，装完再切回来，这不影响工具本身使用。

2.2 登录认证与首次启动

安装完成后，在任意目录输入claude，就会进入交互式命令行界面。第一次启动会引导你完成登录认证，目前主流方式有两种：一种是使用 Claude 账号登录，会走浏览器授权流程；另一种是使用 API Key。

我日常用的是 API Key 方式，环境变量设置好之后启动：

export ANTHROPIC_API_KEY=你的key claude

如果你不想每次 export，可以把写入 shell 配置文件（比如.zshrc）。需要注意：API Key 是敏感信息，千万别提交到 git 仓库或者截图发群里。丢了可以作废重生成，泄露到公网是实打实的事故。

首次启动成功后会显示版本信息、当前模型和可用的交互提示。到这一步，工具已经可以用了。

2.3 在真实仓库里跑通第一次对话

我强烈建议你第一次使用不要在一个空目录里试，而是找一个真实的项目仓库，这样才看得出它的能力边界。进入项目目录：

cd my-project claude

进去之后，先别急着让它写功能，你可以对它说：

“帮我看看这个项目的目录结构、技术栈和核心入口，先不要改任何代码。”

它会很快列出文件树、解读package.json、定位入口文件，并且用你能看懂的话把项目骨架说清楚。我印象最深的是，它确实会自己去打开文件看内容，而不是靠目录名瞎猜。这一步跑通了，你就建立了对它的初步信任感。

随后你可以输入/init，让它在项目里生成一个CLAUDE.md文件。这是它后续理解项目的记忆锚点，下一节我会专门讲这个文件的威力。

3. 写进 CLAUDE.md 的项目记忆玩法

用过几轮你一定会发现：每次新开会话，AI 好像不记得上一个会话说了什么。这是 Agent 工作模式的天然限制——每次会话的上下文是新的。但claude-code提供了一个非常关键的机制来弥补：项目记忆文件。这个文件用好之后，AI 的稳定性会提升一个档次。

3.1 建好记忆文件，让 AI 懂工程规范

CLAUDE.md是放在项目根目录的 Markdown 文件，也可以是仓库某个子目录下的CLAUDE.md，作用是在每次会话开始时自动被加载进上下文，相当于给 AI 一份“项目操作手册”。

这个文件可以写什么？我建议至少包含四块内容：

• 项目结构和职责边界：哪些目录是源码、哪些是构建产物、哪些是生成文件千万别改。
• 常用命令：安装依赖用什么、跑测试用什么、lint 用什么、构建用什么。
• 代码风格和命名约定：组件命名、工具函数命名、是否使用 TypeScript、API 返回格式统一规格。
• 禁止事项：比如“不要把环境变量写进代码”“不要直接改数据库”“不要动 lock 文件”。

为什么要写这么细？因为 Agent 和聊天机器人不一样，它是会动手的。如果你不明确告诉它“dist 目录是构建产物，绝对不能改”，它完全可能在某个操作里不小心动到生成文件，然后让你排查半天。明确边界，既是保护项目，也是在给 AI 减负——它不用每次猜。

3.2 几个值得推荐的配置片段

我拿自己维护的一个 Node.js 服务项目举例，根目录的CLAUDE.md是这样的：

# 项目约定 ## 技术栈 - Node.js 20 + TypeScript + Express - 包管理器为 pnpm ## 常用命令 - `pnpm install` 安装依赖 - `pnpm dev` 启动开发服务 - `pnpm test` 运行单元测试 - `pnpm lint` 运行 ESLint ## 目录结构 - `src/` 源码目录 - `src/routes/` 接口路由层 - `src/services/` 业务逻辑层 - `src/models/` 数据模型层 - `tests/` 单元测试目录 ## 代码风格 - 文件名使用 camelCase - 组件和类名使用 PascalCase - API 统一返回 `{ code, data, message }` 格式 - 错误处理统一走 `AppError` 类 ## 禁止事项 - 不要修改 `dist/` 下的任何文件 - 不要修改 `public/` 下的静态资源文件 - 不要删除 `CHANGELOG.md` 中的历史内容 - 修改数据库迁移前必须先在 `README.md` 中阅读迁移流程

这个文件写完之后，后面再开新会话，它跑测试知道用pnpm test，返回格式不会乱写，也不会去乱动 dist 目录。配置的前期成本很低，后期的节省非常明显。

我还试过在子目录放局部的CLAUDE.md，比如src/services/CLAUDE.md，只描述这个目录下的业务规则。这样遇到深层任务时，它能获取更精确的局部约束。

3.3 记忆文件的维护节奏

CLAUDE.md不是写一次就一劳永逸。我的维护习惯是：每当我发现 AI 在某个约定上反复犯同样的错误，就会把这个约定补进文件里。比如有几次它总喜欢给 select 的 SQL 加ORDER BY id，但业务上其实应该按created_at排序——纠正两次之后，我写进了文件，之后再没犯过。

另一个时机是项目发生结构性变化时，例如新增了一个目录规范、切换了包管理器、调整了 API 返回格式，这时要第一时间更新记忆文件。

还要提醒一点：CLAUDE.md不是越长越好。它会被加载进上下文，占用 token 空间。我的经验是控制在 80 到 120 行为宜，只写真正重要且稳定的规则。如果啥都往里塞，文件臃肿不说，AI 反而可能忽略关键条目。

4. 权限、MCP 与 hooks：把控制权握在自己手里

很多开发者第一次用 Agent 类工具时最大的顾虑是：它改我代码，改坏了怎么办？这个担忧合理。claude-code提供了几个层面来管理风险，用好它们，你就能安心地把工作交给它，同时把控制权牢牢握在自己手里。

4.1 权限模式

交互式模式下，默认会对文件编辑和命令执行进行询问。你同意它才执行，相当于每一步都过你的手。这个模式对新手最友好，但用久了会发现弹窗略多。

为了效率，我一般分两段走。第一阶段用只读模式做侦查，让它只读文件、搜索、梳理思路，不改任何东西：

claude --permission-mode plan-only

它输出一份分析和实施计划，我看过觉得靠谱，再进入第二阶段，正常写权限模式下执行。启动时指定模式，也可以在会话中用/permission切换。

对于bash命令，权限规则也支持粒度控制。可以设置某些危险命令（比如rm -rf、迁移命令）必须每次询问，而像pnpm test、git diff这类安全命令自动放行。这个配置在项目中的.claude/settings.json里可自定义。

我的原则是：不要给 Agent 绝对的默许信任。你可以让它全自动跑，但请放在容器、CI 这类隔离环境里，而不是直接在本地裸跑全权限模式。它本质上是一个执行能力很强的程序，边界必须你来定。

4.2 MCP 扩展

MCP 全称是 Model Context Protocol，你可以把它理解成给模型外挂“工具箱”的标准协议。claude-code支持接入 MCP 服务器，从而让 AI 调用外部服务或数据源。

举个例子。我有一个内部接口文档站，字段说明和回调状态码很多。以前 AI 改代码时要我手动贴文档到对话里，费时又占上下文。后来我接了一个 MCP 服务器，把接口文档封装成可查询的工具。AI 在改造代码时，直接调工具去查接口签名和字段定义，准确率明显提高，也不再需要我来回粘贴资料。

MCP 的适用场景很广：连数据库查询表结构、读日志系统、调用内部搜索、访问项目 Wiki。你可以用现成社区服务器，也可以写一个轻量 Node/Python 服务。配置方式是在.claude/settings.json里注册 mcpServers：

{ "mcpServers": { "my-api-docs": { "command": "npx", "args": ["-y", "my-api-docs-mcp-server"] } } }

对我来说，MCP 最大的价值不是增加“功能”，而是把外部知识变成 AI 可主动调用的资产。你不需要预先把所有信息塞进上下文，它需要时会自己去取。这一下就绕开了上下文窗口的根本瓶颈。

4.3 hooks 自动化

hooks 是事件触发的自动化脚本，可以理解为 Git 钩子的 Agent 版本。它能在特定事件发生后执行命令。我目前用到的主要是两个场景：

一是代码编辑后自动跑 lint。AI 改完文件，立刻触发pnpm lint，如果有格式问题，它能及时收到反馈并修复。这比人工 review 完丢给 CI 发现 lint 挂了要快得多。

二是会话结束时把摘要写入笔记文件。这样每次工作的产出、决策和遗留问题都有记录，下次用/resume恢复会话时能快速找到上下文。

hooks 配置同样写在.claude/settings.json里，比如一个编辑后钩子：

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "pnpm lint --fix" } ] } ] } }

讲真，hooks 是进阶玩法，新手可以先用权限控制和 CLAUDE.md。但如果你想让claude-code真正适配团队规范、在无人值守的管道里跑起来，hooks 几乎是必须掌握的。

5. 实战复盘：用 Claude Code 修一个线上 Bug

讲了这么多配置和原理，来一次真实的实战吧。这是最近让我对 Agent 能力印象很深的一次：后端订单模块偶发 500，最后就是靠claude-code定位并闭环修复的。完整过程我尽量还原。

5.1 任务描述与初始提示

当时线上日志显示，订单列表接口偶尔返回 500，报错信息指向customerId为空导致序列化异常。问题是偶发，本地稳定复现不了，手工排查要翻一大圈代码。

我进入后端仓库，给了它这样一个任务描述：

“订单列表接口偶尔 500，日志报错是 customerId 为 null 导致序列化失败。帮我排查根因，先不要改代码，分析完把疑似位置和依据列出来。”

注意我在描述中明确了验收标准和约束条件：“先不要改代码”。这一步很重要的原因是，如果没说这句，Agent 很可能在给出分析的同时直接动手改，打乱我的节奏。给它一个“只读-分析”的任务阶段，我就能先看思路再决定后续方向。

5.2 排查过程

它没有直接从日志报错的那一行开始猜，而是先从订单列表接口入口切入，找到了对应的 service 和 SQL 查询逻辑。随后追踪到customerId的出处是一次 JOIN 查询，发现这个查询用了LEFT JOIN关联用户表，但后续没有对用户是否存在进行判断。对部分已注销的软删除用户来说，关联结果为空，customerId就成了 null，进入 JSON 序列化后抛异常。

它把关键代码路径贴出来，还给出了证据：哪个文件哪一行取值没判空、序列化阶段的哪个类不允许字段为 null。整个过程像是一个有经验的开发者在单向讲述推理链，而不是丢一个结论让你去验证。

看完后我没急着让它改，而是让它执行了一条只读命令，拉出一个测试订单的数据看看。这一步是为了验证它描述的“软删除用户”是否真的存在。它跑完命令后，把数据和预判对应了起来。

5.3 代码修改与验证

确认根因后，我让它进入修改阶段，指令变成：

“按你刚才的分析修复，注意兼容正常用户和软删除用户两条路径。补一个单元测试覆盖这个场景。改完跑全部测试。”

它先改了 service 层，把取customerId的逻辑加上判空和默认值处理，保证序列化阶段不拿到 null；然后补了一个针对软删除用户的单测；最后执行了pnpm test，全部通过。整个过程我只需要在关键节点审批命令执行和过一遍 diff，不需要一行一行手把手教它怎么写。

这个用例给我最大的启发是：Agent 类工具最适合的任务，恰恰是那些“线索隐藏在多文件调用链”里的问题。它能快速展开调用链，记录中间推理，不遗漏上下文，而人脑做这类跨文件追踪往往费时费力。

6. 我在实践中踩过的坑与排查清单

没有哪个工具是不踩坑的。我这几个月用下来，也遇到不少问题，有些很快就定位了，有些折腾了不短时间。整理成清单供你参考。

6.1 常见问题速查表

下面这个表格基本覆盖了我遇到的高频问题，可以直接对照排查：

6.2 关于上下文与 token 消耗的几点心得

无论用哪种 AI 工具，上下文管理都是绕不开的话题。claude-code每次会话能容纳的上下文虽然不小，但也不是无限。如果任务特别重，会发现后面它的“记忆力”变差，开始忽略前文说过的话，像是人连续高强度工作一下午后的状态。

我的做法是把大任务拆成多个小会话。比如一个“新增报表模块”的任务，我会拆成：设计数据结构一个会话、编写接口一个会话、写前端页面一个会话。每个会话目标明确，上下文干净，效果比一个会话里从头干到尾好很多。

CLAUDE.md也不是越详细越好。上下文窗口是稀缺资源，记忆文件过于臃肿，留给真实任务的空间就少了。我通常只保留稳定且重要的约定，边边角角的东西让它遇到问题现查。

token 消耗直接关系成本。如果觉得每次任务烧得太快，可以换更经济的模型，或者在非交互模式下用一个合理的最大预算。此外，别让它无意义地反复扫全仓库。一个明确的CLAUDE.md、一次聚焦子目录的操作，都能明显降低 token 用量。

6.3 几条提高成功率的常用技巧

分享几个我个人认为最关键的工作技巧，它们能让 Agent 的产出质量提升一个台阶。

第一，任务描述里带上“验收标准”和“禁止事项”。光说“优化订单查询性能”太模糊，要补充“N+1 查询必须改掉”“SQL 不能动索引”“完成后跑压力测试”这类明确边界。越具体，它发挥越稳定。

第二，让 AI 先给计划再执行。默认交互式模式下，你可以直接让它“先列出实施步骤，我来确认”。这个过程像代码评审中的设计评审，提早发现方向性错误，避免它写完一大半你才发现思路不对。

第三，每次大改动前要求它创建一个新分支。你可以让它执行“建分支、改代码、跑测试、汇报 diff”，这样即使改砸了，主分支也是安全的，回退成本极低。

第四，善用/resume继续工作。如果夜里有任务没完成，第二天进到仓库输入/resume，它能找回上个会话的上下文继续干，省去重新描述的功夫。

第五，改完必看git diff，尤其是 AI 自动生成的改动。它不是神，也会犯低级错误，比如把测试文件的某一段不小心改掉。保留人工审查这一步，Agent 能帮你干活，但不能替你背锅。

最后说一点个人的体会。用claude-code几个月，我觉得最准确的定位是“一个高水平的初级开发者和搜索机器人的合体”。它的上限其实取决于使用者——你怎么定义任务边界、怎么设计验收标准、怎么审查产出，直接决定了最终质量。把它当成一个需要你带、需要你把关的结对工程师，而不是全自动写码机，长期使用下来你会越来越顺手，它也会越来越懂你的项目。