这次我们来看一个很实用的话题给 Claude Code 装一个“测试生成外挂”。不是画大饼而是用一个官方支持的机制——SKILL.md从零手写一个技能让 Claude Code 在项目里自动分析代码、生成单元测试和接口测试还能尝试跑起来。很多刚接触 Claude Code 的朋友装完claude命令之后只会简单提问不知道它的 Skills 机制怎么用也不知道SKILL.md到底是干什么的。一些朋友抄了网上的技能文件结果发现技能根本没被触发还有人问“SKILL.md 里 # 后面的是不是不执行”。这篇文章会把这些坑一次讲清楚。文章会按下面的顺序展开先给你一张核心能力速览表让你 30 秒判断适不适合自己然后从 Claude Code 的安装、VS Code 配置、DeepSeek 等模型接入讲起接着进入重头戏手写一个SKILL.md再把它升级成“测试生成外挂”最后补上头less 模式、批量任务、资源占用、常见问题和最佳实践。全程给可直接复制的命令、配置和代码。1. 核心能力速览能力项说明项目类型官方 CLI 编程助手 可扩展 Skills 机制开发方Anthropic第三方工具 cc-switch 可切换模型供应商主要功能代码读写、终端命令执行、文件批量修改、技能扩展、测试生成、代码审查运行平台Windows / macOS / Linux是否依赖 GPU否不需要本地显卡计算在远端 API 完成本地环境要求Node.js 18 或更高版本磁盘空间约几百 MB启动方式终端命令claudeVS Code 插件桌面版客户端接口能力支持 headless 模式claude -p可直接输出结果支持 JSON 输出批量任务支持可通过 CLI 循环处理也可交给技能内部做批量生成技能扩展支持.claude/skills/技能名/SKILL.md自定义技能适合人群开发者、测试开发、技术管理者、需要自动化代码任务的工程师首先要明确一个点Claude Code 是本地安装的命令行工具但推理不靠本地显卡。你不需要为它配 GPU也不需要关注显存它的资源消耗主要在 Node.js 进程和 API 调用量上。对大多数办公笔记本和开发机来说运行门槛很低。2. 适用场景与使用边界2.1 适合什么场景Claude Code 最适合的场景是“直接在代码仓库里干活的自动化任务”。它和网页聊天不一样它能读取项目文件、创建文件、执行命令、跑测试。基于这个特性典型用法包括新项目脚手架生成让 Claude Code 按团队规范创建目录结构。批量重构比如统一改日志格式、替换废弃 API。自动化测试生成让 Claude Code 分析函数逻辑后生成pytest、Jest等测试代码。代码审查用技能约束审查重点输出规范报告。定时或批量文档生成让技能自动维护 README、CHANGELOG。2.2 不适合什么场景Claude Code 不适合替代完整的持续集成测试平台。它能生成测试、能尝试运行测试但它不是真正的测试执行调度器。如果你要做非常严格的覆盖率门禁、分布式测试、多环境矩阵还是应该交给 CI/CD 系统。另外如果代码仓库特别大或者有大量私有二进制文件需要先配置好忽略规则否则会拖慢上下文加载也容易产生大量无意义的 token 消耗。2.3 使用边界与合规提醒涉及代码生成和测试生成时必须注意三点只对自己拥有或已获授权的代码做测试生成与分析不要用 Claude Code 去抓取、逆向或绕过他人系统的授权限制。不要在对话和技能模板中硬编码 API Key、账号密码、云厂商密钥。所有密钥通过环境变量或系统密钥服务注入。如果代码包含敏感业务逻辑、个人隐私数据或客户信息接入第三方 API 前要确认数据合规策略。使用测试环境数据不要直接用生产真实数据。3. 环境准备与前置条件3.1 操作系统与软件要求Claude Code 官方支持 Windows、macOS、Linux。最常见的安装方式是 npm 全局安装因此你的机器需要先有 Node.js。建议满足以下条件项目要求Node.js18 或更高版本npm随 Node.js 自带建议保持较新版本Git建议安装用于代码仓库场景终端Windows 推荐 PowerShell 或 Windows TerminalmacOS/Linux 使用系统终端网络能访问 Claude Code 官方服务或已配置第三方 API 端点磁盘至少预留 1GBnpm 全局包和日志文件会占用空间检查 Node.js 版本node -v npm -v如果版本过低去 Node.js 官网下载 LTS 版本或者用nvm管理版本。这里不展开 Node.js 安装细节但建议不要用太老的版本否则 npm 安装时可能报 engine 错误。3.2 准备账号或 API Key安装完成之后Claude Code 需要鉴权。常见方式有两种方式一使用 Claude 订阅账号登录适合个人日常使用。方式二使用 Anthropic API Key或者接入兼容 Anthropic 协议的第三方 API。如果你打算接 DeepSeek 这类第三方模型可以跳过官方订阅直接用环境变量或 cc-switch 配置。后面会专门讲接入方式。4. Claude Code 安装部署与启动4.1 npm 全局安装安装命令很简单直接在终端执行npm install -g anthropic-ai/claude-code安装完成后确认版本claude --version如果 npm 全局安装遇到权限问题在 macOS/Linux 上可能需要调整 npm 全局目录权限或者用sudo。在 Windows 上如果报“无法识别 claude 命令”检查 npm 全局 bin 目录是否在 PATH 中。更新到最新版本npm update -g anthropic-ai/claude-code4.2 启动并登录在项目目录启动cd your-project claude首次启动会进入登录流程通常是在浏览器里完成授权然后回到终端。登录成功后你会看到交互式对话界面可以直接输入中文或英文指令。启动后先做一个最小测试。输入类似这样的指令请读取当前目录结构并告诉我这个项目用了哪些主要技术栈。如果 Claude Code 能正确列出目录并分析技术栈说明安装和鉴权都正常。4.3 VS Code 插件配置如果不想在终端里反复敲命令可以直接用 VS Code 插件。打开 VS Code 扩展市场搜索“Claude Code”安装官方扩展。安装后左侧会多出对应的面板入口也可以用快捷键唤起。VS Code 插件本质上会复用本机安装的claude命令行所以使用前建议先确认终端里claude命令可用。插件适合需要在编辑器上下文里直接圈选代码、让 Claude Code 解释或修改的场景。4.4 桌面版客户端除了 CLI 和 VS Code 插件Claude Code 也有桌面版客户端。桌面版提供图形界面适合不习惯纯终端操作的用户。安装包可以从 Claude Code 官网或其他官方渠道下载。桌面版底层依然是 Claude Code 的逻辑同样支持技能和配置目录。这里要提醒一句CLI、桌面版、VS Code 插件三者共用本机配置目录也就是项目下的.claude/和用户级配置。所以你在 CLI 里写的技能文件桌面版也能识别。4.5 接入 DeepSeek 或第三方模型Claude Code 默认连接 Anthropic 官方服务但它的协议是兼容 Anthropic API 的因此可以通过环境变量指向第三方端点。常见用法是接入 DeepSeekexport ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥 export ANTHROPIC_MODELdeepseek-chat在 Windows PowerShell 中$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥 $env:ANTHROPIC_MODELdeepseek-chat还有一种更省心的方式使用 cc-switch 工具在多个供应商配置之间切换。cc-switch 会在本地管理多套 Claude Code 配置切换后会自动修改环境变量或配置文件。你可以在 GitHub 搜索 cc-switch 了解安装方式这里不展开。需要注意接入第三方模型后不同模型对工具的调用能力可能不一致。比如部分模型对长上下文的处理、对特殊指令的遵循程度可能与官方模型有差异。如果发现技能不生效先考虑是不是模型兼容性问题。4.6 项目级配置目录Claude Code 会在项目根目录创建或使用.claude/文件夹。常用子路径.claude/ settings.json skills/ test-generator/ SKILL.md个人用户级别的配置在系统用户目录下比如 macOS 和 Linux 通常在~/.claude/Windows 在用户目录下的.claude/。settings.json可以用来配置权限、忽略规则等。示例{ permissions: { allow: [ Bash(npm test) ] } }这样当 Claude Code 需要执行npm test时可以避免频繁弹窗确认。5. 从零手写 SKILL.md5.1 Skills 机制是什么Skills 是 Claude Code 的扩展机制。它的核心思路是你把一份写好的技能定义放在项目里Claude Code 启动或运行时会扫描技能目录根据用户请求自动加载匹配的技能。技能本身是一种结构化的提示词包含触发条件、工作流程、注意事项甚至还可以附带脚本和模板文件。一个技能就是一个文件夹文件夹里必须有一个SKILL.md文件。可选的内容包括scripts/技能附带的脚本。templates/技能使用的模板文件。reference.md参考文档。5.2 SKILL.md 的文件结构SKILL.md使用 Markdown 语法但最顶部必须是一段 YAML frontmatter用---包裹。整个文件结构如下--- name: skill-name description: 技能的触发条件和使用场景描述 --- # 技能标题 ## 使用场景 ... ## 工作流程 ... ## 注意事项 ...关键点是name是技能名称尽量使用英文小写加短横线。description是触发描述要写清楚“当用户需要……时使用这个技能”。这个字段是 Claude Code 判断是否调用技能的主要依据。正文部分用 Markdown 标题组织Claude Code 会读取正文作为技能执行指令。5.3 frontmatter 写法先看一个合法的 frontmatter--- name: test-generator description: 当用户需要对 Python、JavaScript、TypeScript、Java 等代码生成单元测试、接口测试时使用。 ---这里有一个容易踩的坑。frontmatter 是 YAML 格式在 YAML 中#是注释符号。如果你在 frontmatter 里写--- name: test-generator # 一个技能 description: 生成测试 ---那么# 一个技能会被当作 YAML 注释不参与解析。这个行为不影响运行但如果你把一行关键配置写在了#后面那部分内容就会被忽略。5.4 关于“# 后面是不是不执行”这个问题要分场景回答场景一#写在 YAML frontmatter 里比如name: test-generator # 注释。这种写法中#后面的内容是 YAML 注释不会被解析相当于“不执行”。场景二#写在 frontmatter 之外也就是 Markdown 正文里比如## 使用流程。这种写法是标准 Markdown 标题Claude Code 会读取标题并用它来理解正文结构不存在“不执行”。场景三有人把 frontmatter 写成了# name: test-generator也就是把配置项本身当成了注释。这种情况下name和description根本没有被解析Claude Code 无法识别技能名称和触发条件技能自然不会被加载。所以“# 后面的是不是不执行”的正确理解是#在 frontmatter 里是注释符号在正文里是标题符号。真正导致技能失效的往往不是#本身而是 frontmatter 缺失、被注释掉、或者没有用---包裹。5.5 最小可用示例创建一个最小技能演示完整的 SKILL.md 流程。.claude/skills/demo-skill/ SKILL.md创建目录mkdir -p .claude/skills/demo-skill然后编写.claude/skills/demo-skill/SKILL.md--- name: demo-skill description: 当用户需要演示技能机制时使用例如要求展示技能运行流程。 --- # 演示技能 ## 使用场景 当用户想确认 Skill 机制是否生效时使用本技能。 ## 执行步骤 1. 输出当前技能名称和简介。 2. 列出技能目录下的文件清单。 3. 提示用户技能机制已生效。保存后在项目根目录启动 Claude Codeclaude然后输入请调用 demo-skill 演示技能机制如果 Claude Code 回应了“演示技能已加载”之类的信息说明技能目录和 frontmatter 解析正常。6. 实战给 Claude Code 装上“测试生成外挂”接下来从零手写一个更实用的技能test-generator。这个技能的目标是当用户指出项目里的某个文件或目录时Claude Code 自动分析代码生成符合项目语境的测试用例并尝试运行。6.1 设计技能目录.claude/skills/test-generator/ SKILL.md templates/ pytest_template.md jest_template.md scripts/ run_tests.sh这个目录结构覆盖主定义、模板和辅助脚本三层。如果你的项目只使用 Python可以只保留 pytest 模板如果涉及前端可以加 jest 模板。6.2 编写 SKILL.md--- name: test-generator description: 当用户需要对 Python、JavaScript、TypeScript、Java、Go 等代码文件生成单元测试、接口测试或测试计划时使用。当用户提到“生成测试”“写测试用例”“补充单测”时使用。 --- # 测试生成技能 ## 目标 根据用户指定的源文件或目录生成可运行、可维护、符合项目现有测试框架的测试代码。 ## 工作流程 1. 读取目标文件路径。 2. 分析项目结构和现有测试框架。优先检查项目根目录是否存在 pyproject.toml、pytest.ini、package.json、jest.config.js、pom.xml 等配置文件。 3. 输出测试计划包括 - 被测模块名 - 测试文件路径 - 使用的测试框架 - 关键测试用例列表 4. 生成测试代码。 - 如果项目使用 Python优先使用 pytest 风格。 - 如果项目使用 JavaScript/TypeScript优先使用 Jest 或 Vitest。 5. 触发测试运行。 - Python 项目尝试执行 python -m pytest 测试文件。 - Node 项目尝试执行 npx jest 测试文件。 ## 测试用例编写规范 - 每个测试用例包含 given、when、then 三要素。 - 对纯函数优先测试正常输入、边界输入、异常输入。 - 对 HTTP 接口优先测试状态码、响应结构、错误响应。 - 不生成只断言函数不报错的空测试。 ## 注意事项 - 如果目标文件依赖外部服务或数据库优先使用 mock 或 fixture。 - 生成测试代码后先向用户确认是否执行测试命令。 - 如果测试运行失败需要根据日志修复测试代码不要直接删除失败用例。6.3 设计模板文件模板的作用是给 Claude Code 提供生成测试代码的标准格式避免每次生成风格都不一致。templates/pytest_template.md# pytest 测试模板 导入被测模块 python import pytest from module_path import ClassName测试类结构class TestClassName: def setup_method(self): # 前置数据准备 pass def test_normal_case(self): # given # when # then assert True边界和异常用例def test_boundary_value(): # 边界输入 pass def test_invalid_input_raises(): # 预期抛出异常 with pytest.raises(ValueError): passtemplates/jest_template.md markdown # Jest 测试模板 导入被测模块 javascript const { functionName } require(module_path); // 或 import { functionName } from module_path;测试用例describe(functionName, () { it(should handle normal case, () { expect(functionName(input)).toBe(expected); }); it(should handle boundary value, () { expect(functionName(boundary)).toBeDefined(); }); it(should throw on invalid input, () { expect(() functionName(null)).toThrow(); }); });注意模板里的 是 Markdown 代码围栏如果放在 .md 模板文件中要注意嵌套围栏的写法。实际项目中建议把模板改成 .txt 或 .md 并使用完整围栏避免解析问题。 ### 6.4 编写辅助运行脚本 scripts/run_tests.sh bash #!/usr/bin/env bash # 根据项目结构选择测试命令 if [ -f pytest.ini ] || [ -f pyproject.toml ]; then python -m pytest $ exit $? fi if [ -f package.json ]; then if [ -f jest.config.js ]; then npx jest $ exit $? fi npm test $ exit $? fi echo 未识别到常见测试框架跳过自动运行 exit 0给脚本执行权限chmod x .claude/skills/test-generator/scripts/run_tests.sh6.5 在 Claude Code 中触发技能启动 Claude Codeclaude然后输入使用 test-generator 技能分析 src/calculator.py并生成 pytest 测试用例。如果技能触发成功Claude Code 会先输出测试计划再生成测试文件然后询问是否运行测试。你可以让它把测试写入tests/test_calculator.py然后执行运行测试并告诉我结果此时 Claude Code 会读取run_tests.sh的逻辑或者直接执行python -m pytest把测试结果汇报给你。7. 功能测试与效果验证7.1 验证技能是否被识别技能识别失败是最常见的问题。可以用一个简单方法验证在 Claude Code 中输入列出你已经加载的技能如果 Claude Code 能列出test-generator说明 Skills 扫描正常。如果列不出来检查目录路径是否是.claude/skills/test-generator/SKILL.md。SKILL.md文件名大小写是否正确。frontmatter 是否写在文件最顶部并且用---包裹。description是否写清楚。7.2 单元测试生成测试准备一个简单 Python 文件def add(a, b): return a b def divide(a, b): if b 0: raise ValueError(b cannot be zero) return a / b让 Claude Code 生成测试。预期输出包含add的正常输入用例。包含divide的边界用例。包含divide(1, 0)的异常断言。判断标准生成的测试代码能够通过python -m pytest运行并且存在一个测试失败用例或异常用例覆盖。7.3 接口测试生成测试如果项目里有 FastAPI、Flask 或 Express 接口可以要求技能生成接口测试。例如对 FastAPI使用 test-generator 生成 main.py 中所有 HTTP 接口的测试用例使用 httpx 或 fastapi.testclient。预期输出针对每个路由的 GET/POST 请求测试覆盖正常状态码、参数校验错误、鉴权失败等场景。7.4 批量测试生成对于多文件项目可以要求技能批量处理遍历 src/services 目录下的所有 Python 文件为每个文件生成对应的测试文件放在 tests/services 目录下。Claude Code 会分批读取文件并生成测试。批量任务耗时较长建议设置明确范围不要一次喂几百个文件。如果目录过大先用文件列表缩小范围。7.5 效果验证清单检查项通过标准技能识别Claude Code 能列出 test-generator单测生成测试文件正常生成无语法错误测试运行pytest 或 jest 能执行并输出结果边界覆盖包含异常输入和边界输入用例批量任务能按目录生成多个测试文件重复执行同一任务二次执行不会生成重复文件或能正确覆盖旧文件8. 接口 API、Headless 模式与批量任务8.1 Headless 模式除了交互式对话Claude Code 还支持非交互模式适合脚本调用。核心参数是-p后面跟提示词。单次执行claude -p 分析 src/calculator.py并用 pytest 生成测试用例输出到 tests/test_calculator.py输出 JSON 格式结果claude -p 分析 src/calculator.py列出其中的函数 --output-format json这种方式很适合在 CI 脚本或本地自动化任务里调用。注意headless 模式下 Claude Code 不会弹交互确认所以权限配置要提前写好否则可能因为权限确认卡住。8.2 Python 批量调用示例可以写一个 Python 脚本遍历项目源码目录逐个调用 Claude Code 生成测试。import subprocess import pathlib source_dir pathlib.Path(src) output_dir pathlib.Path(tests) output_dir.mkdir(exist_okTrue) for py_file in source_dir.rglob(*.py): relative py_file.relative_to(source_dir) test_file output_dir / relative.with_name(ftest_{py_file.stem}.py) test_file.parent.mkdir(parentsTrue, exist_okTrue) prompt ( f使用 test-generator 技能分析 {py_file} f并生成 pytest 测试文件保存到 {test_file} ) result subprocess.run( [claude, -p, prompt, --output-format, text], capture_outputTrue, textTrue, timeout300, ) print(f{py_file} - {test_file}) print(result.stdout[-1000:])这个脚本用subprocess调用claude -p适合以目录为单位的批量测试生成。生产环境建议增加超时、失败重试、日志记录。8.3 调用 API 时的注意点如果已经通过 API Key 接入可以把 Claude Code 当作一个命令行客户端来调用。不过要注意 token 消耗。批量任务会消耗大量 token建议先用--max-turns或类似参数限制轮数避免无限制循环。先在小目录上跑通再扩展到全项目。对输出做落盘不要只依赖终端日志。9. 资源占用与性能观察9.1 本机资源占用Claude Code 是 Node.js 编写的 CLI 工具不依赖 GPU不需要考虑显存。主要占用是Node.js 进程内存正常对话场景通常在几百 MB 以内具体取决于会话上下文长度。磁盘占用npm 全局包、日志、会话缓存总体不会太大但日志文件会随着使用增长。CPU本地几乎不做模型推理只有代码扫描和工具调用时会短暂占用。如果发现 Claude Code 越用越卡优先检查项目目录是不是被node_modules、.git、大二进制文件塞满。~/.claude/或.claude/下的日志和缓存是否过大。是否有多个claude进程残留。macOS 和 Linux 下查看进程ps aux | grep claude手动清理残留进程时需要谨慎避免误杀会话。9.2 API 消耗观察虽然本地资源占用低但 API 消耗是你真正要关心的成本。影响消耗的因素包括项目目录文件数量Claude Code 在分析项目时可能读取较多文件。上下文长度对话越长每次请求携带的历史上下文越多。技能指令长度SKILL.md正文过长每次触发都会占用 token。批量任务规模批量生成测试时token 消耗线性增长。降低消耗的方法在.claude/settings.json中配置忽略目录减少无关文件读取。每个技能正文控制在必要范围内不要写重复的“你是一个优秀的工程师”这类话。批量任务优先拆小批次用完即停避免长会话积累。10. 常见问题与排查方法问题现象可能原因排查方式解决方案claude命令找不到npm 全局 bin 不在 PATH执行npm bin -g查看路径把 npm 全局目录加入 PATH安装时报 Node.js 版本过低本地 Node 版本过老执行node -v安装 Node.js 18 或更高版本启动报 529远端 API 过载或限流查看错误日志稍后重试降低批量任务并发提示 your organization has disabled claude subscription access订阅权限或环境变量冲突检查是否设置了 ANTHROPIC_BASE_URL 等变量清除多余环境变量或改用 API Key 登录提示模型名不被识别配置的模型名与实际模型不匹配检查 ANTHROPIC_MODEL 或 cc-switch 配置使用供应商文档中正确的模型名技能没有被触发SKILL.md 路径错误或 frontmatter 格式错误检查目录结构并让 Claude Code 列出技能修正路径确保用---包裹 frontmatterSKILL.md 里 # 后面的内容不执行把 frontmatter 配置写成了 YAML 注释查看文件开头是否有---确保#在正文中是标题frontmatter 中不要放配置技能触发了但行为混乱description 写得太宽泛或正文指令冲突检查 description 和正文优化触发描述精简工作流程批量任务卡住一次处理文件过多或等待用户确认观察终端输出分批处理提前配置权限允许项测试生成后无法运行测试框架不一致或依赖缺失检查项目配置文件先安装测试框架依赖再运行11. 最佳实践与使用建议11.1 先从一个小项目验证第一次使用 Claude Code 写技能不要直接上生产大仓库。先在一个只有几个文件的测试目录里跑通确认技能可以被识别、能生成测试、能运行测试再迁移到真实项目。11.2 目录管理规范建议固定一套目录结构.claude/ settings.json skills/ test-generator/ SKILL.md templates/ scripts/输入素材、输出测试文件、日志分别放不同目录。不要把所有文件都放在根目录否则 Claude Code 在分析项目时会读入大量无关文件。11.3 技能设计原则每个技能只解决一个问题。description使用明确的触发条件避免“帮助用户”这类空泛描述。正文使用编号步骤降低歧义。需要模型做决定的地方给出优先级规则。涉及执行命令时明确命令的适用范围。11.4 密钥与接入安全所有 API Key 使用环境变量不要写死在技能和配置里。使用 cc-switch 切换多个供应商时注意不同供应商的模型名差异。如果公司项目有保密要求在接入前确认第三方 API 的数据使用政策。11.5 批量任务的工程化建议先小批次测试再全量执行。为每次任务输出日志记录输入文件、生成文件、耗时、结果。对失败任务做重试但设置最大重试次数。使用timeout限制单次执行时间防止个别文件卡住整个队列。12. 总结与下一步Claude Code 的 Skills 机制并不复杂核心就四个字结构化提示。把你要做的事情写进.claude/skills/技能名/SKILL.md用 frontmatter 约定触发条件用正文约定执行步骤再用模板和脚本补充细节就能让 Claude Code 在项目里按固定套路工作。这篇文章里最有价值的部分不是“安装命令”和“技能代码”而是你应该先做什么验证第一先跑通最小技能确认你的SKILL.md格式没问题。第二再扩展成测试生成技能跑通单文件测试。第三最后上批量任务。最容易踩的坑有三个SKILL.md的 frontmatter 写错、description描述不清晰导致技能不触发、批量任务一次喂太多文件导致卡死。这三个坑解决掉后面基本就顺了。下一步你可以继续扩展这个“测试生成外挂”让它支持更多测试框架、自动分析覆盖率、输出测试报告甚至把它接进 Git 提交流程让每次提交代码后自动生成候选测试用例。建议把这篇文章收藏备用等你实际配置 Claude Code 和手写 SKILL.md 时按步骤排查会比临时搜索更省时间。