khufu-kit
v0.6.0
Published
Test generation skill framework for AI IDEs, following the test pyramid methodology. Provides /khufu-doc-prd, /khufu-doc-api, /khufu-doc-adr, /khufu-doc-testcase, /khufu-harness, /khufu-test-unit, /khufu-test-integration, /khufu-test-api, and /khufu-test-
Downloads
821
Maintainers
Readme
Khufu
English | 简体中文
面向 AI IDE 的测试生成技能框架,遵循测试金字塔方法,并采用评估驱动开发(EDD)与规约驱动开发(SDD)。
Khufu 提供九项技能——/khufu-doc-prd、/khufu-doc-api、/khufu-doc-adr、/khufu-doc-testcase、/khufu-harness、/khufu-test-unit、/khufu-test-integration、/khufu-test-api 与 /khufu-test-e2e。它们借助 AI 智能体,为项目生成按 MVP 划分的 PRD、REST API 契约、架构决策记录、测试用例文档、项目约束资产(Harness Engineering)、单元测试、集成测试、API 测试与端到端测试。
特性
- 测试金字塔:覆盖全部四层测试,并内置去重——上层只测下层在结构上测不到的内容
- 评估驱动开发(EDD):生成测试之前,先定义可量化的质量标准(覆盖率、性能、正确性)。每条测试都服务于一项可度量的评估标准。内置
评估 → 验证 → 改进反馈闭环 - 规约驱动开发(SDD):测试用例是显式、带版本的 Markdown 规约文件(
specs/<feature>/spec.v<N>.md)。支持正向生成(规约 → 测试)与反向生成(测试 → 规约)。每条测试都链回对应的规约条目 - 生成路径:
- 基于规约:从规约文档生成测试(
/khufu-test-unit @docs/spec.md) - 基于代码:阅读现有实现生成测试(并自动补写回溯规约)
- 两者一起(API 与 E2E):测试用例和实现都在时,调用目标来自真实的路由或页面,断言来自测试用例
- 基于规约:从规约文档生成测试(
- 语言感知:自动识别项目语言,并推荐合适的测试框架
- 可测试性评估(UT):将源文件评为 A/B/C——可直接测试、需要 PowerMock(标记为
fragile),或需要重构(记入untestable-report.md) - H2 数据库支持(IT):为 Java 集成测试提供轻量内存数据库选项——无需 Docker,启动时间小于 5 秒,便于在 CI 中快速得到反馈
- 共享测试数据工厂:测试数据定义一次,在 IT、API、E2E 各层复用
- 对齐 TDD:测试遵循测试驱动开发与敏捷实践
- 需求到 PRD:
/khufu-doc-prd追问需求描述,将其拆成多个 MVP,并在docs/prd/写入一整套 PRD。项目目标、范围与术语表放在prd-catalog.md,该文档同时链接所有 PRD;Cockburn 完全正式用例放在prd-mvp1.md、prd-mvp2.md……;非功能性需求放在prd-quality.md - PRD 到测试用例:
/khufu-doc-testcase在docs/test-cases/为一份 PRD 写下对应的一份用例文档(test-cases-prd-mvp1.md……)。基本流、备选流,以及需要单独断言的业务规则,各写一条。脚本只判断命令后面的文字。没有 PRD 路径时,技能在回复里提问,不扫描、也不写文件。用户选择扫描之后,先列出文件,再次确认后才生成。prd-catalog.md是目录,不是输入 - PRD 质量属性到 ADR:
/khufu-doc-adr读取prd-quality.md与 ADR 模板,按模板要素(背景、驱动因素、备选方案、利弊、影响、确认)对每个决策做架构分析,每次只提出一个决策问题,以可上下选择的方式给出 2–3 个主流方案、推荐项与“用户自行决定”选项;宿主没有结构化提问工具时降级为带编号的纯文本提问。随后把每个确认的技术选型或架构决策写成独立的 ADR。项目已有 khufu-harness 约束资产时写入其 ADR 目录,否则写入docs/architecture/adr/,并维护链接到全部 ADR 的目录文档 - PRD 用例到 API 契约:
/khufu-doc-api读取 Cockburn 用例与prd-quality.md,界定前后端界限,把每个调用点转成 RESTful 契约。它写入docs/design/api-catalog.md与docs/design/api-contracts.md,包含请求/响应/错误 schema、内嵌 OpenAPI 3.0.3、逐 API 的 SLA、验收标准与可测试性说明。输出既可作为实现契约,也可作为 API 测试生成的输入 - 代码绑定调用(API 与 E2E):已绑定的测试调用真实入口,并按测试用例断言,即便这会让当前实现失败。找不到唯一匹配的用例不生成测试,而是写入
docs/khufu/api/oracle-mismatch.md或docs/khufu/e2e/oracle-mismatch.md - 多 IDE 支持:可安装到 Claude Code、Cursor、OpenCode、Codex、Qoder 与 Trae——每个工具都按自身的技能/命令目录约定放置技能
快速开始
# 全局安装
npm install -g khufu-kit
# 在项目中初始化。工具列表没有任何预选项。
cd your-project
khufu init
# 对照 npm 上的最新版本,有更新则升级
khufu update
# 在 IDE 中使用技能(以 Claude Code 为例)
/khufu-doc-prd # 追问需求并生成按 MVP 划分的 PRD
/khufu-doc-api # 把 PRD 用例转成 REST API 契约
/khufu-doc-adr # 把 PRD 质量属性转成 ADR
/khufu-doc-testcase @docs/prd/prd-mvp1.md # 把该 PRD 生成测试用例
/khufu-harness # 建立 / 更新项目约束资产
/khufu-test-unit # 生成单元测试
/khufu-test-integration # 生成集成测试
/khufu-test-api # 生成 API 测试
/khufu-test-e2e # 生成端到端测试技能重命名
技能已按产物重新命名:doc-* 生成文档,test-* 生成测试代码。旧名称不再作为别名保留。升级后请重新安装,安装器会移除旧技能目录:
khufu init --force
# 或在本仓库中
bash scripts/link.sh| 旧名称 | 新名称 |
|--------|--------|
| /khufu-ut | /khufu-test-unit |
| /khufu-it | /khufu-test-integration |
| /khufu-api | /khufu-test-api |
| /khufu-e2e | /khufu-test-e2e |
| /khufu-to-prd | /khufu-doc-prd |
| /khufu-to-test-cases | /khufu-doc-testcase |
| /khufu-adr-with-prd | /khufu-doc-adr |
| /khufu-api-with-prd | /khufu-doc-api |
| /khufu-harness | 保持不变 |
支持的智能体编程工具
Khufu 按各工具自己的技能/命令目录约定安装技能,因此同一条 khufu init 在所有工具中都能使用:
| 工具 | 技能/命令目录(项目内) | 全局目录 |
|------|------------------------|----------|
| Claude Code | .claude/skills/ | ~/.claude/skills |
| Cursor | .cursor/commands/ | ~/.cursor/commands |
| OpenCode | .opencode/commands/ | ~/.opencode/commands |
| Codex (OpenAI) | .codex/skills/ | ~/.codex/skills |
| Qoder | .qoder/skills/ | ~/.qoder/skills |
| Trae | .trae/skills/ | ~/.trae/skills |
khufu init 会请你选择要安装的工具,没有任何预选项。--yes 和非交互运行不会代选工具,需要自己传入 --ide:
khufu init --ide claude,qoder,trae # 带 --yes,或没有终端时必须传入
khufu init --ide claude --scope global # 等同于 --global;默认范围是项目内
khufu init --ide claude --yes --force # 跳过其余提问,并覆盖 .khufu/khufu.yaml--yes 会直接采用检测到的语言,不再询问;检测不到语言时回退到 Java。它不会代选工具。
每个被选中的工具都会在自己的目录中收到全部九项技能(khufu-doc-prd、khufu-doc-api、khufu-doc-adr、khufu-doc-testcase、khufu-harness、khufu-test-unit、khufu-test-integration、khufu-test-api、khufu-test-e2e)。技能附带的文件会一起安装,其中包括 khufu-doc-testcase/scripts/resolve_prd_args.py,以及 khufu-doc-prd、khufu-doc-adr、khufu-doc-api 的模板。
更新
khufu update 将已安装版本与 npm 上最新发布的 khufu-kit 进行比较:
- 若有更新版本,则执行升级(交互模式下会先询问确认)。
- 否则提示当前已是最新版本。
khufu update # 交互模式——升级前询问
khufu update -y # 直接升级,不再询问支持的语言
| 语言 | UT 框架 | IT 框架 | API 框架 | E2E 框架 | |------|---------|---------|----------|----------| | Java | JUnit 5/4, TestNG | Spring Boot Test, Testcontainers, H2 | REST Assured, MockMvc | Playwright, Selenium | | Python | pytest, unittest | pytest + testcontainers | pytest + httpx | Playwright | | TypeScript/JS | Jest, Vitest, Mocha | Jest + Supertest | Supertest | Playwright, Cypress | | Go | testing + testify | testing + dockertest | testing + httptest | Playwright | | C# | xUnit, NUnit, MSTest | xUnit + Testcontainers | RestSharp | Playwright | | C++ | Google Test, Catch2, doctest | Google Test | pytest + httpx | Playwright, Qt Test |
初始化会从项目文件识别 Java、Python、TypeScript、JavaScript、Go、C#、C++、Rust、Ruby 和 Elixir。上表中的语言会写入框架、目录和覆盖率默认值。Rust、Ruby 和 Elixir 能被识别,交互式语言列表里也有 Rust 和 Ruby,但这三者没有框架默认值。C++ 由 CMakeLists.txt 或 xmake.lua 识别,不在手动语言列表里。
测试金字塔策略
Khufu 强制执行互不重叠的测试金字塔。每一层负责一个独立的风险维度:
| 层级 | 负责 | 不负责 | |------|------|--------| | UT | 业务逻辑、算法、校验、状态迁移 | 数据库查询、HTTP 路由、UI | | IT | 组件装配、事务边界、ORM 映射、数据库约束 | 业务逻辑细节、HTTP 状态码 | | API | 状态码、响应结构、请求头、认证/鉴权、内容协商 | 组件内部实现、数据库状态 | | E2E | 关键用户旅程、多页面流程、浏览器交互 | 边界校验、穷举错误路径 |
在某一层生成测试时,khufu 会扫描下层已有测试,并跳过不会带来新风险的场景——让测试套件保持精简、快速。
规约体系(SDD)
Khufu 把测试规约当作一等产物。每个功能对应一份带版本的 Markdown 规约:
specs/
├── UserRegistration/
│ ├── spec.v1.md # 带版本的规约
│ ├── spec.v2.md
│ └── CHANGELOG.md # 规约变更历史每份规约文件包含:
# Feature: UserRegistration
- Version: 1 | Created: 2026-06-25 | Source: spec-based | Criticality: High
## Evaluation Criteria ← EDD: defined BEFORE tests
### Correctness(正确性)
- [ ] Normal input returns User with ID
- [ ] Duplicate email throws DuplicateEmailException
## Unit Tests
### UT-USER-001: shouldCreateUser_whenValidInputGiven
- Category: happy-path | Status: implemented
- Test File: `__tests__/UserService.test.ts`
- Evaluates: Correctness — normal input returns User
**Scenario:** Given ... When ... Then ...
## Evaluation Summary ← EDD: filled AFTER test execution
| Criteria | Target | Actual | Status |
|----------|--------|--------|--------|
| Line coverage | ≥85% | 88% | ✅ |
| Branch coverage | ≥75% | 72% | ❌ |规约生命周期:planned → implemented → evaluated → passed(未达标项会触发重新评估)。
脆弱测试处理
对于难以用常规 mock 拆开的紧耦合代码,khufu-test-unit 提供:
- Java 的 PowerMock / Mockito-inline 支持(静态方法、构造函数、final 类)
- 此类测试一律标记
@Tag("fragile"),并且默认不进入 CI - 脆弱测试按技术债跟踪——目标是不超过测试套件的 20%
- 不可测代码(C 级)记入
untestable-report.md,并附重构建议
配置
执行 khufu init 后,配置写在 .khufu/khufu.yaml。.khufu/installed-skills.json 记录已安装的技能。TypeScript 项目的内容如下:
ide:
- claude
- qoder
- trae
language: typescript
frameworks:
ut: jest
it: jest
api: supertest
e2e: playwright
directories:
ut: __tests__/
it: __tests__/integration/
api: __tests__/api/
e2e: e2e/
coverage:
ut:
tool: jest
thresholds:
line: 80
branch: 70
function: 80
formats: [lcov, html, text]
excludes: ['**/*.d.ts', '**/index.ts', '**/*.config.*']
it:
tool: jest
thresholds:
line: 60
branch: 50
formats: [lcov, html]
excludes: ['**/*.config.*']
scope: projectJava、Python、Go、C# 和 C++ 会写入各自的框架、目录和覆盖率默认值。初始化不会写入 spec、evaluation、categories 或 dataFactories。这些规则仍由 skills/_shared/ 里的技能约定执行。之后可以自行补上可选的 spec 块;测试层技能在它存在时读取 spec.directory(默认 specs/)和 spec.docsDirectory(默认 docs/khufu/)。--force 会替换已有的 .khufu/khufu.yaml。
架构
skills/
├── _shared/
│ ├── mode-selection.md # 基于规约 vs 基于代码
│ ├── language-detection.md # 语言与 khufu.yaml
│ ├── framework-selector.md # 按语言 × 层级选择框架
│ ├── directory-resolver.md # 测试目录解析
│ ├── coverage-config.md # 覆盖率工具配置
│ ├── compilation-verification.md # 编译生成的测试
│ ├── test-execution-verification.md # 运行生成的测试
│ ├── evaluation-framework.md # EDD 方法
│ ├── test-pyramid-strategy.md # 分层去重规则
│ ├── spec-sync.md # 跳过已经生成过的场景
│ ├── spec-doc-scanner.md # 读取 docs/khufu 执行记录
│ ├── spec-doc-generator.md # 写入 docs/khufu 执行记录
│ ├── test-data-factories.md # 共享数据工厂模式
│ ├── report-template.md # 统一报告生成
│ ├── parallel-execution.md # 把生成工作分给子代理
│ └── oracle-binding.md # 代码绑定调用,测试用例锁定断言
├── khufu-doc-prd/
│ ├── SKILL.md # PRD 集:目录、MVP 用例、质量需求
│ └── assets/ # PRD、用例与质量需求模板
├── khufu-doc-api/
│ ├── SKILL.md # 由 PRD 用例生成 REST API 契约
│ ├── assets/ # API 目录、契约、REST 与 SLA 模板
│ └── references/ # RESTful API 设计原则
├── khufu-doc-adr/
│ ├── SKILL.md # 由 PRD 质量属性生成 ADR
│ └── assets/ # ADR 与 ADR 目录模板
├── khufu-doc-testcase/
│ ├── SKILL.md # 由 PRD 生成 docs/test-cases
│ └── scripts/resolve_prd_args.py # 判断本次调用是否给出了 PRD 路径
├── khufu-harness/SKILL.md # 约束资产生成器
├── khufu-test-unit/SKILL.md # 单元测试生成器
├── khufu-test-integration/SKILL.md # 集成测试生成器
├── khufu-test-api/SKILL.md # API 测试生成器
└── khufu-test-e2e/SKILL.md # 端到端测试生成器khufu-test-unit、khufu-test-integration、khufu-test-api 和 khufu-test-e2e 通过 Read 工具读取 _shared/。共享逻辑只定义一次。khufu-harness、khufu-doc-prd、khufu-doc-testcase、khufu-doc-adr 和 khufu-doc-api 走各自的流程。
开发
在本仓库中开发
一条命令把技能软链接到位,Claude Code 会直接从工作区加载它们:
git clone https://github.com/agiledon/khufu.git
cd khufu
npm install
npm run build
npm run setup # 为本地开发创建软链接setup 会做这些事:
- 将
skills/_shared/软链接到项目根目录的_shared/(这样技能文件里的Read _shared/...引用才能正确解析) - 将每个
skills/khufu-*/软链接到.claude/skills/khufu-*/(Claude Code 从.claude/skills/加载技能) - 替换先前
khufu init留下的过期副本
设置完成后,直接编辑 skills/ 下的任意文件,改动立即生效——无需重新构建,也无需再复制一次。
npm test # 运行 khufu 自身的测试
npm run dev # 监听模式(tsc --watch)从本地源码安装到其他项目
用 npm link 把本地 khufu CLI 注册为全局命令,再在目标项目中初始化:
# 第 1 步:从源码构建 khufu-kit
cd /path/to/khufu-kit
npm install
npm run build
npm link # 全局注册 khufu 命令
# 第 2 步:安装到你的项目
cd /path/to/your-project
khufu init # 写入 .khufu/khufu.yaml,并把技能安装到所选 IDE 的技能/命令目录修改 khufu-kit 源码后,这样获取更新:
cd /path/to/khufu-kit
npm run build # 重新编译 TypeScript
# khufu 命令会自动使用更新后的构建产物(npm link)用完后取消全局链接:
cd /path/to/khufu-kit
npm unlink -g khufu-kit也可以用本地路径直接 npm install(不注册全局链接):
cd /path/to/your-project
npm install /path/to/khufu-kit
npx khufu init许可证
MIT
