Skill + CLI 支持 Claude Code 与 Codex

大需求进，小而可验证的提交出。

Hepha 把大需求拆成小任务。只有真实的 RED、GREEN、regression 测试记录，以及分开进行的 Spec 审查、代码审查和人工批准都落了盘，任务才算完成。可复用的结论沉淀进你的个人工程 Wiki。

开始使用 GitHub 真实示例

MIT 许可
Node ≥ 18
零运行时依赖
纯本地，无遥测

.hepha/evidence/TASK-001.json mode: full

rednode --test test/slugify.test.jsexit 1
greennode --test test/slugify.test.jsexit 0
regressionnpm test --silentexit 0
spec reviewclaude-spec-reviewerpassed
code reviewclaude-code-reviewerpassed
humanmelonlee (recorded by agent)passed

hepha transition --task TASK-001 --to done

{ "ok": true, "task": { "id": "TASK-001", "state": "done" … } }

SPECPLANRESEARCHREDGREENREGRESSIONREVIEWSUMMARYWIKICOMMIT

01 问题

“测试都通过了”只是一句话，Hepha 留下的是证据。

让 Agent 连续跑一个大需求，最后留给你的是一大坨 diff、一长串对话和一句很自信的总结。事后能检查的，只有 diff 和 Agent 说过的话。Hepha 改变的是跑完之后磁盘上留下了什么：Spec、代码和记录仍然由 Agent 来写；测试命令由 CLI 执行并记录结果，审查也由 CLI 记录。证据不全时，CLI 会拒绝推进任务状态。

跑完之后，你能核实……	一次长时间 Agent 会话	一次 Hepha 交付
……当初约定的行为是什么？	也许在提示词里	`specs/SPEC-*.md` 里有带编号的场景；每个任务有 Given/When/Then 验收条件，开工时固化指纹
……修复之前测试真的失败过？	碰巧做过、又能在对话里翻到才行	`evidence/TASK-*.json` 里有 RED 的命令、非零退出码和输出
……现在测试是通过的？	Agent 的一句话	GREEN、regression 记录，以及可以重跑的 `test_plan.commands`
……Spec 和代码都审过？	通常混在一起，或者干脆跳过	`spec`、`code`、`human` 三条独立审查记录，带审查人和备注
……哪个提交做了什么？	一个大 diff	一个任务一个小提交；资产能追溯 Spec → Task → Test → Commit
……哪些值得复用？	埋在对话里	按日期归档的 Summary，加上审核过、可以跨项目检索的 Wiki 资产

Hepha 做不到的事：它判断不了测试有没有意义、审查是否认真。它能证明命令确实跑过、结果就是记录里那样，也能证明每一步审查都被显式记录了。把它当作审计记录和护栏，而不是判断力的替代品。

02 工作原理

每轮只做一个就绪任务，每一步都留下 CLI 能检查的东西。

.hepha/ 里的 JSON 是事实源，Markdown 是阅读层。记录证据、推进任务状态，Agent 都通过调用 CLI 完成。

01 · 规划
SPEC
写清目标、非目标，以及带稳定编号的行为场景。
specs/SPEC-001.md
02 · 规划
PLAN
每个任务都有 spec_refs、Given/When/Then 验收、风险、测试命令和资产策略。
hepha validate
03 · 规划
RESEARCH
只在引入新工具、架构变更、安全或迁移风险、确实存在多个方案时才做。
decision-log.md
04 · 锻造
RED
先写测试。命令由 CLI 亲自执行，而且必须真的失败。
record-check --phase red
05 · 锻造
GREEN
用最小实现让测试通过；命令、退出码和输出都会保存。
--phase green
06 · 锻造
REGRESSION
改动之后，更大范围的测试依然通过。
--phase regression
07 · 淬炼
REVIEW
Spec 审查和代码审查分开记录，默认还要人工批准。
record-review
08 · 记录
SUMMARY
为这一轮写一份事实性的 Summary。
summary/<日期>/<人>/
09 · 记录
WIKI
可复用的结论先成为候选，经过审核和敏感信息检查才发布。
publish-asset
10 · 交付
COMMIT
一个任务一个最小的 conventional commit，然后重建索引、同步资产。
build-index

会说“不”的门禁

hepha transition 负责 todo → doing → review → done 状态机（另有 blocked / skipped），每一步都检查已记录的证据。缺什么，它会直接说出来，并以非零退出码结束。

→ doing

满足以下条件才放行

依赖任务全部 done。
进入时固化任务契约指纹（验收、测试、Spec 引用、模式、资产策略）。

→ review

满足以下条件才放行

记录里有失败的 RED、通过的 GREEN 和通过的 regression。
契约指纹没有变化。

→ done

满足以下条件才放行

Spec 审查和代码审查通过。
有人工批准（除非 manifest 设置了 approval_required: false）。
Summary 存在，资产策略满足。

examples/slugify · 摘自 progress.md 与证据文件

# 实现还没保存就跑了 GREEN，所以它以 1 退出
$ hepha transition --root . --task TASK-001 --to review
Hepha: 状态门禁未通过：
缺少 GREEN 通过测试证据
缺少 regression 通过证据
# 退出码 1

# 之后：还没写 Summary 就想标记 done
$ hepha transition --root . --task TASK-001 --to done
Hepha: 状态门禁未通过：
缺少人工批准
缺少任务 summary
缺少资产候选
# 退出码 1

真实的拒绝，原样留档

真实示例是从空目录开始、只用 CLI 完成的。过程中门禁拒绝了两次。那次失败的 GREEN 仍按顺序保存在 evidence/TASK-001.json 里：

red:1green:1regression:1green:0regression:0

证据只追加不覆盖，门禁读取的是最近一次运行。CI 每次运行都会重新校验示例的全部门禁。

full 还是 lite

小而低风险的改动可以声明 "mode": "lite"。只有 risk: "low" 且 asset_policy: "none" 时，validator 才接受 lite。

门禁	full（默认）	lite
Spec 引用 + Given/When/Then	✓	✓
RED + GREEN	✓	✓
regression	✓	–
Spec 审查	✓	–
代码审查 + 批准	✓	✓
Summary	✓	–
Wiki 资产	按策略	不允许

契约指纹

进入 doing 时，CLI 保存任务契约的 SHA-256。做到一半想放宽验收条件、换掉测试或者改成 lite，下一道门禁就会拒绝。

.hepha/evidence/TASK-001.json

"task_contract_hash": "fa67d99d67793423…f01c04db0f",
"contract_recorded_at": "2026-10-31T15:17:50.211Z"

# 之后若契约发生变化：
任务契约已变更；请将任务标记 blocked、
记录原因并重新规划，不得静默降低门禁

03 证据与回看

回看交付过程，而不是翻聊天记录。

hepha-server 把 .hepha/ 渲染成一个本地只读站点：时间线、每条命令和审查记录、Wiki 卡片、搜索和来源谱系。下面是它在真实示例上运行的截图。

127.0.0.1:3000

Hepha Review 概览页：任务与资产计数、搜索框、运行产物文件、PAT-001 与 CHK-001 两张个人 Wiki 卡片，以及任务时间线 — 概览：运行产物、Wiki 卡片、候选队列、任务时间线。

TASK-002 任务页：TDD 检查表中 red 退出码 1、green 退出码 0、regression 退出码 0，spec、code、human 三项审查均为 passed — **任务详情**：RED / GREEN / regression 记录与退出码，以及 spec / code / human 审查。

PAT-001 资产页及来源谱系：SPEC-001、TASK-002、test/slugify.test.js 和已解析的 commit hash — **Wiki 资产**：Spec → Task → Test → Commit 来源谱系，已解析为真实 commit hash。

搜索“nfkd”的结果：一条匹配的资产和一条匹配的任务 — 搜索：覆盖任务、资产、标签和来源 ID。

只读只接受 GET 和 HEAD 请求，从不写入你的项目。

默认只绑定本机绑定 127.0.0.1，并发送严格的安全响应头。

零依赖纯 Node ≥ 18，除了 Skill 目录什么都不用装。

可重跑每条命令都原样保存，你可以自己再跑一遍。

04 个人 Wiki

学到的东西留下来，连同它的出处。

Evidence 说明跑了什么，Summary 说明发生了什么，Wiki 资产说明以后能复用什么、哪些场景不适用。个人索引则跨项目记录每条经验从哪来。

Evidence跑了什么、结果如何？.hepha/evidence/TASK-*.json

Summary这一轮发生了什么？.hepha/summary/YYYY-MM-DD/<person>/TASK-*.md

Wiki 资产以后能复用什么，哪些场景不适用？.hepha/wiki/assets/*.md

个人索引这条经验从哪来，可信度如何？~/.hepha/wiki/index.json

可追溯的来源谱系

资产带有 source_specs、source_tasks、source_tests、source_commits 四类来源。提交之前写 source_commits: [self]，sync-personal 会把它解析成最近一次改动该资产文件的提交 hash。示例中的 PAT-001 解析结果如下：

SpecSPEC-001

TaskTASK-002

Testtest/slugify.test.js

Commitself → 5a94717

先审核，再复用

结论先以候选的形式存在。publish-asset 发布前会校验 Schema 并检查敏感信息。标为 project-confidential 的资产不会离开项目。

candidate→reviewed→published→stale→superseded

05 快速开始

克隆一次，链接 Skill，显式调用。

Skill 不会被隐式触发，需要你显式调用。npm 包已经准备好，但还没有发布，所以请从 GitHub 安装。

只对单个项目生效（Claude Code）：把 skills/hepha 复制到项目的 .claude/skills/ 并提交，团队成员也能用。
守卫规则（可选，推荐）：rules/hepha-guard.mdc 是硬性门禁的精简版。Claude Code 复制到 .claude/rules/hepha-guard.md，Cursor 放进 .cursor/rules/，Codex 写进 AGENTS.md。
其他 Agent：只要能读 SKILL.md、能执行 shell 命令，就可以按这个协议工作；CLI 是纯 Node。

安装 Skill

个人级 Skill，对所有项目生效。

bash

git clone https://github.com/melonlee/hepha-skill.git
cd hepha-skill
mkdir -p ~/.claude/skills && ln -s "$PWD/skills/hepha" ~/.claude/skills/hepha

让 Agent 运行它

Agent 会初始化 .hepha/，写 Spec 和通过校验的 backlog，然后每轮做一个任务。

Claude Code 提示词

/hepha 为订单页实现 CSV 导出。
Spec 和 Summary 用中文；任何任务标记完成前先问我。

回看过程

打开 http://localhost:3000。服务是只读的，默认只绑定 127.0.0.1。

bash

node ~/.claude/skills/hepha/scripts/hepha-server.js --root . --port 3000

安装 Skill

Codex 用户级 Skill。

bash

git clone https://github.com/melonlee/hepha-skill.git
cd hepha-skill
mkdir -p ~/.agents/skills && ln -s "$PWD/skills/hepha" ~/.agents/skills/hepha

让 Agent 运行它

Agent 会初始化 .hepha/，写 Spec 和通过校验的 backlog，然后每轮做一个任务。

Codex 提示词

$hepha 为订单页实现 CSV 导出。
Spec 和 Summary 用中文；任何任务标记完成前先问我。

回看过程

打开 http://localhost:3000。服务是只读的，默认只绑定 127.0.0.1。

bash

node ~/.agents/skills/hepha/scripts/hepha-server.js --root . --port 3000

CLI 参考

在克隆的仓库里用 node skills/hepha/scripts/hepha-cli.js <command>。所有命令都支持 --root <项目目录>。环境变量：HEPHA_PERSON、HEPHA_WIKI_ROOT、HEPHA_PORT、HEPHA_HOST。

命令	作用
`init --requirement "…" [--person NAME]`	创建 `.hepha/`、manifest、空 backlog 和 Spec 起始文件
`validate [--allow-empty]`	校验 backlog Schema、Spec 引用、模式和依赖 DAG
`record-check --task T --phase red\|green\|regression\|lint\|build\|browser --command "…"`	执行命令并记录退出码和输出；RED 必须失败，其余阶段必须通过
`record-review --task T --type spec\|code\|human --status passed\|failed\|changes-requested`	记录一次审查，可选 `--reviewer` 和 `--notes`
`transition --task T --to doing\|review\|done\|blocked\|skipped`	门禁通过后变更状态
`publish-asset --file .hepha/wiki/candidates/X.md [--reviewer N]`	校验资产、检查敏感信息并发布
`build-index`	重建任务和资产索引
`sync-personal [--wiki-root DIR]`	把已发布、非机密的资产同步到个人 Wiki
`version`	输出版本号
`hepha-server [--port 3000] [--host 127.0.0.1] [--wiki-root DIR]`	只读的本地 Review 页面

06 对比

刻意收窄。

Hepha 借鉴了 Superpowers 和 Spec Kit 推广的 Spec 先行与 TDD 纪律。三者都有价值，只是解决的问题不同。以下对比依据各自 2026 年 10 月的 README，如有不准确欢迎指正。

维度	Superpowers	Spec Kit	Hepha
定位	由一组可组合 Skill 构成的开发方法论（头脑风暴、计划、worktree、子代理开发、TDD、代码审查等）	开源工具包：Python CLI（`specify`）+ 模板 + Agent 命令，覆盖 SDD、修 bug、想法评估	一个交付 Skill + 一条守卫规则 + 零依赖 Node CLI
范围	覆盖完整研发流程，支持众多 Agent	多种流程、多种 Agent；面向团队的扩展、预设、工作流和目录	刻意收窄：服务个人交付的一条循环
安装	各 Agent 的插件市场	`uv tool install specify-cli`	软链接或复制目录（npm 包已就绪，尚未发布）
约束落在哪里	自动触发的 Skill 指令	命令、模板和可选的扩展门禁	CLI 状态机读取已记录的证据，缺失时以非零退出
测试证据	TDD Skill：先看测试失败，再看通过	取决于所选流程和扩展	每个任务保存 RED/GREEN/regression 的命令、退出码和输出
知识沉淀	设计文档与计划	Markdown 形式的 Spec、计划、任务	Summary + 审核过的 Wiki 资产，带 Spec/Task/Test/Commit 来源，可跨项目同步
回看入口	Agent 会话 / PR	Agent 会话 / 生成的文档	本地只读 HTML：时间线、证据、搜索、谱系

怎么选：想要一套覆盖面广、能自动触发、支持多种 Agent 的技能库，选 Superpowers；想在团队里推行可定制的 Spec 驱动流程，选 Spec Kit；想要一条小而可审计的循环，让“完成”意味着证据落盘，同时积累个人知识，选 Hepha。Hepha 也可以和前两者一起用。

07 常见问题

常见疑问，直接回答。

会不会让 Agent 变慢？

会慢一些：先写失败测试、记录两次审查都要花时间。lite 模式就是为不值得走全流程的小改动准备的。Hepha 适合“问题发现得晚，代价比多走几步更大”的工作。

Agent 不能直接伪造证据吗？

record-check 自己执行命令、记录真实退出码，门禁读取的就是这些记录。但如果 Agent 铁了心直接改 JSON，没有任何东西能拦住它，所以证据的可信度取决于你的流程：守卫规则禁止手改证据，而记录里的每条命令你都可以重跑。Hepha 让偷工减料变得可见、成本更高，但做不到彻底杜绝。

支持哪些 Agent？

为 Claude Code 和 Codex 设计，两者都有原生的 Skill 目录。CLI 是纯 Node，任何能读 SKILL.md、能执行 shell 命令的 Agent 都可以按这个协议工作。

为什么 CLI 提示和模板是中文？

这个 Skill 最初是为中文团队设计的。Spec、Summary 和资产可以用任何语言写，仓库里的示例就是英文。CLI 提示的多语言化在计划中，欢迎 PR。

它会自动提交或推送吗？

Skill 要求按你批准的提交策略，一个任务一个小提交，默认需要人工批准。CLI 自己从不提交，只会调用两个只读的 git 命令：git config user.name（默认负责人名）和 git log（用来解析 self 提交引用）。

数据会上传吗？

不会。所有数据都在项目的 .hepha/ 里；如果你执行了同步，还会写到 ~/.hepha/wiki。Review 服务只绑定本机，只接受 GET/HEAD 请求，并发送严格的安全响应头。

让“完成”意味着证据已经落盘。

先把真实示例从头看到尾，或者直接安装 Skill，用这条循环交付你的下一个需求。

开始使用真实示例在 GitHub 上 Star

大需求进， 小而可验证的提交出。

“测试都通过了”只是一句话，Hepha 留下的是证据。

每轮只做一个就绪任务，每一步都留下 CLI 能检查的东西。

SPEC

PLAN

RESEARCH

RED

GREEN

REGRESSION

REVIEW

SUMMARY

WIKI

COMMIT

会说“不”的门禁

→ doing

→ review

→ done

真实的拒绝，原样留档

full 还是 lite

契约指纹

回看交付过程，而不是翻聊天记录。

学到的东西留下来，连同它的出处。

可追溯的来源谱系

先审核，再复用

克隆一次，链接 Skill，显式调用。

安装 Skill

让 Agent 运行它

回看过程

安装 Skill

让 Agent 运行它

回看过程

CLI 参考

刻意收窄。

常见疑问，直接回答。

让“完成”意味着证据已经落盘。

大需求进，小而可验证的提交出。