spec-runner 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-runner",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "docs を正本にした開発運用ハーネスを Claude / Copilot に導入する",
   "license": "MIT",
   "bin": {

package/spec-runner/templates/.claude/rules/design-docs.md

@@ -69,7 +69,8 @@ spec_runner:
 | `{対象}` の選択肢 | `全体` / `ドメイン` / `UC` / `DB` | — |
 | `docs/バックエンド/03_詳細設計/01_ドメイン`（style: ddd のみ） | 日本語 | `注文.md`, `在庫.md` |
 | `docs/バックエンド/03_詳細設計/02_ユースケース`（style: ddd） / `01_ユースケース`（style: layered） | `UC-{日本語名}.md` | `UC-注文確定.md` |
-| `docs/バックエンド/03_詳細設計/03_DB・外部サービス`（style: ddd） / `02_DB・外部サービス`（style: layered） | 日本語 | `スキーマ定義.dbml`, `外部サービス.md` |
+| `docs/バックエンド/03_詳細設計/03_DB・外部サービス`（style: ddd） / `02_DB・外部サービス`（style: layered） | 日本語 | `スキーマ定義.dbml`, `AWS/S3.md`, `GCP/BigQuery.md` |
+| `docs/バックエンド/04_調査資料/{カテゴリ名}/` | 日本語 | `AWS/DynamoDB-キー設計.md`, `設計パターン/CQRS.md` |
 
 ### フロントエンド（has_frontend: true のみ）
 

package/spec-runner/templates/.claude/skills/ddd-seed/SKILL.md

@@ -23,8 +23,9 @@ description: UC/DDD 駆動の docs 正本開発フローの種（バックエン
 Phase 1: 要件定義
 Phase 2: 概要設計（ユースケース + ドメインモデル）
 Phase 3: ADR（必要時のみ）
-Phase 4: 詳細設計（ドメイン → UC → DB・外部サービス）
-Phase 5: TDD → 実装
+Phase 4: ベストプラクティス調査（必要時のみ）
+Phase 5: 詳細設計（ドメイン → UC → DB・外部サービス）
+Phase 6: TDD → 実装
 ```
 
 ## 前提ルール
@@ -73,6 +74,8 @@ docs/バックエンド/02_概要設計/
 
 ## Phase 3: ADR（必要時のみ）
 
+ADR テンプレート: `templates/90_ADR/ADRテンプレート.md`
+
 1. 設計判断が必要な場合だけ ADR を作る
 2. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
@@ -86,11 +89,31 @@ docs/バックエンド/02_概要設計/
 
 4. 採用案を概要設計へ反映してから次へ進む
 
-## Phase 4: 詳細設計
+## Phase 4: ベストプラクティス調査（必要時のみ）
+
+ADR で使用サービス・技術が確定した後、詳細設計に入る前に実施する。
+
+1. 「詳細設計に先立ち、ベストプラクティスを調査すべき技術・サービスはありますか？」とユーザーに確認する
+2. 調査する技術・サービスの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+テンプレート: `templates/04_調査資料/{カテゴリ名}/{トピック名}.md`
+
+```
+docs/バックエンド/04_調査資料/
+  {カテゴリ名}/          # 例: AWS/, GCP/, 設計パターン/
+    {トピック名}.md      # 例: DynamoDB-キー設計.md, S3-アクセス制御.md
+```
+
+- 1 調査テーマ = 1 ファイル（複数テーマは別ファイルに分ける）
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 5: 詳細設計
 
 ドメイン → UC → DB・外部サービス の順に設計する。
 
-### 4-1. ドメイン
+### 5-1. ドメイン
 
 テンプレート: `templates/03_詳細設計/01_ドメイン/{ドメイン名}.md`
 
@@ -99,7 +122,7 @@ docs/バックエンド/03_詳細設計/01_ドメイン/
   {ドメイン名}.md
 ```
 
-### 4-2. ユースケース
+### 5-2. ユースケース
 
 シーケンス図は UC ファイルに Mermaid で埋め込む。
 
@@ -110,16 +133,20 @@ docs/バックエンド/03_詳細設計/02_ユースケース/
   UC-{日本語名}.md
 ```
 
-### 4-3. DB・外部サービス（必要時のみ）
+### 5-3. DB・外部サービス（必要時のみ）
 
 ```
 docs/バックエンド/03_詳細設計/03_DB・外部サービス/
   スキーマ定義.dbml
-  外部サービス.md
+  {プロバイダー名}/      # 例: AWS/, GCP/, Azure/
+    {サービス名}.md      # 例: S3.md, DynamoDB.md, Athena.md
 ```
 
+- 外部サービスはクラウドプロバイダー（AWS / GCP / Azure など）をカテゴリフォルダとし、中にサービス名の md を置く
+- `外部サービス.md` のような汎用名は使わない
+
 4. ユーザーに確認・承認を得る
 
-## Phase 5: TDD → 実装
+## Phase 6: TDD → 実装
 
 `test-driven-development` スキルへ移行する。

package/spec-runner/templates/.claude/skills/ddd-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/03_DB/343/203/273/345/244/226/351/203/250/343/202/265/343/203/274/343/203/223/343/202/271/{/343/203/227/343/203/255/343/203/220/343/202/244/343/203/200/343/203/274/345/220/215}/{/343/202/265/343/203/274/343/203/223/343/202/271/345/220/215}.md

@@ -0,0 +1,24 @@
+---
+spec_runner:
+  type: external-service
+  provider: {プロバイダー名}
+  service: {サービス名}
+  maps_to: ""
+  depends_on: []
+---
+
+# {サービス名}
+
+## 用途・役割
+
+## 設定・接続情報
+
+| 項目 | 値 |
+|------|-----|
+|  |  |
+
+## データ構造・スキーマ
+
+## アクセス制御・権限
+
+## 注意事項

package/spec-runner/templates/.claude/skills/ddd-seed/templates/04_/350/252/277/346/237/273/350/263/207/346/226/231/{/343/202/253/343/203/206/343/202/264/343/203/252/345/220/215}/{/343/203/210/343/203/224/343/203/203/343/202/257/345/220/215}.md

@@ -0,0 +1,20 @@
+---
+spec_runner:
+  type: research
+  topic: {トピック名}
+  category: {カテゴリ名}
+  searched_at: YYYY-MM-DD
+  sources:
+    - title: ""
+      url: ""
+---
+
+# {トピック名}
+
+## 調査目的
+
+## ベストプラクティス
+
+## 注意点・落とし穴
+
+## 本プロジェクトへの適用方針

package/spec-runner/templates/.claude/skills/ddd-seed/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,48 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+---
+
+# {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/02_概要設計/{対象文書}.md`
+- `docs/03_詳細設計/src/{対象パス}.md`

package/spec-runner/templates/.claude/skills/design-change/SKILL.md

@@ -28,8 +28,9 @@ Phase 1: 変更要求の整理と軽い影響調査
 Phase 2: ADR 作成（必要時）
 Phase 3: 影響ドキュメントの確定
 Phase 4: 概要設計の修正
-Phase 5: 詳細設計の修正
-Phase 6: TDD → 実装 → 検証
+Phase 5: ベストプラクティス調査（必要時）
+Phase 6: 詳細設計の修正
+Phase 7: TDD → 実装 → 検証
 ```
 
 ## Phase 1: 変更要求の整理と軽い影響調査
@@ -90,7 +91,24 @@ Phase 6: TDD → 実装 → 検証
 
 修正完了ごとにチェックリストを更新する。全概要設計の修正完了後、ユーザーに確認・承認を得る。
 
-## Phase 5: 詳細設計の修正
+## Phase 5: ベストプラクティス調査（必要時）
+
+概要設計の修正が承認された後、詳細設計の修正に入る前に実施する。
+
+1. 「詳細設計の修正に先立ち、ベストプラクティスを調査すべき技術・サービスはありますか？」とユーザーに確認する
+2. 調査する技術・サービスの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+```
+docs/バックエンド/04_調査資料/
+  {カテゴリ名}/          # 例: AWS/, GCP/, 設計パターン/
+    {トピック名}.md
+```
+
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 6: 詳細設計の修正
 
 ### バックエンド
 
@@ -112,6 +130,6 @@ Phase 6: TDD → 実装 → 検証
 
 ヘッダーの `depends_on` / `maps_to` を更新する。ユーザーに最終確認を得る。
 
-## Phase 6: TDD → 実装 → 検証
+## Phase 7: TDD → 実装 → 検証
 
 設計書修正が承認されたら `test-driven-development` スキルへ移行する。

package/spec-runner/templates/.claude/skills/design-change/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -8,7 +8,6 @@ spec_runner:
 
 **ステータス**: 提案 / 採用 / 廃止 / 置換
 **日付**: YYYY-MM-DD
-**決定者**: {名前}
 
 ## コンテキスト
 

package/spec-runner/templates/.claude/skills/frontend-seed/SKILL.md

@@ -22,8 +22,9 @@ description: フロントエンド向け docs 正本開発フローの種。画
 Phase 1: 要件定義
 Phase 2: 概要設計（画面一覧 + 画面遷移図 + コンポーネント一覧）
 Phase 3: ADR（必要時のみ）
-Phase 4: 詳細設計（画面 → コンポーネント）
-Phase 5: TDD → 実装
+Phase 4: ベストプラクティス調査（必要時のみ）
+Phase 5: 詳細設計（画面 → コンポーネント）
+Phase 6: TDD → 実装
 ```
 
 ## 前提ルール
@@ -81,17 +82,39 @@ docs/フロントエンド/02_概要設計/
 
 ## Phase 3: ADR（必要時のみ）
 
+ADR テンプレート: `templates/90_ADR/ADRテンプレート.md`
+
 1. 設計判断が必要な場合だけ ADR を作る
 2. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は `90_ADR/`
 
 4. 採用案を概要設計へ反映してから次へ進む
 
-## Phase 4: 詳細設計
+## Phase 4: ベストプラクティス調査（必要時のみ）
+
+ADR で使用フレームワーク・ライブラリが確定した後、詳細設計に入る前に実施する。
+
+1. 「詳細設計に先立ち、ベストプラクティスを調査すべき技術・ライブラリはありますか？」とユーザーに確認する
+2. 調査する技術・ライブラリの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+テンプレート: `templates/04_調査資料/{カテゴリ名}/{トピック名}.md`
+
+```
+docs/フロントエンド/04_調査資料/
+  {カテゴリ名}/          # 例: React/, アクセシビリティ/, 設計パターン/
+    {トピック名}.md
+```
+
+- 1 調査テーマ = 1 ファイル（複数テーマは別ファイルに分ける）
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 5: 詳細設計
 
 画面 → コンポーネント の順に設計する。
 
-### 4-1. 画面
+### 5-1. 画面
 
 カテゴリ（機能ドメイン）でディレクトリを切り、画面ごとに 1 ファイル作成する。
 
@@ -103,7 +126,7 @@ docs/フロントエンド/03_詳細設計/01_画面/
     {画面名}.md
 ```
 
-### 4-2. コンポーネント
+### 5-2. コンポーネント
 
 概要設計のコンポーネント一覧をもとに、共通コンポーネントごとに 1 ファイル作成する。
 
@@ -116,6 +139,6 @@ docs/フロントエンド/03_詳細設計/02_コンポーネント/
 
 ユーザーに確認・承認を得る。
 
-## Phase 5: TDD → 実装
+## Phase 6: TDD → 実装
 
 `test-driven-development` スキルへ移行する。

package/spec-runner/templates/.claude/skills/frontend-seed/templates/04_/350/252/277/346/237/273/350/263/207/346/226/231/{/343/202/253/343/203/206/343/202/264/343/203/252/345/220/215}/{/343/203/210/343/203/224/343/203/203/343/202/257/345/220/215}.md

@@ -0,0 +1,20 @@
+---
+spec_runner:
+  type: research
+  topic: {トピック名}
+  category: {カテゴリ名}
+  searched_at: YYYY-MM-DD
+  sources:
+    - title: ""
+      url: ""
+---
+
+# {トピック名}
+
+## 調査目的
+
+## ベストプラクティス
+
+## 注意点・落とし穴
+
+## 本プロジェクトへの適用方針

package/spec-runner/templates/.claude/skills/frontend-seed/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,48 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+---
+
+# {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/フロントエンド/02_概要設計/{対象文書}.md`
+- `docs/フロントエンド/03_詳細設計/{対象パス}.md`

package/spec-runner/templates/.claude/skills/simple-seed/SKILL.md

@@ -23,8 +23,9 @@ description: レイヤードアーキテクチャ / CRUD 中心のプロジェ
 Phase 1: 要件定義
 Phase 2: 概要設計（ユースケース + システム全体俯瞰）
 Phase 3: ADR（必要時のみ）
-Phase 4: 詳細設計（UC → DB・外部サービス）
-Phase 5: TDD → 実装
+Phase 4: ベストプラクティス調査（必要時のみ）
+Phase 5: 詳細設計（UC → DB・外部サービス）
+Phase 6: TDD → 実装
 ```
 
 ## 前提ルール
@@ -63,6 +64,8 @@ docs/バックエンド/02_概要設計/
 
 ## Phase 3: ADR（必要時のみ）
 
+ADR テンプレート: `templates/90_ADR/ADRテンプレート.md`
+
 1. 設計判断が必要な場合だけ ADR を作る
 2. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
@@ -75,11 +78,31 @@ docs/バックエンド/02_概要設計/
 
 4. 採用案を概要設計へ反映してから次へ進む
 
-## Phase 4: 詳細設計
+## Phase 4: ベストプラクティス調査（必要時のみ）
+
+ADR で使用サービス・技術が確定した後、詳細設計に入る前に実施する。
+
+1. 「詳細設計に先立ち、ベストプラクティスを調査すべき技術・サービスはありますか？」とユーザーに確認する
+2. 調査する技術・サービスの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+テンプレート: `templates/04_調査資料/{カテゴリ名}/{トピック名}.md`
+
+```
+docs/バックエンド/04_調査資料/
+  {カテゴリ名}/          # 例: AWS/, GCP/, 設計パターン/
+    {トピック名}.md      # 例: DynamoDB-キー設計.md, S3-アクセス制御.md
+```
+
+- 1 調査テーマ = 1 ファイル（複数テーマは別ファイルに分ける）
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 5: 詳細設計
 
 UC → DB・外部サービス の順に設計する。
 
-### 4-1. ユースケース
+### 5-1. ユースケース
 
 テンプレート: `templates/03_詳細設計/01_ユースケース/UC-{日本語名}.md`
 
@@ -88,17 +111,21 @@ docs/バックエンド/03_詳細設計/01_ユースケース/
   UC-{日本語名}.md
 ```
 
-### 4-2. DB・外部サービス（必要時のみ）
+### 5-2. DB・外部サービス（必要時のみ）
 
 ```
 docs/バックエンド/03_詳細設計/02_DB・外部サービス/
   スキーマ定義.dbml
-  外部サービス.md
+  {プロバイダー名}/      # 例: AWS/, GCP/, Azure/
+    {サービス名}.md      # 例: S3.md, DynamoDB.md, Athena.md
 ```
 
+- 外部サービスはクラウドプロバイダー（AWS / GCP / Azure など）をカテゴリフォルダとし、中にサービス名の md を置く
+- `外部サービス.md` のような汎用名は使わない
+
 3. ユーザーに確認・承認を得る
 
-## Phase 5: TDD → 実装
+## Phase 6: TDD → 実装
 
 `test-driven-development` スキルへ移行する。
 

package/spec-runner/templates/.claude/skills/simple-seed/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//350/246/201/344/273/266/345/256/232/347/276/251.md

@@ -0,0 +1,34 @@
+---
+spec_runner:
+  node_id: requirement.要件定義
+  kind: requirement
+  depends_on: []
+  maps_to:
+    - docs/バックエンド/02_概要設計/
+---
+
+# 要件定義
+
+## 解決すべき課題・提供価値
+
+- {課題}
+- {提供価値}
+
+## 対象ユーザー
+
+- {ユーザー種別}: {説明}
+
+## 非機能要件
+
+| 項目 | 内容 |
+|------|------|
+| {パフォーマンス} | {要件} |
+| {セキュリティ} | {要件} |
+
+## スコープ外
+
+- {スコープ外の機能・要件}
+
+## 技術・ビジネス制約
+
+- {制約}

package/spec-runner/templates/.claude/skills/simple-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_DB/343/203/273/345/244/226/351/203/250/343/202/265/343/203/274/343/203/223/343/202/271/{/343/203/227/343/203/255/343/203/220/343/202/244/343/203/200/343/203/274/345/220/215}/{/343/202/265/343/203/274/343/203/223/343/202/271/345/220/215}.md

@@ -0,0 +1,24 @@
+---
+spec_runner:
+  type: external-service
+  provider: {プロバイダー名}
+  service: {サービス名}
+  maps_to: ""
+  depends_on: []
+---
+
+# {サービス名}
+
+## 用途・役割
+
+## 設定・接続情報
+
+| 項目 | 値 |
+|------|-----|
+|  |  |
+
+## データ構造・スキーマ
+
+## アクセス制御・権限
+
+## 注意事項

package/spec-runner/templates/.claude/skills/simple-seed/templates/04_/350/252/277/346/237/273/350/263/207/346/226/231/{/343/202/253/343/203/206/343/202/264/343/203/252/345/220/215}/{/343/203/210/343/203/224/343/203/203/343/202/257/345/220/215}.md

@@ -0,0 +1,20 @@
+---
+spec_runner:
+  type: research
+  topic: {トピック名}
+  category: {カテゴリ名}
+  searched_at: YYYY-MM-DD
+  sources:
+    - title: ""
+      url: ""
+---
+
+# {トピック名}
+
+## 調査目的
+
+## ベストプラクティス
+
+## 注意点・落とし穴
+
+## 本プロジェクトへの適用方針

package/spec-runner/templates/.claude/skills/simple-seed/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,48 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+---
+
+# {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/02_概要設計/{対象文書}.md`
+- `docs/03_詳細設計/src/{対象パス}.md`

package/spec-runner/templates/.github/instructions/design-docs.instructions.md

@@ -68,7 +68,8 @@ spec_runner:
 | `{対象}` の選択肢 | `全体` / `ドメイン` / `UC` / `DB` | — |
 | `docs/バックエンド/03_詳細設計/01_ドメイン`（style: ddd のみ） | 日本語 | `注文.md`, `在庫.md` |
 | `docs/バックエンド/03_詳細設計/02_ユースケース`（style: ddd） / `01_ユースケース`（style: layered） | `UC-{日本語名}.md` | `UC-注文確定.md` |
-| `docs/バックエンド/03_詳細設計/03_DB・外部サービス`（style: ddd） / `02_DB・外部サービス`（style: layered） | 日本語 | `スキーマ定義.dbml`, `外部サービス.md` |
+| `docs/バックエンド/03_詳細設計/03_DB・外部サービス`（style: ddd） / `02_DB・外部サービス`（style: layered） | 日本語 | `スキーマ定義.dbml`, `AWS/S3.md`, `GCP/BigQuery.md` |
+| `docs/バックエンド/04_調査資料/{カテゴリ名}/` | 日本語 | `AWS/DynamoDB-キー設計.md`, `設計パターン/CQRS.md` |
 
 ### フロントエンド（has_frontend: true のみ）
 

package/spec-runner/templates/.github/skills/ddd-seed/SKILL.md

@@ -23,8 +23,9 @@ description: UC/DDD 駆動の docs 正本開発フローの種（バックエン
 Phase 1: 要件定義
 Phase 2: 概要設計（ユースケース + ドメインモデル）
 Phase 3: ADR（必要時のみ）
-Phase 4: 詳細設計（ドメイン → UC → DB・外部サービス）
-Phase 5: TDD → 実装
+Phase 4: ベストプラクティス調査（必要時のみ）
+Phase 5: 詳細設計（ドメイン → UC → DB・外部サービス）
+Phase 6: TDD → 実装
 ```
 
 ## 前提ルール
@@ -73,6 +74,8 @@ docs/バックエンド/02_概要設計/
 
 ## Phase 3: ADR（必要時のみ）
 
+ADR テンプレート: `templates/90_ADR/ADRテンプレート.md`
+
 1. 設計判断が必要な場合だけ ADR を作る
 2. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
@@ -86,11 +89,31 @@ docs/バックエンド/02_概要設計/
 
 4. 採用案を概要設計へ反映してから次へ進む
 
-## Phase 4: 詳細設計
+## Phase 4: ベストプラクティス調査（必要時のみ）
+
+ADR で使用サービス・技術が確定した後、詳細設計に入る前に実施する。
+
+1. 「詳細設計に先立ち、ベストプラクティスを調査すべき技術・サービスはありますか？」とユーザーに確認する
+2. 調査する技術・サービスの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+テンプレート: `templates/04_調査資料/{カテゴリ名}/{トピック名}.md`
+
+```
+docs/バックエンド/04_調査資料/
+  {カテゴリ名}/          # 例: AWS/, GCP/, 設計パターン/
+    {トピック名}.md      # 例: DynamoDB-キー設計.md, S3-アクセス制御.md
+```
+
+- 1 調査テーマ = 1 ファイル（複数テーマは別ファイルに分ける）
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 5: 詳細設計
 
 ドメイン → UC → DB・外部サービス の順に設計する。
 
-### 4-1. ドメイン
+### 5-1. ドメイン
 
 テンプレート: `templates/03_詳細設計/01_ドメイン/{ドメイン名}.md`
 
@@ -99,7 +122,7 @@ docs/バックエンド/03_詳細設計/01_ドメイン/
   {ドメイン名}.md
 ```
 
-### 4-2. ユースケース
+### 5-2. ユースケース
 
 シーケンス図は UC ファイルに Mermaid で埋め込む。
 
@@ -110,16 +133,20 @@ docs/バックエンド/03_詳細設計/02_ユースケース/
   UC-{日本語名}.md
 ```
 
-### 4-3. DB・外部サービス（必要時のみ）
+### 5-3. DB・外部サービス（必要時のみ）
 
 ```
 docs/バックエンド/03_詳細設計/03_DB・外部サービス/
   スキーマ定義.dbml
-  外部サービス.md
+  {プロバイダー名}/      # 例: AWS/, GCP/, Azure/
+    {サービス名}.md      # 例: S3.md, DynamoDB.md, Athena.md
 ```
 
+- 外部サービスはクラウドプロバイダー（AWS / GCP / Azure など）をカテゴリフォルダとし、中にサービス名の md を置く
+- `外部サービス.md` のような汎用名は使わない
+
 4. ユーザーに確認・承認を得る
 
-## Phase 5: TDD → 実装
+## Phase 6: TDD → 実装
 
 `test-driven-development` スキルへ移行する。

package/spec-runner/templates/.github/skills/ddd-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/03_DB/343/203/273/345/244/226/351/203/250/343/202/265/343/203/274/343/203/223/343/202/271/{/343/203/227/343/203/255/343/203/220/343/202/244/343/203/200/343/203/274/345/220/215}/{/343/202/265/343/203/274/343/203/223/343/202/271/345/220/215}.md

@@ -0,0 +1,24 @@
+---
+spec_runner:
+  type: external-service
+  provider: {プロバイダー名}
+  service: {サービス名}
+  maps_to: ""
+  depends_on: []
+---
+
+# {サービス名}
+
+## 用途・役割
+
+## 設定・接続情報
+
+| 項目 | 値 |
+|------|-----|
+|  |  |
+
+## データ構造・スキーマ
+
+## アクセス制御・権限
+
+## 注意事項

package/spec-runner/templates/.github/skills/ddd-seed/templates/04_/350/252/277/346/237/273/350/263/207/346/226/231/{/343/202/253/343/203/206/343/202/264/343/203/252/345/220/215}/{/343/203/210/343/203/224/343/203/203/343/202/257/345/220/215}.md

@@ -0,0 +1,20 @@
+---
+spec_runner:
+  type: research
+  topic: {トピック名}
+  category: {カテゴリ名}
+  searched_at: YYYY-MM-DD
+  sources:
+    - title: ""
+      url: ""
+---
+
+# {トピック名}
+
+## 調査目的
+
+## ベストプラクティス
+
+## 注意点・落とし穴
+
+## 本プロジェクトへの適用方針

package/spec-runner/templates/.github/skills/ddd-seed/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,48 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+---
+
+# {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/02_概要設計/{対象文書}.md`
+- `docs/03_詳細設計/src/{対象パス}.md`

package/spec-runner/templates/.github/skills/design-change/SKILL.md

@@ -28,8 +28,9 @@ Phase 1: 変更要求の整理と軽い影響調査
 Phase 2: ADR 作成（必要時）
 Phase 3: 影響ドキュメントの確定
 Phase 4: 概要設計の修正
-Phase 5: 詳細設計の修正
-Phase 6: TDD → 実装 → 検証
+Phase 5: ベストプラクティス調査（必要時）
+Phase 6: 詳細設計の修正
+Phase 7: TDD → 実装 → 検証
 ```
 
 ## Phase 1: 変更要求の整理と軽い影響調査
@@ -90,7 +91,24 @@ Phase 6: TDD → 実装 → 検証
 
 修正完了ごとにチェックリストを更新する。全概要設計の修正完了後、ユーザーに確認・承認を得る。
 
-## Phase 5: 詳細設計の修正
+## Phase 5: ベストプラクティス調査（必要時）
+
+概要設計の修正が承認された後、詳細設計の修正に入る前に実施する。
+
+1. 「詳細設計の修正に先立ち、ベストプラクティスを調査すべき技術・サービスはありますか？」とユーザーに確認する
+2. 調査する技術・サービスの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+```
+docs/バックエンド/04_調査資料/
+  {カテゴリ名}/          # 例: AWS/, GCP/, 設計パターン/
+    {トピック名}.md
+```
+
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 6: 詳細設計の修正
 
 ### バックエンド
 
@@ -112,6 +130,6 @@ Phase 6: TDD → 実装 → 検証
 
 ヘッダーの `depends_on` / `maps_to` を更新する。ユーザーに最終確認を得る。
 
-## Phase 6: TDD → 実装 → 検証
+## Phase 7: TDD → 実装 → 検証
 
 設計書修正が承認されたら `test-driven-development` スキルへ移行する。

package/spec-runner/templates/.github/skills/design-change/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -8,7 +8,6 @@ spec_runner:
 
 **ステータス**: 提案 / 採用 / 廃止 / 置換
 **日付**: YYYY-MM-DD
-**決定者**: {名前}
 
 ## コンテキスト
 

package/spec-runner/templates/.github/skills/frontend-seed/SKILL.md

@@ -22,8 +22,9 @@ description: フロントエンド向け docs 正本開発フローの種。画
 Phase 1: 要件定義
 Phase 2: 概要設計（画面一覧 + 画面遷移図 + コンポーネント一覧）
 Phase 3: ADR（必要時のみ）
-Phase 4: 詳細設計（画面 → コンポーネント）
-Phase 5: TDD → 実装
+Phase 4: ベストプラクティス調査（必要時のみ）
+Phase 5: 詳細設計（画面 → コンポーネント）
+Phase 6: TDD → 実装
 ```
 
 ## 前提ルール
@@ -81,17 +82,39 @@ docs/フロントエンド/02_概要設計/
 
 ## Phase 3: ADR（必要時のみ）
 
+ADR テンプレート: `templates/90_ADR/ADRテンプレート.md`
+
 1. 設計判断が必要な場合だけ ADR を作る
 2. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は `90_ADR/`
 
 4. 採用案を概要設計へ反映してから次へ進む
 
-## Phase 4: 詳細設計
+## Phase 4: ベストプラクティス調査（必要時のみ）
+
+ADR で使用フレームワーク・ライブラリが確定した後、詳細設計に入る前に実施する。
+
+1. 「詳細設計に先立ち、ベストプラクティスを調査すべき技術・ライブラリはありますか？」とユーザーに確認する
+2. 調査する技術・ライブラリの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+テンプレート: `templates/04_調査資料/{カテゴリ名}/{トピック名}.md`
+
+```
+docs/フロントエンド/04_調査資料/
+  {カテゴリ名}/          # 例: React/, アクセシビリティ/, 設計パターン/
+    {トピック名}.md
+```
+
+- 1 調査テーマ = 1 ファイル（複数テーマは別ファイルに分ける）
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 5: 詳細設計
 
 画面 → コンポーネント の順に設計する。
 
-### 4-1. 画面
+### 5-1. 画面
 
 カテゴリ（機能ドメイン）でディレクトリを切り、画面ごとに 1 ファイル作成する。
 
@@ -103,7 +126,7 @@ docs/フロントエンド/03_詳細設計/01_画面/
     {画面名}.md
 ```
 
-### 4-2. コンポーネント
+### 5-2. コンポーネント
 
 概要設計のコンポーネント一覧をもとに、共通コンポーネントごとに 1 ファイル作成する。
 
@@ -116,6 +139,6 @@ docs/フロントエンド/03_詳細設計/02_コンポーネント/
 
 ユーザーに確認・承認を得る。
 
-## Phase 5: TDD → 実装
+## Phase 6: TDD → 実装
 
 `test-driven-development` スキルへ移行する。

package/spec-runner/templates/.github/skills/frontend-seed/templates/04_/350/252/277/346/237/273/350/263/207/346/226/231/{/343/202/253/343/203/206/343/202/264/343/203/252/345/220/215}/{/343/203/210/343/203/224/343/203/203/343/202/257/345/220/215}.md

@@ -0,0 +1,20 @@
+---
+spec_runner:
+  type: research
+  topic: {トピック名}
+  category: {カテゴリ名}
+  searched_at: YYYY-MM-DD
+  sources:
+    - title: ""
+      url: ""
+---
+
+# {トピック名}
+
+## 調査目的
+
+## ベストプラクティス
+
+## 注意点・落とし穴
+
+## 本プロジェクトへの適用方針

package/spec-runner/templates/.github/skills/frontend-seed/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,48 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+---
+
+# {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/フロントエンド/02_概要設計/{対象文書}.md`
+- `docs/フロントエンド/03_詳細設計/{対象パス}.md`

package/spec-runner/templates/.github/skills/simple-seed/SKILL.md

@@ -23,8 +23,9 @@ description: レイヤードアーキテクチャ / CRUD 中心のプロジェ
 Phase 1: 要件定義
 Phase 2: 概要設計（ユースケース + システム全体俯瞰）
 Phase 3: ADR（必要時のみ）
-Phase 4: 詳細設計（UC → DB・外部サービス）
-Phase 5: TDD → 実装
+Phase 4: ベストプラクティス調査（必要時のみ）
+Phase 5: 詳細設計（UC → DB・外部サービス）
+Phase 6: TDD → 実装
 ```
 
 ## 前提ルール
@@ -63,6 +64,8 @@ docs/バックエンド/02_概要設計/
 
 ## Phase 3: ADR（必要時のみ）
 
+ADR テンプレート: `templates/90_ADR/ADRテンプレート.md`
+
 1. 設計判断が必要な場合だけ ADR を作る
 2. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
@@ -75,11 +78,31 @@ docs/バックエンド/02_概要設計/
 
 4. 採用案を概要設計へ反映してから次へ進む
 
-## Phase 4: 詳細設計
+## Phase 4: ベストプラクティス調査（必要時のみ）
+
+ADR で使用サービス・技術が確定した後、詳細設計に入る前に実施する。
+
+1. 「詳細設計に先立ち、ベストプラクティスを調査すべき技術・サービスはありますか？」とユーザーに確認する
+2. 調査する技術・サービスの公式ドキュメント URL を `.spec-runner/references/resources.md` に追記する（ユーザーが知っている URL ＋ AI が有用と判断した URL も積極的に追加する）
+3. WebSearch（resources.md の URL を起点に）でベストプラクティスを調査し、結果を保存する
+4. 調査不要の場合はスキップして次へ進む
+
+テンプレート: `templates/04_調査資料/{カテゴリ名}/{トピック名}.md`
+
+```
+docs/バックエンド/04_調査資料/
+  {カテゴリ名}/          # 例: AWS/, GCP/, 設計パターン/
+    {トピック名}.md      # 例: DynamoDB-キー設計.md, S3-アクセス制御.md
+```
+
+- 1 調査テーマ = 1 ファイル（複数テーマは別ファイルに分ける）
+- ユーザーに確認・承認を得てから次へ進む
+
+## Phase 5: 詳細設計
 
 UC → DB・外部サービス の順に設計する。
 
-### 4-1. ユースケース
+### 5-1. ユースケース
 
 テンプレート: `templates/03_詳細設計/01_ユースケース/UC-{日本語名}.md`
 
@@ -88,17 +111,21 @@ docs/バックエンド/03_詳細設計/01_ユースケース/
   UC-{日本語名}.md
 ```
 
-### 4-2. DB・外部サービス（必要時のみ）
+### 5-2. DB・外部サービス（必要時のみ）
 
 ```
 docs/バックエンド/03_詳細設計/02_DB・外部サービス/
   スキーマ定義.dbml
-  外部サービス.md
+  {プロバイダー名}/      # 例: AWS/, GCP/, Azure/
+    {サービス名}.md      # 例: S3.md, DynamoDB.md, Athena.md
 ```
 
+- 外部サービスはクラウドプロバイダー（AWS / GCP / Azure など）をカテゴリフォルダとし、中にサービス名の md を置く
+- `外部サービス.md` のような汎用名は使わない
+
 3. ユーザーに確認・承認を得る
 
-## Phase 5: TDD → 実装
+## Phase 6: TDD → 実装
 
 `test-driven-development` スキルへ移行する。
 

package/spec-runner/templates/.github/skills/simple-seed/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//350/246/201/344/273/266/345/256/232/347/276/251.md

@@ -0,0 +1,34 @@
+---
+spec_runner:
+  node_id: requirement.要件定義
+  kind: requirement
+  depends_on: []
+  maps_to:
+    - docs/バックエンド/02_概要設計/
+---
+
+# 要件定義
+
+## 解決すべき課題・提供価値
+
+- {課題}
+- {提供価値}
+
+## 対象ユーザー
+
+- {ユーザー種別}: {説明}
+
+## 非機能要件
+
+| 項目 | 内容 |
+|------|------|
+| {パフォーマンス} | {要件} |
+| {セキュリティ} | {要件} |
+
+## スコープ外
+
+- {スコープ外の機能・要件}
+
+## 技術・ビジネス制約
+
+- {制約}

package/spec-runner/templates/.github/skills/simple-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_DB/343/203/273/345/244/226/351/203/250/343/202/265/343/203/274/343/203/223/343/202/271/{/343/203/227/343/203/255/343/203/220/343/202/244/343/203/200/343/203/274/345/220/215}/{/343/202/265/343/203/274/343/203/223/343/202/271/345/220/215}.md

@@ -0,0 +1,24 @@
+---
+spec_runner:
+  type: external-service
+  provider: {プロバイダー名}
+  service: {サービス名}
+  maps_to: ""
+  depends_on: []
+---
+
+# {サービス名}
+
+## 用途・役割
+
+## 設定・接続情報
+
+| 項目 | 値 |
+|------|-----|
+|  |  |
+
+## データ構造・スキーマ
+
+## アクセス制御・権限
+
+## 注意事項

package/spec-runner/templates/.github/skills/simple-seed/templates/04_/350/252/277/346/237/273/350/263/207/346/226/231/{/343/202/253/343/203/206/343/202/264/343/203/252/345/220/215}/{/343/203/210/343/203/224/343/203/203/343/202/257/345/220/215}.md

@@ -0,0 +1,20 @@
+---
+spec_runner:
+  type: research
+  topic: {トピック名}
+  category: {カテゴリ名}
+  searched_at: YYYY-MM-DD
+  sources:
+    - title: ""
+      url: ""
+---
+
+# {トピック名}
+
+## 調査目的
+
+## ベストプラクティス
+
+## 注意点・落とし穴
+
+## 本プロジェクトへの適用方針

package/spec-runner/templates/.github/skills/simple-seed/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,48 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+---
+
+# {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/02_概要設計/{対象文書}.md`
+- `docs/03_詳細設計/src/{対象パス}.md`

package/spec-runner/templates/.spec-runner/references/resources.md

@@ -1,7 +1,7 @@
 # Resources
 
 エラーや調査が必要なときにサブエージェントが参照する外部リソース一覧。
-`architecture-skill-development` 実行時に登録する。
+設計・実装を進める中で随時追記していく。AI が有用と判断したリファレンスも積極的に追加する。
 
 ## 言語・ランタイム