2026最新国内用户Claude Code 开发配置详细手册

你有没有遇到过这些情况？

• 每次打开新会话，又要跟 Claude 重新解释一遍我们项目的命名规范
• Claude 突然跑去执行了一条危险命令，比如删文件
• 让 Claude 做代码审查，结果它把整个项目都塞进上下文，又慢又贵
• 你精心调教出来的一套 Claude 用法，新同事完全不知道怎么复用

这些问题，都可以用一套叫做 Agent Development Kit（ADK，智能体开发套件） 的结构来解决。

它的核心就是 5 个文件夹，通过这 5 个文件夹我们可以把 Claude Code 变成一支有记忆、懂规矩、会分工、能复制的自动化开发团队。

整体结构：

你的项目/
├── CLAUDE.md/     ← 第一层：记忆
├── skills/        ← 第二层：知识
├── hooks/         ← 第三层：护栏
├── subagents/     ← 第四层：分工
└── plugins/       ← 第五层：复制

层级	目录 / 文件	作用	核心意义	类比理解
第1层	CLAUDE.md/	智能体的全局规则与记忆中心	定义 AI 的行为规范、项目背景、开发约束	AI 项目操作手册
	architecture.rules	架构规则定义	规定代码结构、命名规范、目录设计	技术团队编码规范
	global.md	全局共享记忆	所有项目都生效的长期规则	AI 的长期记忆
	project.md	当前项目专属记忆	当前仓库的业务背景、特殊要求	项目 README 的增强版
第2层	skills/	技能模块目录	给 AI 注入专业能力	AI 的技能库
	SKILL.md	技能描述文件	告诉 AI 什么情况下调用该技能	技能说明书
	scripts/	技能脚本目录	存放自动化脚本与模板	工具箱
	context.md	技能上下文	提供技能运行时需要的背景知识	专业知识库
第3层	hooks/	Hook 钩子系统	在执行前后自动插入检查逻辑	自动安全审计
	PreToolUse.sh	工具执行前钩子	执行命令前做校验	"危险操作确认器"
	PostToolUse.sh	工具执行后钩子	执行完成后自动处理	自动格式化、通知
	SessionStart.sh	会话启动钩子	初始化开发环境	IDE 启动脚本
第4层	subagents/	子智能体目录	拆分不同专业 Agent	AI 团队协作系统
	code-reviewer.md	代码审查 Agent	专门负责代码 Review	Reviewer 工程师
	test-runner.md	测试 Agent	自动运行测试	QA 测试工程师
	explorer.md	探索型 Agent	分析代码库结构	技术调研员
第5层	plugins/	插件系统	将能力模块化分发	AI 应用市场
	manifest.json	插件配置清单	定义插件元数据	npm package.json
	marketplace.url	插件市场地址	插件下载与共享入口	应用商店
	team.install	团队安装脚本	一键同步团队环境	DevOps 初始化脚本

每一层解决一个具体问题，下面逐一拆解。

---

第一层：CLAUDE.md — 给 Claude 装一块长期记忆

问题是什么？

Claude 没有跨会话记忆。你今天告诉它组件命名用大驼峰，明天开新会话它就忘了。

解决方案

在项目里放一个 CLAUDE.md 文件，把所有不想重复说的事写进去。每次会话开始，Claude 自动读取它。

两个文件，两个作用范围：

文件位置	作用范围
~/.claude/CLAUDE.md	你电脑上的所有项目都生效
项目根目录 .claude/CLAUDE.md	只对这一个仓库生效

写什么进去？想想你最常对 Claude 重复说的话：

# 项目：我的电商平台

## 技术栈
- 前端：Next.js 14（App Router）
- 样式：Tailwind CSS
- 数据库：PostgreSQL + Prisma

## 命名规范
- 组件文件：大驼峰，如 `UserCard.tsx`
- 工具函数：小驼峰，如 `formatPrice.ts`
- API 路由：短横线，如 `/api/user-profile`

## 注意事项
- 禁止使用 `any` 类型
- 所有异步函数必须有 try/catch
- 提交代码前必须通过 ESLint 检查
- 不要直接操作 `main` 分支

## 代码风格
- 缩进：2 个空格
- 引号：单引号
- 函数优先用箭头函数

效果： 你再也不用在每次对话开头粘贴一大段背景介绍了。

---

第二层：skills/ — 把你的经验存起来

问题是什么？

你每次让 Claude 帮我写一个新组件，它可能每次做法都不一样——有时候加测试，有时候不加，有时候有 TypeScript 类型，有时候没有。

解决方案

把标准做法写成技能文件放进 skills/ 目录，Claude 会根据你的任务描述，自动匹配并调用对应的技能，你不需要输入任何命令。

目录结构：

skills/
├── SKILL.md              ← 技能索引（描述 + 触发条件）
├── create-component.md   ← 创建 React 组件的标准流程
├── write-api.md          ← 写接口的标准流程
└── fix-bug.md            ← 排查 Bug 的标准流程

一个技能文件长什么样？

---
name: create-react-component
description: >
  当用户说"创建组件"、"新建页面"、"写一个 UI"时，
  自动调用此技能。
---

# 创建 React 组件的标准流程

## 步骤
1. 检查 `src/components/` 下是否已存在同名组件
2. 用大驼峰命名新建 `.tsx` 文件
3. 必须定义 TypeScript interface，不允许 any
4. 同步在 `src/stories/` 下新建对应的 Storybook 故事
5. 在 `__tests__/` 下新建单元测试文件

## 代码模板
\`\`\`tsx
interface Props {
  // 在这里定义 props
}

export const ComponentName: React.FC<Props> = ({ }) => {
  return <div>{/* 内容 */}</div>;
};
\`\`\`

效果： 你说帮我创建一个用户卡片组件，Claude 自动按照你团队的标准流程来做，测试、类型、文档一个不漏。

💡 通俗理解： 这就像给一个新员工写了一本《操作手册》，它照着手册做事，不需要你每次盯着。

---

第三层：hooks/ — 设一道不可绕过的护栏

问题是什么？

AI 有时候会做出一些你绝对不想要的操作——比如在生产环境直接删数据库，或者跑了一条 rm -rf 命令。这种事情靠在提示词里说不要这样做是不可靠的。

解决方案

Hooks 是在 Claude 每次工具调用前后自动运行的 Shell 脚本。它是纯代码逻辑，确定性执行，AI 绕不过去。

三个核心文件：

hooks/
├── PreToolUse.sh    ← 工具调用「之前」运行
├── PostToolUse.sh   ← 工具调用「之后」运行
└── SessionStart.sh  ← 会话「开始时」运行

PreToolUse.sh 示例 — 拦截危险命令：

#!/bin/bash
# 检查 Claude 准备执行的命令

TOOL_INPUT="$2"

# 禁止执行 rm -rf /
if echo "$TOOL_INPUT" | grep -qE "rm\s+-rf\s+/"; then
  echo "已拦截：禁止执行破坏性删除命令" >&2
  exit 1
fi

# 禁止在没有确认的情况下操作生产数据库
if echo "$TOOL_INPUT" | grep -q "prod_db" && echo "$TOOL_INPUT" | grep -qE "DROP|DELETE"; then
  echo "已拦截：生产数据库的破坏性操作需要人工确认" >&2
  exit 1
fi

exit 0

PostToolUse.sh 示例 — 保存文件后自动格式化：

#!/bin/bash
# 每次 Claude 写完文件，自动跑 lint 和格式化

TOOL_NAME="$1"
FILE_PATH="$2"

if [ "$TOOL_NAME" = "write_file" ]; then
  case "$FILE_PATH" in
    *.ts|*.tsx|*.js|*.jsx)
      npx eslint --fix "$FILE_PATH"
      npx prettier --write "$FILE_PATH"
      echo "已自动格式化：$FILE_PATH"
      ;;
  esac
fi

效果：

• Claude 写完代码，自动帮你 lint，不用你手动跑
• 危险命令在执行前就被拦截，你连看都不用看
• 部署脚本跑完，自动发 Slack 通知给团队

💡 通俗理解： 就像工厂流水线上的质检环节。产品出厂前强制过一遍，不符合规格的直接挡回去，不依赖工人的个人判断。

---

第四层：subagents/ — 让专门的人做专门的事

问题是什么？

让 Claude 在一个会话里同时做"代码审查 + 跑测试 + 写文档"，上下文会越来越大，越来越慢，而且各种任务互相干扰。

解决方案

把不同任务拆分给独立的子代理。每个子代理有自己独立的上下文窗口、专属的工具权限，只做一件事，做完汇报结果。

目录结构：

subagents/
├── code-reviewer.md   ← 专门做代码审查
├── test-runner.md     ← 专门跑测试
└── doc-writer.md      ← 专门写文档

code-reviewer.md 示例：

---
name: code-reviewer
description: PR 需要代码审查时调用此代理
tools:
  - read_file        # 只允许读文件
permissions:
  - read_only        # 只读权限，绝对不会误操作
---

# 代码审查专用代理

你是一名资深代码审查员。你只会收到 git diff，不需要了解整个项目。
你没有写入权限，只能阅读和分析。

## 审查清单
- [ ] 有没有硬编码的密钥或密码？
- [ ] 新函数有没有对应的单元测试？
- [ ] TypeScript 类型是否明确，有没有 any？
- [ ] 异步操作有没有错误处理？
- [ ] 有没有遗留的 console.log？

## 输出格式
1. **总体评价**：一句话说清楚
2. **必须修改**：阻塞合并的问题
3. **建议优化**：非阻塞的改进项
4. **结论**：可以合并 / 需要修改

整体运作流程：

你说："帮我审查这个 PR 并运行测试"
          │
          ├──→ 调用 code-reviewer 子代理
          │         独立上下文，只看 diff，只读权限
          │         返回：结构化审查报告
          │
          ├──→ 调用 test-runner 子代理
          │         独立上下文，有执行测试的权限
          │         返回：测试通过/失败摘要
          │
          └──→ 主会话汇总结果，上下文始终保持干净

💡 通俗理解： 就像一个包工头。他自己不撸代码，但他手下有专门的水电工、瓦工、木工。谁的活儿谁干，互不干扰，最后包工头统一汇报进度。

---

第五层：plugins/ — 一键复制给全团队

问题是什么？

你花了好几天把以上四层全部调教好了，但新同事入职，他怎么知道这套配置？难道要让他再配置一遍？

解决方案

把整套系统打包成一个插件，新成员执行一条命令，立刻拥有和你完全相同的 Claude Code 工作环境。

目录结构：

plugins/
├── manifest.json    ← 描述插件包含什么
├── marketplace.url  ← 分享链接
└── team.install     ← 一键安装脚本

team.install 示例：

#!/bin/bash
echo "🚀 正在安装团队 ADK 配置..."

# 安装项目级 CLAUDE.md
cp ./CLAUDE.md/project.md ./.claude/CLAUDE.md

# 安装所有技能
mkdir -p ./.claude/skills && cp -r ./skills/* ./.claude/skills/

# 安装钩子（记得加执行权限）
mkdir -p ./.claude/hooks && cp -r ./hooks/* ./.claude/hooks/
chmod +x ./.claude/hooks/*.sh

# 安装子代理
mkdir -p ./.claude/subagents && cp -r ./subagents/* ./.claude/subagents/

echo "安装完成！Claude Code 已配置为团队模式。"

新同事入职第一天：

bash plugins/team.install

完毕。和你用的是完全一样的 Claude Code。

💡 通俗理解： 就像公司的"新员工电脑配置包"。IT 部门做好一个镜像，新人一键安装，环境和老员工一模一样，不用挨个手动配。

完整流程图：5 层如何协同工作

开发者输入任务
      │
      ▼
  CLAUDE.md        → 加载项目规范和背景知识
      │
      ▼
  skills/          → 匹配任务类型，调用对应工作流
      │
      ▼
  hooks/PreToolUse → 执行前检查，拦截危险操作
      │
      ▼
  subagents/       → 复杂任务拆分给专属子代理执行
      │
      ▼
  hooks/PostToolUse→ 执行后处理，自动格式化/通知
      │
      ▼
  plugins/         → 整套配置一键同步给所有团队成员

5 层对应解决的问题汇总

层级	文件夹	解决什么问题	类比
第一层	CLAUDE.md/	Claude 每次都忘记项目规范	员工手册
第二层	skills/	同类任务每次做法不一致	操作手册
第三层	hooks/	危险操作无法防范	流水线质检
第四层	subagents/	复杂任务上下文膨胀	专业分工
第五层	plugins/	配置无法在团队复用	新人入职包

---

快速上手：今天就能做的 3 件事

如果你觉得一次全部配置太复杂，可以先从最高回报的开始：

第 1 步（5 分钟）： 建一个 CLAUDE.md，把你最常跟 Claude 重复说的项目背景都写进去。

第 2 步（10 分钟）： 建一个 hooks/PreToolUse.sh，加入几条你最不想 Claude 执行的危险命令的拦截规则。

第 3 步（30 分钟）： 把你最常做的一类任务（比如"创建组件"）写成第一个 skills/ 文件，积累你的团队标准。

附官网使用全流程

如果你是第一次接触 Claude，最自然的入口还是官网。

官网路线的优点很直接：你不需要自己写代码，不需要先理解 SDK，也不用一开始就思考“怎么接到业务系统里”。注册、登录、升级之后，直接就能开始对话、上传文档、做总结、写内容、拆方案。对大多数非开发型用户，或者只是想先感受 Claude 能力的人来说，这条路门槛最低。

第一步：进入官网

Claude 的官方入口是 claude.ai。从这里开始，你可以直接注册账号并进入对话界面。

第二步：完成账号验证

官网注册流程的核心通常是 3 步：邮箱、邮件验证、手机号验证。真正让很多国内用户卡住的，其实是后两步，尤其是手机号验证和后续的稳定性问题。

通常会用到这些准备项：

• 海外邮箱
• 稳定的网络环境
• 可用于验证的海外手机号

如果你只是轻量体验，免费版可以先试；但只要你开始认真使用，尤其是处理长文档、长上下文、多轮复杂任务，付费版和免费版的差距会很快体现出来。

第三步：看懂套餐差异

Claude 官网这套使用方式，大致可以分成 Free、Pro、Max 以及 API 按量几类。把它理解成“不同层级的使用深度”会更容易：

方式	门槛	适合人群	主要用途
Free	低	初次体验用户	轻量试用、基础问答
Pro	中	高频个人用户	长文档、深度对话、日常生产力
Max	较高	重度用户、团队核心成员	更高强度、更高吞吐使用
API 按量	中	开发者、产品团队	把 Claude 接进项目或服务

其中最常见的个人使用升级路径，还是从免费版到 Pro。

如果你的使用方式主要是：

• 看文档、提问题
• 写总结、周报、文章草稿
• 让它帮你分析一批文本或方案
• 偶尔讨论代码思路

那官网通常就是最省事的入口。

官网适合什么人

一句话概括：官网适合“先把 Claude 当生产力助手用起来”的人。

你不需要先做技术接入，也不需要搭环境。很多人第一次真正感受到 Claude 的优势，就是在官网里把一篇长文、一个复杂需求、一个项目背景喂进去，然后发现它不仅能回答，还能持续保持上下文，不容易在长对话里失焦。

如果你只是想先感受 Claude，而不想马上去处理注册、订阅和环境问题，也可以先从更低门槛的体验入口入手。比如 Cursor 的文档页里就有过 Claude 的集成体验，适合先试模型风格和对话质量。

API 与开发者接入

当你开始想把 Claude 放进自己的产品、脚本、工作流或者团队工具里时，官网就不够了，这时候该看的是 API。

API 最大的价值，不是“换个地方提问”，而是让 Claude 从一个聊天入口变成你的应用能力层。你可以把它接到客服系统、代码审查工具、知识库问答、文档处理流水线、IDE 插件、企业内部助手里。也就是说，官网解决的是“人如何使用 Claude”，API 解决的是“系统如何使用 Claude”。

什么情况下该用 API

如果你有下面这些需求，基本都属于 API 场景：

• 想把 Claude 集成进自己的产品或网站
• 想做自动化内容处理、批量摘要、分类、分析
• 想给内部工具、IDE、企业系统接入智能能力
• 想把提示词、上下文、调用逻辑都掌握在自己手里

这类场景里，API 的灵活性远高于官网。你不仅能控制输入输出格式，还能自己设计系统提示词、业务流程、错误处理和成本策略。

最小 SDK 调用示例

如果你用 Python，最小接入通常长这样：

import anthropic

client = anthropic.Anthropic(api_key="your-api-key")

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "帮我分析这段代码的潜在问题"}
    ]
)

print(response.content)

这类调用方式适合先快速打通：先把模型跑起来，再逐步补充系统提示词、流式输出、异常处理、日志记录和成本监控。

API 的成本怎么理解

API 通常按 token 计费。简单理解就是：输入多少、输出多少，分别按模型计费。模型越强，价格越高；任务越复杂、输出越长，成本也越高。

一个比较实用的选择思路是：

• 轻量任务优先用 Haiku
• 大多数正式生产任务优先用 Sonnet
• 只有真的需要最复杂推理、重度代码分析时再上 Opus

这样既能控制成本，也不会一上来就把所有请求都压到最贵模型上。

Claude Code 和 API 是什么关系

很多人第一次接触 Claude Code 时，会误以为它只是“Claude 的命令行皮肤”。其实不是。

Claude Code 更接近一个终端里的自主 Agent。 它不是单纯补全代码，而是能在项目目录里读取文件、理解结构、执行命令、跨文件修改、跑测试、根据结果继续修正。也就是说，官网适合人直接对话，API 适合系统调用，而 Claude Code 适合把 Claude 放进真实工程环境里干活。

从能力理解上，你可以把它看成 Claude 在开发工作流里的落地形态。它为什么常被拿来和 Cursor、Copilot 放在一起比较？因为大家都在解决“ AI 如何进入开发流程”这个问题。但 Claude Code 的重点不是编辑器补全，而是任务闭环。

国内使用落地方案

如果只看产品层面，Claude 的入口其实很清楚：官网、API、Claude Code。

但一落到国内使用，问题马上就变成另一套了。很多人不是不懂官网和 API 的区别，而是卡在“我知道该怎么用，但我就是用不上”。这时候真正需要看的，是落地路线而不是产品宣传。

官网路线的门槛

官网路线最直接，但门槛也最集中：

• 注册需要处理邮箱和手机号验证
• 使用过程依赖稳定网络环境
• 升级订阅通常涉及海外支付
• 账号稳定性和风控也需要长期维护

如果你能接受这套成本，官网路线当然是最原生的；但只要你想长期用、稳定用，维护成本往往比第一次注册更麻烦。

API 路线的门槛

开发者这边的问题又不太一样。

API 本身并不复杂，真正麻烦的是：

• 如何创建和维护可用的 Key
• 如何处理支付与充值
• 服务端怎么稳定访问 endpoint
• 团队里怎么统一配置、统一调用方式

很多团队不是接不了 Claude，而是接上之后很难把这条链路稳定运营起来。

三种常见落地思路

把国内常见路线压缩一下，大致可以看成这 3 种：

路线	门槛	适合谁	主要特点
官网直连	高	重度个人用户、对原生体验要求高的人	功能完整，但注册、支付、风控压力最大
低门槛体验入口	低	想先试 Claude 的人	上手快，但能力或次数通常有限
API 转发 / 中转	中	开发者、团队、想减少折腾的人	更适合接入工作流，但要选兼容性与稳定性更好的方式

不过说实话，官方订阅和 API 对国内用户都不算省心——支付、网络和稳定性都需要自己处理。如果嫌麻烦，想找个更省事的入口，可以看看 Code80，真实订阅帐号转 API，换个 endpoint 就能直接用，体验方式和官方一致。详情可以到官网了解：code.ai80.vip

这类路线适合的不是“完全不懂 Claude 的人”，而是已经明确知道自己要官网能力、要 API 兼容、要更低接入摩擦的人。

常见问题

Q：Claude 官网和 API 有什么区别？ A：官网适合人直接使用，打开就能对话、上传文档、做分析；API 适合系统接入，能把 Claude 放进自己的应用、脚本和团队工具里。一个偏“人用”，一个偏“系统用”。

Q：Claude 更适合普通用户还是开发者？ A：两边都适合，只是入口不同。普通用户通常从官网开始，开发者更容易从 API 或 Claude Code 开始。Claude 的强项在于长上下文、复杂分析和持续保持任务状态，所以不只是程序员能用。

Q：Claude Code 和 Claude 官网是什么关系？ A：它们底层都基于 Claude 模型，但使用形态不同。官网是对话入口，Claude Code 是终端里的开发 Agent，能直接进入代码库、读写文件、执行命令、完成更完整的工程任务。

Q：免费版够不够用，什么时候该升级？ A：如果你只是偶尔体验、低频提问，免费版可以先用；但只要开始处理长文档、复杂任务，或者把 Claude 当成日常主力工具，升级通常会明显提升体验。

Q：国内怎么更方便地用上 Claude？
A：如果你愿意自己处理网络、手机号和支付问题，可以走官网或官方 API；如果你更在意接入省事、调用兼容和团队统一配置，国内也可以通过 Code80 这类兼容官方调用方式的入口更方便地使用。