Claude Code 完整使用指南：从安装到工程化落地
- 开发工具
- 9天前
- 25热度
- 0评论
Claude Code 不是「再多一个聊天窗口」，而是 Anthropic 推出的智能体式编程工具：它能读懂整个仓库、跨文件改代码、执行终端命令、跑测试、操作 Git，并按你的自然语言目标把事情做完。
本文按真实上手顺序写：装起来 → 会用 → 写好项目约定 → 接工具与自动化。信息对齐 Claude Code 官方文档（2026），产品迭代快，细节以官网为准。
它到底能干什么
可以把它当成「能动手的高级同事」：
| 能力 | 说明 |
|---|---|
| 读代码库 | 按需搜索、阅读文件，不必手动塞满上下文 |
| 改代码 | 跨文件实现功能、修 bug、重构 |
| 跑命令 | 构建、测试、装依赖、查日志 |
| Git 协作 | 看 diff、提交、建分支、开 PR、处理冲突 |
| 接工具 | 通过 MCP 连 Jira、GitHub、数据库等 |
| 可扩展 | CLAUDE.md、Skills、Hooks、Subagents |
常用入口有四类，底层是同一套引擎，项目里的 CLAUDE.md、设置和 MCP 在多数场景可互通：
- 终端 CLI（功能最全，更新最快）
- VS Code / Cursor / JetBrains 扩展或插件
- Desktop 桌面端
- Web / 手机（claude.ai/code）
用之前先确认两件事
账号需要以下之一：Claude Pro / Max / Team / Enterprise，或 Anthropic Console（按 API 计费），或企业云（Bedrock 等）。免费版通常不包含 Claude Code。
环境上准备一个真实项目目录，会用终端即可。Windows 原生建议安装 Git for Windows，Claude 才能更好地用 Bash 工具；WSL 按 Linux 安装即可。
安装
优先用原生安装（会后台自动更新）：
macOS / Linux / WSL：
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell：
irm https://claude.ai/install.ps1 | iex
Windows CMD：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
PowerShell 提示符一般是 PS C:\...，CMD 则是 C:\...，命令别混用。
其他方式：
# macOS Homebrew（需手动 brew upgrade）
brew install --cask claude-code
# Windows WinGet（需手动 upgrade）
winget install Anthropic.ClaudeCode
验证：
claude --version
应看到版本号，并带有 (Claude Code)。旧版 npm 包已逐步被原生二进制取代，新装请优先走官方脚本。
第一次打开
cd /path/to/your/project
claude
首次会引导浏览器登录；之后凭证会本地保存。会话内切换账号用 /login。
登录后先别急着改代码，先问清楚：
这个项目是做什么的？用了哪些技术？入口在哪里？本地怎么启动和测试？
再试一个无风险小改动：
在主入口加一个 hello world 函数，并保证能通过现有构建或检查
是否自动写入文件，取决于下面的权限模式。
三种用法：交互、一句话、管道
交互模式（日常主用）：claude 进入多轮对话，改完、测完再 /exit，或按两次 Ctrl+D。
一次性任务：
claude "修复当前构建错误"
非交互 / 管道（脚本与 CI）：
claude -p "用中文说明这个仓库的目录结构"
tail -200 app.log | claude -p "如果有异常，总结根因与建议"
git diff main --name-only | claude -p "审查这些文件的安全风险"
claude -p "列出 3 个最紧急的技术债" --output-format json
-p 跑完即退出，适合嵌进流水线。
权限模式：Shift+Tab 切换
| 模式 | 行为 | 什么时候用 |
|---|---|---|
| 默认 | 改文件 / 敏感操作前询问 | 陌生仓库、学习期 |
acceptEdits |
自动批准文件编辑 | 任务明确、想加快迭代 |
plan |
只读分析、先出方案 | 大重构、先对齐再动手 |
auto（部分账号） |
后台安全检查，风险操作仍可能拦截 | 少确认又要兜底 |
启动时也可指定：
claude --permission-mode plan
经验上：新项目先 plan 或默认；小而清晰的改动再开 acceptEdits；无人值守 CI 不要随便「跳过全部权限」。
命令速查
启动与恢复
| 命令 | 作用 |
|---|---|
claude |
交互模式 |
claude "任务" |
一次性任务 |
claude -p "查询" |
非交互后退出 |
claude -c |
继续当前目录最近会话 |
claude -r |
选择并恢复历史会话 |
claude --worktree <name> |
独立 git worktree 开会话 |
claude --bg "任务" |
后台 Agent |
claude agents |
查看各会话状态 |
claude mcp list |
列出 MCP |
会话里常用 / 命令
输入 / 可补全。常用：/help、/clear、/compact（压缩上下文）、/model、/effort、/mcp、/skills、/usage、/init（生成 CLAUDE.md）、/loop、/schedule、/desktop、/exit。
版本不同命令可能略有增减，以会话内 /help 为准。
CLAUDE.md：给 Agent 的项目说明书
每次会话开始，Claude 都会读 CLAUDE.md。这是工程化里投入产出比最高的一步。
建议位置：
- 项目根目录
CLAUDE.md（入库，团队共享） ~/.claude/CLAUDE.md（个人全局偏好）.claude/rules/（规则拆文件）
在项目里先跑 /init，再人工精修。写短而可执行的约定，例如：
# 项目约定
## 技术栈
- 后端：Spring Boot 3 + MyBatis-Plus
- 前端：Vue 3 + TypeScript
## 命令
- 前端：`cd frontend && npm run build`
- 后端：`cd backend && mvn -DskipTests package`
## 风格
- Controller 保持薄，业务放 Service
- 不要引入项目里没有的 UI 库
## 禁区
- 不要改生产密钥相关配置
- 未经明确要求不要 force push
## Git
- 只有用户明确要求时才 commit / 开 PR
原则就四条：少而准、给清命令、划红线、随架构演进更新。Claude 也会积累 auto memory，但 CLAUDE.md 才是你可控、可共享的那一层。
怎么提问，比「会不会用 AI」更重要
差：
修一下 bug
好：
登录页在密码错误时会白屏。请从登录 API 响应处理到前端错误展示排查。
复现：输入错误密码 → 点击登录。修好后补充验证步骤或相关测试。
四个习惯很管用：
- 先探索再动手：「先分析认证模块，不要改代码」
- 复杂任务拆步：建表 → API → 页面 → 测试
- 写清验收标准：
npm test全绿、首屏无布局跳动等 - 给现象：堆栈原文、相关 issue、约束路径
可直接套用的片段
理解仓库：
用中文说明架构、核心模块和本地启动方式
修 Bug：
下面是堆栈：……请定位根因并修复，然后跑相关测试
加功能（推荐先 plan）：
为文章列表增加按标签筛选。先给出改动计划（涉及哪些文件），我确认后再实现
Git（注意：是否提交由你决定）：
看看我改了哪些文件；用简洁中文写 commit message 并提交（不要 push）
Code Review：
审查相对 main 的改动，按正确性 / 安全 / 性能 / 可维护性分类给意见
MCP：把外部工具接进会话
MCP 让 Claude 直接读写外部系统，少复制粘贴。
# 远程 HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 本地 stdio 示例
claude mcp add --transport stdio --env SOME_KEY=xxx myserver -- npx -y some-mcp-server
claude mcp list
会话内用 /mcp 完成认证。Scope 可选 local（默认）、--scope project（写入 .mcp.json，适合团队）、user。
接好之后就可以说人话：
根据 Jira ENG-4521 实现功能，并在 GitHub 开 PR
输入时用 @ 可引用 MCP 资源。工具默认可延迟加载，减轻上下文压力。
Skills：把重复流程固化成 /命令
Skills 是带 frontmatter 的 SKILL.md，相关时自动触发，或用 /skill-name 调用。
常见路径：~/.claude/skills/（个人）、.claude/skills/（项目，建议入库）。
最小例子 summarize-changes/SKILL.md：
---
description: 总结未提交改动并标出风险。用户问改了什么、要写 commit 或 review diff 时使用。
---
## 当前改动
!`git diff HEAD`
## 要求
用 2–3 条要点总结；列出风险（缺错误处理、硬编码、缺测试等）。无改动则直接说明。
!command`` 会在加载时执行命令，注入实时输出。团队可以沉淀 /review-pr、/release-notes 这类高频流程。
Hooks：自动 format，也能拦危险操作
Hooks 挂在生命周期节点上，例如每次编辑后跑 lint，或在危险命令前 deny。
常见配置位置：
~/.claude/settings.json（用户）.claude/settings.json（项目）.claude/settings.local.json（本机，通常 gitignore）
典型用法：PostToolUse 匹配 Edit|Write 后执行 format；PreToolUse 返回 deny 阻止破坏性命令。企业还可托管强制策略。细节见官方 Hooks 文档。
并行、Worktree 与多 Agent
两个功能互不踩脚：
claude --worktree fix-login-bug
claude --worktree feature-auth
claude agents # 查看各会话
claude --bg "迁移鉴权到 v2，完成后开 PR"
也可以在会话里说：
用 subagent 调查 token refresh 实现，只汇总结论，主会话先别改代码
子 Agent 有独立上下文，适合「先大范围阅读，再回主会话动手」，避免把主会话读爆。大迁移、全仓补测试可考虑多 Agent 编排，但安全与数据层改动仍建议你最终 review。
管道、CI 与定时任务
管道示例：
git log --oneline -20 | claude -p "用中文写今日站会摘要"
CI 里常见：PR review、失败日志归因、依赖审计。注意最小权限 Token、限制可写路径，且不要把密钥打进日志。
定时方面：
| 方式 | 适合 |
|---|---|
Routines（/schedule 或 Web/Desktop） |
关机也能跑：早间 PR 摘要等 |
| Desktop 定时任务 | 需要本机文件 |
| GitHub Actions / GitLab Cron | 跟仓库事件绑定 |
/loop |
当前会话内轮询 |
多端怎么选
| 你想… | 更合适的入口 |
|---|---|
| 终端深度开发、脚本 | CLI |
| 看 diff、@ 文件 | VS Code / Cursor / JetBrains |
| 多会话并排 | Desktop |
| 无本地环境、长任务挂起 | Web |
| CLI 转桌面看 diff | /desktop |
| 云端任务拉回终端 | claude --teleport（需订阅支持） |
省用量：别把上下文当垃圾桶
Pro 适合中轻度；长重构、多 Agent、高峰时段更容易顶限流，重度日常更宜 Max 或团队套餐（以官网定价为准）。
实用习惯：
- 一事一会话，做完就
/clear或新开 - 长会话中途
/compact - 先 plan 再改，减少无效试错
CLAUDE.md写清构建命令，少让模型反复猜- 大范围探索交给 subagent
- 简单任务不必上最强模型 / 最高 effort
上下文快满时：/compact，或让旧会话写交接说明再新开：
把当前进度、已改文件、未完成项写成交接说明，方便新会话继续
常见坑
装不上 / 找不到命令：检查代理与防火墙；PowerShell 与 CMD 别混用；重开终端确认 PATH。
Windows 体验怪：优先装 Git for Windows；项目放在用户可写目录。
改得不对：补验收标准，切 plan 对齐，检查 CLAUDE.md 是否过时，必要时 /clear 重来。
MCP 连不上：/mcp 看状态与鉴权；项目级配置可能显示 Pending approval。
更多见官方 Troubleshooting。
一条建议的上手路径
第 1 天：装好 → 登录 → 问清项目结构 → 做一个小改动 → 熟悉 Shift+Tab 与 /help。
第 1 周：/init 精修 CLAUDE.md → 固定「先 plan → 实现 → 测试」→ 用 Claude 写测试、修 lint、准备 commit。
第 1 个月：沉淀 2～3 个项目 Skills → 接 1～2 个高价值 MCP → worktree 并行 → 视需要加自动 format → 把重复劳动丢进 CI 或 Routines。
附录：开工提示模板
只读摸底：
你是本仓库的编码助手。请先只读探索，用中文回复。
1. 总结技术栈、目录结构、本地启动与测试命令
2. 标出和「用户登录」相关的核心文件
3. 不要修改任何文件
完成后停下，等我下达具体改动任务。
大任务：
目标：<一句话>
背景：<现象 / 链接 / 约束>
验收：
- [ ] <测试或手动步骤>
约束：
- 不要改 <路径>
- 不要提交 / 推送，除非我明确说
流程：先给简短计划 → 我确认 → 再实现 → 跑相关测试并汇报
主循环可以记成：
描述目标 → 读 CLAUDE.md → 探索代码 → 计划或改文件
→ 跑构建/测试 → 迭代至验收通过 →（可选）commit / PR
延伸阅读
会话里也可以直接问它：how do I create custom skills in Claude Code?，或输入 /help。
如果你已经在用 Cursor 或其他 Agent，可以把 Claude Code 当成「终端里的主力执行器」：编辑器里想方案，CLI 里落地长任务——两者并不互斥。