仕様駆動開発スキルバンドル

01 設計思想

AI（Claude）との協調開発では、派生 Q の取りこぼし、GROUP 番号の衝突、既存仕様の誤前提、設計書類のスタイル不統一、 コード ↔ 設計書のトレーサビリティ欠落 — いずれも「AI の心がけだけでは保ちにくい」種類の課題があります。

これらを tool 経由化で構造的に排除 するため、Claude Code skill 形式で 作成した汎用ツールキットが本バンドルです。BorgesTag（個人開発の Firefox 拡張）から抽出し、 config.yaml の書換のみで別プロジェクトに流用できる設計を意図しています。

4 つの設計原則

02 ツールバンドル全体像

計 12 skill ＋ 21 workflow_pattern 同梱（送信前検査カテゴリ 33 種）。バンドル本体は「共有コア」として独立し、複数プロジェクトがリンク参照＋プロジェクト別設定の重ね合わせで同一実装を継承する方式へ発展。各 skill の役割：

仕様駆動コア

運用層（応答品質・診断・リリース）

トレーサビリティ

運用 hardening（2026-04-30 追加）

双子 UI 整合性（2026-05-01）

応答送信前必須 step 自動内蔵（v1.46.1）

共通 helper emit_next_step_footer(pattern_num, section_label, skill_used) を _config.py に新設し、5 skill の主要 cmd 末尾でフッタを print（応答送信前必須 3 step：compose / scan-response / 検出補正）。

起動冒頭 banner（v1.46.3）

共通 helper emit_next_step_top_banner(pattern_num) を新設し、全 12 skill の主要 cmd 冒頭で 1 行 banner を print（「⚠️ 送信前必須: workflow-stamp compose --pattern N + scan-response（詳細はフッタ参照）」）。

運用層パターン拡張（v1.46.3）

• #19 skill バンドル仕様の挙動・coverage 報告：spec-cite に --scope skills 追加、skill バンドル自身を grep して coverage 表化、対象外ゼロを強制
• ユーザー フィードバック解釈時の意図確認：直前変更との照合を最優先化
• 課題報告フォーマット：報告構造を定型化、plan log への記録を組込

双子 UI 改修ルール（v1.46.4）

双子 UI 改修時は spec-cite で双方全件 grep → 差分表をユーザーに提示 → 確定後実装、の 4 手順を明文化。

scan-response unification-claim カテゴリ追加（2026-05-01）

応答送信前検査の workflow-stamp scan-response に unification-claim カテゴリを追加。「両 UI を合わせろ」「双子 UI を統一」等の統一主張を検出し、近傍（±150 chars）に delta-audit / 双方 grep 根拠の併記がない場合 flag する。

Claude Code Stop hook 連動（2026-05-01）

Claude Code の Stop event hook を整備。.claude/skills/spec-driven/workflow-stamp/stop_hook.py wrapper を新設、stdin から hook context 受領 → transcript_path から最新 assistant text を抽出 → scan-response 実行 → 検出時に {"decision":"block","reason":"..."} を stdout 出力で再生成促進。.claude/settings.local.json に hooks.Stop[0].matcher="*" で登録、enforcement.mode は config.yaml で warn / gate / off 切替可能。Windows 環境向けに UTF-8 stdout wrapper も同梱。

連携図

ユーザー依頼受領
   ↓
[group-id-allocator next] → 新規番号採番
   ↓
[question-builder issue] → Q を plan log + Q ログへ
   ↓
[spec-cite cite] → 既存仕様の grep + Read 引用
   ↓
（実装フェーズ）
   ↓
[spec-linter validate] → 設計書類 frontmatter 検証
   ↓
[trace-extractor extract] → AUTO_TRACE.md 生成
[trace-linter validate]   → broken link / orphan 検出
   ↓
[plan-snapshot list] → 未完了項目で残タスク提示
   ↓
（リリースフェーズ）
   ↓
[release-flow preflight] → リリース前 6 項目 gate
   ↓ (commit / push)
[release-flow pre-tag-check] → tag push 前 3 項目 gate
   ↓ (tag push → Actions 自動発火)
[release-flow status] → Release / XPI 確認手順

各応答送信前：
[workflow-stamp scan-response] → 33 カテゴリ＋ヘッダ存在 gate
                                  （+ Claude Code Stop hook で自動発動、enforcement.mode で gate/warn/off）
                                  （promise / hypothesis / cleanup / normalcy / unverified-reference / scope-claim）
不具合報告時：
[error-triage triage <cat>] → 全レイヤー診断（1 ターン目で baseline）

state switch / migration リリース時：
[migration-matrix audit <key>]   → 5 経路 callsite の leak 0 件確認
[release-flow uat-checklist]      → 実機確認チェックリスト自動生成
      

03 個別 skill 解説

question-builder：取りこぼし防止

a/b/c/d の選択肢付き Q を発行すると、plan log（プロジェクト統括）と Q ログ（GROUP ごとの YAML バックアップ）の二箇所に同時書込。 prerequisites（既存仕様の引用）が未充足だと warning を出す。

用途：選択肢付き Q を plan log と Q ログの双方に確実に記録する（v1.44.0 で導入）。

group-id-allocator：番号衝突予防

plan log と実装計画書の GROUP-N を全件 grep し、未使用最大 +1 を返す。 さらに既存衝突を検出して renumber も可能。CHANGELOG / commit / tag の番号は immutable のため historical reference として保護する。

用途：GROUP 番号衝突の予防（v1.45.0 で導入）。Plan log 内は新規を別番号へ renumber。

plan-snapshot：残タスク自動抽出

plan log と実装計画書から未完了項目を 4 列形式（グループ／記号／内容／状態）で抽出。 状態列が — / 受領（着手予定） 等のままになっている **stale 候補**を warning。 TodoWrite 整理時に必ず実行し、TodoWrite と plan log の同期を保つ。

spec-cite：grep + Read 強制

機能名 / 関数名を入力すると ripgrep（or Python fallback）で全件検索、 各マッチ位置を file:line 注記付き markdown 引用ブロックで出力。 Q の prerequisites、設計提示の根拠、対策案の関連シンボル網羅で経由必須化。

用途：Q 選択肢や設計提示の根拠を、実コードの grep + Read で裏付ける。

spec-linter：設計書類規約準拠 check

各設計書類（.md）の frontmatter（title / last_updated / status / scope / related_code / related_specs） を検証。必須欠落 / stale 警告（last_updated が 90 日超古い）/ status 値違反を検出。

workflow-stamp：応答書式固定化＋提出物検査

応答セクションに (フローパターン: #N 名称 ／ skill: ... ／ 漏れ: K件 → 🟢/🟡/🔴 ...) の inline ヘッダを付与（compose）。送信前に scan-response で 33 カテゴリ（promise / hypothesis / cleanup / normalcy ほか）＋ヘッダ存在チェック、 検出時 gate（mode で warn / off 切替可能）。

鉄則：応答は「発話」ではなく「成果物（提出物）」。送信前に毎回ツール検査。

error-triage：不具合報告全レイヤー診断

ユーザーから不具合報告を受けた 1 ターン目に triage visual / data / behavior / performance 4 カテゴリのチェックリストを生成。 各カテゴリ × 7 レイヤー（L1 サーバ → L7 体験）で診断、初回 eval / 1 回のコマンドで全件取得を強制。

用途：不具合報告の初回応答で全レイヤーを網羅的に診断し、視認できる要因（例：viewport 0×0）から漏れなく洗い出す。

release-flow：リリースフロー 4 段階 gate

commit / push / tag / Actions / 動作確認の流れを構造化：

• preflight --version X.Y.Z：commit 前 6 項目（manifest / CHANGELOG / plan log / node --check / git status / remote sync）
• pre-tag-check：tag push 直前 3 項目（manifest version 一致 / CHANGELOG entry / main = remote）
• status：tag push 後の Actions / Release URL ＋ ユーザー側動作確認手順

用途：commit / tag push / Actions / 動作確認の各段階を明示的な gate として構造化する。

trace-extractor / trace-linter：コード ↔ 設計書 トレーサビリティ

コード内に // @spec 詳細設計書.md#section-1-2 のような tag を埋め込むと、 trace-extractor extract で全件抽出 → AUTO_TRACE.md に対応表自動生成。 trace-linter validate で設計書 anchor との突合、broken link（参照先 anchor 不在）と orphan（誰からも参照されていない section）を検出。

BorgesTag では現在 31 件の @spec tag を主要関数に埋め込み、broken link 0 件で運用中（2026-04-29 時点）。

04 別プロジェクトへの流用手順

本バンドルは config-driven 設計のため、config.yaml の書換のみで別プロジェクトに移植可能。

1. .claude/skills/spec-driven/ ディレクトリを丸ごとコピー
2. config.yaml の以下を新プロジェクトの値に書換：
   • project.root：config.yaml からプロジェクトルートへの相対 path
   • design.dir：設計書類フォルダ名
   • design.required_frontmatter：自プロジェクトの規約に合わせる
   • planning.plan_log / planning.impl_plan：プランログのパス
   • source.scopes：ソースコードのパス（複数可）
   • trace.tag_patterns：コード言語別 @spec tag regex
   • enforcement.mode：scan-response gating（gate / warn / off）
   • enforcement.bypass_patterns：例外パターン（pure-ack 等）
   • workflow_patterns：catalog をプロジェクト固有に編集
3. 動作確認：spec-linter validate / plan-snapshot list / workflow-stamp list-patterns
4. 既存コードに @spec tag を順次追加 → trace-extractor 実行 → trace-linter 検証

詳細は README.md（流用手順マニュアル、本バンドルに同梱）参照。

依存関係：Python 3.7+、PyYAML、ripgrep（任意、なければ Python fallback）。外部 SaaS 依存なし、完全ローカル動作。

05 採用判断の経緯

トレーサビリティ実現で 5 方針を評価：

06 拡張可能性・将来展望

新 skill 追加時の作法

1. .claude/skills/spec-driven/<新 skill 名>/ ディレクトリ作成
2. SKILL.md（frontmatter ＋ 目的 ＋ when_to_use ＋ 使い方）を既存 skill 構造に揃えて作成
3. <新 skill 名>.py で _config から共通設定読込
4. config.yaml の workflow_patterns に対応パターン追加（番号は既存最大 +1）
5. 動作確認 6+ ケース（happy path / edge / error）でテスト

Python 以外の言語対応

現状の skill は全て Python 実装。Node.js / Rust / Go 版への移植は config.yaml の構造をそのまま流用すれば可能だが、 現状未実装（Python の標準ライブラリ ＋ ripgrep があれば十分なため）。

IDE プラグイン化候補

VS Code / Cursor 等で @spec tag を hover 時にプレビュー、broken link を即時 underline、 などの拡張は将来検討。現状は CLI ベースで Claude Code から直接呼び出す運用。

残課題（共通テーマ）

• skill 呼出の自動化：毎回実行する強制機構（hooks / harness レベル enforcement / skill auto-trigger）が未整備
• compose 自動呼出統合：他 skill から workflow-stamp compose を内部呼出する設計、未着手
• scan-promises ↔ TodoWrite 自動連携：promise 抽出を TodoWrite に自動 push する仕組みなし
• CHANGELOG / git 履歴 ↔ plan log 状態列の自動 cross-ref：plan-snapshot audit は stale 検出のみ、完了済か未着手かは手動判定

派生提案

• 新規 global state（pool / cache / Map）導入時の交点走査 pattern 化
• 引き継ぎ資料作成の patternize（handover-builder skill）