安装、登录、权限模式和第一个真实仓库任务

TL;DR： 安装 Claude Code 后的第一次操作不应该是让它写代码。正确的顺序是：安装认证 → 配置权限 → 验证项目上下文是否充分 → 做一个低风险的诊断任务。跳过前两步直接上功能的团队，后面花在修复 AI 误操作上的时间是前期配置的 8-10 倍。

安装与认证

安装

Claude Code 是一个 npm 全局包，需要 Node.js 18+ 环境。

# 安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

安装完成后，claude 命令可用。首次运行会进入认证流程。

认证方式

Claude Code 支持两种认证路径，适用场景完全不同：

API Key 方式：

# 写入 shell 配置（zsh 用户）
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

# 验证认证
claude "hello, verify auth"

OAuth 方式：

直接运行 claude，终端会输出一个 URL，在浏览器中打开并授权后自动完成认证。OAuth 方式不需要在本地存储 API Key，更适合共享机器和企业环境。企业团队应优先选择 OAuth 方式，避免成员在个人 shell 配置文件中明文存储密钥。如果公司使用 SSO，OAuth 流程会自动对接企业的身份提供商，无需额外配置。

认证失败的常见原因

目录结构

认证成功后，Claude Code 在用户主目录创建配置结构：

~/.claude/
├── CLAUDE.md              # 用户级全局指令（所有项目生效）
├── settings.json          # 用户级全局设置（权限、环境变量）
├── credentials           # 认证信息（自动管理，不要手动编辑）
└── memory/               # 跨项目自动记忆

项目级配置则在仓库内：

<repo>/
├── CLAUDE.md              # 项目级指令（推荐放在根目录）
├── .claude/
│   ├── CLAUDE.md          # 项目级指令（备选位置，等同根目录版本）
│   ├── settings.json      # 项目级设置（提交到 git，团队共享）
│   ├── settings.local.json # 项目级本地设置（不提交，个人偏好）
│   ├── rules/             # 路径作用域规则
│   │   ├── frontend.md
│   │   └── backend.md
│   ├── hooks/             # Hook 脚本
│   └── memory/            # 项目级自动记忆

settings.json 加载优先级（后加载的覆盖先加载的）：

~/.claude/settings.json           → 全局基线
<repo>/.claude/settings.json      → 项目级覆盖（git 追踪，团队共享）
<repo>/.claude/settings.local.json → 本地覆盖（.gitignore 排除）

这个三级优先级意味着：团队可以在 settings.json 中定义共享的安全策略，个人在 settings.local.json 中添加自己偏好的命令，两者不冲突。比如团队在 settings.json 中统一 deny 了 git push*，个人在 settings.local.json 中添加了 Bash(docker*) 用于本地容器调试，这两条规则会合并生效。settings.local.json 应该在 .gitignore 中排除，避免个人偏好污染团队配置。

四种权限模式深度对比

权限模式决定了 Claude Code 执行工具调用时是否需要人工确认。选错模式的代价不是"麻烦"或"方便"的问题，而是直接影响任务完成效率和事故半径。

模式对比矩阵

各模式的真实配置

default 模式（无需额外配置，这是内置默认值）：

// .claude/settings.json — default 模式即无额外配置
{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

每次 Claude Code 调用 Edit、Write、Bash 时，终端会暂停并等待用户输入 y 确认。一个典型的 bug 修复任务（读 3 个文件、改 1 个文件、跑 1 次测试）会产生约 5-8 次确认提示。

plan 模式：

// .claude/settings.json — plan 模式
{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

启动方式：claude --plan 或会话中使用 /plan 命令。Claude Code 会先输出完整的执行计划，列出所有将要做的事情，等用户确认后再开始执行。适合你不确定 AI 会怎么改、需要先审查意图的场景。

auto 模式（推荐用于日常开发）：

// .claude/settings.json — auto 模式 + allowlist
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "LS",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(npm run typecheck*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add*)",
      "Bash(node*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(curl*|*)",
      "Bash(wget*)",
      "Write(.env*)",
      "Edit(.env*)"
    ]
  }
}

allowlist 中的操作自动执行，denylist 中的操作直接拒绝，不在两个列表中的操作仍需确认。这是日常开发中效率和安全性的最佳平衡点。

bypassPermissions 模式：

// .claude/settings.json — 仅限 CI/沙箱环境
{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

启动方式：claude --dangerously-skip-permissions。这个模式不在 settings.json 中配置，而是通过命令行参数启用。永远不要在日常开发中使用这个模式。它存在的唯一理由是 CI/CD 管道和完全隔离的沙箱环境，详见 27 — Headless 模式 和 28 — GitHub Actions。

确认提示的 Token 成本分析

每次确认提示不是"按一下 y 那么简单"。确认提示的完整流程是：

Claude Code 暂停 → 输出确认消息（~50-100 tokens）
→ 用户输入 y → 系统回传确认（~20 tokens）
→ 模型重新加载上下文继续推理（~200-500 tokens）

单次确认的 Token 成本约 270-620 tokens。一个中等复杂度的 bug 修复任务在 default 模式下可能产生 10-15 次确认，总成本约 2700-9300 tokens 的纯开销——这些 tokens 没有产出任何有用信息，全部花在"等待确认"这个流程上。

以 Claude Sonnet 的定价计算，9300 tokens 约 $0.014。金额不大，但这些 tokens 占用的是上下文窗口空间。在 200K 的窗口里，9000 tokens 意味着约 4.5% 的有效空间被确认流程消耗。对于长会话，这个成本会显著挤压模型可用的推理空间，加速触发压缩。

auto 模式 + 精确 allowlist 的实际收益：

同样的 bug 修复任务，配置好 allowlist 后：

• Read、Grep、Glob 自动放行（3-5 次调用免确认）
• npm test 自动放行（1-2 次调用免确认）
• 仅 Edit/Write 需确认（1-2 次）
• 总确认次数从 10-15 降到 1-2
• 节省 Token 开销约 5000-8000 tokens

确认提示减少还意味着上下文中断更少。模型在连续执行中能维持更完整的推理链路，每次被打断确认都会造成微小的注意力偏移。对于需要连贯推理的复杂任务，这种偏移的累积效果不可忽视。

第一个任务：诊断框架

团队第一次在真实仓库中使用 Claude Code，任务不应该是"实现一个功能"，而应该是"诊断 Claude Code 是否具备足够的上下文来正确操作这个项目"。

这个诊断分四步，每一步都有明确的验证标准。

第一步：让 Claude Code 解释项目结构

在项目根目录启动 claude，输入：

阅读 README、package.json 和项目根目录结构。
用你自己的话告诉我：
1. 这个项目是做什么的
2. 如何安装依赖
3. 如何运行测试
4. 如何构建
5. 主要目录各自的作用

验证标准：逐条检查 Claude Code 的回答是否与实际一致。

常见错误信号：

• 把 pnpm 项目说成 npm 项目 → CLAUDE.md 缺失命令配置
• 不知道测试框架 → 没有读取测试配置文件
• 目录作用描述模糊 → 项目结构不在记忆中
• 把 monorepo 当成单体项目 → 缺少架构边界说明

第二步：验证构建和测试命令

运行安装、类型检查和测试命令，报告每个命令的结果。
如果有命令失败，说明失败原因和你建议的修复方式。

验证标准：

• 安装命令执行成功
• 类型检查通过（或有明确错误）
• 测试全部通过（或有明确失败用例）
• Claude Code 正确识别了包管理器（pnpm/npm/yarn/bun）

如果这步失败，说明环境本身有问题，任何代码修改任务都不会有好结果。先修复环境。

第三步：评估上下文充分性

根据前两步的结果，判断是否需要补充 CLAUDE.md：

基于你对这个项目的理解，列出：
1. 你目前不确定的项目约定
2. 你可能会误判的模块边界
3. 你不知道但做任务时可能需要知道的规则

验证标准：如果 Claude Code 列出的"不确定"超过 3 条，说明 CLAUDE.md 需要补充。

至少应该创建一个最小 CLAUDE.md：

# CLAUDE.md

## Commands
- Install: pnpm install
- Test: pnpm test
- Typecheck: pnpm typecheck
- Build: pnpm build

## Architecture
- src/modules/ 下按业务域分模块
- 共享逻辑放 src/shared/

## Rules
- 用 pnpm，不要用 npm 或 yarn
- 改 API 要更新对应的测试

## Safety
- 不要编辑 .env* 文件
- 不要运行部署命令

关于 CLAUDE.md 的完整配置方法，见 04 — CLAUDE.md 项目记忆。

第四步：执行一个低风险修改

只有前三步都通过后，才做第一个真正的代码修改。选择一个已知的小 bug 或文档过期问题：

修复 docs/ 中一个明显过期的命令引用。
修改后运行最小相关的检查命令。
最后报告：修改了哪些文件、diff 内容、验证结果、剩余风险。

验证标准：

• 修改文件数 <= 2（超过说明改多了）
• 测试通过（改了代码但测试挂了说明改法有问题）
• Claude Code 报告了剩余风险（说明它知道自己的修改边界）

完整配置示例：TypeScript 服务项目

以下是一个典型的 TypeScript 服务项目在首次使用 Claude Code 时的完整配置。

项目假设

一个 Express + TypeScript + Vitest 的后端服务，使用 pnpm 管理：

my-service/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   └── rules/
│       └── api-routes.md
├── src/
│   ├── routes/
│   ├── services/
│   ├── middleware/
│   └── utils/
├── tests/
├── tsconfig.json
├── vitest.config.ts
└── package.json

CLAUDE.md

# CLAUDE.md

## Project
Express.js 后端 API 服务。TypeScript + Vitest + Prisma + PostgreSQL。
包管理器：pnpm。Node >= 20。

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Test (single): pnpm test -- src/routes/users.test.ts
- Test (watch): pnpm test -- --watch
- Typecheck: pnpm typecheck
- Lint: pnpm lint
- DB migrate: pnpm prisma migrate dev
- DB generate: pnpm prisma generate

## Architecture
- src/routes/ — API 路由处理，每个资源一个文件
- src/services/ — 业务逻辑，routes 调用 services
- src/middleware/ — 中间件（认证、日志、错误处理）
- src/utils/ — 工具函数，无状态
- tests/ — 测试文件，结构与 src/ 对应

## Rules
- 测试框架是 Vitest，不是 Jest。用 vi.fn() 不是 jest.fn()
- 导入路径用 TypeScript path alias：@/routes/users
- 错误处理使用 src/utils/errors.ts 中的标准错误类
- API 响应统一使用 { success: boolean, data?: T, error?: string } 格式
- 不要引入新的依赖，除非明确要求

## Safety
- 不要编辑 .env* 文件
- 不要运行 prisma migrate reset
- 不要执行 pnpm publish
- 数据库迁移需要逐个确认

## Verification
- 修改 src/routes/ 后：pnpm test -- src/routes/
- 修改 src/services/ 后：pnpm test -- src/services/
- 任何修改后：pnpm typecheck

.claude/settings.json（团队共享）

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "LS",
      "Bash(pnpm test*)",
      "Bash(pnpm lint*)",
      "Bash(pnpm typecheck*)",
      "Bash(pnpm build*)",
      "Bash(pnpm dev*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add*)",
      "Bash(git branch*)",
      "Bash(node*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(git clean*)",
      "Bash(curl *)",
      "Bash(wget*)",
      "Bash(pnpm publish*)",
      "Bash(sudo*)",
      "Write(.env*)",
      "Edit(.env*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_MAX_TURNS": "50"
  }
}

.claude/settings.local.json（个人偏好，不提交）

{
  "permissions": {
    "allow": [
      "Bash(docker*)",
      "Bash(pnpm prisma studio*)"
    ]
  }
}

settings.local.json 加在 .gitignore 中：

# .gitignore 追加
.claude/settings.local.json
.claude/memory/

.claude/rules/api-routes.md

---
paths:
  - "src/routes/**"
  - "tests/routes/**"
---

# API Routes Rules

- 每个路由文件导出一个 Router 实例
- 路由参数用 Zod schema 校验
- 错误统一抛出，由 src/middleware/error-handler.ts 捕获
- 新增路由必须补对应的测试文件

失败案例：跳过上下文配置的代价

这是真实发生在一个 6 人团队的案例。

背景

团队决定试用 Claude Code 加速开发。周一早上，技术负责人在群里发了安装命令和 API Key，让大家直接用。没有写 CLAUDE.md，没有配 settings.json，没有做诊断任务。

事件

周三下午，一个开发者让 Claude Code 实现"用户可以上传头像"的功能。任务本身涉及 2 个文件：新增一个 API 端点（src/routes/users.ts 加一个 POST handler）和对应的 service 方法（src/services/users.ts 加一个 uploadAvatar 函数）。

Claude Code 实际做了什么：

1. 在 src/routes/users.ts 添加了 POST /users/:id/avatar 路由 -- 正确
2. 在 src/services/users.ts 添加了 uploadAvatar 方法 -- 正确
3. 新建了 src/services/image-resize.ts -- 未要求，但合理
4. 修改了 src/middleware/upload.ts -- 认为需要调整文件上传中间件的配置
5. 修改了 src/utils/s3-client.ts -- 修改了 S3 上传的超时配置
6. 新建了 tests/routes/users-avatar.test.ts -- 使用 describe/it/expect 的 Jest 风格
7. 修改了 package.json -- 添加了 sharp 依赖用于图片压缩

问题清单：

后果

• 功能分支的 CI 构建失败：Vitest 不认识 jest.fn()，类型检查报错。
• 原有的文件上传功能（PDF 导出）被中间件修改影响，集成测试挂了 2 个。
• 代码审查花了 40 分钟，发现上述所有问题。
• 开发者花了 2 小时回滚不必要的修改，只保留路由和 service 的变更。
• 修复后的版本只改了 2 个文件，测试通过。

根因分析

所有问题追溯到同一个根因：没有 CLAUDE.md。

Claude Code 不知道：

• 项目用 Vitest 而非 Jest（测试框架错误）
• 导入用 path alias（导入风格错误）
• src/middleware/upload.ts 和 src/utils/s3-client.ts 不需要改（模块边界不清）
• 项目已有 sharp（重复依赖）

一个 15 分钟就能写好的 CLAUDE.md，可以避免这 2 小时的修复工作。按投入产出比算，写 CLAUDE.md 的 15 分钟在这一个任务上就收回了 8 倍的时间投资。后续每个任务都持续享受这个回报。

修复措施

团队事后添加了上面"完整配置示例"章节中的 CLAUDE.md、settings.json 和 rules。同时按本文"落地验证清单"做了完整的初始诊断。此后同类任务的结果：

• 修改文件数从 7 降到 2
• 测试一次通过（使用正确的 Vitest API）
• 不再修改无关模块
• 代码审查时间从 40 分钟降到 10 分钟

权限模式的性能分析

用数据量化不同权限模式在同一个任务上的效率差异。

测试任务

修复一个 TypeScript 服务中的输入校验 bug：添加缺少的空值检查，确保测试通过。

任务分解和工具调用

各模式确认次数和 Token 开销

计算方式：

• 单次确认 Token 开销：~600 tokens（提示消息 + 用户输入 + 上下文重载）
• default 模式：8 x 600 = 4800 tokens
• plan 模式：额外的计划展示和确认约增加 600 tokens
• auto + allowlist 模式：Read/Grep/Glob 在 allowlist 中自动放行，仅 Edit 和首次 Bash 需确认

效率决策矩阵

环境变量调优

settings.json 的 env 字段可以设置影响 Claude Code 行为的环境变量：

{
  "env": {
    "CLAUDE_CODE_MAX_TURNS": "50",
    "CLAUDE_CODE_USE_BEDROCK": "0"
  }
}

CLAUDE_CODE_MAX_TURNS 限制单次会话的最大工具调用轮次。默认值较高（200），对于日常 bug 修复任务，设为 50 足够，同时防止失控循环消耗大量 Token。如果任务经常在 50 轮内完不成，说明任务粒度太粗，应该拆分。这个参数不是优化项，而是成本控制手段——一个没有边界限制的会话可能因为模型陷入循环而消耗大量 Token。建议团队为不同类型的任务设定不同的轮次上限：bug 修复 30-50 轮，功能开发 50-100 轮，重构任务 100-150 轮。超出上限说明任务需要拆解或者项目上下文配置不够充分，模型在反复探索中浪费了轮次。

落地验证清单

以下清单用于验证 Claude Code 在项目中的初始配置是否到位。每个条目都有明确的验证方式。

环境与认证

• claude --version 输出正确版本号
• claude "hello" 正常响应，无认证错误
• API Key 或 OAuth 认证成功
• 公司代理环境下 HTTPS_PROXY 已配置（如需要）

项目上下文

• Claude Code 能正确列出项目目录结构（第一步验证）
• Claude Code 知道测试命令和包管理器（第二步验证）
• Claude Code 能正确运行 install/test/typecheck（第二步验证）
• CLAUDE.md 已创建，包含 Commands、Architecture、Rules、Safety 四段
• Claude Code 的"不确定"条目 <= 3 条（第三步验证）

权限配置

• .claude/settings.json 已创建，包含 allowlist 和 denylist
• allowlist 覆盖 Read/Grep/Glob + 测试/lint/typecheck 命令
• denylist 覆盖 rm -rf / git push --force / .env 写入 / 部署命令
• 权限模式与项目风险等级匹配（参见效率决策矩阵）
• .claude/settings.local.json 在 .gitignore 中排除

首次任务验证

• 第一个任务修改文件数 <= 2
• 修改后测试全部通过
• Claude Code 报告了 diff 内容和验证结果
• Claude Code 列出了剩余风险
• 无非预期文件被修改（git diff 中无意外文件）

团队共享

• CLAUDE.md 已提交到 git
• .claude/settings.json 已提交到 git
• .claude/rules/ 按路径域拆分（如需要）
• 团队成员拉取代码后无需额外配置即可使用

与系列其他章节的关系

本文覆盖了 Claude Code 从安装到首次任务的完整流程。每个配置点的深入内容在后续章节展开：

• 运行时心智模型：00 — Claude Code 作为工程代理运行时 解释了四层架构，权限模式是治理层的一部分。
• 上下文配置：04 — CLAUDE.md 项目记忆 详细说明如何编写有效的项目记忆，05 — rules 路径作用域 说明按路径拆分规则的方法。
• 安全与治理：22 — Hooks 入门 介绍确定性控制机制，23 — PreToolUse 阻断 说明如何在工具执行前拦截危险操作。
• 三个根因：01 — 上下文搬运、验证缺失和权限失控 建立了本文所依赖的诊断框架。
• CI/CD 集成：27 — Headless 模式 和 28 — GitHub Actions 说明 bypassPermissions 模式的正确使用场景。