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

Claude Code との協調開発を「アドリブ排除・取りこぼし防止」で構造化する skill bundle

最終更新: 2026-05-01（delta-audit / unification-claim 7 カテゴリ / Stop hook 整備、12 skill ／ 22 pattern ／ 7 カテゴリ完成）

01 設計思想

AI（Claude）との協調開発を続けるうち、構造的に発生するミスが複数回観測されました。 派生 Q の取りこぼし、GROUP 番号の衝突、既存仕様の誤前提、設計書類のスタイル不統一、 コード ↔ 設計書のトレーサビリティ欠落 — いずれも「AI の心がけだけでは保てない」種類のミスです。

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

4 つの設計原則

A. STRUCTURED

アドリブ排除

人間（Claude）の心がけで担保していた手順を tool 経由化し、構造的に強制。 grep + Read を skill 内蔵、Q を 4 列形式で記録、GROUP 番号を採番ツール経由に。

B. REUSABLE

流用可能（config-driven）

プロジェクト固有値はすべて config.yaml に分離、コード本体は不変。 別プロジェクトへ skill bundle ごとコピー＋ config 編集で動作。

C. FAIL-LOUDLY

違反を即検出

linter が必須欠落 / stale / リンク先不在を warning / error で即検出、ユーザー判断を促す。 silent な失敗を作らない。

D. INCREMENTAL

段階導入可能

各 skill 単独で価値、組合せで相乗効果。bundle 全部入れずに 1 つだけ流用も可。 既存プロジェクトへの導入もスムーズ。

02 ツールバンドル全体像

計 12 skill ＋ 22 workflow_pattern 同梱（2026-05-01 / delta-audit 新設 ＋ scan-response 7 カテゴリ拡張 ＋ Stop hook wrapper 整備時点）。各 skill の役割：

仕様駆動コア（Phase 1〜3）

skill 名役割
question-builder a/b/c/d 選択肢付き Q を plan log + Q ログへ二箇所書込（取りこぼし防止）
group-id-allocator 新規 GROUP 番号採番＋衝突検出＋ renumber（番号衝突予防）
plan-snapshot プランログ未完了項目を 4 列形式で抽出＋ stale 候補警告（残タスク提示自動化）
spec-cite 機能名 / 関数名 → grep + Read → file:line 引用ブロック自動生成
spec-linter 設計書類 frontmatter 規約準拠 check（必須欠落 / stale / リンク先存在）

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

skill 名役割
workflow-stamp 応答ヘッダ inline 付与（compose）／ 7 カテゴリ＋ヘッダ存在 gating（scan-response：promise / hypothesis / cleanup / normalcy / unverified-reference / scope-claim / unification-claim、mode で gate / warn / off 切替）／ catalog 全 22 パターン参照（list-patterns、v1.46.3 で #19 skill 仕様報告 / #20 fb 解釈 / #21 違反報告 with 再発防止策同梱、2026-05-01 に #22 双子 UI 改修時 を追加）／ Claude Code Stop hook 用 wrapper stop_hook.py 同梱
error-triage 不具合報告時に 1 ターン目で全レイヤー診断（visual / data / behavior / performance の 4 カテゴリ × 7 レイヤー）
release-flow リリースフロー 4 段階 gate（preflight 6 項目 / pre-tag-check 3 項目 / status / uat-checklist）。Actions 未発火のまま動作確認指示する事故、および移送系リリースの実機確認漏れを予防

トレーサビリティ（Phase 4）

skill 名役割
trace-extractor コード内 @spec <file>#<anchor> tag を抽出し、AUTO_TRACE.md（コード ↔ 設計書の対応表）を自動生成
trace-linter AUTO_TRACE.md と設計書 anchor を突合、broken link（参照先 anchor 不在）/ orphan（参照されていない section）を検出

運用 hardening（Phase 5、2026-04-30 v1.45.5 saveHistory 全消失事案を受けて追加）

skill 名役割
migration-matrix storage key（saveHistory 等）の callsite を 5 経路（read / write / delete / import / export）に分類列挙、aware helper（_readSaveHistory 等）経由でない leak を検出。状態切替（migration）リリース前の preflight で必須。書込側のみ aware 化、import 経路の漏れ → 移送後 import で IDB store.clear()+put により既存全消失する重大事案の再発防止

同 Phase で workflow-stamp に第 6 カテゴリ scope-claim も追加（「全 read 経路を統一」「すべての X を Y」「網羅的に」「漏れなく」等の網羅性主張に grep 根拠の併記を強制）、release-flow に uat-checklist サブコマンドを追加（state switch / migration / UI / IPC 系リリースの実機確認チェックリストを git diff から自動カテゴリ検出）。

双子 UI 整合性（2026-05-01、編集パネル乖離事案の Tier 2 構造的予防）

skill 名役割
delta-audit 双子 UI（機能的に対の UI を別ファイルに 2 重実装する構造）の差異を検出。class prefix ペアから button label / input placeholder / handler 関数名を双方 grep し並列比較、leak 表化。release-flow preflight に組込（git diff で双方変更検知時に自動呼出、leak ≥ 1 件で gate failure）。「編集パネルの bottom-row レイアウトのみ同期、5 項目乖離のまま push」事案の構造的予防

連動して workflow-stamp catalog に pattern #22「双子 UI 改修時」を登録。「modal側もsettings側に合わせろ」「バラバラにするな」等の同期指示を受けた際、改修着手前に delta-audit audit <pair-name> で双方の delta 表を取得 → ユーザー提示 → 確定後実装、の 4 step を強制。

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

workflow-stamp / scan-response / question-builder / migration-matrix を Claude が手動で呼ばないと発動しない設計だったため、忘れた瞬間に違反が応答に混入する弱点があった。これを構造的に塞ぐため、共通 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、出力切詰時のリマインダ見落とし対策）

skill 出力末尾フッタを head -N で切詰めて読み飛ばすと reminder を見落とす経路が判明。共通 helper emit_next_step_top_banner(pattern_num) を新設し、全 12 skill の主要 cmd 冒頭で 1 行 banner を print（「⚠️ 送信前必須: workflow-stamp compose --pattern N + scan-response（詳細はフッタ参照）」）。冒頭 ＋ 末尾の両端で reminder が見られる設計、CLAUDE.md「skill 出力フィルタ禁止」節も併設。

Pattern #19 / #20 / #21（v1.46.3、運用層拡張）

  • #19 skill バンドル仕様の挙動・coverage 報告：spec-cite に --scope skills 追加、skill バンドル自身を grep して coverage 表化、対象外ゼロを強制
  • #20 ユーザー fb 解釈時の意図確認：「〜が逆」「〜消えてる」「〜おかしい」等の状態指摘 fb を受けた時、直前変更との照合最優先 ＋ 一意解釈での実装走行禁止
  • #21 違反行為の報告（自己違反 / 機構不備 / 設計ギャップの自己申告）：再発防止策同梱必須（自己規律のみは無効、Tier 別構造的予防策の提示、plan log / memory への永続化必須）

双子 UI 改修ルール（v1.46.4、CLAUDE.md 節新設）

v1.46.3 で双子 UI（編集パネル）の統一を視覚レイアウト同期だけで完了とみなし、5 項目（保存ラベル / 閉じるラベル / undo button / autosave / save feedback / globalTags merge）が乖離したまま AMO 自動署名 + Release 連鎖発火後に発覚した違反を受けて、CLAUDE.md「双子 UI 改修時」節を新設：spec-cite で双方全件 grep → delta 表をユーザーに提示 → 確定後実装、の 4 step を明文化。Tier 2 = delta-audit skill 新設（2026-05-01 完了）、Tier 3 = scan-response 第 7 カテゴリ「unification-claim」追加（2026-05-01 完了）。

scan-response 第 7 カテゴリ unification-claim（2026-05-01、双子 UI 違反の Tier 3）

応答送信前検査の workflow-stamp scan-response を 6 → 7 カテゴリへ拡張。「両 UI を合わせろ」「双子 UI を統一」「両方統一」「バラバラにするな」「双方への言及」等の双子 UI 統一主張を検出し、近傍（±150 chars）に delta-audit / 双方 grep 根拠（delta-audit / delta_audit / 双方 grep / 両ファイル grep / leak 0 件 / 該当ファイル行引用 等）の併記がない場合 flag。書く前に delta-audit audit <pair-name> で leak 0 を確認し、結果を近傍に書く運用へ強制。Tier 3 構造的予防として実装。

Claude Code Stop hook 連動（2026-05-01、応答送信前検査の手動忘れ対策 Tier 2）

応答送信前 scan-response の手動呼出忘れを構造的に塞ぐため、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 cp932 stdout で emoji（🟢 / 🔴）crash を回避するため UTF-8 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] → 7 カテゴリ＋ヘッダ存在 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 未記録、 コンテキスト圧縮で本文消失して復元不能になった事故（v1.44.0 着手時）。

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

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

起源：v1.45.0 リリース時に GROUP 番号を別の GROUP と衝突させた事故。 Plan log 内では新規を別番号へ renumber、git 履歴側は残置で対応。

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

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

spec-cite：grep + Read 強制

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

起源：保存経路の冗長性監査検討時に当該機能の挙動を grep + Read せず関数名から推測し、Q 選択肢に誤った仕様を書いた事故。

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 で 4 カテゴリ（promise / hypothesis / cleanup / normalcy）＋ヘッダ存在チェック、 検出時 gate（mode で warn / off 切替可能）。

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

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

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

起源：preview blank 報告に対し、サーバ・DOM だけ確認して「正常」と返答を 5 ターン繰り返した事故（viewport 0×0 を見逃し）。

release-flow：リリースフロー 3 段階 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 ＋ ユーザー側動作確認手順

起源：Actions 未発火のまま「動作確認してください」と指示した事故（保存履歴 IDB 移送シリーズの初期段階）。

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

コード内に // @spec 02_詳細設計書.md#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. CLAUDE.md（or 同等の運用ルールファイル）に「skill 経由必須フロー」表を追記
  5. 既存コードに @spec tag を段階追加 → trace-extractor 実行 → trace-linter 検証

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

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

05 採用判断の経緯

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

方針内容評価
A 最小 設計書側に手動でコード位置をリンク（[foo.js:10](path)） 保守コスト高、コード変更追従困難
B section-link 設計書 section に「対応コード」一覧 footer 追加 A の派生、同じ問題
C code-comment コード側にコメントで対応 spec を記載（人間可読） 機械的検証不可、broken link を見逃す
D JSDoc tag 自動生成 コードに @spec tag → 自動 trace 表生成 採用：機械検証可、保守容易
E 双方向 graph 設計書 ↔ コードを GraphViz 等で可視化 過剰、依存増、リターン低

D 採用後、Phase 4-prep（既存 5 skill の config-driven refactor）→ Phase 4a（trace-extractor 実装） → Phase 4b（trace-linter 実装）→ Phase 4c（重要関数 30+ に @spec tag 埋込） → Phase 4d-final（README ＋ 本ページ ＋ 設計書類 13 確定）の段階展開で 2026-04-29 完了。

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. CLAUDE.md のパターン表と「skill 経由必須フロー」表を更新
  6. 動作確認 6+ ケース（happy path / edge / error）でテスト
  7. 第 1 サンプル抽出：実運用 1 回を記録、catalog の note に追記

Python 以外の言語対応

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

IDE プラグイン化候補

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

残課題（弱点として残る共通テーマ）

  • 「私が呼ぶ判断」のアドリブ依存：tool は揃ったが毎回実行する強制機構（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 化（DOM ライフサイクル × global state pool の race 教訓に基づく）
  • 引き継ぎ資料作成の patternize（handover-builder skill 新設、本セッションを第 1 サンプルとして抽出）