Claude Code 中文开发套件：从零配置到开箱即用的完整指南

简介：AI编程助手正在改变开发者的工作流，但要让大语言模型在本地代码库中高效协作，合理的环境配置和提示词工程必不可少。Claude Code 作为命令行 AI 编程工具，通过 CLI 直接操作文件、执行命令，其能力高度依赖 CLAUDE.md 项目记忆和 skill 的预置。对于中文开发者，默认英文提示词、跨平台配置差异、多项目模板复用等问题显著增加了上手成本。本文从 AI 编程与提示词工程的基础原理出发，介绍一套开源的中文开发套件，将安装脚本、中文 prompt 模板、CLAUDE.md 分层配置、skill 注册和 VSCode 集成方案标准化，并提供从环境准备到问题排查的实操流程。无论是个人开发还是团队协作，这套方案都能帮助降低配置门槛，让 Claude Code 真正成为开箱即用的编码助手。 最近一直在折腾 Claude Code，说实话这工具本身确实能打，但一台新机器从装好 CLI 到真正用得顺手，中间还是有不少琐碎事：默认英文提示词、内置 skill 偏英文场景、不同项目要反复写 CLAUDE.md、Windows 和 macOS 的路径差异……我干脆把这一套东西整理成了一个开箱即用的中文开发套件，把启动脚本、中文 prompt 模板、常用 skill、配置管理和 VSCode 集成方案全部打包在一起，源码可以直接拉下来用。这篇文章就把整个套件的设计思路、核心源码拆解、一步一步的实操流程，还有我踩过的坑全部写清楚，给想用 Claude Code 但不想从零开始折腾的人一份能直接抄作业的参考。

这套东西适合谁？刚接触 Claude Code 不久、英文提示词用着别扭的开发者，想在团队里统一 AI 编程规范的技术负责人，还有喜欢自己调教工具链、想把 skill 和记忆机制玩明白的折腾型玩家。下文所有源码和配置都基于我在实际项目里验证过的版本，你拿过去改改路径就能用。

1. 内容整体设计与思路拆解

1.1 为什么需要一套中文开发套件

Claude Code 本身是命令行工具，装好之后敲claude就能进入交互界面，核心能力是让 AI 直接读你的代码仓库、改文件、跑命令、提交代码。但实际用下来，对中文开发者有几个明显的别扭点。

第一是提示词习惯问题。默认的英文 prompt 在处理中文注释、中文 README、中文项目文档时，理解深度明显不如中文提问直接。尤其当你的代码里混着拼音变量名、中文日志、中文数据库字段注释，用英文描述需求经常会出现理解偏差，来回纠正反而浪费时间。

第二是记忆机制需要反复配置。Claude Code 通过 CLAUDE.md 来记忆项目规范、代码风格、常用命令，这文件写得好不好直接决定 AI 的表现。但对一个多项目开发者来说，每个项目都从头写一份高质量的 CLAUDE.md 成本很高，起码得有个能复用的模板。

第三是环境搭建成本。新机器上要装 Node.js、装 CLI、配 API Key、装 VSCode 插件、处理各种网络和权限问题，今天装好过段时间换机器又得重来。这种重复劳动完全可以用脚本和配置模板固化下来。

所以我做这个套件的时候，核心思路就是三件事：把中文提示词沉淀成模板库，把 CLAUDE.md 和 skill 做成标准化的可复用结构，把安装配置流程压缩成一两条命令。源码仓库里每个文件都要能单独看懂、独立替换，这样你用的时候不是黑盒，而是可以按自己的需求改。

1.2 方案选型：为什么是 CLI 而不是桌面版或网页版

Claude 有好几种使用形态，我在套件里特意选了 CLI 作为主力环境，这里把几种方案放在一起对比一下就清楚了。

CLI 的核心价值在于它在你的项目目录里运行，AI 能直接看到文件结构、读取代码、执行命令，这是网页版做不到的。而且 CLI 的可脚本化能力很强，我可以把一组命令封装成 skill，让 AI 按固定流程做事，比如“跑一轮测试再帮我修失败的用例”，这对工程效率的提升是实打实的。

当然我也在套件里留了桌面版的配置说明，如果你更喜欢可视化界面，装好桌面版之后把 API Key 填进去，然后把套件里的 CLAUDE.md 模板复制到项目根目录，同样能享受到中文提示词和 skill 的增强效果。

1.3 套件源码的目录结构与设计原则

整个套件仓库的结构是这样的：

claude-code-chinese-kit/ ├── install.sh # 一键安装脚本，自动检测系统环境 ├── uninstall.sh # 卸载脚本，清理所有配置 ├── config/ │ ├── settings.example.json # 配置文件模板 │ └── .env.example # 环境变量模板（API Key 等） ├── templates/ │ ├── CLAUDE.md # 项目记忆文件通用模板 │ ├── frontend.md # 前端项目规范模板 │ ├── backend.md # 后端项目规范模板 │ ├── python.md # Python 项目规范模板 │ └── prompts/ │ ├── code-review.md # 中文代码评审提示词 │ ├── refactor.md # 中文重构提示词 │ ├── test-writing.md # 中文测试编写提示词 │ └── debug.md # 中文调试提示词 ├── skills/ │ ├── skill-registry.md # skill 注册说明 │ └── examples/ │ ├── git-commit-helper/ # 自动生成规范 Git 提交信息 │ └── test-runner/ # 一键运行测试并分析结果 ├── scripts/ │ ├── init-project.sh # 初始化新项目并应用模板 │ ├── backup-config.sh # 备份 Claude Code 配置 │ └── sync-templates.sh # 同步最新模板到项目 └── vscode/ ├── settings.json # VSCode 推荐配置 └── keybindings.json # 快捷键建议

设计原则上有几条很重要。第一，配置与代码分离，API Key 这类敏感信息永远放在.env里，不会写死在配置文件中。第二，模板与使用解耦，模板目录只是素材库，你用init-project.sh初始化项目时才复制到项目里。第三，所有脚本都做幂等处理，重复执行不会产生副作用。

1.4 配置管理的几个关键决策

做这套件的时候有几次取舍，我认为对后续使用体验影响很大。

首先是 API Key 的管理。Claude Code 官方支持用ANTHROPIC_API_KEY环境变量，但这个变量在 shell 里是全局的，如果你有多个项目、多个 Key 需求，全局变量就很麻烦。我在套件里做了一个折中方案：install.sh会把.env.example复制为.env，然后在 shell 配置文件中添加读取逻辑，让每个项目可以有自己的.env，通过set -a; source .env; set +a这种模式加载。这样既不用反复设置环境变量，也不会因为 Key 泄露在 Git 历史里。

其次是模型配置。Claude Code 的模型名、接口地址可以通过环境变量控制。我在.env.example里统一写了标准配置，并且用注释说明每个变量是干什么的。这样你如果要用第三方兼容接口，只需要改环境变量指向对应的 endpoint 和模型名即可，套件本身不需要改代码。

第三是 Windows 和 macOS/Linux 的统一问题。CLI 的核心逻辑是跨平台的，但 shell 脚本有差异，所以我把安装脚本分成了两步：先检测系统类型，再执行对应的配置逻辑。Windows 用户推荐用 Git Bash 或者 WSL 来跑这套脚本，实测兼容性最好。

2. 核心细节解析与实操要点

2.1 启动脚本 install.sh 是怎么设计的

安装脚本是整个套件的入口，目标是让用户在拿到源码后跑一条命令就完成大部分配置。脚本的核心流程分四步：环境检测、依赖安装、配置生成、验证运行。

#!/usr/bin/env bash # Claude Code 中文套件安装脚本 set -euo pipefail echo "开始安装 Claude Code 中文开发套件..." # 1. 检查 Node.js 版本，要求 >= 18 if ! command -v node >/dev/null 2>&1; then echo "未检测到 Node.js，请先安装 Node.js 18 或更高版本" exit 1 fi NODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1) if [ "$NODE_VERSION" -lt 18 ]; then echo "Node.js 版本过低，需要 18+，当前版本: $(node -v)" exit 1 fi # 2. 检查是否已安装 Claude Code CLI if ! command -v claude >/dev/null 2>&1; then echo "未检测到 claude 命令，正在安装..." npm install -g @anthropic-ai/claude-code fi # 3. 生成配置文件 mkdir -p ~/.claude-code-kit if [ ! -f ~/.claude-code-kit/.env ]; then cp .env.example ~/.claude-code-kit/.env echo "已生成环境变量模板，请编辑 ~/.claude-code-kit/.env 填入你的 API Key" fi # 4. 在 shell 配置中加载 .env SHELL_RC="" if [ -f "$HOME/.zshrc" ]; then SHELL_RC="$HOME/.zshrc" elif [ -f "$HOME/.bashrc" ]; then SHELL_RC="$HOME/.bashrc" fi if [ -n "$SHELL_RC" ]; then grep -q "claude-code-kit/.env" "$SHELL_RC" || cat >> "$SHELL_RC" << 'EOF' # Claude Code 中文套件环境变量加载 if [ -f "$HOME/.claude-code-kit/.env" ]; then set -a source "$HOME/.claude-code-kit/.env" set +a fi EOF echo "已更新 shell 配置: $SHELL_RC" fi echo "安装完成！请运行: claude"

脚本用set -euo pipefail保证任何一个环节出错就立即停止，避免半途而废的配置状态。Node.js 版本检查卡在 18 是因为 Claude Code CLI 的依赖要求，太老的版本装不上。

还有一个细节：~/.claude-code-kit/.env这个路径里存了全局默认配置，而项目级的.env可以覆盖它。加载顺序是 shell 先读全局配置，进入项目后再由init-project.sh把项目配置追加到当前环境。这种分层设计可以兼顾全局统一和项目隔离。

2.2 中文提示词模板库为什么这样组织

提示词模板放在templates/prompts/目录下，每个文件都是一个独立的、场景化的中文提示词。我举个例子，code-review.md的内容是这样的：

你是一位资深代码评审专家，请对以下代码进行评审。 评审要求： 1. 从正确性、性能、可维护性、安全性四个维度分析 2. 先指出必须修复的问题，再提优化建议 3. 对每个问题标注严重级别：严重 / 中等 / 轻微 4. 用中文输出，代码示例要完整可运行 5. 最后给出总体评价和修改优先级建议 当前需求上下文： {{context}} 需要评审的代码： ```{{language}} {{code}}

这种模板的作用有两个。一个是把评审的维度、输出格式、语言要求固化下来，让 AI 的输出更稳定，不会这次让写中文下次写英文。另一个是可以配合 `/import` 命令或者手动复制，在会话中快速注入。模板里用了 `{{context}}`、`{{language}}`、`{{code}}` 这种占位符，方便你在自己的脚本里做字符串替换。 模板库的组织方式是按场景分的：代码评审、重构、测试编写、调试，这四个是日常开发中最常见的需求。你完全可以根据自己的工作流加新的模板，比如前端样式调整、数据库迁移脚本生成、API 文档编写等等。 ### 2.3 预置 skill 的注册机制与实战示例 Claude Code 的 skill 相当于给 AI 预装了一套“操作手册”，让它知道在特定场景下应该按什么步骤做事。套件里带了两个示例 skill，一个是 git commit 信息生成，一个是测试运行器。 Skill 的注册机制其实不复杂，就是在一个 markdown 文件里描述这个 skill 的触发条件、执行步骤、注意事项。比如 `skill-registry.md` 里定义： ```markdown # Skill 注册表 ## commit-helper - 触发词: /commit, 提交信息, commit message - 功能: 分析当前 Git 暂存区的改动，生成符合 Conventional Commits 规范的提交信息 - 执行步骤: 1. 运行 git diff --cached 查看暂存区改动 2. 分析改动的类型（feat/fix/refactor/docs/test/chore） 3. 用中文写简洁的描述，英文关键词保留 4. 输出建议的完整提交命令 - 注意事项: - 不要直接执行 git commit，只输出建议命令 - 描述控制在 50 字以内 - 如果有 breaking change，必须标注 BREAKING CHANGE

在会话中，你只要输入“帮我生成提交信息”，AI 就会按这个注册表里的步骤走，不需要你每次重新解释需求。skill 的好处是让重复性的操作流程规范下来，尤其是团队协作时，每个人的提交习惯不同，用 skill 统一格式很有价值。

2.4 CLAUDE.md 模板的编写思路

CLAUDE.md 是 Claude Code 的项目记忆文件，里面写的是“这个项目是什么、有什么约定、常用命令有哪些、代码风格注意事项”。AI 每次启动会话都会读这个文件，相当于它的上岗培训资料。

套件里给出了通用模板 CLAUDE.md，以及针对前端、后端、Python 的变体。通用模板的结构是：

# 项目名称 ## 技术栈 - 后端: Node.js / Express - 前端: Vue 3 / Vite - 数据库: PostgreSQL 15 ## 常用命令 - 启动开发环境: npm run dev - 运行测试: npm test - 构建生产包: npm run build ## 代码规范 - 组件文件名使用大写驼峰 - 接口返回统一格式: { code, message, data } - 禁止在业务代码中使用 console.log，用封装好的 logger ## 目录结构说明 - src/api: 接口请求层 - src/components: 公共组件 - src/views: 页面级组件 - src/utils: 工具函数 ## 注意 - 修改数据库结构时必须写迁移脚本 - 新增第三方依赖需要团队评审通过

你在初始化项目的时候，init-project.sh会根据项目类型自动选择合适的模板复制到目标目录。模板可以自己改，但核心建议是保持精简，只写那些“AI 不知道就会犯错”的信息，写太多反而会让 AI 分心。

2.5 初始化脚本 init-project.sh 的工作流

这个脚本是套件里使用频率最高的一个，用途是在新项目里快速套用模板。它的流程是：读取参数（项目路径、项目类型）、复制对应的 CLAUDE.md 模板、根据类型复制额外配置、检查是否需要初始化 Git。

#!/usr/bin/env bash set -euo pipefail PROJECT_PATH="${1:-.}" PROJECT_TYPE="${2:-generic}" if [ ! -d "$PROJECT_PATH" ]; then echo "目录不存在: $PROJECT_PATH" exit 1 fi # 复制 CLAUDE.md 模板 case "$PROJECT_TYPE" in frontend) cp templates/frontend.md "$PROJECT_PATH/CLAUDE.md" ;; backend) cp templates/backend.md "$PROJECT_PATH/CLAUDE.md" ;; python) cp templates/python.md "$PROJECT_PATH/CLAUDE.md" ;; *) cp templates/CLAUDE.md "$PROJECT_PATH/CLAUDE.md" ;; esac echo "已生成 CLAUDE.md 到 $PROJECT_PATH" # 如果存在项目级 .env，加载到当前 shell if [ -f "$PROJECT_PATH/.env" ]; then set -a source "$PROJECT_PATH/.env" set +a echo "已加载项目环境变量: $PROJECT_PATH/.env" fi # 检查 Git 仓库 if [ ! -d "$PROJECT_PATH/.git" ]; then echo "检测到目录还不是 Git 仓库，初始化..." git -C "$PROJECT_PATH" init fi echo "项目初始化完成，进入目录后运行 claude 即可开始使用"

有一点要特别提醒：CLAUDE.md 本身不需要提交到 Git，建议加进.gitignore。因为有时候你在本地改的规则是临时的，不想影响团队其他人。如果你希望团队共用一套规范，那可以提交一个CLAUDE.example.md，让大家自己复制。

3. 实操过程与核心环节实现

3.1 从零起步：环境准备与套件安装

不管你是 macOS、Linux 还是 Windows，第一步都是把 Node.js 装好。我推荐用 nvm 装，方便切换版本，Claude Code CLI 要求 Node.js 18 以上，考虑到稳定性建议直接用 20 LTS。

Node.js 装好之后，把套件源码拉下来：

git clone https://github.com/yourname/claude-code-chinese-kit.git cd claude-code-chinese-kit chmod +x install.sh init-project.sh ./install.sh

脚本会做几件事：检查 node 版本、安装@anthropic-ai/claude-code、生成~/.claude-code-kit/.env配置模板、把环境变量加载逻辑写进 shell 配置文件。整个过程应该在一两分钟内完成。

装完 CLI 之后，验证一下是否正常：

claude --version

能输出版本号说明 CLI 本体没问题。接下来是配置 API Key。

3.2 API Key 配置与模型参数选择

编辑~/.claude-code-kit/.env，填入你的 Key：

# Claude Code 中文套件环境配置 # 必填：API Key ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxx # 可选：指定模型 ANTHROPIC_MODEL=claude-sonnet-4-20250514 ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-20250514 # 可选：第三方兼容接口地址（如使用兼容服务时修改） # ANTHROPIC_BASE_URL=https://api.example.com

两个模型变量要说明一下。ANTHROPIC_MODEL是主模型，处理复杂任务，质量高但速度稍慢；ANTHROPIC_SMALL_FAST_MODEL是轻量模型，用来处理简单任务，比如生成 commit message、简短问答，速度快且成本低。Claude Code 内部会根据任务复杂度自动切换。

填好之后，要让配置在当前 shell 生效：

source ~/.zshrc # 如果用 bash 则 source ~/.bashrc

然后跑claude就能进入交互界面了。第一次启动如果报 key 相关的错误，基本就是环境变量没加载上，检查一下.zshrc里有没有那段加载代码。

3.3 在 VSCode 中集成 Claude Code

很多人习惯在 VSCode 里跑命令，Claude Code 官方提供了 VSCode 插件，安装之后可以在侧边栏直接开终端，也可以把 Claude Code 集成到右键菜单。

插件的安装方式是在 VSCode 扩展商店搜 “Claude Code”，装好之后启动终端，确认claude命令可用，然后在项目里打开一个新的终端窗口，直接敲claude就行。

套件里带的vscode/settings.json有一段推荐配置：

{ "terminal.integrated.env.linux": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }, "terminal.integrated.env.osx": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }, "terminal.integrated.env.windows": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}" }, "claude-code.enableNewCli": true }

这里主要解决一个跨平台问题：不同系统的终端环境变量传递方式不同，统一配置一下可以保证在任何终端里都能读到 API Key。实际测试下来，插件版和 CLI 版共用同一个~/.claude目录，所以你的会话历史和配置在两边是同步的。

3.4 初始化一个新项目并应用模板

现在假设你要开始一个 Vue 前端项目，试试套件的初始化脚本：

mkdir my-vue-project ./init-project.sh my-vue-project frontend cd my-vue-project cat CLAUDE.md

脚本会把templates/frontend.md复制成CLAUDE.md，里面预填了 Vue 3 项目的常用命令、目录结构约定、代码风格要求。如果你用的技术栈不是那几种预设类型，可以先用 generic 模板，然后自己手动改 CLAUDE.md。

初始化完成之后，进入项目，启动 claude：

claude

在提示符里输入“帮我看看这个项目的结构，然后写一个组件示例”，AI 会先读 CLAUDE.md 了解项目约束，再看目录结构，然后按要求写代码。你会发现带模板和没带模板的差距非常大，带模板的情况下 AI 写出来的代码更符合项目现有风格，变量命名、样式方案都会对齐。

3.5 首次会话验证：跑通一个完整任务

我建议你第一次用套件的时候，用一个真实的小任务来验证整条链路是否正常。比如在当前项目里输入：

请帮我创建一个简单的登录页面组件，包含用户名和密码输入框、登录按钮，表单校验规则参考项目现有风格，创建完文件后运行测试确认无报错。

这时候 Claude Code 会自动读项目结构，找到组件目录，参考 CLAUDE.md 里的命名规范生成文件，然后执行测试命令。这一步能同时验证文件操作、命令执行、模板生效三个环节。

如果中途报错，最常见的两种情况：一是 API Key 配置不正确导致请求失败，二是模型名不被识别导致启动异常。这两个问题在下一节详细排查。

4. 常见问题与排查技巧实录

4.1 模型不识别：提示 "model not recognized"

这个错误在社区里被问烂了，典型报错长这样：

"claude-sonnet-4" is not a model this version of claude code recognizes

出现这个错误有几种可能。

第一种是模型名写错了或者版本不对。Claude Code 每个版本能识别的模型列表是固定的，你设置的模型名不在当前版本的支持列表里就会报这个错。解决办法很简单，你可以打开交互界面输入/model查看当前支持的模型列表，或者直接改环境变量：

ANTHROPIC_MODEL=claude-sonnet-4-0

我实测下来，模型名的稳定写法是把大版本完整写出来，不要省略后缀。具体支持哪些模型，以你安装的 CLI 版本和官方文档为准，不同版本支持的模型列表会有差异。

第二种是配置缓存的问题。你改了环境变量但 CLI 还缓存着旧配置，这时候可以清理一下缓存目录：

rm -rf ~/.claude/cached-config.json

然后重新启动 claude。

第三种是第三方兼容接口的模型名映射问题。如果你是通过ANTHROPIC_BASE_URL指向兼容服务，就必须保证环境变量里的模型名在该服务端真实存在。之前遇到过有人配了个拼写错误的模型名，CLI 一直报 not recognized，实际上只是环境变量里少写了个字母。

4.2 组织订阅被禁用：organization has disabled subscription access

这个报错通常是使用公司或组织分发的账号时出现的：

Your organization has disabled Claude subscription access for Claude Code

核心原因很简单：你的组织在后台把 Claude Code 的访问权限关了。你自己配的个人 API Key 不会触发这个限制，出现这个报错说明环境变量里用的是组织托管的 key 或者走了组织配置。

遇到这个情况，先检查环境变量：

echo $ANTHROPIC_API_KEY echo $CLAUDE_CODE_USE_API_KEY

如果发现 key 是组织签发的，换用自己的个人 key 就能解决。还有一种情况是 shell 的全局配置里残留了组织下发的认证信息，在~/.claude目录下搜一下配置文件：

ls -la ~/.claude/

如果这个目录里有组织下发的 settings 文件，把里面的组织相关配置清理掉，然后重新用个人 key 启动。

另外如果你们团队确实需要统一管理 Claude Code 的访问但不希望被禁用，建议让管理员在控制台里确认下策略，而不是在本地绕过检测。本地绕过虽然技术上可行，但容易踩合规的坑，而且每次更新 CLI 都可能重新触发检测，得不偿失。

4.3 中文输出乱码或出现截断

Claude Code 默认输出是流式的，中文场景下偶尔会遇到乱码或者回复被突然截断的情况。乱码一般和终端编码有关，macOS 和 Linux 的终端默认 UTF-8，基本没问题，Windows 上如果是老版本 CMD 就容易出问题。

解决方法是把终端切换成 Windows Terminal 或者 Git Bash，这两种终端对 UTF-8 的支持很稳定。如果切换之后还乱码，检查一下系统的区域语言设置，把 Unicode 支持改成 UTF-8。

回复截断则通常和“思考很长但输出长度到了上限”有关。CLI 对单次输出有长度限制，中文的 token 消耗比英文高，同样的内容中文占的 token 更多，所以更容易触顶。应对办法是把任务拆小，或者要求 AI 分步骤输出。我在模板库里的refactor.md中就明确写了“先输出方案，确认后再执行”，能有效减少一次输出的内容量。

4.4 Windows 上运行 shell 脚本失败

这套件里的脚本都是 bash 写的，Windows 原生环境跑不了。这里有三种处理方式，按推荐顺序排：

第一种是 Git Bash。装 Git for Windows 的时候自带 Git Bash，直接在套件目录里右键打开 Git Bash，然后执行：

./install.sh

脚本里的命令大部分都能跑，只有少数涉及系统路径的操作需要微调。我在脚本里已经做了系统判断，如果启动install.sh发现是 Windows 且没有 Git Bash 环境，会输出提示让你安装。

第二种是 WSL。如果你日常开发在 WSL 里面，直接把套件放到 WSL 文件系统里，按 Linux 方式跑，完全没问题。而且 WSL 里跑 Claude Code 访问本地代码的速度比通过 /mnt/c 挂载目录快很多，因为文件 I/O 不经过 Windows 层。

第三种是手动配置。如果你不想装 Git Bash 也不想用 WSL，那每一步都得手动做：手动装 Node、手动 npm install CLI、手动设置环境变量。这个能跑，但体验确实差，之前我试过在 PowerShell 里配环境变量，踩了不少坑，不建议新手尝试。

4.5 常见问题速查表

把高频问题的判断方式和处理动作汇总成一张表，方便你遇到问题直接查：

4.6 几个值得收藏的调试技巧

最后分享三个我在调试过程中觉得非常实用的小技巧。

第一个是看调试日志。Claude Code 有内置的日志开关，遇到不明错误先开日志定位：

claude --debug --verbose

这个模式会把每次请求的详细信息、模型响应、错误堆栈全部打到终端上。排查问题的时候信息量非常够用，但平时不建议开着，日志太多影响阅读。

第二个是快速定位环境变量问题。怀疑环境变量没生效的时候，最快的方式是在 claude 会话里直接问它：

请告诉我当前进程里 ANTHROPIC_API_KEY 变量是否已设置，以及它的值前缀是什么？

让 AI 自己用工具去检查环境变量，比你开一堆终端窗口手动查要快。

第三个是用/status查看当前会话状态。这个命令会显示当前模型、API Key 状态、是否加载了 CLAUDE.md、启用了哪些 skill。如果感觉 AI 表现不对，先跑一下/status看看配置是不是你预期的那样。

5. 套件的扩展玩法：按你的场景自定义

5.1 新增自己的 skill 到注册表

套件自带的 skill 是示例级别，真正好用的是你自己定义的 skill。比如你经常处理某个特定框架的报错，可以写一个“Vite 构建报错诊断”的 skill。

写 skill 的时候有个思路供参考：先分析这个场景下你希望 AI 按什么顺序处理，把步骤写出来；再想清楚哪些信息必须由用户提供，哪些信息 AI 应该自己收集；最后明确输出格式。比如：

## vite-build-error - 触发词: vite报错, 构建失败, build error - 功能: 诊断并解决 Vite 构建报错 - 执行步骤: 1. 运行 npm run build 复现报错 2. 查看完整错误日志，定位到具体文件和依赖 3. 检查 vite.config.js 相关配置 4. 分析是依赖版本问题还是配置问题 5. 给出修复方案并验证 - 输出格式: 错误原因 / 修复步骤 / 验证结果

写完放到 skills/examples/ 目录，然后在 CLAUDE.md 里补充一句话“遇到构建报错时参考 skill-registry.md 中的 vite-build-error 处理”。这样 AI 在遇到相关场景时会主动调用。

5.2 多项目模板的分层管理

我自己的项目很多，每个项目的技术栈、规范都不同，最开始把所有项目共用一个 CLAUDE.md，后来发现内容太臃肿，AI 反而抓不住重点。现在采用的方式是分层管理：通用基础规则放一份模板，各技术栈变体单独维护，项目特有规范在初始化之后手动补充。

套件里 templates 目录就按这个思路组织的：CLAUDE.md 是基础规范，适用于所有项目；frontend.md / backend.md / python.md 是在基础规范之上叠加的变体。你在init-project.sh里指定项目类型之前，可以先看下自己的项目属于哪种，选错了也没关系，手动把对应文件复制过去覆盖即可。

这种分层的好处是公共规则只维护一份，技术栈变体独立演进，项目特有内容完全不进模板。就算 AI 支持多文件记忆，CLAUDE.md 本身也不适合写太长，尽量控制在 40 行以内。

5.3 配置备份与迁移

换电脑和重装系统之后，最怕的就是 Claude Code 的所有配置、会话历史、技能定义全部丢失。套件里的backup-config.sh就是为了解决这个问题：

#!/usr/bin/env bash set -euo pipefail BACKUP_DIR="${1:-./backup/claude-code}" mkdir -p "$BACKUP_DIR" # 备份全局配置和会话历史 if [ -d "$HOME/.claude" ]; then tar -czf "$BACKUP_DIR/claude-config.tar.gz" "$HOME/.claude" echo "已备份 ~/.claude 到 $BACKUP_DIR/claude-config.tar.gz" fi # 备份套件配置 if [ -f "$HOME/.claude-code-kit/.env" ]; then cp "$HOME/.claude-code-kit/.env" "$BACKUP_DIR/env.backup" echo "已备份环境变量配置" fi echo "备份完成，恢复时使用: tar -xzf claude-config.tar.gz -C ~/"

恢复也很简单，把 tar 包解压到对应的目录就行。这个脚本我会在每次大版本升级 CLI 之前跑一次，因为升级偶尔会动配置目录，有备份就踏实很多。

关于这套中文开发套件，目前我自己的日常工作已经离不开它了。不管 API Key 对应的模型后续怎么迭代，把中文提示词、CLAUDE.md 模板、skill 注册机制、环境配置脚本整合起来这件事本身，就是一套值得长期维护的工程资产。你不需要把这个套件当成一个固定成品，更建议把它当作一个起点，根据自己的项目类型、团队规范、技术栈偏好去改模板、加 skill，这才是它作为“源码”真正有价值的地方。后续我打算继续往里补前端工程化、自动化测试、Code Review 工作流这几个场景的 skill，如果你在里面加了有意思的模板，欢迎一起交流。

本文还有配套的精品资源，点击获取