spec-init

スキル：spec-init

概要

構造化された対話形式のプロセスを通じて仕様書の作成を支援する、統合スキルです。

次の既存スキルをまとめています。

• context-compressor（要件収集のための段階的開示モード）
• plan-generator（仕様書から計画を作成）

ワークフロー

1. 種別の検出

質問：「何を作成しますか？」

説明から自動検出します。

• 機能：「X の機能を構築する」→ type: feature
• バグ：「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. 計画の提案

仕様書の承認後：

• 「プランナーに計画を作成してもらう準備はできていますか？」と提案
• はいの場合：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：バグ修正

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 に分類します
検証せずに仕様書を生成する	不完全な仕様書がプランナーに渡されます	仕様書を保存する前に、すべての必須セクションを検証します
トラックメタデータがない	下流のエージェントが仕様書を追跡または参照できません	trackId、type、status、created_at の各フィールドを必ず入力します
誤った場所に保存する	他のエージェントが仕様書を見つけられません	標準的な命名規則に従って .claude/context/artifacts/specs/ に必ず保存します

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 問題の発見 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断を想定してください：メモリに記録されていなければ、起きていないのと同じです。