spec-runner 1.1.7 → 1.1.8

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

@@ -0,0 +1,211 @@
+---
+name: test-driven-development
+description: 新機能実装やバグ修正を行う際、実装コードを書く前に必ず使用する。
+---
+
+# テスト駆動開発（TDD）
+
+## 概要
+
+テストを先に書く。失敗するのを確認する。通る最小のコードを書く。
+
+**中核原則:** テストが失敗するのを見ていないなら、そのテストが正しいものを検証しているか分からない。
+
+## いつ使うか
+
+**常に:** 新機能・バグ修正・リファクタリング・振る舞い変更
+
+**例外（ユーザーに確認する）:** 使い捨てプロトタイプ・生成コード・設定ファイル
+
+## 鉄の掟
+
+```
+失敗するテストなしに本番コードを書かない
+```
+
+テストより先にコードを書いたなら削除して最初からやり直す。
+「参考として残す」も「テストを書きながら適応させる」も不可。
+
+## テスト実行コマンド
+
+> このスキルはテンプレートとして配布されます。
+> `architecture-skill-development` を使ってプロジェクト固有のコマンドに書き換えてください。
+
+```bash
+# 全テスト（プロジェクトのテストコマンドに置き換える）
+<your-test-command>
+
+# 特定ファイル
+<your-test-command> <test-file>
+
+# カバレッジ計測
+<your-test-command> --coverage
+```
+
+## Red-Green-Refactor
+
+### RED - 失敗するテストを書く
+
+起きてほしいことを示す、最小のテストを1つ書く。
+
+```
+// 例（言語・フレームワークはプロジェクトに合わせる）
+test("ある入力に対して期待する出力を返す", () => {
+  // 準備 - テスト対象の入力データを用意する
+  const input = ...
+
+  // 実行 - テスト対象の関数を呼び出す
+  const result = targetFunction(input)
+
+  // 判定 - 期待する出力と一致するか確認する
+  expect(result).toBe(expectedOutput)
+})
+```
+
+**要件:**
+- 1つの振る舞い
+- 明確なテスト名（振る舞いを説明する）
+- 実コード中心（不可避な場合のみモック）
+
+### Verify RED - 失敗するのを確認する
+
+**必須。絶対に省略しない。**
+
+`@test-runner` エージェントに委任して実行する。
+
+- テストが**失敗する**（エラーではない）
+- 失敗メッセージが期待通り
+- **機能がないこと**が原因で失敗している（誤字等ではない）
+
+テストが通る → 既存挙動をテストしている。テストを修正する。
+テストがエラー → エラーを直して再実行し、「正しく失敗する」まで繰り返す。
+
+### GREEN - 通す最小のコードを書く
+
+テストを通すための最も単純なコードを書く。
+
+テストにない機能を足さない。他の改善やリファクタもここではしない。
+
+### Verify GREEN - 通るのを確認する
+
+**必須。**
+
+`@test-runner` エージェントに委任して実行する。
+
+- テストが通る
+- **他のテストも全て通る**
+- 出力がクリーン（エラー、警告なし）
+- **カバレッジの未カバー行を確認** — 新規コードが未カバーなら追加テストを書く
+
+テストが落ちる → テストではなくコードを直す。
+他のテストが落ちる → 直ちに修正する。
+
+### REFACTOR - 整理する
+
+Greenの後にのみ: 重複削除・命名改善・ヘルパ抽出。
+テストは常にGreenを維持する。新しい挙動は追加しない。
+
+### 繰り返す
+
+次の機能のために、次の失敗するテストを書く。
+
+## よいテスト
+
+- **最小**: 1つの振る舞いだけ。「and」が入るなら分割する
+- **明確**: テスト名が挙動を説明する
+- **意図が見える**: 望ましいAPIの使い方が伝わる
+
+## テストのコメント
+
+テストコメントの規約は同梱のコーディング規約ファイルの「テストコメント規約」に従う。
+GREEN / REFACTORフェーズで書く実装コードにもビジネスロジックの意図をコメントする。
+
+## テスト構成
+
+テストファイルは `src/` と同じディレクトリ構造を `tests/` に鏡写しにする。
+
+## fixture / テストデータの活用
+
+- テストごとに独立した状態を持つ
+- テストデータ生成にはヘルパ関数を定義して一貫性を保つ
+- 外部サービス（API・メール・ストレージ等）は必要な場合のみモックする
+
+## モックのルール
+
+モックは分離の手段であり、テスト対象ではない。
+
+**モック前の自問:**
+1. 「実メソッドにはどんな副作用があるか？」
+2. 「このテストはその副作用に依存しているか？」
+3. 依存しているなら → より低いレベル（実際に遅い／外部な操作）をモックする
+
+**原則:**
+- 実コンポーネントの**出力**をテストする。モックの呼び出し確認だけにアサートしない
+- 本番クラスにテスト専用メソッドを追加しない → fixtureやテストユーティリティに置く
+- テストデータはドメインモデルの全フィールドを含める
+
+**赤信号（モックをやめて設計を見直す）:**
+- モック準備がテスト本体より長い
+- モックを外すとテストが成立しない
+- なぜモックが必要か説明できない
+
+## なぜ順序が重要か
+
+実装後のテストはすぐ通る。すぐ通ることは何も証明しない:
+- 間違ったものをテストしているかもしれない
+- 実装に引きずられて挙動ではなく実装をテストしがち
+- バグを捕まえる力を見ていない
+
+テストファーストは、テストが本当に何かを検証していることを「失敗」で証明する。
+
+## よくある合理化と赤信号
+
+| 兆候 | 問題 |
+|------|------|
+| 「簡単すぎてテスト不要」 | 簡単でも壊れる。テストは30秒 |
+| 「あとでテストする」 | すぐ通るテストは何も証明しない |
+| 「今回だけTDDを飛ばす」 | 合理化である。止めること |
+| テスト前にコードを書いた | コードを削除し、TDDで最初からやり直す |
+| テストが最初から通る | 既存挙動をテストしている。テストを修正する |
+| なぜ失敗したか説明できない | テストが正しいか再検討する |
+
+**どれか1つでも当てはまるなら: コードを削除し、TDDで最初からやり直す。**
+
+## 完了時のレビュー
+
+実装完了後、以下のエージェントでレビューする:
+- `@code-reviewer` — コーディング規約への適合チェック
+
+## 検証チェックリスト
+
+完了宣言の前に:
+
+- [ ] 新規関数／メソッドにテストがある
+- [ ] 各テストは実装前に失敗するのを見た
+- [ ] 期待通りの理由で失敗した（機能不足であり誤字ではない）
+- [ ] 通す最小コードを書いた
+- [ ] 全テストが通る
+- [ ] 出力がクリーン（エラー、警告なし）
+- [ ] カバレッジを確認し、新規コードの未カバー行がない
+- [ ] 実コード中心（不可避な場合のみモック）
+- [ ] エッジケースとエラーをカバーした
+
+すべてにチェックできないならTDDを飛ばしている。やり直すこと。
+
+## 詰まったとき
+
+| 問題 | 解決 |
+|------|------|
+| どうテストすべきか分からない | 望むAPIを書き、まずアサーションを書く。ユーザーに相談する |
+| テストが複雑すぎる | 設計が複雑すぎる。インターフェースを簡素化する |
+| 何でもモック必須 | 結合が強すぎる。依存性注入を使う |
+| セットアップが巨大 | fixtureやテストユーティリティに抽出する。それでも大きいなら設計を簡素化する |
+
+## 最終ルール
+
+```
+本番コード → 先にテストが存在し、失敗している
+それ以外 → TDDではない
+```
+
+ユーザーの許可なしに例外はない。

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

@@ -0,0 +1,69 @@
+---
+name: code-reviewer
+description: コーディング規約ファイルへの適合をチェックする。コード変更後のレビューに使用する。
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# コーディング規約チェックエージェント
+
+同梱のコーディング規約ファイルに定義されたコーディング規約への適合をチェックする。
+
+## 手順
+
+1. `git diff --name-only` で変更ファイルを確認する（引数でファイルが指定された場合はそちらを使用）
+2. 変更された `.py` ファイルを読み込む
+3. 以下のチェック項目を検証する
+4. 違反を報告する
+
+## チェック項目
+
+### 命名規則
+- ファイル名: snake_case
+- クラス名: PascalCase
+- 関数・メソッド: snake_case
+- 変数: snake_case
+- 定数: UPPER_SNAKE_CASE
+- モジュール内部定数: _UPPER_SNAKE_CASE（先頭アンダースコア）
+- テストクラス: Test + PascalCase
+- テストメソッド: test_ + snake_case（日本語不可）
+
+### 型ヒント
+- Python 3.12+ のビルトイン型を使用（`list[str]`, `dict[str, int]`, `str | None`）
+- `typing` モジュールの `List`, `Dict`, `Optional` を使っていないか
+- 値オブジェクトに `frozen=True` の dataclass を使っているか
+
+### コメント・docstring
+- コメントが日本語であるか（英語コメント禁止）
+- モジュール先頭に1行概要があるか
+- 不要なdocstring（名前で意図が伝わる関数へのdocstring）がないか
+
+### テストコメント
+- 全テストメソッドにdocstring（テスト意図を日本語1行）があるか
+- セットアップ5行以上のテストに `# 準備` / `# 実行` / `# 検証` があるか
+- テストクラスが3つ以上のファイルにセクション区切り（`# ====`）があるか
+
+### プロジェクト構造
+- テストファイルが実装と同じディレクトリ構造にあるか
+- `__init__.py` が存在するか
+
+## 報告フォーマット
+
+```
+## コーディング規約チェック結果
+
+### 違反あり
+#### [ファイルパス]:[行番号]
+- 規約: [違反した規約名]
+- 内容: [具体的な違反内容]
+- 修正案: [修正例]
+
+### 問題なし
+- [チェック済みファイル一覧]
+```
+
+## 注意事項
+
+- 読み取り専用（コードの変更は行わない）
+- 日本語で報告する
+- 変更されたファイルのみをチェック対象とする（既存コードの規約違反は指摘しない）

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

@@ -0,0 +1,65 @@
+---
+name: design-reviewer
+description: 設計書（docs/）と実装コード（src/）の整合性をチェックする。設計書と実装の乖離が心配なときに使用する。
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# 設計書⇔実装 整合性チェックエージェント
+
+docs/ 配下の設計書と src/ 配下の実装コードを突合し、乖離を報告する。
+
+## 手順
+
+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. 乖離を報告する
+
+## チェック項目
+
+### frontmatter
+
+- **必須項目**: `node_id` / `kind` / `depends_on` / `maps_to` が存在するか
+- **依存整合**: `depends_on` の参照先が実在するか。依存の向きが明らかに逆転していないか
+- **対応整合**: `maps_to` の実ファイルが存在するか。変更対象が漏れていないか
+
+### 概要設計
+
+- **ユースケース整合**: `ユースケース一覧.md` と個別 UC が実装のエンドポイント・コマンド・画面遷移と一致しているか
+- **全体俯瞰**: `システム全体俯瞰.md` の責務分割・連携フロー・外部 IF が実装構造と一致しているか
+- **ADR 反映**: `docs/02_概要設計/90_ADR/**` の採用方針が概要設計・詳細設計に反映されているか
+
+### 詳細設計
+
+- **責務整合**: `docs/03_詳細設計/src/**` の責務記述が対応コードの責務と一致しているか
+- **入出力整合**: 関数シグネチャ、設定値、エラー処理、外部依存の扱いが設計どおりか
+- **テスト整合**: `maps_to` に含まれる `tests/**` が設計上の主要シナリオをカバーしているか
+- **不足 / 過剰**: 設計書にあるがコードにない、またはコードにあるが設計書にない要素があるか
+
+## 報告フォーマット
+
+```
+## 整合性チェック結果
+
+### frontmatterの問題
+- [ファイル]: [問題内容]
+
+### 一致（問題なし）
+- [ファイルペアの一覧]
+
+### 乖離あり
+#### [設計書ファイル] ⇔ [実装ファイル]
+- 種別: 不足 / 過剰 / 変更
+- 内容: [具体的な差分の説明]
+- 推奨対応: 設計書を更新 / 実装を修正
+```
+
+## 注意事項
+
+- 読み取り専用（コードや設計書の変更は行わない）
+- 日本語で報告する
+- ADR はコードと 1 対 1 の突合対象ではないが、配置先と反映有無は確認する
+- hard code のパス推定より frontmatter の `maps_to` を優先する

package/spec-runner/templates/.github/agents/test-runner.agent.md

@@ -0,0 +1,34 @@
+---
+name: test-runner
+description: コード変更後にテストを実行し、失敗時は原因分析まで行う。コード修正・機能追加の後に使用する。
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# テスト実行エージェント
+
+テストをDocker環境で実行し、結果を分析する。
+
+## 手順
+
+1. `git diff --name-only` で変更ファイルを確認する
+2. 変更ファイルに対応するテストファイルを特定する（`tests/` 配下の同構造）
+3. テストを実行する:
+   - 対象テストが明確な場合: `docker compose run --rm test pytest tests/path/to/test_file.py -v`
+   - 全体実行が必要な場合: `docker compose run --rm test pytest -v`
+4. 結果を分析する
+
+## 失敗時の分析
+
+テストが失敗した場合、以下を報告する:
+
+- **失敗したテスト**: テスト名とファイルパス
+- **エラー内容**: アサーションエラーやスタックトレースの要約
+- **原因の推定**: 変更内容との関連性を分析
+- **修正案**: 具体的なコード修正の提案（コード例を含める）
+
+## 注意事項
+
+- テスト実行は必ず `docker compose run --rm test pytest` で行う
+- コードの修正は行わない（分析と提案のみ）
+- 日本語で報告する

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

@@ -0,0 +1,105 @@
+---
+applyTo: "src/**,tests/**"
+---
+
+# コーディング規約
+
+## 命名規則
+
+| 対象 | 規則 | 例 |
+|------|------|-----|
+| ファイル名 | snake_case | `domain.py`, `journal_search.py` |
+| クラス名 | PascalCase | `CheckExecution`, `AccountBalance` |
+| 関数・メソッド | snake_case | `aggregate_by_account()`, `determine_severity()` |
+| 変数 | snake_case | `journal_entries`, `diff_amount` |
+| 定数 | UPPER_SNAKE_CASE | `THRESHOLD_ERROR`, `_VALID_SEVERITIES` |
+| モジュール内部定数 | _UPPER_SNAKE_CASE（先頭アンダースコア） | `_THRESHOLD_WARNING` |
+| テストクラス | Test + PascalCase | `TestDetermineSeverity` |
+| テストメソッド | test_ + snake_case（日本語不可） | `test_empty_entries_raises` |
+| ディレクトリ | snake_case | `agents/reconciliation/`, `plugins/tools/` |
+
+## コメント・docstring
+
+- **言語**: 日本語
+- **docstring**: モジュール先頭に1行で概要を書く。関数・クラスには原則不要（名前で意図が伝わる場合）
+- **インラインコメント**: ビジネスロジックの「なぜ」を説明する場合のみ。処理内容の「何」は書かない
+
+```python
+# 良い例
+# 貸方は負の値として扱う（借方 - 貸方 = 残高）
+balances[credit_key] = balances.get(credit_key, 0) - entry.credit_amount
+```
+
+## 型
+
+- Python 3.12+ のビルトイン型を使用（`list[str]`, `dict[str, int]`, `str | None`）
+- `typing` モジュールのインポートは不要（`List`, `Dict`, `Optional` は使わない）
+- dataclass の `frozen=True` を値オブジェクトに使用
+
+## テスト
+
+- テストファイルは実装と同じディレクトリ構造: `tests/agents/reconciliation/test_domain.py`
+- TDDサイクル: RED → GREEN → REFACTOR
+
+### テストコメント規約
+
+- **docstring**: 全テストメソッドにテスト意図を日本語1行で書く（メソッド名の言い換えではなく「なぜそのテストが必要か」を書く）
+- **セクション区切り**: テストクラスが3つ以上あるファイルでは、クラス間に区切りコメントを入れる
+
+```python
+# ============================================================
+# 重要度判定
+# ============================================================
+class TestDetermineSeverity:
+```
+
+- **準備・実行・検証**: セットアップが5行以上のテストでは `# 準備` / `# 実行` / `# 検証` で構造を明示する。`—` で簡潔な意図を添える（推奨）
+
+```python
+def test_full_flow(self):
+    """集計→比較→分析の全フローが動作する"""
+    # 準備 — 仕訳と調書に50K円の差異を作る
+    agent = self._make_agent()
+    entries = [_make_entry("売掛金", "売上高", 1_000_000)]
+    worksheet = [_make_balance("worksheet", "売掛金", 950_000)]
+
+    # 実行
+    results = agent.run_check(entries, worksheet, [])
+
+    # 検証 — 差異がある科目のみ返る
+    assert len(results) == 1
+    assert results[0].severity.value == "error"
+```
+
+- **インラインコメント**: データ構造やモック応答の意図が分かりにくい箇所には積極的にコメントを付ける。特にリスト要素やside_effectの各要素には `# 計画`、`# 1パス目分析` のように役割を明示する
+
+```python
+llm.chat.side_effect = [
+    plan_json,                    # 計画
+    _make_analysis_response(),    # 1パス目分析
+    investigation_needs,          # 調査判断1: 追加調査必要
+    _make_analysis_response(),    # 再分析1
+    # ここで上限到達 → ループ終了
+]
+
+# 1回目: 途中で切れたJSON、2回目: リトライで正しいJSON
+truncated_json = '[{"account_name": "売掛金", ...'
+```
+
+- **英語コメント禁止**: `Arrange` / `Act` / `Assert` 等の英語は使わない
+
+## 検索ルール
+
+- コードの検索・置換は `src/` と `tests/` の両方を対象にする
+- 日本語のキーワード（後方互換、レガシー等）も検索対象に含める
+
+## プロジェクト構造
+
+```
+src/
+  agents/{agent_name}/     # agent.py, domain.py, prompts.py, config.py
+  plugins/tools/{tool}/    # tool.py
+  plugins/skills/{skill}/  # skill.py
+  web/                     # FastAPI + HTMX
+tests/                     # src/ と同じ構造
+```

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

@@ -0,0 +1,62 @@
+---
+applyTo: "docs/**"
+---
+
+# 設計書共通ルール
+
+## フェーズ管理
+
+- **ユーザー承認なしにフェーズを進めない**
+- フェーズは必ず `要件定義 -> 概要設計 -> 詳細設計 -> TDD -> 実装` の順に進める
+
+## テンプレート
+
+- **設計書は必ずテンプレートをコピーして生成する。独自にゼロから作成しない**
+- 手順: テンプレートを読む → 出力先へコピーする → プレースホルダーを埋める
+
+## frontmatter
+
+- **`docs/**` の全設計書に frontmatter を付ける**
+- 正本の必須項目は `spec_runner.node_id` / `spec_runner.kind` / `spec_runner.depends_on` / `spec_runner.maps_to`
+- `depends_on` はまず文字列配列でよい。依存理由が必要な場合のみオブジェクト形式を使う
+- `maps_to` には見直し対象となる `src/` / `tests/` / IaC / 設定ファイルを列挙する
+- `modules` / `source_files` などの拡張項目を足す場合でも、`maps_to` と矛盾させない
+
+```yaml
+---
+spec_runner:
+  node_id: detail.src.agents.reconciliation.agent
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+    - use_case.reconciliation.list
+  maps_to:
+    - src/agents/reconciliation/agent.py
+    - tests/agents/reconciliation/test_agent.py
+---
+```
+
+## 命名規則
+
+| 対象 | 規則 | 例 |
+|------|------|-----|
+| `docs/01_要件定義` | 日本語 | `要件定義.md` |
+| `docs/02_概要設計` | 日本語 | `ユースケース一覧.md`, `システム全体俯瞰.md` |
+| `docs/02_概要設計/ユースケース` | `UC-{日本語名}.md` | `UC-差異一覧表示.md` |
+| `docs/02_概要設計/90_ADR` | `ADR-0001-{slug}.md` | `ADR-0001-detailed-design-mirrors-src.md` |
+| `docs/03_詳細設計/src/**` | `src/` に合わせた英語 `snake_case` | `agent.md`, `domain.md`, `skill.md` |
+| `docs/03_詳細設計/infrastructure/**` | 対応先に合わせる。例外で置く場合も `maps_to` 必須 | `database.md`, `schema.dbml` |
+
+## ADR
+
+- **ADR は必ず 3 案を比較してから採用案を決める**
+- ADR は原則 `docs/02_概要設計/90_ADR/` に置く
+- ドメインローカル ADR が必要な場合だけ `docs/02_概要設計/<ドメイン>/90_ADR/` を使う
+- ADR は理由の記録であり、詳細設計の代わりにしない
+
+## 文書品質
+
+- **概要設計では「何をするか」を書き、コード片・DDL・クラス定義は持ち込まない**
+- **詳細設計では `src/` に対応する責務・入出力・判断条件・テスト観点を書く**
+- **`docs/03_詳細設計` は原則 `src/` ミラーにする。例外文書は `maps_to` で根拠を残す**
+- **Markdown に HTML タグ（details, summary, br など）を使わない**

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

@@ -0,0 +1,60 @@
+---
+name: architecture-definition
+description: 新規プロジェクトで docs と `.spec-runner/architecture/architecture.yaml` を立ち上げるための初期化フロー。
+---
+
+# architecture-definition
+
+新規プロジェクト向けの初期化フロー。
+要件定義から概要設計、architecture contract の作成までを先に固め、その後に project 専用 skill の開発へ渡す。
+
+## 全体フロー
+
+```
+Phase 1: 要件整理
+Phase 2: 概要設計の骨格作成
+Phase 3: アーキテクチャ判断の明文化
+Phase 4: architecture contract 作成
+Phase 5: 次の skill へ引き渡し
+```
+
+## Phase 1: 要件整理
+
+1. ユーザーから背景、提供価値、制約、スコープ外を確認する
+2. `docs/01_要件定義/要件定義.md` を作る
+3. frontmatter を付ける
+4. ユーザーに確認・承認を得る
+
+## Phase 2: 概要設計の骨格作成
+
+1. `docs/02_概要設計/ユースケース一覧.md` を作る
+2. `docs/02_概要設計/システム全体俯瞰.md` を作る
+3. 必要に応じて `ユースケース/`、`外部IF一覧.md`、`非機能・運用方針.md` を追加する
+4. ユーザーに確認・承認を得る
+
+## Phase 3: アーキテクチャ判断の明文化
+
+1. ドメイン分割、責務境界、実装単位、インフラ方針を整理する
+2. 必要なら `docs/02_概要設計/90_ADR/` に ADR を作る
+3. ユーザーに確認・承認を得る
+
+## Phase 4: architecture contract 作成
+
+1. `.spec-runner/architecture/architecture.yaml` を作る
+2. 最低限、以下を構造化する
+   - domain_structure
+   - runtime_units
+   - design_policy
+   - testing_policy
+3. ユーザーに確認・承認を得る
+
+## Phase 5: 次の skill へ引き渡し
+
+1. `architecture-skill-development` に渡す前提を整理する
+2. project 専用 skill に切り出すべき反復フローを列挙する
+
+## 原則
+
+- docs を先に作る
+- `.spec-runner/` は補助情報として扱う
+- project 専用 skill を作る前にアーキテクチャを固める