核心理念：从“代码补全”到“代理式开发”
在使用 Claude Code 之前，最关键的是思维转变。它并非传统意义上的代码补全工具（如 Copilot），而是一个代理式 AI 编码环境（Agentic Coding Environment）。
这意味着你的角色从“写代码的人”转变为“提供目标和监督的架构师”。Claude Code 将自主负责后续的规划、实现、测试、修复直至提交的完整开发闭环。
一个典型的高效工作流如下：
- 目标 (Goal)：你提出明确的开发任务。
- 规划 (Plan)：Claude 分析代码库，提出详细的执行计划。
- 编码 (Edit Code)：根据计划修改或创建文件。
- 测试 (Run Tests)：执行预定义的测试并捕获错误。
- 修复 (Fix)：根据测试结果调试并修正代码。
- 提交 (Commit & PR)：生成规范的 Commit Message 并创建拉取请求 (Pull Request)。
掌握此流程是发挥 Claude Code 十倍潜力的关键。
第一阶段：安装与环境配置
1. 安装
a) CLI (命令行界面)
这是基础，即使使用 VS Code 扩展也建议安装。
b) VS Code 扩展 (强烈推荐)
提供图形化的 diff 审查、上下文管理和更流畅的开发体验。
- 在 VS Code 扩展市场搜索 “Claude Code for VS Code” 并安装。
- 通过快捷键
Option+K / Alt+K 可以快速引用文件。
- 特色功能:
- 实时 Token 显示: 随时监控上下文使用量，避免意外溢出。
- 代码可见性控制: 选中代码后点击“眼睛”图标，可精确控制 Claude 读取的代码范围。
- 并排 Diff 审查: 修改文件后，可通过 VS Code 内置的对比功能查看变更详情。
- Chrome 浏览器控制: 配合 MCP 可直接控制浏览器进行端到端测试。
c) 诊断工具
如果遇到环境问题，可使用 /doctor 命令检查 Claude Code 的运行环境、依赖项和配置状态，快速定位问题根源。
2. 权限与安全配置
首次运行时，Claude Code 会请求授权执行终端命令。
- 白名单: 使用
/permissions 命令将常用命令（如 npm test, git, bun install）加入白名单。
- 沙箱模式: 为了安全，可以使用
--sandbox 或在容器化环境中运行高风险操作。
- 配置文件: 可通过
.claude/settings.json 统一配置允许的命令列表，实现更精细的权限控制，避免每次都要手动确认。
3. (可选) 集成国内模型
你可以通过配置环境变量，将 Claude Code 的底层模型替换为国内提供商的模型。
# 示例：将模型替换为 GLM-5
export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
export ANTHROPIC_AUTH_TOKEN=你的API_KEY
export ANTHROPIC_MODEL=GLM-5
将以上命令加入 ~/.zshrc 或 ~/.bashrc 使其永久生效。
d) 非交互式运行 (CI/CD 集成)
Claude Code 支持在无人值守的环境中运行，适合自动化流程：
claude -p "prompt"
此模式可用于在 CI/CD 流水线中自动执行代码审查、生成文档或运行特定检查任务。
第二阶段：项目初始化与“AI 开发手册”
1. 创建 CLAUDE.md (最重要的一步)
在你的项目根目录下，运行 claude 并输入 /init。这会自动生成一个 CLAUDE.md 文件。
此文件是 AI 的核心开发手册，用于定义项目规范，确保 Claude 的所有操作都符合团队约定。
CLAUDE.md 示例:
# Project: Next.js SaaS Application
## Code Style & Conventions
- Use ES modules (`import/export`).
- Prefer `bun` over `npm` for package management.
- All new components must be functional components with TypeScript.
- Follow SOLID principles.
## Development Workflow
- Always run `bun typecheck` after making changes to TS files.
- New features must include unit tests written with Vitest.
- For speed, prefer single test runs over the full suite during development.
Claude 在每次交互时都会读取此文件，并将其作为最高行为准则。
2. 利用仓库上下文 (Repo Context)
除了 CLAUDE.md，Claude 还会自主学习项目的：
长期使用后，它对项目的理解会越来越深入，生成的代码也会更符合项目风格。
第三阶段：核心工作流：规划 → 编码 → 验证
1. 模型选择策略
不同的任务适用不同的模型。高手会采用多模型工作流 (Multi-Model Workflow) 来最大化效率和质量。
- 复杂任务/架构设计: 使用最高质量的模型（如 Opus）进行规划，确保方向正确。
- 日常编码/实现: 使用速度和性能均衡的模型（如 Sonnet）进行具体实现。
- 简单任务/上下文检索: 使用速度最快的模型（如 Haiku 或国内模型）来收集信息和执行简单修改。
切换模型:
- 在会话中输入
/model <model_name>。
- 或通过环境变量
ANTHROPIC_MODEL 设置。
Extended Thinking (深度思考模式):
- 对于极其复杂的重构或架构决策，建议启用 Extended Thinking。
- 这会让模型进行更长时间的推理，显著提高一次性做对的成功率，减少来回修正的次数。
经典流水线示例:
Haiku → 收集上下文 (Context Retrieval)
Opus → 深度规划 (Planning)
Sonnet → 编码实现 (Implementation)
这是很多高效团队正在使用的 Multi-Model Pipeline。
2. 如何提问 (Prompting)
a) 采用“探索-规划-编码”模式
b) 结构化你的请求
一个高效的 Prompt 结构如下：
- 目标 (Goal): 你想完成什么。
- 约束 (Constraints): 必须遵守的规则（例如，使用特定库、不能修改某些文件）。
- 文件 (Files): 明确指出需要引用的文件或目录 (
@src/components/ 或 @src/main.ts:10-25)。
- 预期输出 (Expected Output): 任务完成的标准（例如，“一个功能可用的上传组件并附带测试”）。
示例:
Goal: Add user avatar upload feature.
Constraints:
- Must use the existing authentication system.
- Store images on S3, using the existing configuration.
Files:
- @app/api/users/route.ts
- @components/profile/Profile.tsx
Output: A working avatar upload feature with passing Vitest tests.
3. 上下文管理 (Context Engineering)
上下文窗口是 AI 的“记忆”，也是最大的瓶颈。管理不善会导致 AI 性能下降或“失忆”。
- /context: 查看当前会话的 Token 占用情况。
- /compact: 压缩对话历史，保留核心信息。例如：
/compact focus on the auth module changes。
- /clear: 清空会话。这是最常用也最重要的命令。在完成一个子任务或切换到新任务时，务必使用它来释放上下文空间。
- 外部记忆: 对于非常复杂的任务，可以创建临时 Markdown 文件（如
task_plan.md, findings.md）来存储中间状态，并在需要时引用它们。
高手实践: 在每个独立的子任务完成后， aggressively (积极地) 使用 /clear。
3.1 会话管理技巧
为了应对复杂项目或多任务并行，Claude Code 提供了强大的会话管理能力：
- /rename: 为当前会话重命名，方便后续查找。
- claude --resume <session_name>: 恢复历史会话，继续之前的工作。
- Git Worktree 并行: 使用
claude --worktree feature-x 在不同的 Git Worktree 中开启独立会话，实现真正的多任务并行开发。
- 多终端/多标签页: 可以在多个终端窗口中同时运行 Claude Code，每个窗口处理不同的任务或分支。
4. 测试驱动开发 (TDD) 工作流
这是 Claude Code 最推荐的工作流，能显著提高代码质量。
- 编写失败的测试:
Write a failing test for the user avatar upload feature. It should check if a 401 error is returned for unauthenticated users.
- 运行测试并确认失败: Claude 会执行测试命令并报告失败。
- 编写代码以通过测试:
Now, implement the necessary code to make the test pass.
- 循环直至完成: 重复此过程，直到所有功能点都被测试和代码所覆盖。
验证闭环 (Verification Loop):
- 每次代码修改后，务必运行 linter、formatter 和测试，确保修改没有引入新问题。
- 可以在 Hooks 中配置
post-tool-use 自动触发 lint 和 format，形成真正的“修改即验证”闭环。
5. Git 与版本控制
Claude Code 将 Git 操作深度集成到工作流中。
第四阶段：高级扩展，引爆生产力
1. Skills (可复用的 AI 工作流)
Skills 是 Claude Code 最强大的扩展机制，允许你将一系列指令和脚本封装为可复用的命令。
- 位置: 在项目
.claude/skills/ 目录下创建。
- 调用: 通过
/skill-name <arguments> 调用。
- 示例:
/review: 自动审查暂存区的代码，并根据 CLAUDE.md 的规范提出建议。/commit-push-pr: 一键完成提交、推送到远程并创建 PR 的操作。
2. Agents (子代理与代理团队)
对于复杂任务，你可以将工作委托给专职的 子代理 (Sub-agents)，以保持主上下文的清洁并实现并行处理。
3. Hooks (自动化事件钩子)
Hooks 允许你在工作流的特定节点自动执行脚本。
- 常见钩子:
post-tool-use: 在 Claude 使用工具（如 edit）后触发，可用于自动运行 linter 或格式化工具。pre-commit: 在提交前触发，可用于运行最终的测试或安全检查。
- 用途: 实现完全自动化的开发流程，例如“代码修改后自动格式化并运行测试”。
4. MCP & Plugins (生态系统)
- MCP (Model Context Protocol): 连接外部工具，如浏览器、数据库、Web 搜索，赋予 Claude 与世界交互的能力。
- Plugins: 将 Skills, Agents, Hooks, 和 MCP 配置打包成一个即插即用的插件，实现团队内或社区间的最佳实践共享。
Claude Code 中 CLAUDE.md 的最佳内容优先级（官方文档 + 全网最佳实践总结）
CLAUDE.md 是 Claude Code 最核心的持久记忆机制（项目根目录 ./CLAUDE.md 或 ~/.claude/CLAUDE.md），每次会话启动时自动加载到上下文。它不是配置，而是“指导性上下文”——Claude 会尽力遵守，但模糊/过长/冲突的内容会被忽略。
官方核心哲学（Anthropic 文档反复强调）：
“对每一条指令都问自己：删除它会让 Claude 犯错吗？ 如果不会，就删掉。”
目标：保持简洁（<200 行，理想 60-100 行），否则 token 消耗大，Claude 反而忽略关键规则。优先放“Claude 靠自己绝对猜不到或常出错”的内容。
优先级排序（高 → 低）：官方 + 全网共识（Anthropic best-practices、memory 文档、HumanLayer、UX Planet、GitHub 模板、Reddit 等 10+ 高质来源）
硬性规则 & 防错指令（最高优先级！官方最强推荐）
放那些 Claude 反复犯错、必须强制的东西（“YOU MUST” 或加粗强调）。
示例：
- “永远根因修复，不要打补丁”
- “NO HARDCODING，全部用配置/环境变量”
- “数据完整性优先：始终使用权威数据源”
- 安全/权限规则、TDD 强制要求
为什么第一：这是唯一能真正改变 Claude 行为的东西，社区 100% 共识“先写这个，否则后面全白费”。
关键命令 & 工作流（第二重要，官方明确列出）
Claude 猜不到的 Bash 命令、环境要求。
示例：
- “构建：
dotnet build / npm run build”
- “测试：始终
npm test -- --watch=false（单测优先）”
- “提交前必须 typecheck + lint”
- 所需 env vars、常见启动命令
全网模板必备，省去每次重复说明。
编码规范 & 风格（project-specific）
与语言默认不同的部分。
示例：
- “使用 ES modules（import/export），绝不用 CommonJS”
- “缩进 2 空格，单引号，解构导入”
- “命名约定：组件用 PascalCase”
官方示例直接来自这里，别写“写干净代码”这种废话。
架构决策 & 文件/项目结构
帮 Claude 快速理解整体。
示例：
- “API handlers 必须放在
src/api/handlers/”
- “Clean Architecture 分层：Domain / Application / Infrastructure”
- 简短项目概览（1-2 句）
社区模板（如 .NET、React、iOS）前 3 节必有。
Tech Stack + 首选库/工具
示例：
- “优先用 FluentValidation 而不是手动校验”
- “数据库：Entity Framework Core + PostgreSQL”
- “测试框架：xUnit + FluentAssertions”
放在前面但别太长，Claude 读代码也能猜到部分。
审查清单 & 仓库礼仪
示例：
- “PR checklist：类型检查通过？测试覆盖率 >80%？分支命名 feature/xxx”
- “Git workflow：始终 rebase 而非 merge”
团队协作必备（放入 git）。
常见陷阱 / gotchas（补充）
“Claude 常忽略的细节”：特定文件类型规则、性能坑、旧代码迁移注意事项。
其他（最低优先，可用 @import 分离）
- 引用 README / package.json
- 个人偏好（放全局
~/.claude/CLAUDE.md）
- TODO 或频繁变动内容（别放，改用 auto memory 或 issues）
其他重要注意事项（避坑指南）
长度与维护：超过 200 行 → 遵守率暴跌。每周末让 Claude 自己 review 并建议精简（prompt：“请审查 CLAUDE.md 并提出删除/优化建议”）。用 /init 命令自动生成初始版本。
文件层级加载技巧（官方高级用法）：
- 项目根目录（git 共享）
- 子目录 CLAUDE.md（自动按需加载，适合 monorepo）
- 全局
~/.claude/CLAUDE.md（个人偏好）
- 组织级（/etc/claude-code/CLAUDE.md）
- 用
@path/to/file 导入（支持递归，最深 5 层），或 .claude/rules/ 模块化 + YAML frontmatter 路径限定。
与 Auto Memory 互补：CLAUDE.md 是你写规则，Auto Memory 是Claude 自动学（build 命令、调试心得）。别把学到的东西硬塞 CLAUDE.md。
测试有效性：写完后故意提一个会违背规则的任务，看 Claude 是否遵守。若不遵守 → 缩短文件或加 “IMPORTANT:” 强调。
别做什么（官方明令）：
- 别放 Claude 读代码就能知道的（文件描述、标准 API）
- 别放长篇教程或频繁变化内容
- 别把 skills（偶尔用到的复杂流程）塞进来，用 skills 更好。
团队/生产实践：
- 放进 git，让全队共同维护。
- 大项目用多个 CLAUDE.md + .claude/rules/ 分治。
- 结合 skills/hooks/MCP 才真正起飞（CLAUDE.md 只管“永远”规则）。
一句话总结：CLAUDE.md 就是“Claude 的项目宪法”——越精炼、越针对“Claude 会犯的错”，效果越爆炸。官方文档说“它会随时间复利增长”，社区真实反馈是“写好后生产力直接翻倍”。
如果你想要我给你完整可复制的模板（中英双语、按优先级排序）、某个语言（.NET/React/iOS/Python）的定制版，或者教你怎么让 Claude 自动更新 CLAUDE.md，直接说一声，我立刻发！（界面/版本随更新微调，随时告诉我你的项目类型我再精准调整。）
总结：高手最佳实践
- 任务分解: 将大任务分解为小而具体、可验证的步骤。
- 小步快跑，频繁提交: 完成一个小的功能点 → 通过测试 → 立刻
/commit。这使得回滚和审查变得容易。
- 最小化上下文: 每次交互只提供完成当前任务所必需的文件和信息。
- 先规划，后编码: 始终使用 Plan Mode 来分析和规划，避免在错误的方向上浪费时间。
- 维护
CLAUDE.md: 将其视为项目的“AI 宪法”，持续更新，让 Claude 与你的项目一同进化。
- 善用子代理: 将重复性的工作（如测试生成、代码审查）委托给 Sub-agents，保持主会话的清晰和高效。
- 自动化验证: 配置 Hooks 实现“修改即检查”，确保每一次提交都符合代码规范。
- 多会话并行: 对于需要并行开发的特性，使用 Git Worktree + 多会话模式同时推进。
通过遵循这份指南，你将能真正发挥 Claude Code 作为“编程搭档”的强大潜力，实现开发效率的飞跃。
