Claude Code 新手快速上手指南

Claude Code 新手快速上手指南

摘要

Claude Code 是可在终端、IDE、桌面端和浏览器等环境中使用的代理式编码工具。进入项目目录后，它会读取相关文件、编辑代码、运行命令，并根据测试与错误输出继续调整。

本文以 Windows PowerShell 7 为例，完成环境检查、安装登录、首个任务、多文件修改、交互调试、项目指令、敏感信息保护、连接超时排查和结果验收。命令与配置依据 2026-10-27 查阅的 Claude Code 官方文档整理；版本更新后，以本机 claude --version 和官方 CLI 帮助为准。

一、背景与问题

第一次使用 Claude Code 时，常见问题并不在"不会写提示词"，而在几个更基础的工程环节：安装命令在错误的 Shell 中执行；同时存在订阅登录和 API Key，导致调用来源不明确；没有 Git 基线就允许大范围修改；项目指令塞入过期路径；连接超时后反复重装；或者把"模型说已完成"当成测试已通过。

这些问题会共同破坏一个前提：开发者必须能看见并撤销 AI 的每一步修改。一个安全的上手过程应当先建立环境、身份、工作区和权限边界，再逐步扩大任务规模。

二、核心概念

机制	作用	新手要注意什么
代理循环	收集上下文、执行动作、验证结果并重复	任务越复杂，计划与反馈越重要
内置工具	搜索、读写文件、运行 Shell、使用 Git	工具能力越强，越需要最小权限
权限模式	决定哪些动作需要人工确认	在模式名称旁确认当前实际权限
CLAUDE.md	保存每个会话都应知道的仓库指令	只写代码里不易推断的事实
Checkpoint	为文件编辑提供会话内回退能力	不能替代 Git，也不覆盖远程系统操作
/init、/doctor	初始化项目说明、诊断安装配置	自动生成内容仍要人工检查

Claude Code 官方将权限模式概括为 Auto、Manual、Accept Edits 和 Plan 等形态，并提供 Shift+Tab 切换。模式与默认值可能随版本和账号方案变化，执行高风险任务前应在界面中确认当前模式。(code.claude.com)

对项目上下文来说，CLAUDE.md 是开发者编写的持续指令，自动记忆是 Claude 根据纠正自行积累的笔记。两者都会被当作上下文，而不是无法绕过的安全配置；必需的限制应放到权限规则、Hooks、沙箱或 CI。(code.claude.com)

三、工作原理

一次可靠的新手会话大致经过以下路径：

确认系统、Shell 和 Git
        ↓
安装 Claude Code → 验证 claude --version
        ↓
选择登录方式 → /status 确认身份
        ↓
进入项目根目录 → 检查 git status → 建立安全基线
        ↓
只读调查 → Plan 模式确认方案 → 小范围编辑
        ↓
运行测试 / 构建 / 检查 → 根据反馈修复
        ↓
审查 diff 与证据 → 人工决定是否提交

Claude Code 的官方工作说明把代理循环分为收集上下文、采取行动和验证结果三个阶段。文件编辑虽有 Checkpoint 可回退，但 Git 仍是跨工具、跨会话和团队协作的主要版本安全网。数据库、部署、推送等远程副作用无法由本地 Checkpoint 撤销，必须依赖权限控制与人工审批。

四、实战示例

1. 准备运行环境

Windows 需要 10 1809 或更高版本、4 GB 以上内存和可用网络；Git for Windows 不是强制依赖，但安装后 Claude Code 可以使用 Bash 工具，通常更适合常见开发脚本。先打开 PowerShell 7 检查环境：

$PSVersionTable.PSVersion
git --version
winget --version

如果 git 不存在，先安装 Git for Windows 并重新打开终端。不要在 CMD 中执行 PowerShell 的 irm，也不要反过来执行 CMD 的 && 安装命令。

2. 安装并验证命令

官方推荐原生安装器，PowerShell 命令是：

irm https://claude.ai/install.ps1 | iex

这条命令会下载并执行官方安装脚本。组织有脚本审查要求时，应先核对下载来源、代理证书和内部软件策略，再决定是否执行。偏好包管理器时也可以使用：

winget install Anthropic.ClaudeCode

WinGet 安装不会像原生安装器一样后台自动更新，需要定期运行 winget upgrade Anthropic.ClaudeCode。安装完成后重新打开终端：

claude --version
claude doctor

能输出版本号表示命令已进入 PATH；claude doctor 用于检查安装和基础配置。若提示找不到 claude，先按 claude doctor 与官方安装排障文档修复 PATH，不要连续重复安装。

3. 登录并确认身份来源

推荐在项目目录中运行 claude，按官方流程打开浏览器完成订阅或 Console 登录。登录后在会话里执行：

/status

/status 可确认当前登录方式、组织和凭据来源。如果环境中同时设置了 ANTHROPIC_API_KEY，Claude Code 可能优先使用该 Key，导致你以为正在使用订阅账号。切换凭据前先清理错误的旧环境变量，再重新启动会话。

需要临时使用 API Key 时，不要把密钥写进仓库的 .env 文件，也不要直接粘贴到命令历史。可以在 PowerShell 密码输入框中读取，只注入当前终端进程：

$secureKey = Read-Host "Anthropic API Key" -AsSecureString
$env:ANTHROPIC_API_KEY = [System.Net.NetworkCredential]::new('', $secureKey).Password
Remove-Variable secureKey
claude
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue

这种方式只适合本地临时会话。CI 和团队环境应使用秘密管理工具、短期凭据或官方 apiKeyHelper，并为不同环境设置独立权限。不要把真实密钥写进 CLAUDE.md、.claude/settings.json 或截图。

4. 完成首个代码任务

先进入一个已经纳入 Git 的项目，确认起点：

Set-Location 'C:\work\my-project'
git status
git branch --show-current
claude

如果工作区已有未提交修改，先确认这些修改属于谁。不要在包含他人改动的文件上直接开始大范围重构。第一次会话先要求只读调查：

请先只读分析这个项目。告诉我：
1. 项目做什么、如何启动、如何运行测试；
2. 入口文件和主要目录；
3. 当前工作区有哪些改动；
4. 如果我准备修改用户注册校验，应该先读哪些文件。
先不要编辑或运行有副作用的命令。

确认它对项目的理解后，再提交一个范围很小、验收明确的任务：

目标：为用户注册接口增加邮箱格式校验。

约束：
- 复用项目已有错误响应结构；
- 不修改数据库字段和公开 API 路径；
- 不引入新依赖；
- 不提交、不推送。

验收：
- 合法邮箱保持原有行为；
- 空值、缺少 @、非法域名返回既有参数错误格式；
- 新增测试，并运行相关测试与完整测试。

先给出最小实施计划，等确认后再改文件。

执行前按 Shift+Tab 切换到 Plan 模式，或明确要求"只计划、不修改"。计划阶段重点检查：是否找到了真实入口、是否遗漏鉴权与错误处理、测试是否覆盖边界。计划确认后再允许编辑。

5. 完成多文件修改与交互调试

跨文件任务应写出"允许改什么"和"必须保持不变什么"。例如：

目标：把订单服务中散落的请求重试逻辑收敛到现有 HttpClient 封装。

允许修改：
- src/orders/ 下的调用方；
- 对应单元测试；
- docs/orders.md 中与重试配置有关的说明。

保持不变：
- 所有公开接口及默认重试次数；
- 现有鉴权和日志字段；
- 不修改项目依赖版本。

验收：
- 先用现有测试建立基线；
- 补充只读操作重试、幂等操作重试、不可重试错误三类用例；
- 执行聚焦测试、完整测试和类型检查；
- 最后按文件总结 diff 和未覆盖风险。

遇到构建或测试失败时，不要直接说"帮我修一下"。要求它先复现和定位：

运行失败的测试，完整读取错误输出。
先找出根因和最小复现，不要立刻修改。
确认根因后：
1. 先加一个能复现该问题的回归测试；
2. 做最小修复；
3. 先运行失败测试，再运行完整测试；
4. 汇报失败前后的实际命令与结果。

"最小复现 → 回归测试 → 最小修复 → 分层验证"比盲目修改更可靠。若助手连续两次修复都没有进展，停止扩大改动，回到原始错误、版本和输入条件重新定位。

6. 用 CLAUDE.md 固化项目上下文

在项目根目录的会话中运行：

/init

Claude Code 会生成初始 CLAUDE.md。不要直接接受自动生成的全部内容，删除可随时从代码发现的目录说明，只保留每次会话真正需要的命令和约定。一个精简示例是：

# Project Instructions

## Commands
- Install: `python -m pip install -e ".[dev]"`
- Focused test: `python -m pytest tests/unit -q`
- Full check: `python -m pytest && ruff check .`

## Invariants
- Public API paths and response envelopes are backward compatible.
- Money is stored as integer cents; never use float for financial totals.
- Do not edit files under `generated/`.

## Workflow
- Inspect before editing; propose a plan for changes touching 3+ files.
- Run focused tests first, then the full check.
- Never commit secrets, environment files, or local settings.

把个人项目偏好写进 CLAUDE.local.md，并确保它不进入提交；团队共享的稳定规则放在项目 CLAUDE.md。如果仓库已经使用 AGENTS.md，Claude Code 也支持将其作为项目说明来源，具体加载顺序以当前官方文档为准。

7. 设置权限与敏感路径边界

团队共享规则可放在 .claude/settings.json，个人覆盖放在 .claude/settings.local.json。下面示例允许读取 Git 状态、要求推送前确认，并拒绝读取常见秘密路径：

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

权限规则按实际命令和路径匹配，不能理解成完整沙箱。例如读取拒绝规则主要拦截明确命名的文件读写，递归搜索仍可能从目录获得信息。需要更强边界时，还应配置沙箱、Hooks 和系统目录权限。

在会话中执行 /permissions 可查看规则来源。遇到"路径不可访问"时，先确认 Claude Code 从哪个目录启动、目标是否在工作目录内，以及仓库是否已被信任；确实需要额外目录时，应由人工审阅后显式添加，不要用"跳过所有权限"来绕过问题。

8. 排查连接超时与权限错误

连接失败时，先按层排查：

能否运行 claude --version
        ↓ 否 → PATH / 安装问题
能否完成 /status
        ↓ 否 → 登录、凭据或代理问题
普通网页和 API 域名能否访问
        ↓ 否 → DNS、防火墙、代理
只有长任务超时
        ↓ 可能是网络波动、上游限流或任务范围

优先运行 claude doctor，再用 claude --debug 获取更明确的连接和配置信息。企业代理通常使用标准环境变量；变量必须在启动 Claude Code 之前设置，运行中的会话不会自动读取后来的终端变量。

$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
$env:NO_PROXY = 'localhost,127.0.0.1,.example.internal'
claude doctor
claude --debug

代理证书、IP 白名单和 WebSocket 域名需要按组织网络配置处理。不要在连接失败时反复重装，也不要把代理密码保存到项目配置；先确认错误属于安装、登录、证书还是上游服务，再采取对应措施。

遇到权限拒绝时，先查看请求的具体命令或路径。拒绝一次高风险动作并不会破坏项目；为了"让它继续跑"而关闭全部保护，才会把单个任务变成不可控的机器级操作。

9. 用证据验收结果

任务结束时，要求助手给出可重复的验证摘要：

请进入验收阶段：
1. 列出修改文件和每个文件的作用；
2. 运行 git diff --check；
3. 运行相关测试、完整测试和项目已有的类型检查；
4. 按"需求项 → 证据 → 结果"列出验收矩阵；
5. 明确失败、跳过、警告和未验证的部分；
6. 不要提交或推送。

然后由开发者自己查看：

git status --short
git diff --stat
git diff --check
git diff

测试命令根据项目替换成 npm test、python -m pytest、go test ./... 或其他实际命令。测试全绿仍不代表业务一定正确，还要检查接口兼容、权限、迁移脚本、日志泄露和依赖变化。

10. 建立高效的协作节奏

每次任务开始前确认工作区，任务结束后审查 diff；每次只解决一个可验证问题。对多文件方案先 Plan，对高风险命令逐次批准，对并行任务使用独立分支或 worktree。完成一个明确阶段后及时提交，避免几十个文件混在一次未审查的改动里。

会话变长且已经切换到新主题时，使用 /clear 开始干净上下文；需要恢复旧会话时使用 /resume。不要为了"保留记忆"把无关历史一直堆在同一会话里。

五、常见问题与实践建议

1. 安装后提示找不到 claude

这是 PATH 问题，不是模型问题。重新打开终端后仍失败，执行官方安装排障流程并检查安装目录；不要连续运行多个安装器导致版本来源混杂。

2. 已经登录但请求仍使用错误账号

运行 /status，检查环境中的 ANTHROPIC_API_KEY 和其他认证配置。关闭会话，清理错误凭据，再重新启动；若需长期并行使用工作和个人账号，可按官方文档为不同账号设置独立配置目录。

3. 助手没有找到相关文件

先确认启动目录是仓库根目录，再补充入口名称、错误文本、请求路径等仓库外信息。仍然找不到时，检查 .gitignore、符号链接、网络路径和搜索工具。不要一开始就把整个项目粘贴进对话。

4. 一次修改过多文件

按 Esc 中断，恢复到可理解的状态，重新缩小任务。要求先列出计划、影响文件和验收命令，再分批修改。已经产生的文件修改可通过 Checkpoint 或 Git 回退，但数据库和远程服务操作不能依赖本地回退。

5. 测试通过但功能仍错误

检查测试是否只验证了 mock、是否漏了真实入口、是否跳过了关键用例。补充端到端或集成验证，并由开发者核对业务语义。测试是证据，不是正确性的全部。

6. 遇到危险命令

拒绝执行，要求解释命令将要改变什么；优先使用只读预览、测试环境或备份。不要因为当前处于 Auto 模式就默认所有外部副作用都可安全执行。

六、进阶思考

把规范分成不同层次。 偏好和知识放在 CLAUDE.md，项目级权限放在 .claude/settings.json，个人例外放在 local 设置，必须执行的安全策略放在企业托管设置、Hooks 或沙箱。层次清楚后，团队不需要把所有规则写成一大段提示词。

为 AI 协作设计代码结构。 清晰入口、可快速运行的测试、稳定的类型边界和较小模块，既方便人理解，也方便代理定位。若某类任务总要读取大量文档或人工解释，说明项目缺少可执行的工程契约。

建立可量化评估。 记录任务通过率、首次测试通过率、人工返工时间、diff 大小、失败回滚和凭据异常。评估应比较完整交付周期，而不是只看生成速度。

限定无人值守边界。 进入 CI 或自动化后，必须设置超时、预算、只读依赖、分支保护和人工合并门。无人值守不等于无限权限，自动化越独立，事前限制越要明确。

结论

Claude Code 的上手重点不是记住更多命令，而是建立"安全基线 → 只读调查 → 小范围实施 → 反馈修复 → 证据验收"的工作节奏。安装登录解决入口问题，Git、项目指令和权限规则解决边界问题，测试、diff 与人工审查解决可信问题。

掌握首次任务后，下一篇会进一步讨论怎样把需求转换成明确的目标、上下文、约束与验收标准，让 AI 编程助手的输出更稳定、更容易审查。

参考资料

• Claude Code：Quickstart
• Claude Code：Advanced setup
• Claude Code：Authentication
• Claude Code：How Claude Code works
• Claude Code：How Claude remembers your project
• Claude Code：Permissions
• Claude Code：Enterprise network configuration
• Claude Code：Troubleshooting