市面上的 Claude Code 入门教程大多教你"从零造一个小工具"。但真实工作里，你面对的几乎都是别人写好的既有工程——一个从 GitHub clone 下来的仓库、一个团队接手的老项目、一个你想贡献 PR 的开源库。本教程换一个更贴近实战的角度：带你装通 Claude Code、配好权限作用域，然后接入一个既有工程，完成"读懂代码 → 定位 Bug → 改代码 → 跑测试 → 提交"的完整调试闭环。适合零基础开发者、刚转 AI 辅助编程的同学，以及想给团队制定 Claude Code 使用规范的技术负责人。
Claude Code 官方现在推荐原生安装（Native Install），它会自动后台更新，省去手动升级的麻烦。
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
如果你偏好包管理器，也有三条路：
# 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
预期结果：安装完成后，终端输入下面命令能看到版本号即装通。
claude --version
常见问题与解决：
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）后重试，或参考官方 安装排错 页匹配错误。brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode。在任意目录直接启动：
claude
首次启动会提示你在浏览器完成登录。订阅用户或 Console 用户按引导授权即可；企业用户可在登录界面选择对应的云提供商或自托管网关。登录后凭证会存到本地，后续无需重复登录。中途想切换账号，在会话内输入：
/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。也就是说项目级配置会覆盖你的个人配置，托管配置谁也覆盖不了。
怎么用？ 记住三条原则：
~/.claude/settings.json。.claude/settings.json 并提交，让队友拉下来就生效。.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 动手，是新手最稳妥的节奏。
在项目根目录建 .claude/settings.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(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，零依赖）。
先建目录与文件：
mkdir cc-onboarding && cd cc-onboarding
git init && npm init -y
把下面这段"看似正确、实则有整数除法 Bug"的代码存为 calc.js：
// 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：
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 模式让它只读分析：
claude
在会话里说：
先别改代码。读一下这个项目，告诉我 calc.js 做了什么，calc.test.js 里哪个断言现在会失败、为什么。
Claude 会调用 Read 工具读文件、可能跑 node calc.test.js 看到红字报错，然后告诉你：avg 里 nums.reduce(...)/nums.length 在 [10,20,30] 上得 20（这组碰巧对），但 tax 没问题……——这种引导会让你先理解代码而非盲改。
确认方案后，让它动手修（切回 default 模式）：
补一组会暴露 avg 整数问题的用例（比如含小数），并修正实现，让 npm test 全绿。
预期闭环：Claude 先展示它要改的 diff → 你确认 → 它改文件 → 它主动跑 npm test（因为 Bash(npm run test *) 已在 allow 里，不会卡权限）→ 看到 all tests passed → 你让它 提交这次修复，它会生成规范的 commit message。
这就是一个完整的"接入既有工程 → 读懂 → 定位 → 修复 → 验证 → 提交"闭环，和真实工作流完全一致。
把上面的套路套到真实仓库上。以一个你想贡献的开源 Node CLI 为例：
git clone https://github.com/<owner>/<repo>.git
cd <repo>
claude # 启动，默认 plan 模式
Step A — 读懂：
用 plan 模式：这个仓库的入口在哪？依赖了哪些技术？README 里说的"快速开始"对应的代码路径是哪些文件？画一下模块依赖关系。
Step B — 找一个 Good First Issue：
查一下 issues，找一个标签是 good first issue 的、描述清楚的小问题，告诉我它的根因可能在哪几个文件。
Step C — 最小修复并自测：
切到 default 模式，按这个 issue 做最小改动，改完跑项目自带的测试命令，确保不破坏现有用例。
Step D — 生成提交：
按这个项目的 commit 规范（看 git log 推断）写提交信息并提交到一个新分支。
整个过程中，权限规则帮你兜底：deny 里拦住的 .env、secrets/** 它读不了；allow 里放行的 npm test 不会反复打断你。这就是"装通 + 配好"之后，接入既有工程该有的顺滑体验。
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
$schema 校验。[!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 等场景全覆盖。