TL;DR安装 Claude Code 后的第一次操作不应该是让它写代码。正确的顺序是安装认证 → 配置权限 → 验证项目上下文是否充分 → 做一个低风险的诊断任务。跳过前两步直接上功能的团队后面花在修复 AI 误操作上的时间是前期配置的 8-10 倍。安装与认证安装Claude Code 是一个 npm 全局包需要 Node.js 18 环境。# 安装npminstall-ganthropic-ai/claude-code# 验证claude--version安装完成后claude命令可用。首次运行会进入认证流程。认证方式Claude Code 支持两种认证路径适用场景完全不同|认证方式|适用场景|配置方式|| — | — | — ||Anthropic API Key|个人开发者、Max 订阅用户|export ANTHROPIC_API_KEYsk-ant-...||OAuth (Claude Pro/Team/Enterprise)|企业团队、组织账号|claude启动时自动引导浏览器 OAuth|API Key 方式# 写入 shell 配置zsh 用户echo#x27;export ANTHROPIC_API_KEYsk-ant-your-key-here#x27; ~/.zshrcsource~/.zshrc# 验证认证claudehello, verify authOAuth 方式直接运行claude终端会输出一个 URL在浏览器中打开并授权后自动完成认证。OAuth 方式不需要在本地存储 API Key更适合共享机器和企业环境。企业团队应优先选择 OAuth 方式避免成员在个人 shell 配置文件中明文存储密钥。如果公司使用 SSOOAuth 流程会自动对接企业的身份提供商无需额外配置。认证失败的常见原因|错误信息|原因|修复|| — | — | — ||Invalid API key|Key 复制不完整或过期|重新从 console.anthropic.com 复制||Billing hard limit reached|API 账户额度用尽|充值或提高限额||OAuth flow timeout|浏览器未在窗口期内完成|重新运行claude确保网络通畅||ECONNREFUSED|公司代理拦截 HTTPS 请求|配置HTTPS_PROXY环境变量|目录结构认证成功后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 执行工具调用时是否需要人工确认。选错模式的代价不是麻烦或方便的问题而是直接影响任务完成效率和事故半径。模式对比矩阵|模式|行为|适用场景|风险|确认提示 Token 成本|| — | — | — | — | — ||default|每个工具调用需确认Read 除外|学习阶段、敏感仓库、生产代码|低效但安全|高||plan|先展示完整计划确认后逐步执行|复杂任务、架构变更、跨模块修改|计划可能不准但执行可控|中||auto|自动执行已允许的操作仅未批准的操作需确认|成熟项目、测试覆盖好、非生产环境|可能越界修改|低||bypassPermissions|跳过所有确认全自动执行|CI/CD、Headless、隔离沙箱环境|生产事故风险极高禁止在日常使用|零|各模式的真实配置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 模式[1] 和 28 — GitHub Actions[2]。确认提示的 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:pnpminstall- Test:pnpmtest- Typecheck:pnpmtypecheck - Build:pnpmbuild## Architecture- src/modules/ 下按业务域分模块 - 共享逻辑放 src/shared/## Rules- 用 pnpm不要用npm或yarn- 改 API 要更新对应的测试## Safety- 不要编辑 .env* 文件 - 不要运行部署命令关于CLAUDE.md的完整配置方法见 04 — CLAUDE.md 项目记忆[3]。第四步执行一个低风险修改只有前三步都通过后才做第一个真正的代码修改。选择一个已知的小 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.jsonCLAUDE.md# CLAUDE.md## ProjectExpress.js 后端 API 服务。TypeScript Vitest Prisma PostgreSQL。 包管理器pnpm。Node20。## Commands- Install:pnpminstall- Dev:pnpmdev - Build:pnpmbuild - Test:pnpmtest- Test(single):pnpmtest-- src/routes/users.test.ts - Test(watch):pnpmtest----watch- Typecheck:pnpmtypecheck - Lint:pnpmlint - DB migrate:pnpmprisma migrate dev - DB generate:pnpmprisma 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 - 不要执行pnpmpublish - 数据库迁移需要逐个确认## Verification- 修改 src/routes/ 后pnpmtest-- src/routes/ - 修改 src/services/ 后pnpmtest-- 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|修改了上传中间件的配置但项目中已有适合的配置|不知道模块边界“顺手优化”||2|修改了 S3 客户端超时影响了其他使用 S3 的功能|不知道s3-client.ts是共享模块||3|测试文件用了 Jest APIjest.fn()项目用的是 Vitest|不知道测试框架||4|添加了sharp依赖但项目已有sharp在 devDependencies 里|没有仔细读 package.json||5|导入路径用了相对路径../../services/users项目用 path alias/|不知道项目的导入约定|后果• 功能分支的 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添加缺少的空值检查确保测试通过。任务分解和工具调用|步骤|工具调用|次数|| — | — | — ||读取目标文件|Read(“src/routes/users.ts”)|1||搜索相关代码|Grep(“validateInput”)|1||读取依赖模块|Read(“src/utils/validation.ts”)|1||找到测试文件|Grep(“users.test”)|1||修改代码|Edit(“src/routes/users.ts”, …)|1||运行测试|Bash(“pnpm test – src/routes/”)|1||查看变更|Bash(“git diff”)|1||总计| |8 次工具调用|各模式确认次数和 Token 开销|模式|需确认的调用|免确认的调用|确认次数|Token 开销|等待时间|| — | — | — | — | — | — ||default|全部 8 次|0|8|~4800 tokens|~2 分钟||plan|计划确认 1 次 执行确认 8 次|0|9|~5400 tokens|~2.5 分钟||auto allowlist|Edit(1) Bash·test(1)|Read(1) Grep(2) Bash·git(1)|2|~1200 tokens|~30 秒||bypass|0|全部 8 次|0|0|0|计算方式• 单次确认 Token 开销~600 tokens提示消息 用户输入 上下文重载• default 模式8 x 600 4800 tokens• plan 模式额外的计划展示和确认约增加 600 tokens• auto allowlist 模式Read/Grep/Glob 在 allowlist 中自动放行仅 Edit 和首次 Bash 需确认效率决策矩阵|项目特征|推荐模式|理由|| — | — | — ||第一次使用 Claude Code|default|先观察行为建立信任||测试覆盖率 50%|default 或 plan|修改风险高需要逐条确认||测试覆盖率 50-80%|auto allowlist|测试兜底allowlist 防越界||测试覆盖率 80%CI 完备|auto allowlist|自动化防线充分||CI/CD 管道|bypassPermissions|无人工交互但必须在隔离环境||生产代码库|auto denylist|必须有危险操作黑名单||个人实验项目|auto|低风险效率优先|环境变量调优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 作为工程代理运行时[4] 解释了四层架构权限模式是治理层的一部分。•上下文配置04 — CLAUDE.md 项目记忆[3] 详细说明如何编写有效的项目记忆05 — rules 路径作用域[5] 说明按路径拆分规则的方法。•安全与治理22 — Hooks 入门[6] 介绍确定性控制机制23 — PreToolUse 阻断[7] 说明如何在工具执行前拦截危险操作。•三个根因01 — 上下文搬运、验证缺失和权限失控[8] 建立了本文所依赖的诊断框架。•CI/CD 集成27 — Headless 模式[1] 和 28 — GitHub Actions[2] 说明 bypassPermissions 模式的正确使用场景。引用链接[1]27 — Headless 模式:./27-headless-mode.md[2]28 — GitHub Actions:./28-github-actions.md[3]04 — CLAUDE.md 项目记忆:./04-claude-md-project-memory.md[4]00 — Claude Code 作为工程代理运行时:./00-claude-code-as-agent-runtime.md[5]05 — rules 路径作用域:./05-rules-path-scoped-context.md[6]22 — Hooks 入门:./22-hooks-introduction.md[7]23 — PreToolUse 阻断:./23-pretooluse-guardrails.md[8]01 — 上下文搬运、验证缺失和权限失控:./01-context-validation-permission.md