Claude Code辅助软件开发实用教程

先让 Claude 拥有项目记忆

在开始任何阶段前，务必在项目根目录下，创建CLAUDE.md ，这是 Claude Code 的"系统提示词"和"项目圣经"。

CLAUDE.md会在每次会话开始时加载，告诉 Claude Code：这个项目怎么运行、怎么测试、怎么提交、有哪些编码规范。

# 在项目根目录启动 Claude Code
claude

# 首次进入，可以使用 /init 命令让它自动分析项目并生成基础的 CLAUDE.md
/init

示例：

# Project Guidelines

## 目录结构
- 核心代码在哪，配置在哪，测试在哪

## 技术栈

- Frontend: React + TypeScript + Vite
- Backend: Node.js + NestJS
- Database: PostgreSQL
- Package manager: pnpm

## 常用命令

- 安装依赖：pnpm install
- 启动开发环境：pnpm dev
- 运行测试：pnpm test
- 类型检查：pnpm typecheck
- 代码检查：pnpm lint
- 构建：pnpm build

## 开发规则

- 所有新代码必须使用 TypeScript。
- 修改业务逻辑时必须补充或更新测试。
- 不要直接修改数据库迁移文件，除非我明确要求。
- 不要自动提交 Git，除非我明确说"提交"。
- 重大重构前先给出方案，不要直接改文件。

## 编码规范
- 必须使用 TypeScript 严格模式，错误处理规范，命名规范等。

## 输出要求

- 修改前先说明影响范围。
- 修改后必须说明改了哪些文件、为什么这么改、如何验证。

在项目根目录下，启动Claude。

需求分析阶段：让 Claude 先读代码，不要急着改

场景 1：理解已有功能

请分析当前项目中"用户登录"功能的实现链路。
要求：
1. 找到前端入口、API调用、后端controller/service、数据库相关代码；
2. 画出文字版调用链；
3. 说明当前实现有哪些潜在问题；
4. 不要修改任何文件。

场景 2：评估新需求影响范围

我准备新增"手机号验证码登录"功能。
请先分析这个需求会影响哪些模块：
1. 前端页面和组件；
2. 后端接口；
3. 数据表或缓存；
4. 鉴权逻辑；
5. 测试用例；
6. 可能的风险点。
先不要写代码。

场景 3：读陌生项目

我第一次接触这个项目。
请帮我生成一份onboarding文档，包括：
1. 项目用途；
2. 技术栈；
3. 目录结构；
4. 核心模块；
5. 本地启动方式；
6. 常见开发任务；
7. 新人最容易踩坑的地方。
不要修改文件，只输出分析结果。

方案设计阶段：使用 Plan Mode

对于中大型修改，建议使用计划模式。

claude --permission-mode plan

或者在 Claude Code 会话里按：

Shift + Tab

切换到 plan mode。

计划模式下，Claude 会先读文件并提出修改方案，不会直接改代码，直到批准计划。

示例：

请为"手机号验证码登录"功能制定实现方案。
要求：
1. 先分析当前认证模块；
2. 给出最小可行改动方案；
3. 列出需要新增/修改的文件；
4. 给出接口设计；
5. 给出数据库设计；
6. 给出测试计划；
7. 等我确认后再开始编码。

方案阶段需要关注三件事：

1. 它有没有找到正确的业务入口？
2. 它有没有误判技术栈或架构？
3. 它有没有提出过度设计？

Claude Code 很适合执行，但需求边界、业务取舍、产品规则仍然要由人确认。

开发实现阶段：小步快跑

确认方案后，再让它分步骤实现。

示例：

按照刚才确认的方案开始实现。
要求：
1. 每次只完成一个小步骤；
2. 修改前说明将要改哪些文件；
3. 修改后运行相关测试；
4. 如果测试失败，先分析原因再修复；
5. 不要提交 Git。

常见开发任务示例

新增功能

请实现"用户头像上传"功能。
要求：
1. 支持 jpg/png/webp；
2. 限制文件大小 2MB；
3. 后端校验 MIME 类型；
4. 前端显示上传进度；
5. 增加单元测试和错误处理；
6. 修改完成后运行相关测试。

修 bug

当前存在一个bug：用户提交空表单时后端仍然创建了记录。
请：
1. 定位问题原因；
2. 给出修复方案；
3. 实现修复；
4. 增加回归测试；
5. 运行测试验证。

重构

请重构 src/services/orderService.ts。
目标：
1. 拆分过长函数；
2. 保持外部 API 不变；
3. 不改变业务行为；
4. 增加必要测试；
5. 重构完成后说明前后结构变化。

类型修复

请运行类型检查，并修复 TypeScript 报错。
要求：
1. 不要使用 any 逃避问题；
2. 优先补充正确类型；
3. 修改完成后重新运行 typecheck。

测试阶段：让它先跑，再修，再解释

测试阶段不要只说"帮我写测试"。更好的方式是让 Claude Code 明确测试目标。

生成测试计划

请为当前"订单创建"模块生成测试计划。
要求：
1. 覆盖正常路径；
2. 覆盖参数校验；
3. 覆盖权限问题；
4. 覆盖数据库异常；
5. 先输出测试清单，不要写代码。

写单元测试

请根据刚才的测试计划，为订单创建逻辑补充单元测试。
要求：
1. 使用项目现有测试框架；
2. 遵循已有测试风格；
3. 不要引入新的测试库；
4. 写完后运行测试。

修复失败测试

请运行测试并分析失败原因。
要求：
1. 区分是测试写错、代码 bug，还是环境问题；
2. 不要盲目修改；
3. 先给出判断，再修复。

端到端验证

请检查当前项目是否已有 e2e 测试。
如果有，请为登录流程补充 e2e 测试；
如果没有，请先说明是否值得引入，不要直接添加新框架。

代码审查阶段：让它当 reviewer，不要只当 coder

开发完成后，可以让 Claude Code 做自查。

请review当前 git diff。
重点检查：
1. 业务逻辑是否正确；
2. 是否有安全问题；
3. 是否有边界条件遗漏；
4. 是否有性能问题；
5. 是否有重复代码；
6. 测试是否充分；
7. 是否符合 CLAUDE.md 中的项目规范。
只输出问题清单和建议，不要修改文件。

如果想让它直接修复 review 发现的问题：

根据刚才 review 的问题，优先修复高风险问题。
要求：
1. 一次只修一个问题；
2. 每个问题修复后说明验证方式；
3. 不要引入无关重构。

Git 工作流：分支、提交、PR

Claude Code 可以用自然语言辅助 Git 操作，包括查看修改文件、提交描述性 commit message、创建分支、查看最近提交、解决 merge conflicts 等。

查看当前修改

请查看当前 git diff，总结我改了哪些内容。
不要提交。

生成 commit message

请根据当前 git diff 生成一个规范的 commit message。
要求：
1. 使用 Conventional Commits；
2. 标题不超过 72 个字符；
3. body 说明主要变更和测试情况。

让它提交

请提交当前修改。
commit message 使用你刚才生成的版本。

生成 PR 描述

请根据当前分支相对 main 的 diff，生成 PR 描述。
包括：
1. 背景；
2. 主要改动；
3. 测试情况；
4. 风险点；
5. 回滚方案。

创建 PR

请创建一个 PR 到 main 分支。
标题使用简洁的功能描述，正文使用刚才生成的 PR 描述。

并行开发：worktree 与多会话

如果同时处理多个任务，不建议在同一个工作区里让 Claude 到处改。可以使用 worktree：

claude --worktree feature-auth

worktree 可以让你在一个终端做 feature，同时让 Claude 在另一个终端修 bug，避免编辑冲突；每个 worktree 是独立 checkout 和独立分支。

典型用法：

claude --worktree fix-login-bug

claude --worktree refactor-order-service

claude --worktree add-payment-tests

适合：

1. 一个任务一个分支；
2. 一个 Claude 会话只做一件事；
3. 完成后 review diff；
4. 再合并回主分支。

恢复上下文：continue / resume

如果一个任务没做完，可以继续上次会话：

claude --continue

或者在会话中使用：

/resume

Claude Code 会把 conversation 保存到本地；claude --continue 会恢复当前目录最近一次会话，claude --resume 可以从列表中选择。

常用场景：

昨天做到一半的重构，今天继续。

刚才测试失败了，恢复之前的上下文继续修。

这个 PR review 了一半，继续完成剩下的 review。

非交互模式：脚本化与自动化

Claude Code CLI 不只是聊天式工具，也可以作为命令行工具接入脚本。

使用 -p 一次性执行

claude -p "总结这个项目的技术栈和主要模块"

这种方式称为可以用于 CI、pre-commit hook、batch processing 的非交互用法，stdin 和 stdout 可以像 Unix 工具一样工作。

管道输入

git log --oneline -20 | claude -p "总结最近 20 次提交的主要变化"

cat error.log | claude -p "分析这个错误日志，给出最可能的根因和修复建议"

git diff | claude -p "review 这次改动，指出潜在 bug 和安全风险"

限制工具权限

只允许它读文件和看 git diff：

claude -p "review 当前改动" \
  --allowedTools "Bash(git diff *)" "Bash(git status *)" "Read"

--allowedTools 可以让指定工具无需再次请求权限；如果要限制可用工具，应使用 --tools。

限制成本和轮次

claude -p "分析当前测试失败原因" \
  --max-turns 3 \
  --max-budget-usd 2.00

CLI reference 里列出了 --max-turns 和 --max-budget-usd，适合非交互任务控制执行轮次和预算。

JSON 输出

claude -p "分析 git diff 中的风险点，只输出 JSON" \
  --output-format json

CI/CD：接入 GitHub Actions

Claude Code 可以接入 GitHub Actions，可以通过终端里运行：

/install-github-app

来引导安装 GitHub App 和配置 secrets；它可以基于 issue / PR / workflow 执行代码任务、创建 PR、参与 review。

适合场景：

1. PR 创建后自动 review；
2. issue 打上某个 label 后自动实现；
3. CI 失败后自动分析失败日志；
4. 定时扫描 flaky tests；
5. 自动更新文档或依赖说明。

一个保守的 CI 使用方式是：只让 Claude 输出 review 建议，不允许自动 push。

示例思路：

name: Claude Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Review diff
        run: |
          git diff origin/main...HEAD | claude -p "Review this PR diff. Output risks and suggestions only."

实际生产环境里，建议进一步限制权限、预算、工具调用范围和 secrets 访问范围。

MCP：连接外部系统

Claude Code 可以通过 MCP 连接外部工具和数据源。MCP 可以让 Claude Code 连接 issue tracker、monitoring dashboard、database、Figma、Slack、Gmail 等工具，而不是每次都靠你手动复制信息。

典型用法：

读取 Jira issue，实现对应功能，并创建 PR。

查看 Sentry 最近 24 小时的错误，定位最可能的代码问题。

根据 Figma 设计稿更新邮件模板。

查询 PostgreSQL 中某类用户样本，用于复现 bug。

使用 MCP 时要特别注意权限和安全。不要随便接入未知 MCP server，尤其是能访问数据库、代码仓库、浏览器、内部文档的 server。

Hooks：把团队规则自动化

Hooks 可以让你在 Claude Code 生命周期中的某些节点自动执行命令。hooks 可以是 shell command、HTTP endpoint 或 LLM prompt，会在 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop 等事件触发。

适合做：

1. 修改文件后自动运行 lint；
2. 提交前自动检查 secrets；
3. 禁止 Claude 修改某些目录；
4. 每次停止前生成变更摘要；
5. Claude 要执行危险命令前拦截。

例如，可以设计一个规则：

当 Claude 修改 src/** 文件后，自动运行 pnpm test。

或者：

当 Claude 尝试执行 rm、drop database、kubectl delete 等危险命令时，直接阻止。

如果你想无条件阻止某类动作，应该使用 PreToolUse hook，而不是只靠 CLAUDE.md 提醒，因为 CLAUDE.md 是上下文指导，不是强制配置。

完整开发流程示例

下面是一套比较稳的日常工作流。

第 1 步：创建分支

git checkout -b feature/sms-login
claude

第 2 步：让它读项目

请分析当前项目的登录认证实现。
重点关注：
1. 登录入口；
2. token 生成和校验；
3. 用户表结构；
4. 前端登录页；
5. 测试覆盖情况。
不要修改文件。

第 3 步：需求影响分析

我要新增手机号验证码登录。
请分析影响范围，并给出最小可行实现方案。
不要修改文件。

第 4 步：进入计划模式

claude --permission-mode plan

或者在当前会话中按 Shift + Tab。

请制定详细实现计划。
要求：
1. 拆成 5 个以内的小步骤；
2. 每一步说明修改文件；
3. 每一步说明验证方式；
4. 等我确认后再开始实现。

第 5 步：逐步实现

开始执行第 1 步。完成后停下来说明修改内容和验证结果。

继续：

继续执行第 2 步。

继续执行第 3 步，并运行相关测试。

第 6 步：测试

请运行 lint、typecheck 和相关测试。
如果失败，先解释失败原因，再修复。

第 7 步：自查

请 review 当前 git diff。
只输出问题清单，不要修改文件。

第 8 步：修复 review 问题

请修复 review 中的高风险问题。
不要做无关重构。

第 9 步：生成提交信息

请根据当前 git diff 生成 Conventional Commit message。

第 10 步：提交

请提交当前修改。

第 11 步：生成 PR 描述

请生成 PR 描述，包括：
1. 背景；
2. 主要改动；
3. 测试情况；
4. 风险点；
5. 回滚方案。

推荐提示词模板库

代码理解模板

请分析这个模块的实现。
要求：
1. 找到入口文件；
2. 说明调用链；
3. 说明核心数据结构；
4. 说明依赖的外部服务；
5. 说明潜在风险；
6. 不要修改文件。

方案设计模板

请为以下需求制定技术方案：
【需求描述】

要求：
1. 先分析现有实现；
2. 给出最小可行方案；
3. 列出需要修改的文件；
4. 说明数据库/API/前端影响；
5. 说明测试方案；
6. 说明风险和回滚方案；
7. 不要直接写代码。

实现模板

请按照确认后的方案实现。
要求：
1. 小步提交思路；
2. 每次修改前说明文件；
3. 修改后运行相关测试；
4. 不要引入无关重构；
5. 不要提交 Git，除非我明确要求。

Bug 修复模板

请修复以下 bug：
【bug 描述】

要求：
1. 先复现或定位问题；
2. 解释根因；
3. 给出修复方案；
4. 实现最小修复；
5. 添加回归测试；
6. 运行测试验证。

重构模板

请重构以下模块：
【模块路径】

目标：
1. 降低复杂度；
2. 保持外部行为不变；
3. 不改变公共 API；
4. 补充或更新测试；
5. 修改后说明重构前后差异。

Review 模板

请 review 当前 git diff。
重点检查：
1. 逻辑 bug；
2. 安全风险；
3. 性能问题；
4. 并发问题；
5. 边界条件；
6. 测试缺失；
7. 是否符合项目规范。
只输出 review 结果，不要修改文件。

团队落地建议

如果是团队场景，可以这样规范 Claude Code CLI 的使用：

1. 每个项目必须维护 CLAUDE.md；
2. 大改动必须先用 plan mode；
3. 一个 Claude 会话只做一个任务；
4. 不允许 Claude 直接操作生产环境；
5. 不允许 Claude 自动提交未 review 的代码；
6. 所有 Claude 生成代码必须跑测试；
7. 所有 PR 必须人工 review；
8. 对数据库、权限、安全相关改动必须二次确认；
9. CI 中优先让 Claude 做 review，不要一开始就自动 push；
10. 对新同事，先训练"读代码"和"写测试"，再训练"自动实现功能"。

最小上手路线

可以按这个顺序练：

第 1 天：安装、登录、让 Claude 分析项目
第 2 天：让 Claude 写 README / onboarding 文档
第 3 天：让 Claude 修一个小 bug
第 4 天：让 Claude 补测试
第 5 天：用 plan mode 做一个小功能
第 6 天：让 Claude review git diff
第 7 天：接入 GitHub PR 流程或脚本化命令

最终建议

Claude Code CLI 最好不要被当成"聊天机器人"，而要当成"在你本地仓库里工作的 AI 开发助理"。

最稳的工作方式是：

先读代码 → 再出方案 → 人确认 → 小步实现 → 跑测试 → review diff → 提交 PR

真正高效的用法不是"让 AI 一次性写完"，而是把它纳入你的工程流程，让它按你的架构、测试、规范和 Git 工作流执行。