Claude Code 从安装到生产级工作流的完整手册

网上关于 Claude Code 的碎片教程很多：有人只讲 npm install，有人只晒一张 diff 截图，有人把 MCP 和权限混在一起讲。真正要上线时，你缺的不是「又一个快捷键」，而是一条从装 CLI 到 CI 绿灯的完整路径。

本篇是 Cloud Mac AI Stack · L6 支柱手册（L6-Q01）：把 Claude Code 当作端到端编码 Agent，从安装、第一天试跑、日常委托、MCP 接入，一直写到和 GitHub Runner 联动的生产级工作流。决策与权限门槛见 L3 决策首讲；MCP 逐步安装见 MCP 教程——本篇只管主线串联。

本篇知识骨架

下面不是 Claude Code 官方能力全集，而是本篇 L6-Q01 手册的主线树——每一枝对应正文一节，括号内是锚点。正文各节标题下方有知识骨架标注，与下表一一对应。未画进树的能力（Hooks、子代理、企业托管等）留给后续专题或官方文档。

从安装到生产级工作流 · 2026 年 6 月版

本篇主线（Claude Code 完整手册）
├── 环境选型（#prereq）
│   ├── macOS / Linux 官方支持边界
│   ├── 本地 Mac mini / MacBook vs Cloud Mac
│   └── Node 18+ · 网络 · Anthropic 账号 / API Key
├── 安装验收（#install）
│   ├── npm install -g @anthropic-ai/claude-code
│   ├── claude doctor · claude login
│   └── 5 步验收（进仓库根 · /help · 无 401）
├── 第一天试跑（#first-day）
│   ├── 小范围委托 + 全绿测试
│   ├── git diff 审查改动范围
│   └── 建立审查习惯（越界 → 回 L3 决策）
├── 项目边界（#claude-md）
│   ├── CLAUDE.md 最小模板（安装 / 测试 / 禁止改动）
│   └── 可执行命令优先于 prose 说明
├── 日常节奏（#daily）
│   ├── 三档委托（高 / 协作 / 低）
│   └── 四步循环（委托 → 观察 → 审查 → 合并）
├── 连接层（#mcp）
│   ├── ~/.claude.json · mcpServers
│   ├── GitHub / CodeGraph / Fetch 常见组合
│   └── /mcp 验收（细节 → MCP 安装教程）
├── CI 事实链（#ci）
│   ├── Diff（Claude Code）vs Fact（Runner）
│   ├── feature 分支 → self-hosted Runner → PR 绿灯
│   └── secrets 与 Agent 环境隔离
├── 生产清单（#production）
│   ├── CLAUDE.md / 权限 / MCP / 密钥 / CI / 审查 / 成本
│   └── 试跑 vs 生产级对照表
└── Stack 定位（#stack-map）
    ├── L0–L5 在 Cloud Mac AI Stack 中的位置
    └── 外链：L3 决策 · MCP 教程 · Runner 执行引擎

环境准备：Mac 还是 Cloud Mac？

知识骨架 · #prereq · 环境选型

Claude Code 官方支持 macOS 和 Linux。如果你只做 Web/后端，Linux 云主机也能跑；但只要涉及 xcodebuild、iOS 模拟器或 macOS 专属工具链，就必须有 macOS 环境。

• 本地 Mac mini / MacBook — 24GB 内存更稳（Chrome + Docker + Claude Code 并行时 16GB 容易 Swap），参考 M4/M5 选型
• Cloud Mac — 不想先买硬件、或需要与主力机隔离的开发/CI 环境，见 买还是租
• 不推荐 — 在主力笔记本上同时跑生产 secrets、无隔离的 Agent 与 CI Runner（见 Runner 隔离）

软件前置：Node.js 18+、可访问 Anthropic 的网络、Anthropic 账号（Claude Pro/Max/Team）或 API Key。

安装与登录（5 步验收）

知识骨架 · #install · 安装验收

以下命令在 macOS 终端执行（Cloud Mac 上同样适用）：

# 1. 全局安装 CLI
npm install -g @anthropic-ai/claude-code

# 2. 环境自检（Node 版本、PATH 等）
claude doctor

# 3. 登录（浏览器 OAuth 或 API Key）
claude login

第一天：跑通第一个委托任务

知识骨架 · #first-day · 第一天试跑

安装成功不等于「会用」。第一天只做一件事：让小范围改动 + 全绿测试，建立你对 Agent 行为的直觉。

1. 在仓库根创建或完善 CLAUDE.md（下一节详解）
2. 启动 claude，委托词示例：「给 README 增加一节『本地开发』，只改 README，不要动其他文件」
3. 观察 Agent 是否先读文件、再改、再执行你指定的验证命令
4. 用 git diff 审查改动范围，确认没有越界
5. 合并前自己再跑一遍测试命令（不要盲信「Agent 说通过了」）

第一天目标不是速度，而是建立审查习惯。如果你发现 Agent 频繁改错目录、乱执行危险命令，先回到 权限决策，不要急着上生产仓库。

CLAUDE.md：项目边界说明书

知识骨架 · #claude-md · 项目边界

CLAUDE.md 是 Claude Code 的「项目 README for Agent」——比给人看的 README 更强调可执行命令与禁止事项。生产级仓库几乎必备。

# 项目：my-saas

## 安装
pnpm install

## 测试（改代码后必须全跑）
pnpm test
pnpm lint

## 禁止改动
- 不要修改 .env、secrets/
- 不要升级 major 依赖除非明确要求
- 计费相关改动必须同时更新对应测试

## 目录约定
- src/app — Next.js 页面
- packages/api — 后端逻辑

写好 CLAUDE.md 后，同样任务的文件误改率和测试循环轮数通常会明显下降——我们在 工作站实测里，完整 CLAUDE.md 与空白模板相差约 20% 耗时。

日常开发工作流

知识骨架 · #daily · 日常节奏

试跑通过后，进入日常节奏。推荐把任务分成三档，而不是「什么都丢给 Agent」：

日常循环建议固定为四步：

1. 委托 — 说清范围、验收标准、禁止碰的目录
2. 观察 — 看 Agent 读了哪些文件、执行了哪些 shell
3. 审查 — git diff + 自己跑测试（与 CLAUDE.md 一致）
4. 合并 — PR + code review；不要直接在 main 上让 Agent 连续提交

与 Cursor 的分工：Cursor 适合编辑器内补全与小范围改写；Claude Code 适合跨文件 + shell + 测试循环的 Agent 任务。两者可以并存，但别指望一个工具覆盖所有场景。

接入 MCP（连接层）

知识骨架 · #mcp · 连接层

当 Agent 需要读 GitHub Issue、查代码图谱、拉 API 文档时，单靠仓库内 grep 不够——这时接 MCP（Model Context Protocol），相当于给 Claude Code 插上「标准 USB 接口」。

• 配置入口 — ~/.claude.json 的 mcpServers 段
• 常见组合 — GitHub MCP（Issue/PR）、CodeGraph MCP（影响面分析）、Fetch MCP（文档）
• 验收 — 在 Claude Code 里输入 /mcp，应看到 mcp__github__* 等工具

逐步安装与排错，跟 MCP 安装教程（15 分钟）；权限模型见 MCP 最小权限。MCP 是生产级工作流的必要组件，但不是第一天就必须全配——建议先跑通无 MCP 的基础流，再加 GitHub MCP。

接上 CI：Claude Code + Runner

知识骨架 · #ci · CI 事实链

本地 Agent 改完代码、测试绿了，还不算「生产级」——你还需要一条与开发机隔离的 CI 事实链。Stack 里的分工口诀：

Claude Code 生产 Diff，GitHub Runner 生产 Fact。

推荐工作流：

1. 开发者在 Cloud Mac / 本地 Mac 上用 Claude Code 完成改动，推送到 feature 分支
2. Self-hosted Runner（与 Agent 环境隔离）触发 xcodebuild test / pnpm test 等
3. PR 必须 CI 绿灯 + 人工 review 才能合并
4. 生产 secrets 只存在于 Runner 或密钥管理服务，不进 Agent 日常 shell 环境

Runner 注册与隔离配置：执行引擎 · 排队与 TCO · 一 job 一 workspace。

若本地同时跑 Ollama + Claude Code + Runner，注意内存排班，避免 Swap 拖慢 CI——见 并行排班。

生产级清单（上线前必查）

知识骨架 · #production · 生产清单

从「能跑」到「能上线」，过一遍这张表：

Stack 全链路地图

知识骨架 · #stack-map · Stack 定位

把本篇放进 Cloud Mac AI Stack，你在整条链上的位置如下：

• L0 底座 — 为什么用 Cloud Mac
• L1 执行 — GitHub Runner（Fact 层）
• L2 推理 — Ollama 私有推理（可选，本地 embedding/小模型）
• L3 编码 — 本篇 · Claude Code 完整手册（Diff 层主线）
• L4 连接 — MCP 三连通
• L5 自动化 — OpenHands Agent 平台

Stack 总架构图 + 五模块接入顺序见支柱地图 L6-Q02 · Claude Code 核心架构与 Stack 总图——本篇是其中「编码 Agent」段的落地手册。

常见问题

知识骨架 · #faq · 补充答疑

Claude Code 必须买 Mac 才能用吗？ 官方支持 macOS 和 Linux。涉及 iOS/macOS 构建时必须用 Mac，可本地或 Cloud Mac。

订阅和 API Key 怎么选？ 个人试跑 Pro/Max 订阅最省事；团队或 CI 集成往往用 API Key + 用量管控。成本对比见 模型计费。

生产级是不是一定要 MCP？ 小仓库可以没有；一旦要读 GitHub Issue、跨服务查文档，MCP 几乎是标配。

Agent 改坏了怎么办？ git checkout -- . 或 git stash；养成小步提交、频繁分支，别在脏工作区上堆多个委托。

• L3 决策：什么时候该让 Agent 正式接入
• Claude Code MCP 安装教程
• Mac mini 工作站实测
• GitHub Runner 执行引擎