跳到主要内容

Claude Code 使用指南（终端里的 AI 搭档）

TL;DR：Claude Code 是面向终端的 AI 编程助手，能在权限允许下 读仓库、改文件、跑命令。它特别适合“需要深度思考”的任务：架构决策、复杂调试、大重构、自动化脚本。最稳的用法是：描述 → 计划 → 执行 → 验证。

你能从这份指南得到什么​

用 15-30 分钟完成 Claude Code 的安装与权限设置，并掌握一套稳定的终端工作流，用于调试、重构与自动化。

快速上手清单：

  • 安装 CLI 并确认命令可用
  • 在仓库根目录运行，避免上下文缺失
  • 固定使用“描述 → 计划 → 执行 → 验证”闭环
  • 权限保持保守，确有需要再逐步放开
  • 用 pnpm lint / pnpm typecheck / pnpm build（或仓库等效命令）做验证

在你开始之前：3 条安全原则（强烈建议）​

  1. 永远先看 diff 再合并：AI 写得快，也能把 bug 写得更快。
  2. 把验证写进流程：每一步都要有“我怎么确认它真的对”。
  3. 权限默认保守：先分析，再小步放开“写文件/跑命令”。

Claude Code + Cursor：最稳的组合方式​

如果你同时用 Cursor（IDE）和 Claude Code（终端），一个很稳的分工是：

  • Cursor：导航、编辑、多文件落地、快速迭代
  • Claude Code：计划、深度排错、批量机械改动、运行验证命令、生成发布/排错文档

当你要做“大改动”时，建议先用 Claude Code 把任务拆成可执行清单，再回到 Cursor 逐步落地。

让 Claude Code 真正“看懂仓库”的上下文策略​

终端工具的优势是能读文件，但前提是你给对目标。建议每次都明确：

  • 入口在哪里（路由/命令/页面）
  • 相关文件路径（先给 2-5 个最关键的）
  • 约束（不加依赖、保持 API、保持目录结构）
  • 验证命令（lint/typecheck/build/tests）

当你不确定给哪些文件时，让它先回答：

  • “为了完成这个任务，你需要读取哪 5 个文件？为什么？”
  • “最小改动方案是什么？风险在哪里？”

Claude Code 适合解决什么问题？​

把 Claude Code 当成“终端里的高阶搭档”最划算的场景是：

  • 复杂排错：日志 + 配置 + 运行行为需要一起推理
  • 跨文件重构：需要拆步骤、做机械改动、逐步验证
  • 自动化脚本：把重复工作变成脚本（生成清单、批处理、检查脚本）
  • 写作类产出：PR 描述、变更说明、迁移文档、排错手册

不太适合的场景（或需要更强约束）：

  • 你无法验证输出（不跑命令/不看 diff）
  • 安全关键改动（鉴权/权限/加密）想“一次交付完成”
  • 对上下文非常敏感但你又不愿意给文件路径/代码片段

权限怎么开才安全？​

Claude Code 的威力来自“能读文件/改文件/跑命令”，风险也来自这里。建议默认从保守开始：

  1. 只读分析：先让它定位问题、给方案，不执行
  2. 允许编辑文件：只在明确目标时打开写权限
  3. 允许跑命令：只允许你认可的验证命令（lint/typecheck/build/tests）

经验法则：任何可能影响 Git 历史、删除大量文件、改 CI/部署 的命令，都必须人工复核。

一个可复制的终端工作流（强烈推荐）​

你可以把每次任务都收敛成这四步：

  1. 描述（Describe）：目标、约束、当前状态
  2. 计划（Plan）：分步计划 + 文件清单 + 验证方式
  3. 执行（Act）：只做第 1 步，完成后停下
  4. 验证（Verify）：跑命令/复现用例，失败就回到第 2 步

模板（可直接用）：

目标：解决 [问题/新增功能]。
约束：不新增依赖；改动最小；保持现有结构与命名。
仓库信息：pnpm + turborepo；主要命令 pnpm lint/typecheck/build。

请先：
1) 列出你要读的文件
2) 给 3-5 步计划（每一步都写验证命令）
3) 只执行第 1 步并停下来等待我确认

在 monorepo 里怎么避免“改错地方”？​

monorepo 最常见的问题是：修改发生在错误的 app/package 里。给 Claude Code 明确这些信息：

  • 目标站点是哪个：apps/docs / apps/tools-site / apps/meows / apps/novel / apps/about
  • 内容在哪：本仓库的 content/（子模块） vs apps/docs/src
  • 验证命令：优先用根目录的 pnpm ...（让 turborepo 处理依赖）

当你不确定它会改哪里时，强制它先回答：

  • “这次改动会涉及哪些目录？为什么？”
  • “每个目录改动的风险是什么？”

常用提示词模板（适配终端工作流）​

1) 先读后改（Read-first）​

请先只做分析，不要改文件。
目标：[目标]

1) 你需要阅读哪些文件？（列路径）
2) 你会如何验证结论？（列命令）
3) 你认为最小可行改动是什么？

2) 重构（强制小步）​

我要重构 [模块/功能]。
约束：
- 行为不变
- 不新增依赖
- 每次只做一步

请输出：
- 分步计划（每步 1-2 句）
- 每步要改的文件
- 每步验证命令

3) 排错（假设→证据）​

我遇到错误：
[日志]

复现步骤：
[步骤]

请输出：
1) 3 个最可能原因（按可能性排序）
2) 每个原因的验证命令/操作
3) 最小修复方案
4) 修复后应新增的回归用例

一个实战例子：把“任务”变成可执行清单​

当你要做一个跨文件改动时，让 Claude Code 先交付“可执行清单”，再执行：

任务：为文档页补充结构化内容（TL;DR/FAQ/内链）。

请先交付：
- 受影响页面清单（路径）
- 每个页面需要补充的内容点（要点列表）
- 预期验证方式（pnpm build 等）

然后再按页面逐个执行，每执行完一个页面就停下来。

常见任务清单（Claude Code 很擅长）​

你可以把下面这些任务当成“练习题库”，用来训练 Claude Code 的使用方式：

  • 生成检查脚本：发现 broken links / 缺失文件 / 重复 frontmatter
  • 批量机械改动：统一标题格式、替换链接、补齐模板段落
  • 写排错手册：症状 → 可能原因 → 验证方式 → 修复步骤
  • 写发布清单：发布前/发布后/回滚

为了让它更“工程化”，建议强制它每次都输出：

  • 受影响文件（路径）
  • 风险（最多 3 条）
  • 验证命令（必须可执行）

Claude Code 是什么？什么时候比 IDE 助手更合适？​

Claude Code 是 Anthropic 面向开发者工作流的编程助手，核心定位是“在 shell 里协作”。它不是把你拉到另一个聊天窗口，而是围绕真实工程流程设计：

  • 你本来就在终端里跑命令
  • 你本来就需要看测试/构建结果
  • 你希望 AI 能在可控前提下帮你完成行动（改文件、跑命令）

Claude Code 往往在这些场景更占优势：

  • 架构推演与取舍：列方案、比 trade-off、提前识别风险。
  • 复杂调试：把日志/配置/运行时行为串起来。
  • 大规模重构：拆步骤、做机械改动、逐步验证。
  • 自动化：脚本、迁移清单、发布说明、重复性修复。

如果你的主要需求是“打字更快”，Copilot/Codeium 可能更够用；如果你想要 IDE 内的多文件改动体验，Cursor 可能更顺手。

如何安装 Claude Code？​

前置条件​

  • Node.js 18+（官方建议）。
  • 可用账号/权限（个人订阅或组织配置，取决于你的使用方式）。

Quickstart（最短路径）​

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

如果是 monorepo，建议从仓库根目录启动，避免只看见一部分代码。

Claude Code 到底能做什么？​

把它当成一个循环：

  1. 读文件
  2. 给计划
  3. 在允许下改文件
  4. 在允许下跑命令
  5. 汇总变更 + 给验证建议

常见高价值用途：

  • 代码库检索与定位入口
  • 产出符合仓库规范的实现计划
  • 跨文件一致性修改（在你允许下）
  • 运行 lint/typecheck/tests/build 并根据失败迭代
  • 从 diff 生成文档、变更说明、迁移步骤

不能依赖它完成的事：

  • 替你决定产品需求
  • 没有测试就保证正确性
  • 替代 code review

你的责任是：给约束、让它按步骤走、强制验证闭环。

Claude Code 如何保证安全？（权限与确认）​

Claude Code 的安全模型通常是“权限驱动”：

  • 默认更保守（很多场景先只读）。
  • 需要改文件/跑命令时会请求权限。
  • 你可以按动作批准，也可以在配置里限制范围。

实践建议：把它当作一个“执行力很强的同事”，但依然需要你的审查与验证。

Claude Code 的最佳工作流​

工作流 A：排查线上问题（从症状到根因）​

  1. 给出症状、复现、日志。
  2. 让它列 3 个假设 + 每个如何验证。
  3. 你跑验证步骤。
  4. 做最小修复。
  5. 补回归测试。

可复制提示词：

Bug：<一句话>
预期：<应该发生什么>
实际：<现在发生什么>
复现步骤：<步骤>
日志/堆栈：<粘贴>
约束：最小 diff、不新增依赖
输出：
1) 3 个假设 + 如何验证
2) 最小修复
3) 回归测试方案

工作流 B：先做架构规划（写代码前先减风险）​

我们要实现 <功能>。
请：
1) 给 2 个架构方案
2) 列 trade-off（性能/复杂度/安全/可维护）
3) 推荐一个并解释原因
4) 列出最可能受影响的文件/模块

工作流 C：大重构（分阶段、每步验证）​

  • 阶段 1：只做机械改动（改名/移动/类型），不改行为
  • 阶段 2：在一切通过后再做行为层优化
重构目标：<目标>
规则：
- 阶段 1 只做机械改动；做完停下来让我审查
- 每一步后都跑 typecheck/tests
- diff 要小且可审查
输出：
- 分步计划
- 只实现第 1 步，然后停下来

工作流 D：自动化与“枯燥活”​

Claude Code 很适合：

  • 批量修复 lint 报错
  • 从 commit/diff 生成 release notes
  • 协助解决冲突（你审查后提交）
  • 生成迁移清单与回滚方案

工作流 E：解释 + 补丁 + 验证（最通用）​

按顺序执行：
1) 先用文件路径解释现有行为。
2) 给最小补丁（避免无关重构）。
3) 验证：pnpm lint、pnpm typecheck、pnpm test。
4) 总结改了什么、为什么、还有哪些风险。

如何在真实仓库里安全使用？​

用 git 当安全网​

大改动前先开分支：

git status
git checkout -b feat/claude-code-change

让它“每步停下来汇总”，你就能用 diff 控制风险：

每一步完成后停下来，总结变更并等我审查再继续。

陌生代码先只读​

先不要改文件。
只做：
- 解释现有行为
- 指出最佳改动点
- 给最小实施计划

把验证当成必选项​

改完后请运行（或指导我运行）：
pnpm typecheck && pnpm test && pnpm build
如果失败请迭代到通过。

如何让 Claude Code 更可靠？（上下文与约束）​

上下文清单​

  • 目标（要达成什么）
  • 非目标（哪些不能动）
  • 代码可能在哪（路径）
  • 验证命令
  • 约束（依赖/兼容/性能）

monorepo 里务必缩小范围​

范围：仅 apps/docs 与 scripts/。
避免：build/ dist/ node_modules/。
完成标准：pnpm lint + pnpm typecheck。

证据优先（避免猜）​

在给方案之前：
- 列出你确定的事实
- 列出你还需要检查的点
- 列出要读的文件/要跑的命令
信息不足就问我，不要猜。

隐私与数据：需要注意什么？​

把它当成外部服务：

  • 不要粘贴密钥
  • 不要粘贴敏感客户数据
  • 尽量给最小复现

如果你在公司/合规环境下使用，务必按组织安全策略配置（例如是否开启遥测、是否允许外发代码片段等）。

如何写提示词才“像工程师在写 ticket”？​

Claude Code 最吃的就是结构化输入：

  1. Context：系统是什么
  2. Goal：必须改什么
  3. Non-goals：哪些不能动
  4. Constraints：依赖/性能/兼容
  5. Verification：怎么验证

示例：

Context：这是一个 pnpm + Turbo 的 monorepo。
Goal：新增一个 tools metadata 校验脚本。
Non-goals：不要改 tools 构建流程。
Constraints：TypeScript、不新增依赖。
Verify：pnpm lint、pnpm typecheck、pnpm validate:metadata。

可复制提示词库​

只要计划（先不动代码）​

我要做：<功能>
约束：最小 diff、不新增依赖、补测试
请：
1) 给 5-10 步计划
2) 列影响文件
3) 列验证命令
只输出计划，然后停下来。

像资深工程师一样做 review​

请 review 这段 diff：
- 正确性
- 边界条件
- 安全（鉴权/注入/密钥）
- 性能
- 命名与结构
先给问题（按严重程度排序），再给建议。

写“真的能抓回归”的测试​

为这个 bug/功能设计测试：
- 修复前会失败
- 修复后会通过
- 覆盖边界条件与错误路径
并给出建议的测试文件路径与命名。

分步执行并停下​

把任务拆成 3 步。
每步结束：
- 总结改动
- 给验证命令
- 停下来等我审查

常见坑与规避​

坑：让它“一口气跑飞”​

解法：权限保守、分步执行、频繁验证。

坑：不给约束，问“最佳实践”​

解法：告诉它仓库上下文与真实限制。

坑：不验证就提交​

解法：把 typecheck/tests/build 变成硬性门槛。

团队 SOP：让 Claude Code 跑得稳（终端流水线视角）​

当 Claude Code 进入团队工作流后，关键不是“它能不能写”，而是“产出能不能稳定落地”。你可以把它当成一个会写补丁的终端同事，给它明确的 SOP。

1) 权限默认保守：先只读，再逐步放开​

推荐默认策略：

  • 首次进入仓库：只读（允许 rg、ls、cat、sed、git status）。
  • 要开始改动：允许写文件，但禁止危险命令（删除、覆盖、重置历史）。
  • 要跑构建/测试：允许 pnpm、node、tsx 等白名单命令。

你可以用提示词固定“命令边界”：

命令策略：
- 允许：rg、ls、cat、sed、git status、git diff、pnpm lint/typecheck/build
- 禁止：rm -rf、git reset --hard、覆盖写敏感文件、上传/外发代码
如果需要额外命令，先解释原因并等我确认。

2) 用“验证清单”替代“感觉没问题”​

把每次改动的完成标准写成清单（越具体越好）：

  • 代码层：类型检查/测试/构建通过
  • 文档层：链接可用、标题层级正确、示例可复制
  • 仓库层：没有误改产物目录；必要时检查 submodule 状态

例如在本仓库（pnpm + monorepo）里，你可以固定：

完成标准：
- pnpm lint 通过
- pnpm typecheck 通过
- pnpm build 通过
- 如果改了 content/：运行 ./scripts/check-submodule.sh 并确认 submodule 状态正确

3) 大改动拆成“可回滚的批次”​

终端工具最容易出现“一次把几十个文件全改了”的情况。建议用批次策略控制：

  1. 批次 1：纯机械改动（改名、移动、格式），行为不变
  2. 批次 2：行为改动（功能/修 bug），每一步都跑验证
  3. 批次 3：清理（删除死代码、补文档、补注释）

每个批次结束都要产出：

  • git diff 可读、范围清晰
  • 明确回滚方式（撤销哪些文件/提交）

4) 让它“像写 ticket 一样”交付结果​

除了代码本身，还可以要求它输出可直接进入 PR 的材料：

  • 变更点列表（What）
  • 动机与约束（Why / Non-goals）
  • 验证记录（How tested）
  • 风险与回滚（Risks / Rollback）

5) 一个实战演练：把“需求”落成可合并的补丁​

你可以用这个演练把团队 SOP 练熟（10-20 分钟一轮）：

目标：做一个小改动，并保证验证闭环完整。

建议任务类型：

  • 修一个 lint/typecheck 报错
  • 给文档补一个 FAQ
  • 对一个小函数做“行为不变”的重构（提取 helper/改名）

可复制提示词：

我们做一个小任务演练，要求最终可合并。
任务：<描述>
范围：只改 <A/B> 两个文件（如必须更多，先解释原因）。
约束：不新增依赖；不要无关重构；每步都要可回滚。
完成标准：
- pnpm lint 通过（或项目等价命令）
- pnpm typecheck 通过
- pnpm build 通过（如适用）
输出要求：
1) 先列要读的文件
2) 给 3-5 步计划（每步含验证命令）
3) 只执行第 1 步并停下来

6) 复盘模板：把“有效的做法”固化下来​

每次用 Claude Code 完成一个任务后，用 2 分钟复盘，持续提高命中率：

  • 这次最关键的上下文是什么？（入口文件/错误日志/约束）
  • 哪一步最容易跑偏？为什么？
  • 下次要写进规则/模板的 1 条提醒是什么？

7) 小心 submodule：文档仓库常见的“坑”​

如果你的文档内容在 submodule（例如本仓库的 content/），团队协作时要特别注意：

  • 不要把“submodule 指针更新”混在大改动里（更难 review）
  • 提交前确认 submodule 状态，避免 CI/部署拉不到正确内容

Troubleshooting​

“claude 命令不存在”​

  • 确认全局安装：npm ls -g --depth=0 | rg claude
  • 重开终端/刷新 PATH。

“读不到文件 / 权限不足”​

  • pwd 确认你在仓库根目录。
  • 先让它只读分析，不要直接改。

“风格不符合项目”​

  • 指向风格文件（lint/formatter 配置）。
  • 要求参考相邻文件。
  • 把 lint/format 纳入验证。

FAQ​

Claude Code / Cursor / Copilot 怎么选？​

  • 选 Claude Code：你更需要规划、推理、终端工作流、复杂重构。
  • 选 Cursor：你想在 IDE 里做多文件改动、快速导航与编辑。
  • 选 Copilot：你主要要行内补全与“打字更快”。

很多人的组合是：Copilot 负责速度，Cursor 负责 IDE 内大改动，Claude Code 负责最难的推理与规划。

初学者适合用 Claude Code 吗？​

适合，但要把它当“教练 + 助手”：先让它解释与给计划，你自己跑命令、自己验证。最重要的习惯是：永远验证。

它会不会跑危险命令？​

它可以提出命令，但你应当用权限与审查控制风险。尤其在生产仓库，权限要保守。

如何防止巨大 diff？​

让它分步骤，每步结束停下来：

只实现第 1 步并停下。
不要动无关文件。

卡住了怎么办？​

让它重新缩小范围：

  • “下一步最小行动是什么？”
  • “下一步该检查哪个文件？”
  • “给 3 个选项与风险。”

相关学习路径​

下一步​