本文面向 Claude Code 新手到进阶用户，系统讲清安装方式、首次配置、提示词写法、项目开发流程、测试验收和常见问题排查。你可以把它当成一篇从打开终端到完成真实开发任务的 Claude Code 实战手册。
摘要：Claude Code 不是聊天窗口，而是开发工作流里的 AI Agent
Claude Code 的核心价值，是把 AI 放进真实项目目录里工作。它可以阅读代码库、理解项目结构、编辑文件、运行命令，并把修改结果交给你用测试和 Git diff 复核。对新手来说，Claude Code 最适合从三类任务开始：读懂项目、修复明确问题、完成小范围功能；对有经验的开发者来说，它更适合做重构、补测试、代码审查、CI 排查和文档维护。
官方 Quickstart 文档目前提供多种安装入口，包括原生安装、WinGet、Homebrew 和 npm。安装之后，推荐先进入项目目录，运行 Claude Code，让它只读项目并解释结构；确认工作方式后，再让它修改小范围文件。不要一开始就要求它“重构整个项目”或“自动完成所有功能”。
如果你还在了解基础概念，可以先阅读站内 Claude Code 是什么 和 Claude Code 怎么用；如果你关心使用边界，可以继续看 Claude Code 使用前必须知道的 10 件事。本文会进一步把安装、提示词和项目开发串成一套完整实战流程。
Claude Code 适合谁用
适合开发者：把重复工程任务交给 AI
如果你已经会使用 Git、会运行测试、能看懂基本错误日志，Claude Code 可以明显提升效率。它适合帮你读陌生模块、定位报错、补单元测试、修复 lint 和类型错误、整理 README、生成迁移说明、审查当前 diff。它不是替代工程判断，而是减少搜索、编辑和验证中的机械劳动。
适合产品和运营技术人员：完成低风险项目改动
如果你不是专业开发者，但需要维护一个工具站、WordPress 插件、脚本或轻量 Web 项目，也可以使用 Claude Code。前提是你要把任务控制得足够小，例如“只修改 README”“只增加一个按钮文案”“只修复一个报错”。越小、越明确、越可验证，成功率越高。
不适合完全没边界的大任务
“帮我做一个完整 SaaS”“全面优化这个系统”“把代码全部升级一下”都不适合作为第一条指令。Claude Code 能执行真实修改，所以任务越宽，产生无关 diff 的风险越高。更好的方式是先让它读项目并出计划，再逐步确认。
安装前准备
准备 Node.js、Git 和一个可运行项目
Claude Code 本身可以帮助你读项目，但不能替你凭空补齐所有本地环境。开始之前，至少确认电脑里有 Git、项目依赖管理器，以及能运行项目的基础环境。前端项目通常需要 Node.js，Python 项目需要对应 Python 版本，后端项目可能还需要数据库、Docker 或本地服务。
准备一个干净的 Git 状态
真实项目中最重要的保护措施是 Git。开始前运行：
git status如果已有未提交改动，要先确认这些改动是不是你自己需要保留的内容。Claude Code 修改之后，你需要再次运行 git diff 来判断哪些变动来自本次任务。
不要暴露真实密钥
不要让 Claude Code 读取生产 .env、数据库密码、支付密钥、管理员账号密码或证书。需要排查配置时，提供 .env.example、脱敏变量名和错误信息即可。
Claude Code 安装方式
方式一：原生安装器
官方 Quickstart 当前推荐使用原生安装器。它会安装 Claude Code 命令行，并帮助你把命令加入系统路径。安装完成后，在终端运行：
claude --version如果能输出版本号，说明命令已经可用。
方式二：Windows 使用 WinGet
在 Windows 上，可以使用官方文档列出的 WinGet 方式安装。安装后重新打开 PowerShell 或 Windows Terminal，再检查版本号。若提示找不到命令，优先检查 PATH 是否刷新，或者重启终端。
方式三：macOS 使用 Homebrew
macOS 用户可以使用 Homebrew 安装。安装后同样运行 claude --version 验证。第一次使用时，通常还需要登录 Claude 账号并授权本机。
方式四：npm 安装
如果你的开发环境已经依赖 Node.js，也可以使用 npm 方式安装。npm 方式适合熟悉 Node 工具链的用户，但新手更建议优先使用官方推荐的系统级安装方式。
首次启动与登录
进入项目目录再启动
不要在桌面或随便一个目录启动 Claude Code。正确做法是先进入项目根目录：
cd path/to/your-project
claudeClaude Code 会围绕当前工作目录理解项目。目录选错，会导致它读不到项目文件，或者误把无关目录当成项目。
第一次先问项目结构
首次启动后，不要马上让它修改代码。先用只读提示词：
请先不要修改文件。
请阅读 README、package.json 和主要目录结构。
请告诉我这个项目的技术栈、启动命令、测试命令、核心目录和你建议优先阅读的文件。这个步骤能确认 Claude Code 是否进入了正确目录，也能帮你快速建立项目地图。
确认权限请求
Claude Code 在读取、编辑、运行命令时会涉及不同权限。新手看到权限确认时，不要直接全量允许。先看清楚它要执行什么命令、会修改哪些文件、是否涉及删除、部署、密钥或生产配置。
提示词的核心结构
一条好提示词包含五个要素
Claude Code 的提示词不需要花哨，但要清楚。建议包含：任务目标、项目上下文、允许范围、禁止事项、验证方式。只要这五项写清楚，Claude Code 的修改通常更可控。
目标：修复登录按钮点击后没有响应的问题。
上下文：这是 React 前端项目，登录页在 src/pages/Login.tsx。
允许范围：只修改登录页、auth hook 和相关测试。
禁止事项：不要重构路由，不要新增依赖，不要读取 .env。
验证方式：修改后运行 npm test 和 npm run lint。先计划，后修改
面对复杂任务时，最好先要求 Claude Code 输出计划：
请先不要修改文件。
先阅读相关代码，输出涉及文件、问题判断、修改计划、风险点和验证命令。
等我确认后再执行。这能有效避免它一上来就大范围改文件。
明确“不要做什么”
很多 AI 编程事故不是因为目标写错，而是边界没写清楚。提示词里可以直接写：不要新增依赖、不要格式化无关文件、不要修改数据库迁移、不要改部署脚本、不要读取密钥文件。
入门任务一：让 Claude Code 读懂项目
适合场景
接手陌生项目、外包项目、开源项目，或者准备修改旧功能前，都可以先让 Claude Code 做项目导览。
推荐提示词
请先不要修改文件。
请阅读项目根目录、README、依赖文件和 src 目录。
输出：
1. 项目用途
2. 技术栈
3. 启动命令
4. 测试命令
5. 核心模块
6. 适合新手先读的 5 个文件验收方式
检查它列出的文件是否真实存在，命令是否来自项目脚本，模块关系是否能在代码中对应上。如果它编造了不存在的文件，要立刻纠正，让它重新搜索。
入门任务二：修复一个明确报错
准备材料
修 Bug 前要准备完整报错、复现步骤、期望结果、实际结果和相关环境。不要只说“页面坏了”。
推荐提示词
下面是报错日志和复现步骤。
请先判断最可能的根因，并列出需要阅读的文件。
不要立刻修改。
确认根因后，给出最小修复方案和验证命令。执行方式
先让 Claude Code 搜索相关文件和调用链，再让它提出方案。确认方案后，才允许它修改。修复完成后，要求它运行对应测试或复现命令。
入门任务三：补测试
为什么补测试适合新手练习
补测试有明确边界，也有明确验收方式。Claude Code 可以参考现有测试风格，快速补齐正常路径、边界值和异常输入。
推荐提示词
请为 src/lib/formatPrice.ts 补充单元测试。
先阅读现有测试风格。
只新增测试，不修改业务代码。
覆盖正常输入、空值、异常输入和边界值。
完成后运行对应测试。验收方式
测试应该和项目现有风格一致，不应为了通过测试而改业务代码。最后检查测试命令是否通过。
项目开发实战流程
第一步：把需求拆成小任务
不要让 Claude Code 一次完成整个功能。以“给文章列表增加标签筛选”为例，可以拆成：阅读现有列表页、确认查询参数、增加 UI 控件、接入接口、补测试、手动验收。
第二步：限定修改范围
提示词里写清楚允许修改哪些文件或目录。例如：
允许修改：
- src/pages/articles
- src/hooks/useArticles.ts
- 相关测试文件
禁止修改：
- 路由结构
- 全局状态模型
- 构建配置
- 依赖版本第三步：要求先列计划
Claude Code 的计划应该包含：涉及文件、改动步骤、风险点、验证命令。如果计划里出现“顺便重构全局状态”这种扩大范围的内容，要先让它收窄。
第四步：执行修改并运行验证
修改后至少运行和任务相关的测试。前端项目可运行 lint、单测和构建；后端项目可运行单测、接口测试或类型检查。无法运行时，要求 Claude Code 说明原因，而不是假装通过。
第五步：检查 Git diff
最后运行：
git status
git diff重点看是否有无关文件、是否改动了密钥或配置、是否新增依赖、是否修改了不该动的模块。
实战案例：新增一个文章筛选功能
需求描述
假设你要给一个内容管理后台增加“按标签筛选文章”的功能。这个需求看似简单，但可能涉及页面组件、URL 参数、接口请求、状态同步和测试。
第一轮：只读分析
请先不要修改文件。
请阅读文章列表页、文章查询 hook、接口请求和相关测试。
告诉我当前筛选功能如何实现，以及增加标签筛选需要改哪些文件。第二轮：确认计划
请给出最小实现计划。
要求：保留现有筛选逻辑，不改全局状态，不新增依赖。
请列出修改文件、风险点和验证命令。第三轮：执行修改
按刚才确认的计划执行。
完成后运行 npm test 和 npm run lint。
如果失败，请判断是否由本次修改引起。第四轮：验收
检查页面交互、接口参数、测试结果和 Git diff。如果 diff 中出现无关重构，要求 Claude Code 收回无关改动，只保留与标签筛选直接相关的修改。
如何让 Claude Code 少犯错
使用 CLAUDE.md 保存项目规则
官方文档支持用项目记忆文件记录开发规则。你可以在项目里写明包管理器、测试命令、禁止读取的文件、代码风格、提交要求和常见排查方式。这样每次会话都不用重复说明。
把任务拆小
单轮任务最好只解决一个目标。修 Bug 就先修 Bug，补测试就先补测试，重构就先重构。不要在一轮里不断追加新目标。
要求输出证据
每次修改后，让 Claude Code 输出：修改文件、修改原因、运行命令、命令结果、剩余风险。没有证据的“完成了”不应该作为验收依据。
人来做最终合并
Claude Code 可以帮你写代码，但最终是否合并、发布、部署，应该由人判断。尤其涉及权限、支付、数据库、生产配置和用户数据时，更要人工复核。
常见问题排查
找不到 claude 命令
通常是安装没有完成、PATH 没刷新，或终端没有重启。先关闭并重新打开终端，再运行 claude --version。Windows 用户还可以检查 WinGet 安装状态。
Claude Code 读不到项目
优先检查当前目录。运行 pwd 或 PowerShell 的 Get-Location，确认你是否在项目根目录。然后运行 git status 看是否识别到仓库。
它改了太多文件
先停止继续修改，运行 git diff。让 Claude Code 列出哪些改动与目标直接相关，哪些是无关改动。必要时回滚无关文件，并重写提示词限制范围。
测试失败了
不要马上让它继续乱改。先要求它判断失败是否由本次修改引起，列出证据。如果是环境问题，不要修改业务代码；如果是本次修改导致，再做最小修复。
FAQ：Claude Code 入门到实战常见问题
Claude Code 适合完全零基础的人吗？
可以用来读项目、解释报错和整理文档，但如果要让它改代码，至少要学会 Git status、Git diff、运行测试和回滚文件。否则很难判断它改得对不对。
安装后第一件事应该做什么？
进入项目目录，让 Claude Code 只读项目并解释结构。不要第一条指令就让它大范围修改。
提示词需要写得很长吗？
不一定。关键是写清目标、范围、禁止事项和验证方式。短但具体的提示词，通常比长但模糊的提示词更好。
Claude Code 能自动完成项目开发吗？
它能帮你完成很多开发步骤，但不建议完全自动化交付。你仍然需要确认需求、审查 diff、运行测试、处理部署和承担最终质量责任。
要不要每个项目都写 CLAUDE.md？
建议写。项目规则、测试命令、禁止事项、目录边界和代码风格都可以写进去，能显著减少重复说明和误改概率。
什么时候不应该用 Claude Code？
需求没想清楚、没有测试或验收方式、涉及生产密钥、涉及管理员账号、需要直接删除线上数据时，都不应该让 Claude Code 直接执行。
参考来源
- Claude Code Docs：Overview
- Claude Code Docs：Quickstart
- Claude Code Docs：Common workflows
- Claude Code Docs：Memory and CLAUDE.md
- Claude Help Center：CLAUDE.md and better prompts
- Claude Help Center：Common developer use cases
环境配置与 Docker 工作流
适合阅读安装部署、本地配置、服务器搭建和自动化流程类文章后继续转化。
