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

一句话总结

用原生安装脚本装好 Claude Code（curl -fsSL https://claude.ai/install.sh | bash），写一份简短的 CLAUDE.md，在 .claude/settings.json 里设好明确的 allow/ask/deny 规则，然后完整跑通一个小任务，再去碰大活。预算约 30 分钟。你需要付费方案——Pro 每月 $20（截至 2026 年 6 月已捆绑 Claude Code 和 Cowork）、Max $100 或 $200，或者 API/Console 账号。免费的 Claude.ai 方案不含 Claude Code。

这篇主要解决什么问题

Claude Code 确实能干活，但在真代码库上第一次跑，面对的是一整面陌生的墙：settings、permissions、CLAUDE.md、slash commands、subagents、MCP servers。常见的翻车方式是：全跳过，直接要它做一件大事，看到 40 个文件、根本没法 review 的 diff 就放弃。这篇把你带到一个有产出的基线：上下文够、agent 不再瞎猜；护栏够、你能审每一步改动；在动大活之前，先有一次完整的小成功垫底。

适合第一次在真实项目（不是练手仓库）上试 Claude Code 的开发者，或者几个月前装了、跑过一次、之后就吃灰的人。适合的时机：开新项目、加入已有代码库、或从 Cursor / Copilot 迁移到终端里的 agent。

什么时候不建议用

• 一次性脚本，配置开销比任务本身还大。
• 没有测试套件的生产关键代码——agent 没东西可验证。
• merge 前不做 code review 的团队。
• 任何 agent 能读到、且存着明文密钥的目录。把 .env 和 secrets/** 放进 deny 列表（下面会讲）。

开始前准备

• 先搞定付费方案。 Claude Code 需要 Pro、Max、Team、Enterprise 或 Console（API）账号。Pro 每月 $20，现已捆绑 Claude Code 和 Cowork。免费 Claude.ai 账号跑不了。
• 从干净的 commit 起步。 Agent 的影响面就是上次 commit 之后的所有改动，所以先 commit（或 stash），留好回滚点。
• 装好 Git。 在原生 Windows 上，装 Git for Windows 能让 Claude Code 用 Bash 工具，而不是只能走 PowerShell。macOS 和 Linux 本来就有 shell。
• 第一个小任务提前选好。 一个类型修复、一个新测试、一次改名——不是”现代化整套 auth”。
• 快速过一遍仓库 README，这样在 CLAUDE.md 里能直接总结，而不是从头重写。

安装 Claude Code

截至 2026 年 6 月，原生二进制安装脚本是 Anthropic 官方推荐方式——不需要 Node.js，还会在后台自动更新。

# macOS、Linux、WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Homebrew（macOS/Linux）——不会自动更新
brew install --cask claude-code

如果你更习惯 npm 也还能用（需要 Node.js 18+），只是它已经不是默认路径了：

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

先验证安装，再做一次深度检查：

claude --version
claude doctor

claude doctor 会报告你的安装方式、版本，以及上一次自动更新的结果——遇到任何不对劲，先跑它。

具体步骤

1. 在项目根目录启动 Claude Code： 跑 claude。第一次启动会打开浏览器握手，用你的 Claude 账号授权。

2. 在仓库根目录新建 CLAUDE.md。 用一段话写清项目是什么，列出准确的 build/test/lint 命令，写下约定，点名 agent 绝对不能碰的文件。保持精简——一两屏胜过 500 行，因为里面的内容每次运行都会被读进上下文。你也可以跑 /init，让 Claude Code 根据代码库先起个草稿，再删减。

3. 在 .claude/settings.json 里配权限。 规则按 deny → ask → allow 的顺序评估，第一条匹配的生效，所以 deny 永远优先。一个安全的起步配置：

   \{
     "permissions": \{
       "allow": [
         "Read",
         "Grep",
         "Glob",
         "Bash(npm run test:*)",
         "Bash(npm run lint:*)",
         "Bash(git status)",
         "Bash(git diff:*)",
         "Bash(pnpm typecheck)"
       ],
       "ask": [
         "Bash(git push:*)",
         "Bash(npm install:*)"
       ],
       "deny": [
         "Read(./.env)",
         "Read(./secrets/**)",
         "Bash(rm -rf:*)",
         "Bash(git push --force:*)",
         "Bash(npm publish:*)"
       ]
     \}
   \}

   没匹配上的会回退到弹窗询问，这正是早期你想要的。

4. 第一次真正改动用 Plan Mode。 按 Shift+Tab 切到 Plan Mode，或者直接说：“只出计划。列出你会改的文件、要加的测试、以及范围外的项。先别写代码。“在它写下任何一行之前，先读计划。

5. 盯着它跑，一跑偏立刻停。 取消是免费的，从 40 个文件的错误 diff 里恢复可不便宜。

6. 每次有产出就 commit。 把 commit 当 save point——之后每次 agent run 都会把最新的 commit 当成新基线。

第一次实操怎么跑

一个 15 分钟、零风险、能攒信任的循环：

1. 选一个没测试的小工具函数。告诉 Claude Code：“为 src/utils/formatDate.ts 写当前行为的测试。覆盖 happy path 加 3 个边界。写之前先给我看 diff。”
2. 审完那份测试文件再批准写入。跑测试套件，应当通过。
3. Commit。然后让它对同一个函数做一次小重构，重跑测试。
4. 如果哪里出岔，准确记下是哪一步挂的。这条记录就写进 CLAUDE.md 变成一条规则——配置就是这样越用越好的，而不是反复踩同一个坑。

每一步之后的质量检查

• 和 main 对 diff。 Agent 只应碰你预期的文件。出现意外文件，说明计划太松。
• 测试通过。 没通过就先回滚再继续，绝不在坏状态上叠加。
• CLAUDE.md 被遵守了。 某条约束被忽略，多半是措辞太模糊；加一个具体例子重写这条规则。
• 建议的 commit message 符合你仓库风格。 不符合就改掉。

进一步：subagents、slash commands、MCP

基本循环用顺之后，三类功能按价值排序逐步加：

功能	是什么	什么时候加
Plan Mode	内置的只读规划，先规划再改（Shift+Tab）	第一天起，每个非琐碎任务
Slash commands	.claude/commands/*.md 里的可复用 prompt（比如带你 message 格式的 /commit）	同一段 prompt 你打第二遍时
Subagents	有独立上下文的专用实例——内置含 Explore（只读）和 Plan	大代码库调研、否则会撑爆主上下文时
MCP servers	连接外部工具的连接器（Playwright、数据库、GitHub）	等核心循环稳了再加，一次加一个

加一个 MCP server，比如：claude mcp add playwright npx @playwright/mcp@latest。一开始一个都别加——它们是额外的活动部件，多数第一个项目根本用不上。

容易踩的坑

• 不写 CLAUDE.md。 每次跑它都会做错假设。
• 第一天就给无限权限。 学习曲线期恰恰是出大事的时候。破坏性命令保持在 ask 或 deny。
• 在脏的或没 git 的 repo 上跑。 没有干净 commit 就没有回滚路。
• 让它无人监督跑 30+ 分钟。 长 run 会把一堆小错攒成一个没法 review 的大 diff。
• 还没建立信任就要它干大活。 第一周只做单文件改动。
• 每个弹窗都无脑同意。 前十几次任务每条都读。这个习惯才是安全机制，不是那份权限文件。

怎么复用这套配置

• 模板化：把 .claude/settings.json 和一份 CLAUDE.md 骨架在新项目里复用。
• 把最好用的 planning prompt 存下来（“只出计划。列文件、测试、范围外项。”），原样复用，或者做成一个 /plan slash command。
• 养成习惯：规划 → 运行 → diff → 测试 → commit → 重复。别因为”这次看着没事”就跳步。
• 每月回看一次 .claude/settings.json。随着信任建立，哪些命令可以放心自动放行会变。

常见问题

用 Claude Code 一定要付费方案吗？ 是的。截至 2026 年 6 月，Claude Code 需要 Pro（每月 $20，捆绑 Claude Code 和 Cowork）、Max（$100 或 $200）、Team、Enterprise，或 Console（API）账号。免费的 Claude.ai 方案不含它。

Claude Code 跑什么模型？ 只跑 Anthropic 的模型——最难的活用 Claude Opus 4.7，日常主力是 Sonnet 4.6，两者都是 100 万 token 上下文。它不跑 GPT-5.5，也不跑 Gemini。需要那些就得用 Cursor 或别的多模型 IDE。

Cursor 还是 Claude Code，用哪个？ Cursor 是 IDE 原生、支持多模型；Claude Code 是终端原生、agent 化、只用 Anthropic 模型。很多开发者两个都用：Cursor 做快速行内编辑，Claude Code 做多步任务。参见 Claude Code vs Cursor。

Claude Code 会把我的代码改坏吗？ 会。永远在已提交的 repo 上跑，把破坏性命令放进 deny 列表，接受前 review 每一份 diff。

Slash commands 和 skills 放在哪？ Slash commands 是 .claude/commands/ 里的 Markdown 文件；skills 是 .claude/skills/ 下的 SKILL.md 文件。两者也能放在用户级的 ~/.claude/。在会话里打 / 就能列出所有可用项。

怎么和同事共享配置？ 把 CLAUDE.md 和 .claude/settings.json 提交进仓库。同事在 repo 里跑 claude 就自动继承两者。机器相关或含密钥的覆盖项放进 .claude/settings.local.json，它默认被 git 忽略。

相关阅读

• Claude Code 新手指南
• Claude Code 工作流
• Cursor vs Claude Code
• Claude GitHub 集成——真用起来的工作流
• Claude Code 的项目 prompt 怎么写
• Claude Code 官方安装文档
• 官方权限配置参考

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

相关文章

AI 工具教程

AI 生成更新日志：从 commits 到人愿意读完的 release note

把 git log 变成读者真会读完的两层 release note，再用一道评审抓出被藏起来的 breaking change。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI 协作数据库迁移——可回滚、有回填、能测

AI 在迁移上最常错的三件事：可回滚、回填策略、大表上的 NOT NULL。

2026/05/24 #AI 编程 #工作流

AI 工具教程

用 AI 写事故复盘，又不冲淡教训

一套用 AI 在 60 分钟内出一份无指责复盘初稿的流程，同时不让模型把难听的真相圆掉。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI 解 merge 冲突：什么时候能信自动合

AI 几分钟能解掉大多数 merge 冲突，真正的功夫在于知道哪 10% 它绝不能碰，以及怎么抓住「靠删一边来合并」这种故障。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI on-call 排障：从被叫醒到修好不慌

凌晨 3 点被 page 了？一套实测过的 AI 流程——分流、给假设排序、破坏性命令前的冷静协议，再把聊天沉淀成 runbook。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI 写 PR 描述——从 diff 到能审

把 git diff 变成 reviewer 真愿意打开看的 PR 描述，prompt 不会编出根本不存在的 test plan。

2026/05/24 #AI 编程 #工作流