AI AI 工具指南
AI 工具教程

Claude Code 项目配置——从空仓库到第一次有用运行

把 Claude Code 接上真实项目，30 分钟内进入有产出的状态。

发布于: 作者: AI Productivity Guide Team 🌐 查看英文版本

这篇主要解决什么问题

Claude Code 很强，但在真代码库上第一次跑就觉得选项太多——settings、permissions、CLAUDE.md、slash commands、MCP servers。大多数人跳过配置直接让它干大事，看到没法 review 的 diff 就放弃。这套配置 30 分钟把你带到产出基线：脚手架够 agent 用、护栏让你能审每一步、动大活之前先攒一次小成功。

这篇适合谁看

第一次在真实项目（不是玩具仓库）上试 Claude Code 的开发者，或几个月前装了试了一下就忘了的人。

什么时候适合用

新项目、加入已有代码库、或从 Cursor / Copilot 迁移到 agent 化 AI。也适合周末有空、想认真把工具配好、不想以后边用边补的时候。

什么时候不建议用

一次性脚本，配置开销比任务本身还大；不该让 agent 碰的代码库（没好测试的生产代码）；merge 前不做 code review 的团队；agent 能读到的位置存着明文密钥。

开始前准备

  • 仓库有最近一次干净 commit。Agent 的影响面就是从上次 commit 起的所有改动，先归零。
  • 装 Node 20+，命令行确认 npm/pnpm 能用。多数装不上是工具链老，不是 Claude Code 的锅。
  • 第一个小任务提前选好。一个类型修复、一个新测试、一个改名——不是”现代化整套 auth”。
  • 重读一遍仓库 README，方便在 CLAUDE.md 里总结而不是重写。

具体步骤

  1. 安装：npm install -g @anthropic-ai/claude-code，或按官方安装包装。claude --version 验证。
  2. 在项目根目录跑：claude。第一次浏览器握手授权。
  3. 根目录新建 CLAUDE.md：写项目说明、build / test / lint 命令、约定、绝对不要碰的文件。500 行以内；一两屏最佳。
  4. 在 .claude/settings.json 配置 permissions：放行常见安全命令（npm run test、git status、pnpm typecheck），破坏性命令（rm -rf、git push --force、npm publish）要审批。无识别的默认 ask。
  5. 挑一个小任务作为第一次运行：补一个类型修复、加一个单测、做一个小重构。先要计划：“先出计划，别写代码。”
  6. 盯着它做什么。跑偏立刻停——不要让坏 run 累积。取消很便宜，从 40 文件错 diff 回滚很贵。
  7. 每次有产出就 commit。把 commit 当 save point。下次 agent run 把上次 commit 当新基线。

第一次实操怎么跑

  1. 选一个没测试的丑工具函数。让 Claude Code：“为 src/utils/formatDate.ts 写当前行为的测试。覆盖 happy path + 3 个边界。先 diff。”
  2. 审完再批准写。跑测试，应当通过。
  3. Commit。再让它对同函数做小重构，重跑测试。
  4. 出岔的话准确记下哪一步。这条记录就变成 CLAUDE.md 里一条规则。

完成后检查

  • 每个 agent 步骤后和 main 对 diff。Agent 只应碰你预期的文件。
  • 每步后测试通过。没通过先回滚，绝不在坏状态上叠加。
  • 验证 agent 遵守了 CLAUDE.md 约束。没遵守一般是措辞模糊，加例子重写。
  • 看它建议的 commit message，不符合你仓库风格就改。

怎么复用这套流程

  • 配置跑通后模板化：.claude/settings.json 和 CLAUDE.md 骨架在新项目里复用。
  • 把最好用的 planning prompt 存下来（“只出计划。列文件、测试、范围外项。”），原样复用。
  • 形成习惯：agent run → diff → 测试 → commit → 重复。别因为”这次看着没事”跳步。
  • 每月回头看一次 .claude/settings.json——随着信任建立，安全命令清单会变。

建议的操作流程

第一天：装好 → CLAUDE.md 写好 build 命令 → “给 src/utils/formatDate.ts 写单测覆盖 3 个 case” → review diff → commit。信任了再做更大任务。第 5 天应当能自信地做跨文件改动。

FAQ

  • Cursor 还是 Claude Code？: Cursor 是 IDE 原生，Claude Code 终端 + agent。很多开发者两个都用——Cursor 快编辑，Claude Code 多步任务。参见 Claude Code vs Cursor。
  • Claude Code 会把代码改坏吗？: 会。永远在已提交的 repo 上跑，接受前 review diff。
  • MCP servers 呢？: 可选；先不上。基本流跑顺后再加 Playwright / 数据库 MCP。
  • Skills 和 slash commands 放哪？: 仓库内 .claude/commands/ 和 .claude/skills/，加上用户级 ~/.claude/。
  • 怎么和同事共享配置？: 把 CLAUDE.md 和 .claude/settings.json 提交。同事在 repo 里跑 claude 自动继承。

容易踩的坑

  • 不写 CLAUDE.md。每次跑它都会做错假设。
  • 第一天就给无限权限。学习曲线期间最容易出事。
  • 在没 git 或者有未提交改动的 repo 上跑。回滚路就没了。
  • 让它一口气跑 30+ 分钟不复查。长无人监督的 run 错误会累积。
  • 还没建立信任就要它干大活——第一周只做单文件改动。
  • 每条命令都无脑同意。前十几次任务每条都读，肌肉记忆才是安全。

进阶技巧

  • 风险任务用 git worktrees——主分支保持干净，让 Claude Code 在分支里实验。
  • 在 .claude/commands/ 加一个 /commit slash command，按你常用的 commit message 格式。
  • 对不熟的命令，让它”先解释这条命令会做什么再跑”——免费，避免事故。
  • 加一个 /plan slash command，自动前置”只出计划，不要写代码”——省每次的打字。

怎么验收输出

  • CLAUDE.md 写清项目、build/test 命令、红区文件。
  • .claude/settings.json 里 permissions 明确 allow/ask 规则。
  • 每次 agent run 前 repo 干净（已提交）。
  • 至少完整跑通过一个小任务。

相关阅读

标签: #Claude #教程 #Claude Code #工作流

相关文章