sparv

SPARV

五阶段工作流：Specify（明确需求）→ Plan（规划）→ Act（执行）→ Review（审查）→ Vault（归档）。

目标：一次完成“需求 → 可验证的交付”，将关键决策记录在外部记忆中，而不是依赖假设。

核心规则（强制）

• 10 分制明确需求门槛：规格评分为 0-10；必须达到 >=9 才能进入 Plan。
• 每 2 次操作保存一次：每调用工具 2 次，就向 .sparv/journal.md 追加一条记录。
• 3 次失败协议：连续失败 3 次后停止并上报用户。
• EHRB：检测到高风险（生产环境/敏感数据/破坏性操作/计费 API/安全关键事项）时，必须获得用户明确确认。
• 固定阶段名称：specify|plan|act|review|vault（存储在 .sparv/state.yaml:current_phase）。

增强规则（v1.1）

不确定性声明（G3）

当任何一项明确需求维度的评分 < 2 时：

• 声明：UNCERTAIN: <what> | ASSUMPTION: <fallback>
• 在进入 Plan 前，将所有假设列入日志
• 针对不明确的需求提供 2-3 个选项

示例：

UNCERTAIN: deployment target | ASSUMPTION: Docker container
UNCERTAIN: auth method | OPTIONS: JWT / OAuth2 / Session

需求分流

模式	条件	流程
Quick	评分 >= 9 且涉及文件 <= 3 个，且无 EHRB	Specify → Act → Review
Full	其他情况	Specify → Plan → Act → Review → Vault

Quick 模式跳过正式的 Plan 阶段，但仍需：

• 将完成承诺写入日志
• 遵守每 2 次操作保存一次的规则
• 必须执行 Review 阶段

上下文获取（可选）

在进行 Specify 评分前：

1. 检查 .sparv/kb.md 中是否有现成的模式/决策
2. 如果信息不足，扫描代码库中的相关文件
3. 在日志的 ## Context 下记录发现

如果用户明确提供了完整上下文，则跳过。

知识库维护

在 Vault 阶段，更新 .sparv/kb.md：

• 模式：发现的可复用代码模式
• 决策：架构选择及其理由
• 注意事项：常见陷阱及解决方案

更新 CHANGELOG

对非简单变更，在 Review 或 Vault 阶段使用：

~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."

外部记忆（两个文件）

初始化（在项目根目录运行）：

~/.claude/skills/sparv/scripts/init-session.sh --force

文件约定：

• .sparv/state.yaml：状态机（最少字段：session_id/current_phase/action_count/consecutive_failures）
• .sparv/journal.md：统一日志（计划/进度/发现都记录在这里）
• .sparv/history/<session_id>/：归档目录

阶段 1：Specify（10 分制）

每项得分为 0/1/2，总分 0-10：

1. 价值：为什么要做，收益/指标是否可验证
2. 范围：MVP 及不在范围内的内容
3. 验收：可测试的验收标准
4. 边界：错误/性能/兼容性/安全方面的关键边界
5. 风险：EHRB/依赖项/未知因素及处理方式

score < 9：继续提问；不要进入 Plan。 score >= 9：写下明确的 completion_promise（可验证的完成承诺），然后进入 Plan。

阶段 2：Plan

• 将工作拆解为原子任务（每项耗时 2-5 分钟），每项都应有可验证的输出/测试点。
• 将计划写入 .sparv/journal.md（Plan 部分或直接追加）。

阶段 3：Act

• TDD 规则：没有失败的测试，就不写生产代码。
• 每 2 次操作自动写入日志（PostToolUse hook）。
• 失败计数（3 次失败协议）：

~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short blocker"
~/.claude/skills/sparv/scripts/failure-tracker.sh reset

阶段 4：Review

• 两阶段审查：规格符合性 → 代码质量（正确性/性能/安全性/测试）。
• 最多进行 3 轮修复；超出后上报用户。

会话结束前运行 3 问题重启测试：

~/.claude/skills/sparv/scripts/reboot-test.sh --strict

阶段 5：Vault

归档当前会话：

~/.claude/skills/sparv/scripts/archive-session.sh

脚本工具

脚本	用途
scripts/init-session.sh	初始化 .sparv/，生成 state.yaml + journal.md
scripts/save-progress.sh	维护 action_count，每 2 次操作向 journal.md 追加内容
scripts/check-ehrb.sh	扫描差异/文本，输出（可选写入）ehrb_flags
scripts/failure-tracker.sh	维护 consecutive_failures，达到 3 次时返回退出代码 3
scripts/reboot-test.sh	3 个问题的自检（可选严格模式）
scripts/archive-session.sh	将 journal.md + state.yaml 归档到 history/

自动钩子

hooks/hooks.json：

• PostToolUse：save-progress.sh（每 2 次操作保存）
• PreToolUse：check-ehrb.sh --diff --dry-run（仅提示词，不写入状态）
• Stop：reboot-test.sh --strict（3 个问题的自检）

---

质量胜于速度——不断迭代，直到真正完成。