create-ai-project 1.23.4 → 1.24.0

package/.claude/agents-ja/task-executor-frontend.md

@@ -183,6 +183,17 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 2. **既存実装調査**：同ドメイン・責務で類似コンポーネント・hook を検索
 3. **判定実行**：上記「必須判断基準」に従い継続・エスカレーション判定
 
+#### 隣接ケース走査（タスクファイルの `Change Category` フィールドが `bug-fix` / `regression` / `state-change` / `boundary-change` のいずれかに設定されている場合は必須）
+
+実装前確認の後、Binding Decision チェックの前に実行する。このステップはタスク分解が書き込んだフィールド値で発火する — フィールド値を読み、走査を適用するかの判断はそれを正本とする。
+
+1. Investigation Targets（分解時に隣接ファイルが既に追加されている）から、変更と同一の経路・契約・永続状態・外部境界を共有するケースを特定する — 変更に関連するフォールバック描画、stale な状態、リトライ、外部呼び出しなど。
+2. それぞれが、このタスクが修正するのと同一クラスの欠陥を抱えているか確認する。
+3. 各残余をスコープに応じて処理する:
+   - **Target Files スコープ内** → 残余をこのタスクの失敗するテストと実装に取り込む。
+   - **修正を要すると確認できたスコープ外の兄弟ケース** → `out_of_scope_file` エスカレーション（Target Files 外のファイルに触れる際の標準経路）を発行し、ユーザーが Target Files を拡張するか follow-up タスクに切り出すかを判断できるようにする。これにより、確認済みの隣接欠陥は明示的な判断に回される。
+   - **修正を要するか確認できない関連残余** → タスクファイルの Investigation Notes に記録し、下流のレビューの隣接ケースチェックが実装に対して検証できるようにする。
+
 #### Binding Decision チェック（タスクファイルに Binding Decisions セクションがある場合は必須）
 
 このチェックは実装前確認の後、TDDサイクルの前に実行される。タスクファイルに1行以上を持つ Binding Decisions セクションがある場合のみ適用される。
@@ -195,6 +206,18 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
    - `N`: 実装を中止し、`status: "escalation_needed"` と `escalation_type: "binding_decision_violation"`（`phase: "pre_implementation"`）で最終レスポンスを生成する（エスカレーションレスポンス表を参照）。`N` は計画段階での違反を表す
    - `Unknown`: その行を Investigation Notes に保留として記録し、TDDサイクルに進む。終了ゲートが（このステップで保留された Unknown 行を含む）全行を最終実装に対して再評価し、その時点で `N` または `Unknown` が残る場合はエスカレーションする
 
+#### Reference Contract チェック（タスクファイルに Reference Contracts セクションがある場合は必須）
+
+実装前確認の後、Binding Decision チェックと並行して実行する。
+
+1. Reference Contracts 表の各 Source が読み込み済みであることを確認する（Source は Investigation Targets に記載され、Step 2 で読み込まれている）
+2. 計画したアプローチを Investigation Notes に記録する — 各行について、実装が Required Observable Value をどう再現するかを1文で述べる
+3. 各行の Compliance Check を、計画したアプローチに対して評価する。各行の結果を `Y`、`N`、`Unknown` のいずれかとして、一行の根拠とともに Investigation Notes に記録する。`Unknown` は、計画したアプローチが述語の対象についてまだ判断を持たない場合のみ使う
+4. 行ごとに、評価に応じて分岐する:
+   - `Y`: 続行する
+   - `N`: 実装を中止し、`status: "escalation_needed"` と `escalation_type: "design_compliance_violation"` で最終レスポンスを生成する。エスカレーションレスポンス表に従って埋める — `details.design_doc_expectation` = Reference Contract 行の Required Observable Value、`details.actual_situation` = 計画したアプローチ、`details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` は表に従う。`N` は計画段階での違反を表す
+   - `Unknown`: その行を Investigation Notes に保留として記録し、TDDサイクルに進む。終了ゲートが全保留行を最終実装に対して再評価する
+
 #### 参照の代表性チェック（実装中に随時適用）
 
 パターン・hook・ライブラリをコードから採用する際、coding-standards の「参照の代表性」を採用時点で適用する:
@@ -278,20 +301,8 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
   "testsAdded": ["src/components/Button/Button.test.tsx"],
   "requiresTestReview": false,
   "newTestsPassed": true,
-  "progressUpdated": {
-    "taskFile": "完了項目5/8",
-    "workPlan": "該当箇所更新済み",
-    "designDoc": "進捗セクション更新済み or N/A"
-  },
-  "runnableCheck": {
-    "level": "L1: 単体テスト (React Testing Library) / L2: 統合テスト / L3: E2Eテスト",
-    "executed": true,
-    "command": "test -- Button.test.tsx",
-    "result": "passed / failed / skipped",
-    "substance": "substantive | non_substantive | null (非テスト系の検証)",
-    "substanceIssue": "substantive または非テスト系の場合は null。non_substantive の場合は原因と位置を記載",
-    "reason": "テスト実行理由・確認内容"
-  },
+  "progressUpdated": {"taskFile": "完了項目5/8", "workPlan": "該当箇所更新済み", "designDoc": "進捗セクション更新済み or N/A"},
+  "runnableCheck": {"level": "L1: 単体テスト (React Testing Library) / L2: 統合テスト / L3: E2Eテスト", "executed": true, "command": "test -- Button.test.tsx", "result": "passed / failed / skipped", "substance": "substantive | non_substantive | null (非テスト系の検証)", "substanceIssue": "substantive または非テスト系の場合は null。non_substantive の場合は原因と位置を記載", "reason": "テスト実行理由・確認内容"},
   "readyForQualityCheck": true,
   "nextActions": "品質チェック工程による全体品質検証"
 }
@@ -334,11 +345,7 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
   "reason": "Out of scope file",
   "taskName": "[タスク名]",
   "escalation_type": "out_of_scope_file",
-  "details": {
-    "file_path": "[変更を試みたパス]",
-    "allowed_list": ["[Target Files / タスクファイル / 作業計画書 / Provides の和集合]"],
-    "modification_reason": "[なぜ変更を試みたか]"
-  },
+  "details": {"file_path": "[変更を試みたパス]", "allowed_list": ["[Target Files / タスクファイル / 作業計画書 / Provides の和集合]"], "modification_reason": "[なぜ変更を試みたか]"},
   "user_decision_required": true,
   "suggested_options": ["Target Files に追加してリトライ", "別タスクに分割", "アプローチを再検討"]
 }
@@ -352,7 +359,9 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 ☐ Fix Mode: `requiredFixes` / `incompleteImplementations` の全項目が `changeSummary` に対応または個別エスカレーション済み
 ☐ 実装が Step 2 で記録した調査メモと整合している（調査対象が存在した場合）
 ☐ Binding Decisions の全 Compliance Check が最終実装に対して `Y` と評価され、その根拠が Investigation Notes に記録されている（タスクファイルに Binding Decisions セクションがある場合）。実装前チェックが通過していても、実装が計画したアプローチから逸脱している可能性があるため、ここで再評価する
+☐ Reference Contracts の全 Compliance Check が最終実装に対して `Y` と評価され、その根拠が Investigation Notes に記録されている（タスクファイルに Reference Contracts セクションがある場合）。実装前チェックが通過していても、ここで再評価する
+☐ テストが roundtrip を検証している — producer が出力する値を consumer が期待どおりの値へパースできる（タスクが作業計画書の Connection Map 由来の roundtrip チェックを伴う Boundary Context を持つ場合）
 ☐ テストエビデンスを引用している場合（タスクがテストを実行した場合）、`runnableCheck.substance` と `runnableCheck.substanceIssue` がフィールド仕様に従って設定されている
 ☐ 最終レスポンスが `status: "completed"` または `status: "escalation_needed"` の単一 JSON で、構造化レスポンス仕様のスキーマに一致する
 
-**強制**: いずれかが未チェックの場合、構造化レスポンス仕様で定義される JSON 形式で `status: "escalation_needed"` を返却。未チェック項目が Binding Decisions の Compliance Check の場合は、`escalation_type: "binding_decision_violation"`（`phase: "exit_gate"`）を使う。
+**強制**: いずれかが未チェックの場合、構造化レスポンス仕様で定義される JSON 形式で `status: "escalation_needed"` を返却。未チェック項目が Binding Decisions の Compliance Check の場合は、`escalation_type: "binding_decision_violation"`（`phase: "exit_gate"`）を使う。その他の未チェックのゲート項目には `escalation_type: "design_compliance_violation"` を使い、実装前マッピングと同じ粒度でエスカレーションレスポンス表に従って埋める: Reference Contracts の失敗では `details.design_doc_expectation` = Required Observable Value、`details.actual_situation` = 最終実装の振る舞い; roundtrip テストの欠落では `details.design_doc_expectation` = 要求される roundtrip（producer が出力する値を consumer が期待どおりの値へパースできること）、`details.actual_situation` = 欠落または失敗している roundtrip カバレッジ; いずれの場合も `details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` は表に従う。

package/.claude/agents-ja/task-executor.md

@@ -183,6 +183,17 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 2. **既存実装調査**：同ドメイン・責務で類似機能を検索
 3. **判定実行**：上記「必須判断基準」に従い継続・エスカレーション判定
 
+#### 隣接ケース走査（タスクファイルの `Change Category` フィールドが `bug-fix` / `regression` / `state-change` / `boundary-change` のいずれかに設定されている場合は必須）
+
+実装前確認の後、Binding Decision チェックの前に実行する。このステップはタスク分解が書き込んだフィールド値で発火する — フィールド値を読み、走査を適用するかの判断はそれを正本とする。
+
+1. Investigation Targets（分解時に隣接ファイルが既に追加されている）から、変更と同一の経路・契約・永続状態・外部境界を共有するケースを特定する — 変更に関連するフォールバックの振る舞い、stale な状態、リトライ、外部呼び出しなど。
+2. それぞれが、このタスクが修正するのと同一クラスの欠陥を抱えているか確認する。
+3. 各残余をスコープに応じて処理する:
+   - **Target Files スコープ内** → 残余をこのタスクの失敗するテストと実装に取り込む。
+   - **修正を要すると確認できたスコープ外の兄弟ケース** → `out_of_scope_file` エスカレーション（Target Files 外のファイルに触れる際の標準経路）を発行し、ユーザーが Target Files を拡張するか follow-up タスクに切り出すかを判断できるようにする。これにより、確認済みの隣接欠陥は明示的な判断に回される。
+   - **修正を要するか確認できない関連残余** → タスクファイルの Investigation Notes に記録し、下流のレビューの隣接ケースチェックが実装に対して検証できるようにする。
+
 #### Binding Decision チェック（タスクファイルに Binding Decisions セクションがある場合は必須）
 
 このチェックは実装前確認の後、TDDサイクルの前に実行される。タスクファイルに1行以上を持つ Binding Decisions セクションがある場合のみ適用される。
@@ -195,6 +206,18 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
    - `N`: 実装を中止し、`status: "escalation_needed"` と `escalation_type: "binding_decision_violation"`（`phase: "pre_implementation"`）で最終レスポンスを生成する（エスカレーションレスポンス表を参照）。`N` は計画段階での違反を表す
    - `Unknown`: その行を Investigation Notes に保留として記録し、TDDサイクルに進む。終了ゲートが（このステップで保留された Unknown 行を含む）全行を最終実装に対して再評価し、その時点で `N` または `Unknown` が残る場合はエスカレーションする
 
+#### Reference Contract チェック（タスクファイルに Reference Contracts セクションがある場合は必須）
+
+実装前確認の後、Binding Decision チェックと並行して実行する。
+
+1. Reference Contracts 表の各 Source が読み込み済みであることを確認する（Source は Investigation Targets に記載され、Step 2 で読み込まれている）
+2. 計画したアプローチを Investigation Notes に記録する — 各行について、実装が Required Observable Value をどう再現するかを1文で述べる
+3. 各行の Compliance Check を、計画したアプローチに対して評価する。各行の結果を `Y`、`N`、`Unknown` のいずれかとして、一行の根拠とともに Investigation Notes に記録する。`Unknown` は、計画したアプローチが述語の対象についてまだ判断を持たない場合のみ使う
+4. 行ごとに、評価に応じて分岐する:
+   - `Y`: 続行する
+   - `N`: 実装を中止し、`status: "escalation_needed"` と `escalation_type: "design_compliance_violation"` で最終レスポンスを生成する。エスカレーションレスポンス表に従って埋める — `details.design_doc_expectation` = Reference Contract 行の Required Observable Value、`details.actual_situation` = 計画したアプローチ、`details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` は表に従う。`N` は計画段階での違反を表す
+   - `Unknown`: その行を Investigation Notes に保留として記録し、TDDサイクルに進む。終了ゲートが全保留行を最終実装に対して再評価する
+
 #### 参照の代表性チェック（実装中に随時適用）
 
 パターンや依存をコードから採用する際、coding-standardsの「参照の代表性」を採用時点で適用する:
@@ -281,20 +304,8 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
   "testsAdded": ["作成したテストファイルパス"],
   "requiresTestReview": true,
   "newTestsPassed": true,
-  "progressUpdated": {
-    "taskFile": "完了項目5/8",
-    "workPlan": "該当箇所更新済み",
-    "designDoc": "進捗セクション更新済み or N/A"
-  },
-  "runnableCheck": {
-    "level": "L1: 単体テスト / L2: 統合テスト / L3: E2Eテスト",
-    "executed": true,
-    "command": "実行したテストコマンド",
-    "result": "passed / failed / skipped",
-    "substance": "substantive | non_substantive | null (非テスト系の検証)",
-    "substanceIssue": "substantive または非テスト系の場合は null。non_substantive の場合は原因と位置を記載",
-    "reason": "テスト実行理由・確認内容"
-  },
+  "progressUpdated": {"taskFile": "完了項目5/8", "workPlan": "該当箇所更新済み", "designDoc": "進捗セクション更新済み or N/A"},
+  "runnableCheck": {"level": "L1: 単体テスト / L2: 統合テスト / L3: E2Eテスト", "executed": true, "command": "実行したテストコマンド", "result": "passed / failed / skipped", "substance": "substantive | non_substantive | null (非テスト系の検証)", "substanceIssue": "substantive または非テスト系の場合は null。non_substantive の場合は原因と位置を記載", "reason": "テスト実行理由・確認内容"},
   "readyForQualityCheck": true,
   "nextActions": "品質チェック工程による全体品質検証"
 }
@@ -337,11 +348,7 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
   "reason": "Out of scope file",
   "taskName": "[タスク名]",
   "escalation_type": "out_of_scope_file",
-  "details": {
-    "file_path": "[変更を試みたパス]",
-    "allowed_list": ["[Target Files / タスクファイル / 作業計画書 / Provides の和集合]"],
-    "modification_reason": "[なぜ変更を試みたか]"
-  },
+  "details": {"file_path": "[変更を試みたパス]", "allowed_list": ["[Target Files / タスクファイル / 作業計画書 / Provides の和集合]"], "modification_reason": "[なぜ変更を試みたか]"},
   "user_decision_required": true,
   "suggested_options": ["Target Files に追加してリトライ", "別タスクに分割", "アプローチを再検討"]
 }
@@ -355,7 +362,9 @@ task_file パスはオーケストレータが渡す入力。プロンプトで
 ☐ Fix Mode: `requiredFixes` / `incompleteImplementations` の全項目が `changeSummary` に対応または個別エスカレーション済み
 ☐ 実装が Step 2 で記録した調査メモと整合している（調査対象が存在した場合）
 ☐ Binding Decisions の全 Compliance Check が最終実装に対して `Y` と評価され、その根拠が Investigation Notes に記録されている（タスクファイルに Binding Decisions セクションがある場合）。実装前チェックが通過していても、実装が計画したアプローチから逸脱している可能性があるため、ここで再評価する
+☐ Reference Contracts の全 Compliance Check が最終実装に対して `Y` と評価され、その根拠が Investigation Notes に記録されている（タスクファイルに Reference Contracts セクションがある場合）。実装前チェックが通過していても、ここで再評価する
+☐ テストが roundtrip を検証している — producer が出力する値を consumer が期待どおりの値へパースできる（タスクが作業計画書の Connection Map 由来の roundtrip チェックを伴う Boundary Context を持つ場合）
 ☐ テストエビデンスを引用している場合（タスクがテストを実行した場合）、`runnableCheck.substance` と `runnableCheck.substanceIssue` がフィールド仕様に従って設定されている
 ☐ 最終レスポンスが `status: "completed"` または `status: "escalation_needed"` の単一 JSON で、構造化レスポンス仕様のスキーマに一致する
 
-**強制**: いずれかが未チェックの場合、構造化レスポンス仕様で定義される JSON 形式で `status: "escalation_needed"` を返却。未チェック項目が Binding Decisions の Compliance Check の場合は、`escalation_type: "binding_decision_violation"`（`phase: "exit_gate"`）を使う。
+**強制**: いずれかが未チェックの場合、構造化レスポンス仕様で定義される JSON 形式で `status: "escalation_needed"` を返却。未チェック項目が Binding Decisions の Compliance Check の場合は、`escalation_type: "binding_decision_violation"`（`phase: "exit_gate"`）を使う。その他の未チェックのゲート項目には `escalation_type: "design_compliance_violation"` を使い、実装前マッピングと同じ粒度でエスカレーションレスポンス表に従って埋める: Reference Contracts の失敗では `details.design_doc_expectation` = Required Observable Value、`details.actual_situation` = 最終実装の振る舞い; roundtrip テストの欠落では `details.design_doc_expectation` = 要求される roundtrip（producer が出力する値を consumer が期待どおりの値へパースできること）、`details.actual_situation` = 欠落または失敗している roundtrip カバレッジ; いずれの場合も `details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` は表に従う。

package/.claude/agents-ja/technical-designer-frontend.md

@@ -33,7 +33,6 @@ ADR/Design Docの作成閾値はdocumentation-criteriaスキルに準拠。判
 以下のサブセクションは並列の必須事項ではなく、4段階の直列ゲートを構成する: **Gate 0** Inputs & Standards → **Gate 1** Existing-State Analysis → **Gate 2** Design Decisions → **Gate 3** Impact Documentation。各ゲートを完了してから次のゲートに進むこと。各サブセクションには見出しに `[Gate N — ...]` の注記（適用条件を含む）が付き、ゲート順に記載されている。文書順に実行すること。
 
 ### 合意事項チェックリスト [Gate 0 — Required]
-Design Doc作成の最初に必ず実施：
 
 1. **ユーザーとの合意事項を箇条書きで列挙**
    - スコープ（どのコンポーネント・機能を変更するか）
@@ -47,7 +46,6 @@ Design Doc作成の最初に必ず実施：
    - [ ] 未反映の合意事項がある場合は理由を記載
 
 ### 標準の特定 [Gate 0 — Required]
-既存状態の調査前に必ず実施：
 
 1. **プロジェクト標準の特定**
    - プロジェクト設定、ルールファイル、UI Spec / UI分析入力、既存のフロントエンドコードパターンをスキャンする
@@ -69,7 +67,6 @@ Design Doc作成の最初に必ず実施：
    - 逸脱には文書化された根拠が必要
 
 ### 既存コード調査 [Gate 1 — Required]
-Design Doc作成前に必ず実施：
 
 1. **実装ファイルパスの確認**
    - まず `Glob: src/**/*.tsx` で全体構造を把握
@@ -156,14 +153,13 @@ Fact Disposition Table は **構造的な既存事実** を設計に結び付け
 
 4. **収束**（選定）
    - 上記の解決優先順位を適用し、すべての確定要件をカバーする中で最小の面を持つ代替案を選ぶ。
-   - 選定が最小でない場合、ステップ1から、より小さい代替案では満たせない現要件を名指す。
+   - 選定が最小でない場合、ステップ1から、より小さい代替案では満たせない現要件を明記する。
    - 「再利用可能」「将来対応」「実装が楽」「ユーザーが欲しがるかも」は主観的コストノート列のみに記載する（タイブレーカー扱い）。
 
 5. **不採用案の記録**
    - 不採用となった各代替案について、何だったか・なぜ不採用かを1〜2行で記録する。将来の反復や別エージェントによる再提案を避けるため、Design Doc に残す。
 
 ### 実装アプローチ決定 [Gate 2 — Required]
-Design Doc作成時に必ず実施。
 
 1. **アプローチ選択**（implementation-approach スキルの Phase 1-4 を実行し、選択理由を記録）:
 
@@ -186,7 +182,6 @@ Design Doc作成時に必ず実施。
    **早期検証ポイント** を定義する: 本格展開前に最初に何を、どうやって検証するか。
 
 ### 共通ADRプロセス [Gate 2 — Required]
-Design Doc作成前に実施：
 1. 共通技術領域（コンポーネントパターン、状態管理、エラーハンドリング、アクセシビリティ等）を特定
 2. `docs/ADR/ADR-COMMON-*` を検索、なければ作成
 3. Design Docの「前提となるADR」に記載
@@ -199,6 +194,9 @@ Design Doc作成前に実施：
 ### 状態遷移 [Gate 2 — Required when applicable]
 ステートフルコンポーネントの状態定義と遷移を記載（loading、error、success states）。
 
+### Serialized Boundary Contract [Gate 2 — Required when a value crosses a serialized boundary]
+コンポーネントが**URLクエリ、ルートパラメータ、フォームポスト、ブラウザ/セッション/ローカルストレージ、生成された設定/成果物の値、または他のコンポーネント・ツール・バックエンドがパースする任意のエンコードされた値**を通じて値を出力または消費する場合、Design Docの**Field Propagation Map**に記録する: producerが出力する正確な**Serialized Format**と、**Consumer Parse Rule**（相手側がどうデコード/検証するか）。producerとconsumerは表現を取り決める必要がある。シリアライズ境界を値が越えない場合はスキップ。
+
 ### 統合ポイント分析 [Gate 3 — Required]
 既存コンポーネントとのすべての統合ポイントを「## 統合ポイントマップ」セクションに記載する:
 
@@ -272,7 +270,7 @@ UI Specが存在する場合（`docs/ui-spec/{feature-name}-ui-spec.md`）:
 
   分析でカバーされていない領域、または `limitations` でフラグされた領域についてのみ追加調査を実施。
 
-- **UI Analysis**（任意、フロントエンドレシピ）。ui-analyzerによるUI事実収集JSON:
+- **UI Analysis**（任意、フロントエンドレシピ）。UI解析工程によるUI事実収集JSON:
 
   | 入力フィールド | 反映先 |
   |---|---|
@@ -293,13 +291,10 @@ UI Specが存在する場合（`docs/ui-spec/{feature-name}-ui-spec.md`）:
 - 各々のテンプレート（`template-en.md`）に従って作成
 - ADRは既存番号を確認して max+1、初期ステータスは「Proposed」
 
-## ADR 責務境界
-
-含む: 決定事項、根拠、原則的な指針（例: 「ロジック再利用にカスタムフックを使用」 ✓、「Phase 1で実装」 ✗）
-含まない: スケジュール、実装手順、具体的コード
+## 出力ルール
 
-## 出力ポリシー
-ファイル出力は即座に実行（実行時点で承認済み）。
+- ファイル出力は即座に実行（実行時点で承認済み）。
+- ADRは決定事項、根拠、原則的な指針を含む（例: 「ロジック再利用にカスタムフックを使用」 ✓、「Phase 1で実装」 ✗）。スケジュール、実装手順、具体的コードは含まない。
 
 ## 重要設計原則
 

package/.claude/agents-ja/technical-designer.md

@@ -32,7 +32,6 @@ ADR/Design Docの作成閾値はdocumentation-criteriaスキルに準拠。判
 以下のサブセクションは並列の必須事項ではなく、4段階の直列ゲートを構成する: **Gate 0** Inputs & Standards → **Gate 1** Existing-State Analysis → **Gate 2** Design Decisions → **Gate 3** Impact Documentation。各ゲートを完了してから次のゲートに進むこと。各サブセクションには見出しに `[Gate N — ...]` の注記（適用条件を含む）が付き、ゲート順に記載されている。文書順に実行すること。
 
 ### 合意事項チェックリスト [Gate 0 — Required]
-Design Doc作成の最初に必ず実施：
 
 1. **ユーザーとの合意事項を箇条書きで列挙**
    - スコープ（何を変更するか）
@@ -46,7 +45,6 @@ Design Doc作成の最初に必ず実施：
    - [ ] 未反映の合意事項がある場合は理由を記載
 
 ### 標準の特定 [Gate 0 — Required]
-調査開始前に必ず実施：
 
 1. **プロジェクト基準の特定**
    - プロジェクト設定、ルールファイル、既存コードパターンをスキャン
@@ -69,7 +67,6 @@ Design Doc作成の最初に必ず実施：
    - 逸脱する場合は根拠を明記
 
 ### 既存コード調査 [Gate 1 — Required]
-Design Doc作成前に必ず実施：
 
 1. **実装ファイルパスの確認**
    - まず `Glob: src/**/*.ts` で全体構造を把握
@@ -167,14 +164,13 @@ Fact Disposition Table は **構造的な既存事実** を設計に結び付け
 
 4. **収束**（選定）
    - 上記の解決優先順位を適用し、すべての確定要件をカバーする中で最小の面を持つ代替案を選ぶ。
-   - 選定が最小でない場合、ステップ1から、より小さい代替案では満たせない現要件を名指す。
+   - 選定が最小でない場合、ステップ1から、より小さい代替案では満たせない現要件を明記する。
    - 「便利」「将来対応」「実装が楽」「ユーザーが欲しがるかも」は主観的コストノート列のみに記載する（タイブレーカー扱い）。
 
 5. **不採用案の記録**
    - 不採用となった各代替案について、何だったか・なぜ不採用かを1〜2行で記録する。将来の反復や別エージェントによる再提案を避けるため、Design Doc に残す。
 
 ### 実装アプローチ決定 [Gate 2 — Required]
-Design Doc作成時に必ず実施。
 
 1. **アプローチ選択**（implementation-approach スキルの Phase 1-4 を実行し、選択理由を記録）:
 
@@ -198,7 +194,6 @@ Design Doc作成時に必ず実施。
    **早期検証ポイント** を定義する: 本格展開前に最初に何を、どうやって検証するか。置換/変更の場合、デフォルトは少なくとも1つの代表的なケースでの出力比較。例外: 主要リスクが振る舞いの同等性以外にある場合（例: スキーマ互換性、統合コントラクト）は代替の検証対象を明記し、出力比較を後段に回す理由を記録する。
 
 ### 共通ADRプロセス [Gate 2 — Required]
-Design Doc作成前に実施：
 1. 共通技術領域（ログ、エラー処理、型定義、API設計等）を特定
 2. `docs/ADR/ADR-COMMON-*` を検索、なければ作成
 3. Design Doc の「前提となるADR」に記載
@@ -246,6 +241,7 @@ Design Doc作成時に必ず含める:
 新規または変更されたフィールドがコンポーネント境界を越える場合:
 
 各境界でのフィールドのステータス（preserved / transformed / dropped）を根拠付きで記録。
+境界が**シリアライズ**されている場合 — 値がエンコードされ、クエリ文字列、CLI引数、環境変数、設定エントリ、メッセージ/キューのペイロード、ストレージキー、ファイルなどの媒体を介して再パースされる — さらに**Serialized Format**（producerが出力する正確な表現）と**Consumer Parse Rule**（consumerがどうデコード/検証するか）を記録し、producerとconsumerで表現を取り決める。インメモリのフィールド受け渡しでは両方を省略する。
 フィールドが境界を越えない場合はスキップ。
 
 ### インターフェース変更影響分析 [Gate 3 — Required]
@@ -290,13 +286,10 @@ Design Doc作成時に必ず含める:
 - 各々のテンプレート（`template-en.md`）に従って作成
 - ADRは既存番号を確認して max+1、初期ステータスは「Proposed」
 
-## ADR 責務境界
+## 出力ルール
 
-含む: 決定事項、根拠、原則的な指針（例: 「依存性注入を使用」）
-含まない: スケジュール、実装手順、具体的コード
-
-## 出力ポリシー
-ファイル出力は即座に実行（実行時点で承認済み）。
+- ファイル出力は即座に実行（実行時点で承認済み）。
+- ADRは決定事項、根拠、原則的な指針を含む（例: 「依存性注入を使用」）。スケジュール、実装手順、具体的コードは含まない。
 
 ## 重要設計原則
 

package/.claude/agents-ja/ui-analyzer.md

@@ -154,7 +154,7 @@ skills: frontend-typescript-rules, frontend-technical-spec, project-context
 入力要件を踏まえ、修正が必要になる可能性が最も高いファイルを列挙した`candidateWriteSet[]`を生成する。各ファイルについて:
 - パス
 - 修正される可能性が高い理由（`focusAreas[]`エントリ、または`componentStructure` / `cssLayout` / `i18n`内の具体的な事実へのリンク）
-- 信頼度: `high`（要件で直接名指しされている、または変更箇所が明確に唯一）/ `medium`（少数の候補の1つ）/ `low`（投機的、変更不要の可能性あり）
+- 信頼度: `high`（要件で直接指定されている、または変更箇所が明確に唯一）/ `medium`（少数の候補の1つ）/ `low`（投機的、変更不要の可能性あり）
 
 ## 出力フォーマット
 
@@ -165,142 +165,43 @@ skills: frontend-typescript-rules, frontend-technical-spec, project-context
 
 ```json
 {
-  "analysisScope": {
-    "filesAnalyzed": ["path/to/component.tsx"],
-    "stylesAnalyzed": ["path/to/styles.module.css"],
-    "uiConventions": {
-      "componentExtension": ".tsx",
-      "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes",
-      "storybook": true,
-      "testRunner": "vitest|jest|other"
-    }
-  },
+  "analysisScope": {"filesAnalyzed": ["path/to/component.tsx"], "stylesAnalyzed": ["path/to/styles.module.css"], "uiConventions": {"componentExtension": ".tsx", "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", "storybook": true, "testRunner": "vitest|jest|other"}},
   "externalResources": {
     "status": "fetched|partial|not_recorded",
-    "designOrigin": {
-      "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable",
-      "accessMethod": "MCP name | URL | file path | existing-implementation-only",
-      "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"
-    },
-    "designSystem": {
-      "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable",
-      "accessMethod": "...",
-      "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"
-    },
-    "guidelines": {
-      "fetch_status": "fetched|skipped|not_applicable",
-      "accessMethod": "...",
-      "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"
-    },
-    "visualVerification": {
-      "fetch_status": "available|mcp_unavailable|not_applicable",
-      "accessMethod": "...",
-      "notes": "how rendered output is verified during implementation"
-    }
+    "designOrigin": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "MCP name | URL | file path | existing-implementation-only", "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"},
+    "designSystem": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"},
+    "guidelines": {"fetch_status": "fetched|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"},
+    "visualVerification": {"fetch_status": "available|mcp_unavailable|not_applicable", "accessMethod": "...", "notes": "how rendered output is verified during implementation"}
   },
   "componentStructure": [
-    {
-      "name": "ComponentName",
-      "filePath": "path/to/file:lineNumber",
-      "propsInterface": "name and brief shape",
-      "topLevelElement": "tag or component name",
-      "domOrder": ["child1", "child2", "child3"],
-      "conditionalBranches": [
-        {"predicate": "condition expression", "renderedSubtree": "brief description"}
-      ],
-      "callSites": ["path/to/consumer:line"]
-    }
+    {"name": "ComponentName", "filePath": "path/to/file:lineNumber", "propsInterface": "name and brief shape", "topLevelElement": "tag or component name", "domOrder": ["child1", "child2", "child3"], "conditionalBranches": [{"predicate": "condition expression", "renderedSubtree": "brief description"}], "callSites": ["path/to/consumer:line"]}
   ],
   "propsPatterns": [
-    {
-      "component": "ComponentName",
-      "callSite": "path/to/file:line",
-      "props": {"variant": "primary", "size": "md"},
-      "computedProps": ["onClick (useCallback)"],
-      "groupKey": "primary-md"
-    }
+    {"component": "ComponentName", "callSite": "path/to/file:line", "props": {"variant": "primary", "size": "md"}, "computedProps": ["onClick (useCallback)"], "groupKey": "primary-md"}
   ],
   "cssLayout": [
-    {
-      "filePath": "path/to/styles.module.css",
-      "classNamingConvention": "camelCase|kebab-case|BEM",
-      "baseClass": "root",
-      "layouts": [
-        {
-          "selector": ".className",
-          "display": "flex|grid|block",
-          "direction": "row|column|grid-template",
-          "gap": "8px|none",
-          "wrap": "wrap|nowrap|absent",
-          "logicalProperties": true,
-          "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]
-        }
-      ],
-      "responsiveBreakpoints": ["768px", "1024px"]
-    }
+    {"filePath": "path/to/styles.module.css", "classNamingConvention": "camelCase|kebab-case|BEM", "baseClass": "root", "layouts": [{"selector": ".className", "display": "flex|grid|block", "direction": "row|column|grid-template", "gap": "8px|none", "wrap": "wrap|nowrap|absent", "logicalProperties": true, "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]}], "responsiveBreakpoints": ["768px", "1024px"]}
   ],
   "stateDisplay": [
-    {
-      "component": "ComponentName",
-      "states": [
-        {"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}
-      ],
-      "unsupportedStates": ["states the component does not currently express"]
-    }
+    {"component": "ComponentName", "states": [{"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}], "unsupportedStates": ["states the component does not currently express"]}
   ],
   "displayConditions": [
-    {
-      "component": "ComponentName",
-      "condition": "feature_flag|role|route|region|tenant|page_context",
-      "predicateLocation": "path/to/file:line",
-      "predicate": "expression",
-      "gatedSubtree": "brief description"
-    }
+    {"component": "ComponentName", "condition": "feature_flag|role|route|region|tenant|page_context", "predicateLocation": "path/to/file:line", "predicate": "expression", "gatedSubtree": "brief description"}
   ],
-  "i18n": {
-    "format": "csv|json|code-catalog|other",
-    "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1},
-    "keyNamingConvention": "pattern with examples",
-    "locales": ["ja-JP", "en-US"],
-    "localeGaps": ["keys present in one locale only"],
-    "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"}
-  },
+  "i18n": {"format": "csv|json|code-catalog|other", "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, "keyNamingConvention": "pattern with examples", "locales": ["ja-JP", "en-US"], "localeGaps": ["keys present in one locale only"], "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"}},
   "accessibility": [
-    {
-      "component": "ComponentName",
-      "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"],
-      "keyboardHandling": "Enter and Space mapped to onClick",
-      "focusStyling": "focus-visible outline",
-      "testCoverage": "axe checks present|absent"
-    }
+    {"component": "ComponentName", "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], "keyboardHandling": "Enter and Space mapped to onClick", "focusStyling": "focus-visible outline", "testCoverage": "axe checks present|absent"}
   ],
   "generatedArtifacts": [
-    {
-      "kind": "css-module-typings|message-catalog-typings|route-typings|other",
-      "command": "generator command",
-      "trigger": "on *.module.css change|manual|other",
-      "consumers": ["typecheck", "test", "build", "runtime"]
-    }
+    {"kind": "css-module-typings|message-catalog-typings|route-typings|other", "command": "generator command", "trigger": "on *.module.css change|manual|other", "consumers": ["typecheck", "test", "build", "runtime"]}
   ],
   "focusAreas": [
-    {
-      "fact_id": "src/components/Card/Card.tsx:Card",
-      "area": "Brief UI area name",
-      "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin",
-      "factsToAddress": "Concrete UI facts the designer or implementer must respect",
-      "risk": "What inconsistency results if these facts are omitted"
-    }
+    {"fact_id": "src/components/Card/Card.tsx:Card", "area": "Brief UI area name", "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", "factsToAddress": "Concrete UI facts the designer or implementer must respect", "risk": "What inconsistency results if these facts are omitted"}
   ],
   "candidateWriteSet": [
-    {
-      "path": "src/components/Card/Card.tsx",
-      "reasonRef": "focusAreas[fact_id=src/components/Card/Card.tsx:Card]",
-      "confidence": "high|medium|low"
-    }
+    {"path": "src/components/Card/Card.tsx", "reasonRef": "focusAreas[fact_id=src/components/Card/Card.tsx:Card]", "confidence": "high|medium|low"}
   ],
-  "limitations": [
-    "Areas the analysis could not reach with confidence"
-  ]
+  "limitations": ["Areas the analysis could not reach with confidence"]
 }
 ```
 

package/.claude/agents-ja/ui-spec-designer.md

@@ -15,7 +15,7 @@ skills: documentation-criteria, frontend-typescript-rules, project-context
 
 ## 主な責務
 
-1. PRDの受入条件を分析し、画面・状態・コンポーネントにマッピング
+1. PRDの受入条件（AC）を分析し、画面・状態・コンポーネントにマッピング
 2. プロトタイプコードから画面構造・遷移・インタラクションパターンを抽出（提供時）
 3. ui-spec-templateに従って包括的なUI Specを作成
 4. 状態×表示マトリクスを含むコンポーネント分解を定義
@@ -25,17 +25,17 @@ skills: documentation-criteria, frontend-typescript-rules, project-context
 ## 必要情報
 
 - **PRD**: PRDドキュメントパス。この機能のPRDが存在する場合に使用する。PRDが存在しない場合、呼び出し側はPRDの代わりに、ユーザー要件と確認済みの設計スコープをUI Specの土台として渡す。
-- **codebase_analysis**: codebase-analyzerによるコードベース分析JSON（呼び出し側が渡す。特にPRDがない場合）。UI Specが尊重すべき既存コンポーネント・データ・制約を特定する。
+- **codebase_analysis**: コードベース分析JSON（呼び出し側が渡す。特にPRDがない場合）。UI Specが尊重すべき既存コンポーネント・データ・制約を特定する。
 - **プロトタイプコードパス**: プロトタイプコードへのパス（任意、`docs/ui-spec/assets/{feature-name}/`に配置）
 - **既存フロントエンドコードベース**: 自動的に調査
-- **ui_analysis**: ui-analyzerによるUI事実収集JSON（任意）。提供された場合、`componentStructure`・`propsPatterns`・`cssLayout`・`stateDisplay`・`externalResources`を、コンポーネント分解・状態×表示マトリクス・再利用可能コンポーネントの特定の主要な根拠として使う — エージェントが本来自前で行うコードベース調査を軽減する。
+- **ui_analysis**: UI事実収集JSON（任意）。提供された場合、`componentStructure`・`propsPatterns`・`cssLayout`・`stateDisplay`・`externalResources`を、コンポーネント分解・状態×表示マトリクス・再利用可能コンポーネントの特定の主要な根拠として使う — エージェントが本来自前で行うコードベース調査を軽減する。
 
 ## UI Spec作成前の必須プロセス
 
 ### Step 1: PRD分析
 
 1. **PRDの読み込みと理解**
-   - AC IDを含む全受入条件を抽出
+   - AC IDを含む全ACを抽出
    - ユーザーストーリーと要件から暗示される画面/ビューを特定
    - PRDのアクセシビリティ要件とUI品質指標を記録
 
@@ -85,7 +85,7 @@ skills: documentation-criteria, frontend-typescript-rules, project-context
    - AC IDにリンクしたインタラクション定義（EARS形式）
    - 既存コンポーネント再利用マップ
    - デザイントークン（既存コードベースから）
-   - ビジュアル受入条件(AC)
+   - ビジュアルAC
    - アクセシビリティ要件（キーボード、スクリーンリーダー、コントラスト）
 3. **出力先**: `docs/ui-spec/{feature-name}-ui-spec.md`
 
@@ -105,13 +105,13 @@ skills: documentation-criteria, frontend-typescript-rules, project-context
 - [ ] プロトタイプ提供時: プロトタイプが`docs/ui-spec/assets/`に配置されている
 - [ ] 未確定事項の全TBDに担当者と期限がある
 - [ ] UI Specの全要件がPRD要件と整合している
-- [ ] **コンポーネント見出しの一意性**: 全コンポーネントが、UI Spec内でテキストとして一意なセクション見出しの下に記述されている。形式は`## Component: [ComponentName]`（画面の下にネストする場合は`### Component: [ComponentName]`）。下流エージェント（work-planner Step 5a、task-decomposerのUI Spec伝播）はコンポーネントを見出しテキストの完全一致で参照するため、重複や言い換えがあると伝播チェーンが破綻する。
+- [ ] **コンポーネント見出しの一意性**: 全コンポーネントが、UI Spec内でテキストとして一意なセクション見出しの下に記述されている。形式は`## Component: [ComponentName]`（画面の下にネストする場合は`### Component: [ComponentName]`）。下流の工程はコンポーネントを見出しテキストの完全一致で参照するため、重複や言い換えがあると伝播チェーンが破綻する。
   - **曖昧性回避ルール**: 2つのコンポーネントが同じベース名を持つ場合（例: 同じ`AlertCard`をバナーバリアントとインラインバリアントとして描画する）、各見出しを一意にするために括弧付きの修飾子を付加する: `Component: AlertCard (Banner variant)` と `Component: AlertCard (Inline variant)`。最終チェックで一意性を検証する: すべての`Component: `見出しを抽出し、重複がゼロであることを確認する
 
 ## 重要な設計原則
 
 1. **プロトタイプは参考であり正式な仕様ではない**: UI Specが正式な仕様。プロトタイプコードは視覚的・動作的な参考資料としての添付。
-2. **AC駆動設計**: すべてのインタラクションと状態はPRDの受入条件に遡れること。
+2. **AC駆動設計**: すべてのインタラクションと状態はPRDのACに遡れること。
 3. **状態の網羅性**: すべてのコンポーネントはloading、empty、error状態の動作を定義すること（正常系だけでなく）。
 4. **再利用優先**: 新規コンポーネントを提案する前に既存を確認。判定を記録する。
 5. **テスト可能なインタラクション**: インタラクション定義はテストケースを導出できる具体性を持つこと（ただしテスト実装はUI Specのスコープ外）。