<!-- title: 装通配好并接入首个真实工程 -->

# 零基础装通 Claude Code 并接入首个真实工程：从安装到调试闭环

## 概述

市面上的 Claude Code 入门教程大多教你"从零造一个小工具"。但真实工作里，你面对的几乎都是**别人写好的既有工程**——一个从 GitHub clone 下来的仓库、一个团队接手的老项目、一个你想贡献 PR 的开源库。本教程换一个更贴近实战的角度：带你**装通 Claude Code、配好权限作用域，然后接入一个既有工程，完成"读懂代码 → 定位 Bug → 改代码 → 跑测试 → 提交"的完整调试闭环**。适合零基础开发者、刚转 AI 辅助编程的同学，以及想给团队制定 Claude Code 使用规范的技术负责人。

## 前置条件

- 一台 macOS 13+、Windows 10 1809+、Ubuntu 20.04+ 或 Debian 10+ 的机器（ARM/x64 均可），4GB 以上内存。
- 一个可用的终端；Windows 用户建议预装 [Git for Windows](https://git-scm.com/downloads/win)，这样 Claude Code 才能用 Bash 工具执行命令。
- 一个 Claude 账号：Pro / Max / Team / Enterprise 订阅，或 [Claude Console](https://console.anthropic.com/)（预付费 API 额度），或企业云（Amazon Bedrock 等）。
- 一个可联网的环境（首次登录与模型调用需要）。
- 一个既有代码项目——没有的话，本文实战环节会给你一个可一键复现的"带 Bug 的既有工程"。

## 步骤一：选对安装方式并装通

Claude Code 官方现在推荐**原生安装（Native Install）**，它会自动后台更新，省去手动升级的麻烦。

**macOS / Linux / WSL：**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows PowerShell：**

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

**Windows CMD：**

```batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

如果你偏好包管理器，也有三条路：

```bash
# Homebrew（macOS/Linux，两个 cask：claude-code 稳定、claude-code@latest 最新）
brew install --cask claude-code

# Windows
winget install Anthropic.ClaudeCode

# Linux 包管理器：Debian/Ubuntu 用 apt，Fedora/RHEL 用 dnf，Alpine 用 apk
```

**预期结果**：安装完成后，终端输入下面命令能看到版本号即装通。

```bash
claude --version
```

**常见问题与解决：**

- Windows 下报 `The token '&&' is not a valid statement separator`：说明你在 PowerShell 里跑了 CMD 语法，换到 CMD，或改用上面的 PowerShell 命令。
- 报 `'irm' is not recognized`：你在 CMD 里跑了 PowerShell 命令，提示符带 `PS` 的才是 PowerShell。
- 报 `syntax error near unexpected token '<'` 或 `403`：通常是网络代理拦截了脚本下载，给 curl 配代理（`HTTPS_PROXY`）后重试，或参考官方 [安装排错](https://code.claude.com/docs/en/troubleshoot-install) 页匹配错误。
- Homebrew / WinGet 装的版本**不会自动更新**，记得定期 `brew upgrade claude-code` 或 `winget upgrade Anthropic.ClaudeCode`。

## 步骤二：登录与认证

在任意目录直接启动：

```bash
claude
```

首次启动会提示你在浏览器完成登录。订阅用户或 Console 用户按引导授权即可；企业用户可在登录界面选择对应的云提供商或自托管网关。登录后凭证会存到本地，后续无需重复登录。中途想切换账号，在会话内输入：

```text
/login
```

**预期结果**：终端出现 Claude Code 的提示符，上方会显示**版本号、当前模型、工作目录**三行信息，说明会话已就绪。

**账号怎么选？** 个人开发选 Pro/Max 订阅最省心（包月不限量档）；做自动化或大量并发调用、需要精确计费选 Console（按 token 付费）；企业内受合规约束则走 Bedrock/Foundry 或自托管网关。

## 步骤三：搞懂四层配置作用域——配置该放哪？

这是新手最容易踩的坑：同一个设置，放在不同文件里，影响范围天差地别。Claude Code 用四级作用域管理配置：

| 作用域 | 位置 | 影响谁 | 是否随仓库共享 |
| :--- | :--- | :--- | :--- |
| **Managed**（托管） | 服务端下发 / `managed-settings.json` / 系统注册表 | 全组织或全机器 | 由 IT 部署 |
| **User**（用户） | `~/.claude/settings.json` | 你本人，跨所有项目 | 否 |
| **Project**（项目） | `.claude/settings.json` | 所有协作者 | 是（提交到 git） |
| **Local**（本地） | `.claude/settings.local.json` | 仅你本人、仅当前项目 | 否（默认 gitignore） |

**优先级**：Managed > 命令行参数 > Local > Project > User。也就是说项目级配置会覆盖你的个人配置，托管配置谁也覆盖不了。

**怎么用？** 记住三条原则：

1. **个人偏好**（主题、跨项目通用的工具放 User）：写进 `~/.claude/settings.json`。
2. **团队共享的规则**（项目要禁用哪些命令、挂哪些 MCP）：写进 `.claude/settings.json` 并提交，让队友拉下来就生效。
3. **只有你机器能跑、或正在试验**的配置：写进 `.claude/settings.local.json`，它被 Claude Code 创建时会自动加入 gitignore，不会被误提交。

CLAUDE.md（项目说明/记忆）遵循同样的分层：`~/.claude/CLAUDE.md`（个人）、`CLAUDE.md`（项目共享）、`CLAUDE.local.md`（本地私有）。

## 步骤四：用权限模式控制安全边界

Claude Code **默认会对每个文件改动、每条危险命令询问你**。但反复点确认很烦，于是有了四种权限模式（在 `settings.json` 里设 `defaultMode`，或会话中用 `/permissions` 切换）：

| 模式 | 行为 | 何时用 |
| :--- | :--- | :--- |
| `plan` | 只读探索：能读文件、跑只读命令，但**不改源码** | 让它先帮你"读代码出方案"，确认思路再动手 |
| `default`（默认） | 每次改动都问你 | 陌生项目、首次接入，最安全 |
| `auto` | 后台做安全校验后自动放行（研究预览特性） | 信任任务描述、想加速时 |
| `dontAsk` | 除 `allow` 列表里预批准的外，一律**自动拒绝** | 受限环境，强约束 |
| `bypassPermissions` | 跳过几乎所有提示（`rm -rf /` 这类仍有熔断） | **仅限容器/虚拟机**等隔离环境 |

**关键认知**：权限是 Claude Code（外壳）强制执行的，**不是模型自觉**。你在 CLAUDE.md 里写"不要删文件"只是建议，真正能拦住的是 `deny` 规则。所以接入既有工程时，**先用 `plan` 模式让它只读分析**，看清方案再切到 `default` 动手，是新手最稳妥的节奏。

## 步骤五：写出第一份 settings.json

在项目根目录建 `.claude/settings.json`，把团队要的"放行清单"和"红线"定下来：

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "defaultMode": "default",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}
```

**预期效果**：加上 `$schema` 后，VS Code/Cursor 里编辑这份文件会有自动补全和校验。保存后 Claude Code 会**热加载**（`permissions`、`hooks` 改动无需重启即生效，仅 `model` 等少数字段需要重启）。

**规则语法要点与避坑：**

- 格式是 `工具(参数)`：`Bash(npm run test *)` 放行测试命令、`Read(./.env)` 精确拦截敏感文件。
- Bash 用 `Bash(rm *)`，**不要**写 `Bash(command:rm *)`——`command` 这类已被规范化的字段不可匹配，写了会被忽略并报警告，等于规则失效、留下安全洞。
- 项目级 `.claude/settings.json` 的 `allow` 规则需要经过"工作区信任（workspace trust）"才会生效；而 `.claude/settings.local.json` 的 `allow` 因为是你私有文件，**直接生效**无需信任步骤。这是 Local 作用域一个实用的小优势。
- 想再加固一道：把 `Bash` 整体加进 `allow`，再挂一个 `PreToolUse` 钩子去拦你想禁的那几条——钩子退出码 2 会**先于**权限规则阻断调用。

## 步骤六：接入既有工程，跑通首个调试闭环

现在进入本教程的核心——**不在空白里生成代码，而是接入一个既有工程**。如果你手头有项目，直接 `cd` 进去；没有的话，用下面这段模拟一个"别人留下、带 Bug"的小模块（Node.js，零依赖）。

先建目录与文件：

```bash
mkdir cc-onboarding && cd cc-onboarding
git init && npm init -y
```

把下面这段"看似正确、实则有整数除法 Bug"的代码存为 `calc.js`：

```javascript
// calc.js —— 一个被同事留下、藏着 Bug 的既有模块
function avg(nums) {
  // 想算平均值
  return nums.reduce((a, b) => a + b, 0) / nums.length;
}

function tax(price, ratePct) {
  // 含税价 = 原价 × (1 + 税率%)；ratePct 是百分数
  return price * (1 + ratePct / 100);
}

module.exports = { avg, tax };
```

再写一个**故意会失败**的测试 `calc.test.js`：

```javascript
const assert = require('assert');
const { avg, tax } = require('./calc');

assert.strictEqual(avg([10, 20, 30]), 20);     // 期望 20
assert.strictEqual(tax(100, 8), 108);          // 期望 108
console.log('all tests passed');
```

启动 Claude Code，建议先用 `plan` 模式让它**只读分析**：

```bash
claude
```

在会话里说：

```text
先别改代码。读一下这个项目，告诉我 calc.js 做了什么，calc.test.js 里哪个断言现在会失败、为什么。
```

Claude 会调用 Read 工具读文件、可能跑 `node calc.test.js` 看到红字报错，然后告诉你：`avg` 里 `nums.reduce(...)/nums.length` 在 `[10,20,30]` 上得 20（这组碰巧对），但 `tax` 没问题……——这种引导会让你**先理解代码**而非盲改。

确认方案后，让它动手修（切回 default 模式）：

```text
补一组会暴露 avg 整数问题的用例（比如含小数），并修正实现，让 npm test 全绿。
```

**预期闭环**：Claude 先展示它要改的 diff → 你确认 → 它改文件 → 它主动跑 `npm test`（因为 `Bash(npm run test *)` 已在 allow 里，不会卡权限）→ 看到 `all tests passed` → 你让它 `提交这次修复`，它会生成规范的 commit message。

这就是一个完整的"接入既有工程 → 读懂 → 定位 → 修复 → 验证 → 提交"闭环，和真实工作流完全一致。

## 实战案例：给开源项目提一个"读后改"的最小改动

把上面的套路套到真实仓库上。以一个你想贡献的开源 Node CLI 为例：

```bash
git clone https://github.com/<owner>/<repo>.git
cd <repo>
claude   # 启动，默认 plan 模式
```

**Step A — 读懂**：

```text
用 plan 模式：这个仓库的入口在哪？依赖了哪些技术？README 里说的"快速开始"对应的代码路径是哪些文件？画一下模块依赖关系。
```

**Step B — 找一个 Good First Issue**：

```text
查一下 issues，找一个标签是 good first issue 的、描述清楚的小问题，告诉我它的根因可能在哪几个文件。
```

**Step C — 最小修复并自测**：

```text
切到 default 模式，按这个 issue 做最小改动，改完跑项目自带的测试命令，确保不破坏现有用例。
```

**Step D — 生成提交**：

```text
按这个项目的 commit 规范（看 git log 推断）写提交信息并提交到一个新分支。
```

整个过程中，权限规则帮你兜底：`deny` 里拦住的 `.env`、`secrets/**` 它读不了；`allow` 里放行的 `npm test` 不会反复打断你。这就是"装通 + 配好"之后，接入既有工程该有的顺滑体验。

## 工作流程图

```mermaid
flowchart TD
    A[选安装方式: native/brew/winget] --> B[claude --version 验证]
    B --> C[claude 启动 + /login 登录]
    C --> D{配置放哪?}
    D -->|个人偏好| E1[~/.claude/settings.json]
    D -->|团队共享| E2[.claude/settings.json 提交git]
    D -->|本地试验| E3[.claude/settings.local.json]
    E1 --> F[定权限: allow放行 + deny红线]
    E2 --> F
    E3 --> F
    F --> G[cd 既有工程]
    G --> H[plan 模式: 只读读懂代码]
    H --> I[default 模式: 改代码]
    I --> J[npm test 验证 自动放行]
    J --> K[生成规范 commit]
    K --> L[完成调试闭环]

    style D fill:#fef3c7
    style H fill:#dbeafe
    style J fill:#dcfce7
```

## 训练营适用性评估

- **适合的训练营类型**：① AI 辅助编程入门营（1–2 天）；② 新员工/新人上手营（侧重"接入既有工程"而非"造轮子"，更贴近真实工作）；③ 团队工程规范营（用四层作用域 + 权限模式做教学载体）。
- **预计教学时长**：纯讲解 + 跟做约 **90–120 分钟**；含接入真实开源项目提交 PR 的实战版约 **半天（3–4 小时）**。
- **难度分级**：⭐⭐（零基础可跟做），重点不在写代码，而在"配置作用域"和"权限模式"两个被多数教程忽略、却决定团队规模化体验的概念。
- **前置衔接**：可作为整个 Claude Code 系列的**第一课**，后续接 Skills 开发、MCP 服务器、Hooks 自动化等进阶主题。
- **延伸练习建议**：让学员两两结对，一人写一份"带 Bug 的既有工程"提交到 git，另一人用 Claude Code 接入并修复，体会"接入既有代码"的真实手感。

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方快速上手：安装、登录、首个会话与首次改代码的八步引导。
2. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 官方系统要求、各平台安装方式（native/Homebrew/WinGet/包管理器）与版本管理。
3. [Claude Code settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — 官方四层配置作用域（Managed/User/Project/Local）、settings.json 结构与 `$schema` 校验。
4. [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) — 官方权限模式（plan/default/auto/dontAsk/bypassPermissions）、allow/deny 规则语法与避坑。
5. [Claude Code settings.json: Complete config guide (2026) - eesel.ai](https://www.eesel.ai/blog/settings-json-claude-code) — 第三方对 settings.json 各选项的实操解读，补充官方文档的实战视角。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)