spec-runner 1.1.13 → 1.1.16

package/spec-runner/templates/.claude/skills/docs-driven-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md

@@ -0,0 +1,55 @@
+---
+spec_runner:
+  node_id: detail.usecase.{UC名}
+  kind: detailed_design
+  depends_on:
+    - overview.use_case_list
+    - detail.domain.{ドメイン名}
+  maps_to:
+    - src/application/{uc_name}/
+    - tests/application/{uc_name}/
+---
+
+# UC-{UC名} 詳細設計
+
+## 概要
+
+- 使用するドメイン: {ドメイン名}
+- トリガー: {何がこのUCを呼び出すか}
+- 事前条件: {UCが成立するために必要な状態}
+- 事後条件: {UC完了後の状態}
+
+## 入出力
+
+| 種別 | 名前 | 型 | 説明 |
+|------|------|----|------|
+| 入力 | {入力名} | {型} | {説明} |
+| 出力 | {出力名} | {型} | {説明} |
+
+## 主要フロー
+
+```mermaid
+sequenceDiagram
+  {シーケンス図}
+```
+
+1. {ステップ1}
+2. {ステップ2}
+
+## 判断条件
+
+| 判断ポイント | 条件 | アクション |
+|------------|------|----------|
+| {判断ポイント} | {条件} | {アクション} |
+
+## エラーポリシー
+
+| エラーケース | 発生条件 | 対応 |
+|------------|---------|------|
+| {エラーケース} | {発生条件} | {対応} |
+
+## テスト観点
+
+- {正常系の観点}
+- {異常系の観点}
+- {境界条件の観点}

package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md

@@ -27,22 +27,25 @@ Phase 5: architecture contract 化
 
 ## Phase 2: 要件とユースケースの抽出
 
-1. 既存機能からユースケースを逆算する
+1. `current-system-inventory.md` を起点に、既存機能からユースケースを逆算する
 2. `docs/01_要件定義/要件定義.md` と `docs/02_概要設計/ユースケース一覧.md` の draft を作る
-3. ユーザーに確認・承認を得る
+3. ドメイン用語が識別できたら `docs/01_要件定義/ユビキタス言語辞書.md` も draft する
+4. ユーザーに確認・承認を得る
 
 ## Phase 3: 概要設計の draft 化
 
-1. `docs/02_概要設計/システム全体俯瞰.md` を作る
-2. 必要なら ADR 候補も洗い出す
-3. ユーザーに確認・承認を得る
+1. UC から集約・境界コンテキストを整理し `docs/02_概要設計/ドメインモデル.md` を draft する
+2. `docs/02_概要設計/システム全体俯瞰.md` を作る
+3. 必要なら ADR 候補も洗い出す（配置先は `90_ADR/全体/` / `ドメイン/` / `UC/` / `DB/`）
+4. ユーザーに確認・承認を得る
 
 ## Phase 4: 詳細設計の draft 化
 
-1. `docs/03_詳細設計/src/**` を `src/` ミラーで作る
-2. `maps_to` に対応コードとテストを入れる
-3. 補助設計が必要なら `docs/03_詳細設計/infrastructure/**` を作る
-4. ユーザーに確認・承認を得る
+1. ドメインごとにビジネスルール・集約を整理し `docs/03_詳細設計/01_ドメイン/{ドメイン名}.md` を draft する
+2. UC ごとに `docs/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を draft する
+3. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/03_DB・外部サービス/` を作る
+4. 各ファイルの `maps_to` に対応コードとテストを入れる
+5. ユーザーに確認・承認を得る
 
 ## Phase 5: architecture contract 化
 

package/spec-runner/templates/.claude/skills/harness-engineering/SKILL.md

@@ -68,6 +68,8 @@ Phase 4: 影響範囲の反映確認
 
 ## Phase 3: skill / rule / agent / template の修正
 
+ファイルを作成・修正する前に **`.claude/rules/harness-formats.md`** を読み、フォーマットを確認する。
+
 1. 対象ファイルを特定する
 2. 意図が変わらない最小差分で修正する
 3. 片系だけでなく、対応するテンプレートも揃えて更新する
@@ -91,6 +93,8 @@ Phase 4: 影響範囲の反映確認
 - Claude / Copilot の対応ファイルに反映漏れがないか
 - 今回限りのノイズをルール化していないか
 - skill 名・起動条件・使いどころを変更した場合、`CLAUDE.md` の記述と一致しているか
+- `CLAUDE.md` が肥大化していないか（20行超えたら `rules/` や `skills/` へ移動を検討する）
+- docs 構造・命名規則・node_id 体系に影響する変更の場合、`design-docs.md` と整合しているか
 
 ## 原則
 

package/spec-runner/templates/.claude/skills/test-driven-development/SKILL.md

@@ -26,13 +26,89 @@ description: 新機能実装やバグ修正を行う際、実装コードを書
 テストより先にコードを書いたなら削除して最初からやり直す。
 「参考として残す」も「テストを書きながら適応させる」も不可。
 
+## テスト戦略：テストピラミッド
+
+実装前にどのテスト種別を書くかを決める。迷ったら**単体テストから始める**。
+
+```
+        /\
+       /E2E\        少数・遅い・ユーザーシナリオ全体
+      /------\
+     /  結合   \    中程度・モジュール間連携・外部境界
+    /----------\
+   /    単体    \   多数・高速・関数・クラス単位
+  /______________\
+```
+
+### 単体テスト（Unit）
+
+**対象:** 関数・クラス・モジュールの振る舞い（外部依存なし）
+
+**書くとき:**
+- ビジネスロジック・計算・変換処理
+- エラー処理・バリデーション
+- 状態変化（純粋関数・値オブジェクト）
+
+**外部依存の扱い:** 実際に遅い・副作用がある依存のみモック。それ以外は実物を使う。
+
+**速度目安:** ミリ秒単位。CI で毎回全件実行できる。
+
+### 結合テスト（Integration）
+
+**対象:** 複数モジュールの連携、DB・キャッシュ・外部APIとの境界
+
+**書くとき:**
+- DB へのクエリ・永続化
+- 外部サービス呼び出し（HTTP, メッセージキュー等）
+- 複数の集約をまたぐユースケース
+
+**外部依存の扱い:** 原則として実物を使う（テスト用 DB、テスト環境の外部サービス）。
+動かせない外部サービスのみスタブ／フェイクで代替する。
+
+**速度目安:** 秒単位。PR ごとに実行できる。
+
+### E2E テスト
+
+**対象:** ユーザーが実際に操作するシナリオ全体（UI から DB まで）
+
+**書くとき:**
+- 最重要のユーザーシナリオ（ハッピーパス）
+- リグレッションが致命的な機能（決済・認証等）
+
+**数を絞る:** E2E は維持コストが高い。書く前に「単体＋結合で代替できないか？」を問う。
+
+**速度目安:** 分単位。夜間や本番リリース前など頻度を落として実行。
+
+## テスト種別の選び方
+
+| 実装するもの | まず書くテスト | 追加で書くテスト |
+|---|---|---|
+| ロジック・計算 | 単体 | — |
+| DB 操作 | 結合 | — |
+| API エンドポイント | 結合 | 主要シナリオは E2E |
+| 複数サービスをまたぐフロー | 結合 | — |
+| ユーザー向け主要機能 | 単体＋結合 | E2E（絞る） |
+| バグ修正 | 最小レベルで再現テスト | — |
+
+**バグ修正の場合:** バグを再現できる最も低いレベルのテストを書く。
+単体で再現できるなら単体、DBが絡むなら結合。E2E で初めて再現するバグは、単体・結合に落とし込めないか検討する。
+
 ## テスト実行コマンド
 
 > このスキルはテンプレートとして配布されます。
 > `architecture-skill-development` を使ってプロジェクト固有のコマンドに書き換えてください。
 
 ```bash
-# 全テスト（プロジェクトのテストコマンドに置き換える）
+# 単体テスト（高速・毎回実行）
+<your-unit-test-command>
+
+# 結合テスト
+<your-integration-test-command>
+
+# E2E テスト
+<your-e2e-test-command>
+
+# 全テスト
 <your-test-command>
 
 # 特定ファイル
@@ -46,7 +122,7 @@ description: 新機能実装やバグ修正を行う際、実装コードを書
 
 ### RED - 失敗するテストを書く
 
-起きてほしいことを示す、最小のテストを1つ書く。
+テスト種別を決めたうえで、起きてほしいことを示す最小のテストを1つ書く。
 
 ```
 // 例（言語・フレームワークはプロジェクトに合わせる）
@@ -93,7 +169,7 @@ test("ある入力に対して期待する出力を返す", () => {
 `@test-runner` エージェントに委任して実行する。
 
 - テストが通る
-- **他のテストも全て通る**
+- **同種のテストが全て通る**（単体なら単体全件、結合なら結合全件）
 - 出力がクリーン（エラー、警告なし）
 - **カバレッジの未カバー行を確認** — 新規コードが未カバーなら追加テストを書く
 
@@ -122,18 +198,34 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
 
 ## テスト構成
 
-テストファイルは `src/` と同じディレクトリ構造を `tests/` に鏡写しにする。
+```
+tests/
+  unit/        # 単体テスト（src/ と同じ構造を鏡写し）
+  integration/ # 結合テスト
+  e2e/         # E2E テスト
+```
+
+テストファイルは `src/` と同じディレクトリ構造を各テスト種別のディレクトリ内に鏡写しにする。
 
 ## fixture / テストデータの活用
 
 - テストごとに独立した状態を持つ
 - テストデータ生成にはヘルパ関数を定義して一貫性を保つ
 - 外部サービス（API・メール・ストレージ等）は必要な場合のみモックする
+- 結合テスト用のシードデータは `tests/integration/fixtures/` に置く
 
 ## モックのルール
 
 モックは分離の手段であり、テスト対象ではない。
 
+**テスト種別ごとのモック方針:**
+
+| テスト種別 | 原則 |
+|---|---|
+| 単体 | 外部 I/O（DB・HTTP・ファイル）のみモック可。ビジネスロジックはモックしない |
+| 結合 | 実物の外部依存を使う。動かせない外部サービスのみスタブ可 |
+| E2E | モックしない。全て実物 |
+
 **モック前の自問:**
 1. 「実メソッドにはどんな副作用があるか？」
 2. 「このテストはその副作用に依存しているか？」
@@ -168,6 +260,8 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
 | テスト前にコードを書いた | コードを削除し、TDDで最初からやり直す |
 | テストが最初から通る | 既存挙動をテストしている。テストを修正する |
 | なぜ失敗したか説明できない | テストが正しいか再検討する |
+| 全部 E2E で書いた | ピラミッドが逆転している。単体・結合に落とし込む |
+| 全部モックだらけ | 結合が強すぎる。または結合テストを書くべき |
 
 **どれか1つでも当てはまるなら: コードを削除し、TDDで最初からやり直す。**
 
@@ -180,14 +274,15 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
 
 完了宣言の前に:
 
+- [ ] 実装前にテスト種別（単体・結合・E2E）を決めた
 - [ ] 新規関数／メソッドにテストがある
 - [ ] 各テストは実装前に失敗するのを見た
 - [ ] 期待通りの理由で失敗した（機能不足であり誤字ではない）
 - [ ] 通す最小コードを書いた
-- [ ] 全テストが通る
+- [ ] 同種のテストが全件通る
 - [ ] 出力がクリーン（エラー、警告なし）
 - [ ] カバレッジを確認し、新規コードの未カバー行がない
-- [ ] 実コード中心（不可避な場合のみモック）
+- [ ] モック方針がテスト種別に合っている
 - [ ] エッジケースとエラーをカバーした
 
 すべてにチェックできないならTDDを飛ばしている。やり直すこと。
@@ -197,9 +292,11 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
 | 問題 | 解決 |
 |------|------|
 | どうテストすべきか分からない | 望むAPIを書き、まずアサーションを書く。ユーザーに相談する |
+| どのテスト種別か迷う | 単体から始める。単体で書けないなら結合を検討する |
 | テストが複雑すぎる | 設計が複雑すぎる。インターフェースを簡素化する |
-| 何でもモック必須 | 結合が強すぎる。依存性注入を使う |
+| 何でもモック必須 | 結合が強すぎる。依存性注入を使う。または結合テストで書く |
 | セットアップが巨大 | fixtureやテストユーティリティに抽出する。それでも大きいなら設計を簡素化する |
+| E2E が遅すぎる | 単体・結合に落とし込めるか検討する |
 
 ## 最終ルール
 

package/spec-runner/templates/.github/agents/design-reviewer.agent.md

@@ -11,12 +11,12 @@ docs/ 配下の設計書と src/ 配下の実装コードを突合し、乖離
 
 ## 手順
 
-1. docs/ 配下の設計書ファイルを一覧取得する
+1. `docs/` 配下の設計書ファイルを一覧取得する
 2. 各設計書の frontmatter を読み、`spec_runner.node_id` / `kind` / `depends_on` / `maps_to` を確認する
-3. `docs/02_概要設計/**` は上位設計として扱い、ユースケース・責務・外部 IF・非機能方針が実装に反映されているか確認する
-4. `docs/03_詳細設計/src/**` は `maps_to` で対応先コードを特定し、責務・入出力・判断条件・テスト観点を比較する
-5. `docs/03_詳細設計/infrastructure/**` などの例外文書も `maps_to` を起点に IaC / 設定 / DB 定義と比較する
-6. 乖離を報告する
+3. `docs/02_概要設計/**` の各ファイルを読む。ユースケース・責務・外部 IF が実装に反映されているか確認するために、`maps_to` から対応する `src/` ファイルを特定して実際に読んで比較する
+4. `docs/03_詳細設計/**` の各ファイルを読む。`maps_to` に列挙された `src/` / `tests/` ファイルを**実際に読み**、責務・入出力・判断条件・テスト観点を設計書と行レベルで比較する
+   - `maps_to` が空または未設定の場合はフロントマターの問題として報告する（パス推定は行わない）
+5. 乖離を報告する
 
 ## チェック項目
 
@@ -28,13 +28,13 @@ docs/ 配下の設計書と src/ 配下の実装コードを突合し、乖離
 
 ### 概要設計
 
-- **ユースケース整合**: `ユースケース一覧.md` と個別 UC が実装のエンドポイント・コマンド・画面遷移と一致しているか
+- **ユースケース整合**: `ユースケース一覧.md` の各 UC が実装のエンドポイント・コマンド・画面遷移と一致しているか
 - **全体俯瞰**: `システム全体俯瞰.md` の責務分割・連携フロー・外部 IF が実装構造と一致しているか
 - **ADR 反映**: `docs/02_概要設計/90_ADR/**` の採用方針が概要設計・詳細設計に反映されているか
 
 ### 詳細設計
 
-- **責務整合**: `docs/03_詳細設計/src/**` の責務記述が対応コードの責務と一致しているか
+- **責務整合**: `docs/03_詳細設計/**` の責務記述が `maps_to` 先コードの責務と一致しているか
 - **入出力整合**: 関数シグネチャ、設定値、エラー処理、外部依存の扱いが設計どおりか
 - **テスト整合**: `maps_to` に含まれる `tests/**` が設計上の主要シナリオをカバーしているか
 - **不足 / 過剰**: 設計書にあるがコードにない、またはコードにあるが設計書にない要素があるか
@@ -62,4 +62,4 @@ docs/ 配下の設計書と src/ 配下の実装コードを突合し、乖離
 - 読み取り専用（コードや設計書の変更は行わない）
 - 日本語で報告する
 - ADR はコードと 1 対 1 の突合対象ではないが、配置先と反映有無は確認する
-- hard code のパス推定より frontmatter の `maps_to` を優先する
+- `maps_to` を唯一の参照先とする。パス推定は行わない

package/spec-runner/templates/.github/agents/impact-analyzer.agent.md

@@ -1,25 +1,44 @@
 ---
 name: impact-analyzer
-description: design-change で影響範囲を調査するときに呼ぶ。変更対象の node_id またはファイルパスを受け取り、docs/ 全体の frontmatter を走査して depends_on / maps_to で連鎖する影響ファイルを一覧化する。
-tools: Read, Grep, Glob
+description: design-change で影響範囲を調査するときに呼ぶ。変更対象の node_id またはファイルパスを受け取り、.spec-runner/scan/graph.json のキャッシュを参照して影響ファイルを一覧化し、maps_to の参照整合性も報告する。
+tools: Bash
 model: sonnet
 ---
 
 # 影響範囲分析エージェント
 
-変更対象の docs ノードを起点に、frontmatter の `depends_on` / `maps_to` を辿って影響を受けるファイルを一覧化する。
+`.spec-runner/scan/graph.json`（`scan.js` が生成するキャッシュ）を読み、変更対象の node_id から連鎖する影響ファイルを一覧化する。
 
 ## 入力
 
-- 変更対象の `node_id`（例: `usecase.order_registration`）またはファイルパス
+- 変更対象の `node_id`（例: `detail.usecase.order_registration`）またはファイルパス
 
 ## 手順
 
-1. `docs/` 配下の全 `.md` ファイルの frontmatter を読む
-2. `depends_on` に入力の node_id を含むファイルを「直接影響」として収集する
-3. 収集したファイルの node_id を起点に同じ検索を繰り返す（2階層まで）
-4. `maps_to` に入力の node_id を含む `src/` / `tests/` ファイルを「実装影響」として収集する
-5. 結果を一覧化する
+### 1. グラフキャッシュの確認・更新
+
+```bash
+node .spec-runner/scripts/scan.js
+```
+
+キャッシュが古い場合や存在しない場合は再生成する。
+
+### 2. 影響範囲をグラフから取得
+
+```bash
+node -e "
+const g = require('./.spec-runner/scan/graph.json');
+const id = '{node_id}';
+const node = g.nodes[id] || {};
+const direct = g.reverse_index[id] || [];
+const indirect = [...new Set(
+  direct.flatMap(n => g.reverse_index[n] || []).filter(n => !direct.includes(n) && n !== id)
+)];
+console.log(JSON.stringify({ node, direct: direct.map(n => ({id: n, ...g.nodes[n]})), indirect: indirect.map(n => ({id: n, ...g.nodes[n]})), missing: g.missing_maps_to }, null, 2));
+"
+```
+
+### 3. 結果を一覧化して報告する
 
 ## 報告フォーマット
 
@@ -29,8 +48,9 @@ model: sonnet
 ### 起点
 - node_id: {node_id}
 - ファイル: {ファイルパス}
+- kind: {kind}
 
-### 直接影響（depends_on で参照）
+### 直接影響（1階層目）
 - [ファイルパス] — node_id: {node_id}, kind: {kind}
 
 ### 間接影響（2階層目）
@@ -39,6 +59,10 @@ model: sonnet
 ### 実装影響（maps_to で対応）
 - [src/ または tests/ のファイルパス]
 
+### maps_to 整合性チェック
+- OK: 全参照ファイルが存在する
+- MISSING: {missing} — {source} ({node_id}) に記載されているが存在しない
+
 ### 影響なし（確認済みで変更不要）
 - [ファイルパス] — 理由: {理由}
 ```
@@ -47,5 +71,5 @@ model: sonnet
 
 - 読み取り専用（ファイルの変更は行わない）
 - 日本語で報告する
-- frontmatter が存在しないファイルはスキップする
+- graph.json が存在しない場合は scan.js を実行してから進む
 - 影響ファイルが多い場合は kind 別にグループ化する

package/spec-runner/templates/.github/instructions/coding.instructions.md

@@ -23,6 +23,7 @@ applyTo: "src/**,tests/**"
 - **言語**: 日本語
 - **docstring**: モジュール先頭に1行で概要を書く。関数・クラスには原則不要（名前で意図が伝わる場合）
 - **インラインコメント**: ビジネスロジックの「なぜ」を説明する場合のみ。処理内容の「何」は書かない
+- **変更履歴コメント禁止**: `# 新機能追加`, `# ここを修正`, `# v2 で変更` のような変更経緯はコードに書かない。git の commit message で管理する
 
 ```python
 # 良い例
@@ -88,6 +89,16 @@ truncated_json = '[{"account_name": "売掛金", ...'
 
 - **英語コメント禁止**: `Arrange` / `Act` / `Assert` 等の英語は使わない
 
+## 後方互換ハックの禁止
+
+使われなくなったコードは完全に削除する。互換性維持のための温存は行わない。
+
+禁止パターン:
+- 未使用の引数・変数を `_` プレフィックスで残す（`_old_param`）
+- 削除した型・関数を `from x import Y` で再公開する
+- `# removed`, `# deprecated`, `# 旧実装` コメントとともにコードを残す
+- 後方互換用のラッパー関数・エイリアスを追加する
+
 ## 検索ルール
 
 - コードの検索・置換は `src/` と `tests/` の両方を対象にする

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

@@ -19,44 +19,61 @@ applyTo: "docs/**"
 - **`docs/**` の全設計書に frontmatter を付ける**
 - 正本の必須項目は `spec_runner.node_id` / `spec_runner.kind` / `spec_runner.depends_on` / `spec_runner.maps_to`
 - `depends_on` はまず文字列配列でよい。依存理由が必要な場合のみオブジェクト形式を使う
-- `maps_to` には見直し対象となる `src/` / `tests/` / IaC / 設定ファイルを列挙する
+- `maps_to` には見直し対象となる `src/` / `tests/` / IaC / 設定ファイルを列挙する。**必ず設定する（空にしない）**
 - `modules` / `source_files` などの拡張項目を足す場合でも、`maps_to` と矛盾させない
 
 ```yaml
 ---
 spec_runner:
-  node_id: detail.src.agents.reconciliation.agent
+  node_id: detail.usecase.注文確定
   kind: detailed_design
   depends_on:
-    - overview.system_context
-    - use_case.reconciliation.list
+    - overview.use_case_list
+    - detail.domain.注文
   maps_to:
-    - src/agents/reconciliation/agent.py
-    - tests/agents/reconciliation/test_agent.py
+    - src/application/order/confirm.py
+    - src/domain/order/aggregate.py
+    - tests/application/order/test_confirm.py
 ---
 ```
 
+### node_id 体系
+
+| 対象 | node_id 形式 | 例 |
+|------|-------------|-----|
+| 要件定義 | `requirement.{名前}` | `requirement.要件定義` |
+| システム全体俯瞰 | `overview.system_context` | — |
+| ドメインモデル | `overview.domain_model` | — |
+| ユースケース一覧 | `overview.use_case_list` | — |
+| ADR | `overview.adr.{slug}` | `overview.adr.0404-ドメイン-注文集約` |
+| ドメイン詳細設計 | `detail.domain.{ドメイン名}` | `detail.domain.注文` |
+| UC 詳細設計 | `detail.usecase.{UC名}` | `detail.usecase.注文確定` |
+| DB・外部サービス | `detail.db.{名前}` | `detail.db.スキーマ定義` |
+
 ## 命名規則
 
 | 対象 | 規則 | 例 |
 |------|------|-----|
-| `docs/01_要件定義` | 日本語 | `要件定義.md` |
-| `docs/02_概要設計` | 日本語 | `ユースケース一覧.md`, `システム全体俯瞰.md` |
-| `docs/02_概要設計/ユースケース` | `UC-{日本語名}.md` | `UC-差異一覧表示.md` |
-| `docs/02_概要設計/90_ADR` | `mmdd-{日本語タイトル}.md` | `0404-詳細設計をsrcミラーにする.md` |
-| `docs/03_詳細設計/src/**` | `src/` に合わせた英語 `snake_case` | `agent.md`, `domain.md`, `skill.md` |
-| `docs/03_詳細設計/infrastructure/**` | 対応先に合わせる。例外で置く場合も `maps_to` 必須 | `database.md`, `schema.dbml` |
+| `docs/01_要件定義` | 日本語 | `要件定義.md`, `ユビキタス言語辞書.md` |
+| `docs/02_概要設計` | 日本語 | `ユースケース一覧.md`, `システム全体俯瞰.md`, `ドメインモデル.md` |
+| `docs/02_概要設計/90_ADR/{対象}/` | `mmdd-{日本語タイトル}.md` | `0404-注文集約の設計.md` |
+| `{対象}` の選択肢 | `全体` / `ドメイン` / `UC` / `DB` | — |
+| `docs/03_詳細設計/01_ドメイン` | 日本語 | `注文.md`, `在庫.md` |
+| `docs/03_詳細設計/02_ユースケース` | `UC-{日本語名}.md` | `UC-注文確定.md` |
+| `docs/03_詳細設計/03_DB・外部サービス` | 日本語 | `スキーマ定義.dbml`, `外部サービス.md` |
 
 ## ADR
 
 - **ADR は必ず 3 案を比較してから採用案を決める**
-- ADR は原則 `docs/02_概要設計/90_ADR/` に置く
-- ドメインローカル ADR が必要な場合だけ `docs/02_概要設計/<ドメイン>/90_ADR/` を使う
+- ADR は `docs/02_概要設計/90_ADR/{対象}/` で管理する（`全体` / `ドメイン` / `UC` / `DB`）
+- ファイル名は `mmdd-{日本語タイトル}.md`。対象はフォルダで表す
 - ADR は理由の記録であり、詳細設計の代わりにしない
+- 廃止 UC の理由も ADR に記録する（UC ファイル本体は削除）
 
 ## 文書品質
 
 - **概要設計では「何をするか」を書き、コード片・DDL・クラス定義は持ち込まない**
-- **詳細設計では `src/` に対応する責務・入出力・判断条件・テスト観点を書く**
-- **`docs/03_詳細設計` は原則 `src/` ミラーにする。例外文書は `maps_to` で根拠を残す**
+- **詳細設計ではドメインルール・UC の責務・入出力・判断条件・テスト観点を書く。コード・プロンプト本文は書かない**
+- **`maps_to` を唯一の src 対応として使う。パス推定に頼らない**
 - **Markdown に HTML タグ（details, summary, br など）を使わない**
+- **`概要.md` のような汎用的な名前のファイルは作らない。内容を具体的に示す名前（`要件定義.md`、`ユースケース一覧.md`、`システム全体俯瞰.md` など）を使う**

package/spec-runner/templates/.github/instructions/harness-formats.instructions.md

@@ -0,0 +1,84 @@
+---
+applyTo: "**"
+---
+
+# ハーネスファイルフォーマット
+
+`harness-engineering` や `architecture-skill-development` で rules / agents / skills を作成・修正するときは、このフォーマットに従う。
+
+## rule ファイル（`.github/instructions/*.instructions.md`）
+
+```markdown
+---
+applyTo: "対象パス/**"   # 省略すると "**"（全ファイルに適用）
+---
+
+# ルール名
+
+本文...
+```
+
+- 対応する `.claude/rules/{name}.md` も同時に作成・更新する
+
+## agent ファイル（`.github/agents/*.agent.md`）
+
+```markdown
+---
+name: agent-name
+description: いつ・何のために呼ぶかを具体的に書く（トリガー型）
+tools: Read, Grep, Glob          # 必要最小限のツールだけ付与
+model: sonnet
+---
+
+# エージェント名
+
+本文...
+```
+
+- `description` はトリガー型で書く（「〇〇のときに自動で呼ぶ」形式）
+- `tools` は最小権限原則。読み取りのみなら `Read, Grep, Glob`
+- 対応する `.claude/agents/{name}.md` も同時に作成・更新する
+
+## skill ファイル（`.github/skills/{name}/SKILL.md`）
+
+```markdown
+---
+name: skill-name
+description: このスキルの目的と使うタイミング（1〜2行）
+---
+
+# スキル名
+
+本文...
+```
+
+- 対応する `.claude/skills/{name}/SKILL.md` も同時に作成・更新する
+
+## CLAUDE.md
+
+CLAUDE.md は**全会話で常にコンテキストに読み込まれる**。書くほどコストが増えるため、最小に保つ。
+
+### 書いてよいもの
+
+- よく使う skill の名前と起動タイミング（開発ワークフローの入口）
+- プロジェクト全体に常時適用すべき制約（例: 言語、承認フロー）
+
+### 書いてはいけないもの（代わりの置き場所）
+
+| 内容 | 正しい置き場所 |
+|------|--------------|
+| コーディング規約の詳細 | `.github/instructions/coding.instructions.md` |
+| フォーマット定義・手順 | `.github/instructions/*.instructions.md` |
+| スキルの詳細フロー | `.github/skills/*/SKILL.md` |
+| 過去の決定・背景 | `docs/02_概要設計/90_ADR/` |
+
+### 目安
+
+- 20行を超えたら見直しを検討する
+- 新しい内容を追加する前に「instructions / skills に移せないか」を先に考える
+
+## 共通原則
+
+- `.claude/` と `.github/` は常に対で更新する（片系だけ更新しない）
+- `description` は「何をするか」より「**いつ・なぜ使うか**」を優先して書く
+- 新規作成時は既存ファイルを参考にフォーマットを確認してから作る

package/spec-runner/templates/.github/skills/architecture-definition/SKILL.md

@@ -28,14 +28,14 @@ Phase 5: 次の skill へ引き渡し
 ## Phase 2: 概要設計の骨格作成
 
 1. `docs/02_概要設計/ユースケース一覧.md` を作る
-2. `docs/02_概要設計/システム全体俯瞰.md` を作る
-3. 必要に応じて `ユースケース/`、`外部IF一覧.md`、`非機能・運用方針.md` を追加する
+2. UC から集約・境界コンテキストを整理し `docs/02_概要設計/ドメインモデル.md` を作る
+3. `docs/02_概要設計/システム全体俯瞰.md` を作る
 4. ユーザーに確認・承認を得る
 
 ## Phase 3: アーキテクチャ判断の明文化
 
 1. ドメイン分割、責務境界、実装単位、インフラ方針を整理する
-2. 必要なら `docs/02_概要設計/90_ADR/` に ADR を作る
+2. 必要なら対象フォルダに ADR を作る（`90_ADR/全体/` / `ドメイン/` / `UC/` / `DB/`）
 3. ユーザーに確認・承認を得る
 
 ## Phase 4: architecture contract 作成