spec-runner 1.1.6 → 1.1.8

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/config.md

@@ -0,0 +1,47 @@
+---
+spec_runner:
+  node_id: detail.src.agents.{agent_name}.config
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+    - detail.src.agents.{agent_name}.agent
+  maps_to:
+    - src/agents/{agent_name}/config.py
+    - tests/agents/{agent_name}/test_config.py
+---
+
+# `src/agents/{agent_name}/config.py` 詳細設計
+
+## LLM設定
+
+| 項目 | 値 | 理由 |
+|------|----|------|
+| モデル | {モデル名} | {選定理由} |
+| temperature | {値} | {理由} |
+| max_tokens | {値} | {理由} |
+
+## エージェント固有設定
+
+| 設定項目 | 値 | 説明 |
+|---------|----|------|
+| **{設定名}** | {デフォルト値} | {説明} |
+
+## タイムアウト / リトライ
+
+| 処理 | 設定 | 理由 |
+|------|------|------|
+| LLM呼び出し | {秒または回数} | {理由} |
+| 外部 API | {秒または回数} | {理由} |
+
+## 環境別設定
+
+| 環境 | 差分 |
+|------|------|
+| 開発 | {差分} |
+| 本番 | {差分} |
+
+## テスト観点
+
+- 設定値の既定値
+- 不正値の拒否
+- 環境差分の取り扱い

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/domain.md

@@ -0,0 +1,67 @@
+---
+spec_runner:
+  node_id: detail.src.agents.{agent_name}.domain
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+    - use_case.{use_case_slug}
+  maps_to:
+    - src/agents/{agent_name}/domain.py
+    - tests/agents/{agent_name}/test_domain.py
+---
+
+# `src/agents/{agent_name}/domain.py` 詳細設計
+
+## 概要
+
+このエージェントが扱うビジネスロジックとデータモデルを定義する。
+
+## エンティティ
+
+### {日本語名}（`{ClassName}`）
+
+{責務の説明}
+
+| フィールド | 型 | 説明 |
+|----------|----|------|
+| {フィールド名} | {型} | {説明} |
+
+**不変条件**
+
+- {条件1}
+- {条件2}
+
+## 値オブジェクト
+
+### {日本語名}（`{ClassName}`）
+
+{責務の説明}
+
+| フィールド | 型 | 説明 |
+|----------|----|------|
+| {フィールド名} | {型} | {説明} |
+
+**バリデーション**
+
+- {ルール1}
+
+## ビジネスロジック
+
+### {ロジック名}
+
+1. {ステップ1}
+2. {ステップ2}
+3. {ステップ3}
+
+## ビジネスルール
+
+| 条件 | アクション |
+|------|----------|
+| {条件} | {アクション} |
+
+## データ変換 / 境界
+
+| 変換方向 | 入力 | 出力 | 概要 |
+|---------|------|------|------|
+| {外部} → 内部 | {外部形式} | {ドメインモデル} | {変換内容} |
+| 内部 → {外部} | {ドメインモデル} | {外部形式} | {変換内容} |

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/prompts.md

@@ -0,0 +1,72 @@
+---
+spec_runner:
+  node_id: detail.src.agents.{agent_name}.prompts
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+    - detail.src.agents.{agent_name}.agent
+  maps_to:
+    - src/agents/{agent_name}/prompts.py
+    - tests/agents/{agent_name}/test_prompts.py
+---
+
+# `src/agents/{agent_name}/prompts.py` 詳細設計
+
+## システムプロンプト
+
+### 役割定義
+
+```text
+あなたは{役割}です。
+
+【責務】
+- {責務1}
+- {責務2}
+```
+
+### 出力形式
+
+```text
+{出力形式の例}
+```
+
+## タスク別プロンプト
+
+### タスク: {タスク名}
+
+**用途**: {タスクの説明}
+
+```text
+{タスク固有の指示}
+```
+
+## Few-shot 例
+
+### 例1
+
+入力:
+
+```text
+{入力例1}
+```
+
+出力:
+
+```text
+{出力例1}
+```
+
+## ガードレール
+
+| 項目 | 内容 |
+|------|------|
+| 禁止事項 | {禁止事項} |
+| 失敗時の扱い | {扱い} |
+| 再試行条件 | {条件} |
+
+## プロンプト戦略
+
+| 戦略 | 適用箇所 | 理由 |
+|------|---------|------|
+| 出力形式固定 | {適用箇所} | {理由} |
+| Few-shot | {適用箇所} | {理由} |

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/skills/{skill_name}/skill.md

@@ -0,0 +1,53 @@
+---
+spec_runner:
+  node_id: detail.src.plugins.skills.{skill_name}.skill
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+  maps_to:
+    - src/plugins/skills/{skill_name}/skill.py
+    - tests/plugins/skills/{skill_name}/test_skill.py
+---
+
+# `src/plugins/skills/{skill_name}/skill.py` 詳細設計
+
+## 概要
+
+| 項目 | 内容 |
+|------|------|
+| スキル名 | {スキル名} |
+| 責務 | {スキルが果たす役割} |
+| 使用するエージェント | {エージェント名} |
+| トリガー | {呼び出しタイミング} |
+
+## 入出力
+
+| 種別 | 名前 | 型 | 説明 |
+|------|------|----|------|
+| 入力 | {入力名} | {型} | {説明} |
+| 出力 | {出力名} | {型} | {説明} |
+
+## 判定ロジック
+
+| 観点 | 確認内容 | 重要度 |
+|------|---------|--------|
+| **{観点名}** | {確認内容} | {高/中/低} |
+
+## プロンプト
+
+```text
+あなたは{専門家の役割}です。
+{タスクの説明}
+```
+
+## エラーケース
+
+| エラーケース | 発生条件 | 対応方法 |
+|------------|---------|---------|
+| **{エラーケース}** | {発生条件} | {対応方法} |
+
+## テスト観点
+
+- 判定ロジックの正常系
+- 閾値・境界条件
+- 入力不足・異常値

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/tools/{tool_name}/tool.md

@@ -0,0 +1,51 @@
+---
+spec_runner:
+  node_id: detail.src.plugins.tools.{tool_name}.tool
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+  maps_to:
+    - src/plugins/tools/{tool_name}/tool.py
+    - tests/plugins/tools/{tool_name}/test_tool.py
+---
+
+# `src/plugins/tools/{tool_name}/tool.py` 詳細設計
+
+## 概要
+
+| 項目 | 内容 |
+|------|------|
+| ツール名 | {ツール名} |
+| 責務 | {ツールが果たす役割} |
+| 使用するエージェント | {エージェント名} |
+| カテゴリ | {計算/検索/変換/その他} |
+
+## 入力
+
+| パラメータ名 | 型 | 必須 | 説明 | 制約 |
+|------------|----|------|------|------|
+| **{パラメータ名}** | {型} | {○/×} | {説明} | {制約条件} |
+
+## 出力
+
+| フィールド名 | 型 | 説明 |
+|------------|----|------|
+| **{フィールド名}** | {型} | {説明} |
+
+## 処理内容
+
+1. {処理ステップ1}
+2. {処理ステップ2}
+3. {処理ステップ3}
+
+## エラーケース
+
+| エラーケース | 発生条件 | 対応方法 |
+|------------|---------|---------|
+| **{エラーケース}** | {発生条件} | {対応方法} |
+
+## テスト観点
+
+- 正常系の入出力
+- エラー時の戻り値または例外
+- 外部依存の失敗時の扱い

package/spec-runner/templates/.github/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ではない
+```
+
+ユーザーの許可なしに例外はない。