spec-init

技能：spec-init

概述

通过结构化的交互流程指导创建规格说明的统一技能。

封装以下现有技能：

• context-compressor（用于需求收集的渐进式披露模式）
• plan-generator（根据规格说明生成计划）

工作流

1. 类型检测

问题：“你要构建什么？”

根据描述自动检测：

• 功能：“构建 X 功能” → type: feature
• Bug：“修复 X 问题” → type: bug
• 杂项：“更新 X 组件” → type: chore
• 重构：“重新组织 X” → type: refactor
• 文档：“编写 X 文档” → type: docs

2. 渐进式披露 v2（自适应，5-7 个问题）

使用自适应算法调用 context-compressor（渐进式披露模式）：

const { AdaptiveQuestioner } = require('.claude/lib/utils/adaptive-discloser.cjs');
const { ContextAccumulator } = require('.claude/lib/utils/context-accumulator.cjs');

// Determine domain from detected type
const domainMap = {
  feature: 'general',
  bug: 'debugging',
  chore: 'general',
  refactor: 'architecture',
  docs: 'documentation',
};
const domain = domainMap[detectedType] || 'general';

const aq = new AdaptiveQuestioner(domain);
const ca = new ContextAccumulator();

let history = [];
let questionCount = 0;

while (questionCount < 7) {
  const context = ca.getContext();
  const result = await aq.getNextQuestion(context, history);

  // Check if we should stop early
  const readiness = await aq.detectOptimalStop(history, context);
  if (readiness.shouldStop) {
    break;
  }

  // Ask the question
  const answer = await AskUserQuestion({ question: result.question });

  // Store answer with metadata
  ca.addAnswer(result.question, answer, { domain, priority: 'HIGH' });
  history.push({ question: result.question, answer });

  questionCount++;
}

// Summary from accumulated context
const summary = ca.buildSummary();

相较于 v1 的主要改进：

• 自适应提问（跳过重复问题）
• 感知上下文（从答案中学习）
• 集成记忆（利用 learnings.md）
• 最优停止（通常为 5-7 个问题，从 10-12 个减少）
• 质量评分（检测是否已准备好生成规格说明）

3. 规格说明模板生成

根据答案自动填充规格说明：

# SPEC: [Feature Name]

## 1. Overview

**Title**: [From question 1]
**Type**: [Detected type]
**Objective**: [User summary]

**User Story**: As a [user type], I want [capability], so that [benefit]

**Acceptance Criteria**: [From question 5]

## 2. Problem Statement

- **Current State**: [From question 1 answers]
- **Pain Points**: [Extracted from answers]
- **Impact**: [Quantified if possible]

## 3. Proposed Solution

- **Approach**: [From user input]
- **Key Features**: [From answers]
- **Scope**: [What's in/out]

## 4. Implementation Approach

- **Phase 1**: [Design/spike if needed]
- **Phase 2**: [Core implementation]
- **Phase 3**: [Testing]
- **Phase 4**: [Documentation]

## 5. Success Metrics

- **Quantitative**: [From question 3]
- **Qualitative**: [User satisfaction]
- **Timeline**: [From question 4]

## 6. Effort Estimate

- **Design**: 1 day
- **Implementation**: 3 days
- **Testing**: 2 days
- **Documentation**: 1 day
- **Total**: 7 days

## 7. Dependencies

- **Required**: [Extracted from context]
- **Blocking**: [What must complete first]
- **Risk**: [Key risks identified]

## 8. Acceptance Criteria Checklist

- [ ] Feature implemented per spec
- [ ] All tests passing
- [ ] Documentation updated
- [ ] No breaking changes
- [ ] Performance targets met

4. 验证

根据架构验证规格说明：

• 在行内验证规格说明是否完整
• 检查：是否包含所有必需章节
• 检查：是否至少有 3 条验收标准
• 检查：工作量估算是否以天为单位

5. 计划建议

规格说明获批后：

• 建议：“准备好让 planner 创建计划了吗？”
• 如果是：显示 Skill({ skill: "plan-generator", args: { specPath: "..." } })
• 如果否：允许编辑规格说明

6. 存储

将规格说明保存到：

.claude/context/artifacts/specs/[feature-name]-spec-YYYYMMDD.md

跟踪元数据：

• trackId：自动生成
• type：检测所得
• status："new"
• created_at：时间戳

使用示例

示例 1：快速开发功能

User: "I want to add dark mode to the UI"

spec-init workflow:
1. Detect: type = "feature"
2. Ask: 5 questions about dark mode
3. User answers in <5 minutes
4. Generate spec
5. Validate against schema
6. Store and offer plan generation

示例 2：修复 Bug

User: "There's a memory leak in the scheduler"

spec-init workflow:
1. Detect: type = "bug"
2. Ask: 5 questions (reproduce steps, impact, etc)
3. Generate bug fix spec
4. Suggest acceptance criteria
5. Ready for planner

输出

• 生成的规格说明 Markdown（已保存）
• 跟踪元数据 JSON
• 计划生成建议
• 后续步骤指导

集成点

• context-compressor（用于需求收集的渐进式披露模式）
• plan-generator（后续步骤）
• track-metadata 架构（元数据）

铁律

1. 绝不提出超过 7 个澄清问题——判断最优停止时机并生成规格说明
2. 始终在提问前检测意图类型（feature/bug/chore/refactor/docs）
3. 绝不在未验证所有必需章节均已填写的情况下生成规格说明
4. 始终按照正确的命名规范，将规格说明保存到 .claude/context/artifacts/specs/
5. 绝不跳过跟踪元数据——每份规格说明都必须包含 trackId、type、status 和 created_at

反模式

反模式	失败原因	正确做法
固定提出 10-12 个问题	过度提问会降低用户参与度	使用渐进式披露；上下文充分时，在提出 5-7 个问题后停止
跳过意图类型检测	问题无法根据任务类型调整	始终先将请求分类为 feature/bug/chore/refactor/docs
未经验证便生成规格说明	不完整的规格说明会交给 planner	保存规格说明前，验证所有必需章节
缺少跟踪元数据	下游 Agent 无法跟踪或引用规格说明	始终填充 trackId、type、status 和 created_at 字段
保存到错误位置	其他 Agent 无法发现规格说明	始终按照标准命名，将规格说明保存到 .claude/context/artifacts/specs/

Memory Protocol（必须遵守）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现的问题 -> .claude/context/memory/issues.md
• 做出的决定 -> .claude/context/memory/decisions.md

假设工作会被中断：如果未记录在记忆中，就等于从未发生。