Claude Code 项目实战：从安装到工程化协作

Claude Code 项目实战：从安装到工程化协作

学习目标

完成后你将能够：

• 把 Claude Code 作为日常开发工具融入自己的工作流
• 用 CLAUDE.md 让它「记住」项目约定，避免每次重复交代
• 安全地让它完成跨文件重构、修 Bug、写测试等成体系的任务
• 建立团队级的 AI 协作规范，让 AI 改动可控可审

前置准备

• Node.js 18+
• 一个你熟悉的真实项目（最好是自己的仓库，方便验收 AI 的改动）
• 终端基础：会看 diff、会 git 暂存与回退

步骤 1：安装与配置

npm install -g @anthropic-ai/claude-code
cd your-project
claude

首次启动按引导完成登录。VS Code 用户可装官方插件获得编辑器内体验。

权限模型一句话：读操作默认允许，写文件与执行命令默认逐次确认。信任度由你在会话中逐步放行，也可以按项目配置白名单。

步骤 2：理解它的工作方式

Claude Code 是工具型 Agent，每轮循环是：理解任务 → 决定动作（读文件/搜索/改文件/跑命令）→ 执行 → 观察结果 → 继续，直到完成任务。

两个关键推论：

1. 它的产出质量取决于上下文质量——项目结构清晰、约定明确，它就表现得像熟手；仓库混乱，它就跟着混乱。 2. 它的行动可以被引导——你给方案它执行，比自己写代码快；你只给目标它自己规划，适合探索性任务。两种模式按风险选择。

步骤 3：写好 CLAUDE.md（最重要的一步）

在仓库根目录创建 CLAUDE.md，让每次会话自动带上项目记忆。推荐结构：

# 项目简介
两三句话说清这是什么项目、技术栈、运行方式。

# 常用命令
- npm run dev        # 本地开发
- npm run test       # 全量测试（改动后必须跑）
- npm run lint       # 提交前必须通过

# 项目约定
- 组件放 components/，页面放 app/，禁止跨层引用
- 提交信息用中文，格式：<类型>: <一句话>
- 不要引入新的 UI 库，样式用现有 Tailwind 体系

# 已知坑
- build 前必须先跑 export 脚本，否则搜索索引是旧的
- windows 下路径分隔符问题，统一用 path.join

写 CLAUDE.md 的原则：只写「不写它就会做错」的事。它不知道的团队习惯、隐藏依赖、历史包袱，全在这里说清；常识性的东西不用写。

步骤 4：实战一——多文件功能开发

任务示例：「给现有博客加一个文章草稿模式：草稿不出现在列表与 RSS 中」。

推荐节奏（小步快跑）：

1. 先对齐方案：「先看代码，给我实现方案，不要改文件」——让它在理解现状后列出改动清单 2. 确认边界：核对它找到的改动点是否遗漏（RSS、sitemap、详情页路由这类容易被忽略的角落实地逐条检查） 3. 分段执行：按「数据层 → 列表过滤 → 详情页守卫 → RSS」逐段实现，每段确认后再下一段 4. 跑测试与构建：让它在完成每个阶段后运行项目定义的检查命令

步骤 5：实战二——测试驱动的 Bug 修复

修 Bug 的黄金流程：

1. 提供复现步骤或报错堆栈，让它先定位根因（只读模式） 2. 要求它先写一个能复现 Bug 的失败测试 3. 再修代码，直到测试变绿 4. 最后让它检查同类问题在别处是否存在（「同样的问题还有哪些地方可能出现？」）

这个流程的价值：修复被测试锁定，Agent 的改动再激进也不会悄悄回退。

步骤 6：大改动用计划模式

涉及架构调整、批量重构、依赖升级时，用计划模式（Plan Mode）：它只产出实施计划不动代码，你审完计划再批准执行。适用判断标准——如果你不确定要让它改哪些文件，就先用计划模式。

配套技巧：

• 大改动拆成多个可独立验收的小提交
• 每个提交前跑一次 lint + test，不让错误滚雪球
• 改坏了就 git diff 审查，不放心整体回退，单次会话的改动是干净可逆的

步骤 7：团队协作规范

• CLAUDE.md 进仓库：项目约定团队共享、版本化演进，谁踩了坑就补一条
• AI 改动照常走 PR：不因为是人机协作就跳过 Review；Review 关注点从「逐行看代码」转向「看方案、看边界、看测试覆盖」
• 敏感操作清单：数据库迁移、支付逻辑、密钥相关文件列为 AI 禁区，写进 CLAUDE.md
• 成本意识：探索性任务用新会话小上下文，长会话及时收口

常见错误

| 错误现象 | 原因 | 解决方法 | |----------|------|----------| | 改了不相关的文件 | 任务太宽泛 | 先要方案再执行；大改动用计划模式 | | 每次都要重新交代背景 | CLAUDE.md 缺失 | 把项目约定沉淀进仓库 | | 重构后功能坏了 | 无测试兜底 | 先补测试再重构，小步提交 | | 长会话越来越笨 | 上下文过载 | 开新会话，靠 CLAUDE.md 承接记忆 | | 提交信息与团队风格不符 | 约定未同步 | 提交规范写进 CLAUDE.md |

进阶扩展

• 自定义命令：把团队常用流程（如「发版检查清单」）写成可复用命令
• 与 CI 结合：让它根据 CI 失败日志自动定位修复
• 配合 MCP：接入内部系统（工单、文档库），从「读代码」扩展到「读业务」

参考资源

• Claude Code 官方文档 - 安装、权限与配置说明
• Anthropic Claude Code 仓库 - 更新日志与反馈
• 本站词条 [AI 智能体](/keywords/ai-agent)、[Agent Skill](/keywords/agent-skill)
• 本站教程 [MCP Server 开发实战](/learn/mcp-server-development)