開発仕様書作成 汎用プロンプト

使い方

推奨: スクリプトパイプライン経由（高品質・自動化）

Gemini アーキテクト推論 + Claude 添削 → Claude Code 自律実行のパイプラインで、手動より高品質な仕様書が生成できる。通常はこちらを使う。

# Step 1: Gemini がアーキテクト推論 → Claude が添削 → tasks/prompts/task_MAS-XXX.md を生成
TASK_IDS=MAS-XXX node scripts/B2_generate_prompts_gemini.js

# Step 2: Claude Code がプロンプトを読んで仕様書を自律作成
scripts/B3_run_writers.sh -i MAS-XXX
# → docs/dev/dev_mas-xxx_<slug>.md + _config.json 登録まで完了

# Step 3: Gemini がアーキテクト目線で仕様書をレビュー → tasks/reviews/<timestamp>_gemini_review.md を生成
SPEC_FILES="dev_mas-xxx_<slug>.md" node scripts/B5_review_specs_by_gemini.js

前提条件:

• .env に GEMINI_API_KEY が設定済みであること
• docs/_internal/todo_master_tables.md に対象案件の「未着手」行があること（スクリプト1が参照）
• claude CLI が利用可能であること（スクリプト1の Claude 添削工程で使用）

手動経路（スクリプト利用不可・緊急時のフォールバック）

仕様書を作成する場合、以下の 2 通りから選択する:

• A. メタプロンプト経由（推奨）: ## メタプロンプト を Claude Code に貼り付け → 案件IDを入力 → 案件固有のプロンプト案が生成される → そのプロンプト案で仕様書を生成
• B. 汎用プロンプト直用: ## プロンプト本文 を Claude Code に貼り付け → 案件IDを入力 → 案件IDから自動的に todo_master_tables.md を参照し仕様書を生成

複雑な案件（マッチングロジック・複数ファイル横断等）はメタプロンプト経由を強く推奨。

前提条件（手動経路）

• 作業用ブランチが作成済みであること（命名例: docs/dev-{ISSUE_ID}）
• 未作成の場合は以下を実行してから開始:

  git checkout main && git pull origin main
  git checkout -b docs/dev-{ISSUE_ID}
  

目次

メタプロンプト: 仕様書作成プロンプトの自動生成

↑ トップに戻る

概要

案件IDを入力するだけで、Claude Code に「高品質な開発仕様書」を作成させるための指示プロンプトを自動生成するメタプロンプトです。汎用プロンプト（上記）をそのまま使うよりも、案件固有の設計要件・エッジケース・関連ファイルを事前に分析した上で、より精度の高いプロンプトを生成できます。

使い方

1. メタプロンプト本文をそのまま Claude Code に貼り付けて実行
2. 実行後に案件IDを聞かれるので入力（例: I-02）
3. 出力されたプロンプト案をレビューし、必要に応じて修正
4. 修正後のプロンプトを Claude Code（別セッションまたは同一セッション）に投入して仕様書を生成

メタプロンプト本文

あなたはGAS会計システム(bizlp-gas-accounting)のシニアアーキテクトです。
まず最初に、対象の案件IDをユーザーに質問してください（例: MAS-146, MAS-085 など）。
ユーザーが回答した案件IDを {ISSUE_ID} として使用し、
Claude Code に「高品質な開発仕様書」を作成させるための指示プロンプト案を作成してください。

以下のステップに従って自律的に分析を行い、最終的なプロンプト案を出力してください。

## Step 1: 案件の要件分析

`docs/_internal/TODO_future.md` を検索し、指定された案件IDの
「案件名」「概要」「期待される効果」「人間が検討すべき事項」を特定・把握してください。

## Step 2: 関連ファイル・類似機能の特定

Step 1 の分析結果をもとに、この案件を設計する上で Claude Code が
事前に読み込むべきファイルを特定してください。

- 類似機能の仕様書（完成度の参考になるもの）
- 影響を受ける既存のロジック（関数、クラス）
- 関連するデータアクセス層（`003_contracts.js` の DTO、`202_repository.js` の Repository）
- 関連する定数やマスタ（`002_constants.js`、`101_sys_config.js`）
- MCP で事前確認すべきマスタデータ（DDLコード値 vs 実データの乖離チェック）

## Step 3: 固有の設計要件とエッジケースの洗い出し

Claude Code が仕様書を書く際に「考慮漏れ」や「車輪の再発明」を起こさないよう、
プロンプトに含めるべき以下の項目を洗い出してください。

【数値要件（v1.9 で明文化・必ず遵守）】
- 各 Step の「アーキテクトからの指示」は **最低 5 項目以上** の箇条書き（1〜2 行の薄い指示は禁止）
- エッジケース・異常系は **最低 10 件以上** を洗い出しテーブル化（条件 / 検知方法 / 期待される挙動 / ログ出力）
- Phase 1「実行前タスク」は **最低 4 件以上** の具体的調査ステップ（ファイルパス・関数名・確認観点）

- アーキテクチャの決定事項（例：専用シートを使うか、直接パースするか等）
- 考慮すべきエッジケース（例：金額ゼロ、重複、1対多の対応等）
- プロダクトポリシー（例：Human-in-the-Loop、確認FLGの必須化等）
- 既存コードとの統合方針（リファクタリングのスコープ境界）
- 計算式がある場合: ゼロ除算、比率異常値、加算可能/非加算の区別
- isActualOnly 等のフィルタが関連する場合: filterValues vs filterWithRecalcTotal の選択基準
- マッチングロジックがある場合:
  - マッチング優先順位の明記（完全一致 > 合算完全一致 > 部分一致）
  - 合算マッチ時の取引先グルーピングと部分集合探索方式
  - マッチ成功時のロック処理（matched=true で二重消費防止）を必須要件に
  - 処理順序のソート（日付昇順）による整合性確保
  - Date オブジェクトの比較は Utils.parseDateToYm() で正規化

【コアコード引用の必須化（v1.9・failure_patterns #18-#20 直接対策）】
使用を推奨する既存関数は、以下 4 ファイルに **実在するもののみ** 挙げる。架空の関数名・推測で補った関数名は禁止:
- `mas/000_infra/002_constants.js`（定数・メニュー定義）
- `mas/000_infra/003_contracts.js`（DTO typedef・行⇔オブジェクト変換）
- `mas/000_infra/004_utils.js`（共通ヘルパー）
- `mas/200_data/202_repository.js`（シート操作リポジトリ）

可能であれば行番号・関数シグネチャを併記する（例: `OrderRepository.findAll() 202_repository.js:L128`）。

【failure_patterns 反映の明示化（v1.9）】
`docs/_internal/failure_patterns.md` の #1〜#27（最新）から該当するものを **実装プロンプトと注意事項にインライン引用** する。特に以下は該当案件で必ず明示的な警告文を入れること:
- #18-#20: 命名造語・コード未読類推の禁止（MAS-003 起因）
- #21-#24: Sheets 数式機能のラベル解決脆弱性（GAS 側でリテラル埋め込み）
- #25: 並列実装の対称性漏れ（bank / cc 等の対称編集）
- #26: `oauthScopes` 部分宣言 → 既存スコープ自動検出完全オフ（`mas/appsscript.json` 手動編集時の地雷）
- #27: Google Admin SDK 等の API イベント名変動（名前指定フィルタを避けて post-processing で絞る）

該当がない場合も「該当なし（理由: ○○）」と明記し、調査したことを可視化する。

## Step 4: プロンプト案の出力

まず `docs/_internal/dev_spec_prompt_template.md` の「Phase 2: 仕様書の作成」セクション構成と
「実装プロンプトのフォーマット」を読み込み、出力するプロンプト案がこの構成に完全準拠するようにしてください。

分析結果をもとに、以下の構成で Claude Code にそのままコピペして
投げられるプロンプト案を出力してください。

【出力フォーマット】
1. 役割定義（あなたはシニア開発者兼仕様書ライターです...）
2. 実行前タスク（Step 2 で特定した読み込みファイルリスト）
3. 既存実装の前提知識（車輪の再発明を防ぐための注意点）
4. 仕様書の出力先ファイル名（例: `docs/dev/dev_I-02_cc_auto_match.md`）
5. 固有の設計要件（Step 3 で洗い出したアーキテクチャ、エッジケース等）
6. 出力品質の基準:
   - `docs/_internal/dev_spec_prompt_template.md` のセクション構成に準拠すること
   - エッジケーステーブル（計算式がある場合は必須）
   - 実データ検証セクション（MCP でのマスタ確認項目）
   - 実装プロンプトはバッククォートで囲まず、行頭4スペースインデントで出力
   - 過去の失敗パターン（テンプレート末尾）を踏まえた注意事項

【タイムアウト回避・実行原則（v1.7・必ずプロンプト案に含めること）】
生成するプロンプト案の冒頭に、次の 4 原則を必ず明記すること。
Claude Code が Phase 2 で API ストリーム idle timeout を起こさないための装備:

1. **拡張思考の使い分け**:
   - Phase 1（設計）では拡張思考をフル活用し、ファイル名形式・エッジケース一覧・
     Step 分割粒度・固有名詞（関数名/シート名/列名/行番号）を完全に確定させる。
   - Phase 2（清書）の各 Step 内では拡張思考を最小限に抑え、Phase 1 で確定済みの
     内容の書き下しに徹する。出力途中で再考しない。

2. **テキスト報告の禁止**:
   - 「〜を作成します」等の text のみで tool_use なしに turn を終了しない。
   - 説明は 1 文以内。直ちに tool を呼ぶ。

3. **4-5 分割の Write/Edit 実行**:
   - 仕様書作成は以下の Step に分けて実行する:
     - 2-1 骨格 Write（~20行）
     - 2-2 概要〜注意事項 Edit/Bash（~300行）
     - 2-3a エッジケース〜人間検討事項 Edit/Bash（~200行）
     - 2-3b 実装プロンプト〜変更履歴 Edit/Bash（~250行）
     - 2-4 `<details>` にプロンプト全文記録 Edit/Bash（最重量・必ず独立 Step）
   - 1 回の Write/Edit は約 300 行以内を目安にする。

4. **各 Step で何を書くかを具体指示**:
   - 設計判断を Phase 2 実行時に持ち込まないよう、プロンプト案の中で
     各 Step の内容を箇条書きで具体的に列挙すること（例:「Step 2-2 には
     アーキテクチャ決定事項 X, Y, Z を書く」）。

【重要な制約】
- 出力するプロンプト案は `docs/_internal/dev_spec_prompt_template.md` の
  「Phase 2: 仕様書の作成」セクション構成に完全準拠すること
- プロンプト案の中で「汎用プロンプトを参照せよ」とは書かず、
  必要な指示をすべて自己完結的に含めること
- 上記【タイムアウト回避・実行原則】の 4 原則は省略・要約せずに
  そのままプロンプト案の冒頭に転記すること

プロンプト本文

↑ トップに戻る

あなたはGAS会計システム(bizlp-gas-accounting)のシニア開発者兼仕様書ライターです。
まず最初に、対象の案件IDをユーザーに質問してください（例: S-13, I-02 など）。
ユーザーが回答した案件IDを {ISSUE_ID} として使用し、その開発仕様書を作成してください。
開発仕様書を新規作成した場合は、`docs/_config.json` の `nav` 配列の適切なセクションにも必ず追記してください。

---

## Phase 1: 案件情報の収集

### 1-A-pre: 案件 ID 重複チェック（**新規案件起票時の必須前処理・failure_patterns #31 反映**）

**新規 ID（{ISSUE_ID} に該当する F-XX / S-XX / N-XX / I-XX 等）を割り当てる前に、必ず以下を実施**:

1. `git fetch origin main` で main の最新状態を取得
2. `git diff HEAD origin/main -- docs/_internal/TODO_future.md` で main の最新 ID 予約状況を確認（自分のワークスペースが古ければ pull）
3. `grep -nE '\| (F|S|N|I|G|DS)-[0-9]+ \|' docs/_internal/TODO_future.md` で全案件 ID の使用状況を一覧化
4. 次に空いている番号を確定してから {ISSUE_ID} に記入

**失敗例（failure_patterns #31）**: 2026-04-27 main 側が F-57 Phase 3 実装中に新規案件「配当ミックス最適化」を「F-60 として起票」と指示したが、F-60 は既に「組織構成シミュレーター」(2026-04-25 起票) として確定使用済 → 番号衝突 → F-66 に振り直し。

**並行開発（複数ワークスペース）時のチェックリスト**:
- [ ] `origin/main` を fetch 済み
- [ ] `TODO_future.md` の使用済 ID を一覧確認済み
- [ ] sub 側未マージの起票 PR がないか `gh pr list` で確認済み
- [ ] 次空き番号が確定済み

これらは**既存案件のリビジョン作業（v1.0 → v1.1 等）では不要**。**新規案件起票時のみ必須**。

### 1-A-pre2: slice_id 確認（**UC スライス開発時の必須前処理・ADR-0025/0028/0029 反映**）

**新規 UC スライス仕様書を起票する場合（既存案件のリビジョンでは不要）、以下を実施**:

1. `docs/_internal/usecase_dev_mapping.md` の §4/§5 テーブルで対象 MAS を検索
2. 該当行の `slice_id` 列を確認（未割当なら `UC-{N}-S{NN}` 形式で新規採番 — ADR-0025 準拠）
3. `walking_skeleton_status` が `pending` → `skeleton` に移行する作業かどうかを判定
4. 仕様書フロントマターの `slice_id` フィールドに値を記入

**Walking Skeleton 4 要素のチェックリスト（ADR-0028/0029 必須）**:

| 要素 | 確認事項 | テスト関数命名（ADR-0027 必須） |
|------|---------|-------------------------------|
| **① 認証 (Input)** | `Env.isDev()` が正常動作し、最小入力データで関数が起動する | `test_{slice_id}_input_()` |
| **② DDL (Output)** | 期待するシート・列に値が書き込まれる（`setupAllSchemas` への追加要否を確認済み） | `test_{slice_id}_output_()` |
| **③ 監査ログ (Log)** | `Utils.auditLog` 呼び出し後、98_audit_log シートに PASS エントリが追記される（failure_patterns #37） | `test_{slice_id}_audit_logged_()` |
| **④ Feature Flag (Error)** | 不正入力で適切に例外が発生し、Flag OFF 時フォールバックが動作する（failure_patterns #38） | `test_{slice_id}_error_handling_()` |

**6 分制限見積もり（failure_patterns #39）**: 推定実行時間を仕様書内に明記すること。360 秒超過リスクがある場合は chunk 分割 + Properties 進捗保存 + Time-driven Trigger パターンを示すこと。

### 1-A: 案件定義の読み込み

以下のファイルから **{ISSUE_ID}** の行を検索し、案件名・カテゴリ・Phase・優先度・概要・人間が検討すべき事項を取得してください。

- `docs/_internal/TODO_future.md` — 案件一覧テーブル（ID, 案件名, カテゴリ, Phase, 優先度, 概要, 人間が検討すべき事項）

### 1-B: プロジェクト規約の読み込み

- `CLAUDE.md` を読み込み、コーディング規約・テスト手順・ファイル番号体系・会計ロジックのルールを把握してください。

### 1-C: 既存仕様書テンプレートの読み込み

- `docs/dev/` 配下の既存仕様書を **1件** 読み込み、フォーマットを把握する
- 案件の性質に応じて最も近いテンプレートを選択:

| 案件の性質 | 参考テンプレート |
|-----------|---------------|
| バグ修正 | `dev_mas-076_idempotency_fix.md` |
| テスト追加 | `dev_mas-196_repo_contracts_test.md` |
| 既存パターンの横展開 | `dev_mas-093_cf_actual_only.md` |
| バリデーション追加 | `dev_mas-075_expense_date_validation.md` |
| 整合性チェック追加 | `dev_mas-085_consistency_check.md` |
| 新機能（FP&A・レポート） | `dev_mas-001_variance_analysis.md` |
| 新機能（UI・メニュー） | `dev_mas-094_boundary_month_selector.md` |
| データ同期・転記 | `dev_mas-077_settlement_date_sync.md` |
| 基盤・インフラ改善 | `dev_mas-178_error_handling.md` |
| ID採番・onEdit拡張 | `dev_mas-080_pipeline_early_id.md` |
| ドキュメント・ガイドライン | `dev_mas-116_migration_framework.md` |

### 1-D: 関連コードの調査

TODO_future.md の概要から対象ファイルを推定し、以下の観点で調査する:

1. **現在のコード**: 修正対象の関数・行番号・ロジック
2. **既存パターン**: 同種の処理が他で実装済みなら、そのパターンを特定（横展開の場合は特に重要）
3. **影響範囲**: 修正対象の関数を呼び出している箇所・参照しているデータ
4. **既存テスト**: `901_test_runner.js` に関連テストがあるか
5. **関連する未定義関数やバグ**: 調査中に発見した問題は仕様書に記載

#### 読み方のルール（Grep vs Read）

仕様書が「既存のパターンに倣って」「L440 付近の `XXX` と同じ形で」と指示する**全ての箇所**について、記述前に該当コードを `Read` で開いて以下を確認する:

- **データ構造の型**: 配列かオブジェクトか、要素の形（`{ pattern, prefix, defaults }` のように明示）
- **固有名詞**: 変数名・関数名・シート名・メニュー名・定数名を**そのままの文字列**で引用
- **呼び出し経路**: その定数/シート/メニューがどこから参照されているか

**Grep は「どこにあるか」の発見まで、「どう書くか」の判断は必ず `Read`。**
名前や記憶から「〜用の配列だろう」「〜というメニューがあったはず」と推測した瞬間に手を止めて Read する。過去に F-03 仕様書で 1 回のコード未読から 3 件の固有名詞誤り（`SHEET_DEFAULTS` 型誤認、`03_sys_params` → 実際は `01_sys_config`、存在しないメニュー「MST_CONF_SHEETS 初期化」）を同時に仕込んだ失敗例あり（付録 F.4 #18-#20）。

---

## Phase 2: 仕様書の作成

### 出力フェーズの実行原則（v1.7・タイムアウト回避）

#### 拡張思考の使い分け

- **Phase 1（設計フェーズ）**: 拡張思考をフル活用する。ファイル名形式・エッジケース一覧・Step 分割粒度・固有名詞（関数名/シート名/列名/行番号）・影響範囲を **ここで完全に確定** させる。Read によるコード裏取りを妥協しない（失敗パターン #18-#20 の直接対策）。
- **Phase 2（清書フェーズ）**: 各 Step 内では拡張思考を **最小限** に抑える。Phase 1 で決定済みの内容をそのまま書き出すことに徹する。出力途中で「本当にこれで良かったか」と再考しない。途中の再考はストリーム idle timeout（通常 60 秒）の直接原因。

#### テキストでの状況報告の禁止

- 「〜を作成します」「一気に進めます」等の **text のみ返して tool_use を発行せずに終了する turn** を作らない。
- 説明は 1 文以内。直ちに tool を呼ぶ。空 turn の連続はハーネス側で idle timeout を誘発する。

#### 出力の分割原則

- 1 回の Write/Edit は概ね **300 行以内** を目安にする。
- 仕様書 1 本を 1 回の Write で書き切らず、**骨格 → 前半 → 後半a → 後半b → プロンプト記録** の最低 4-5 分割で tool_use する（詳細は後述の「分割実行ガイド」）。
- 実装プロンプト（行頭 4 スペース制約の長大ブロック）はインデント生成のトークン消費が大きいため **独立 Step** にする。
- `<details>` 内の投入プロンプト全文記録は **最も重い** 工程のため必ず **最後尾の独立 Step** に配置する。

### 出力先

`docs/dev/dev_{ISSUE_ID}_{短い英語名}.md`

### セクション構成（必須）

以下の順序で全セクションを含めること（**先頭に MDTM YAML フロントマターを必ず付与すること**）:

```
---
id: {NEW_ID}                # MAS-NNN（3桁ゼロ埋め）。新規採番時は docs/_internal/id_mapping_table.csv に追記
aliases: ["{ISSUE_ID}"]     # 旧ID表記（移行期の後方互換用、リスト形式必須）
type: Story                 # Epic | Story | Task | Bug | Research のいずれか
status: Open                # Open | InProgress | Done | Canceled | Duplicate
# parent: MAS-NNN           # 親案件があれば指定（無ければキー自体を省略）
---

# {ISSUE_ID}: {案件名}

## 概要
（テーブル: 案件ID, カテゴリ, Phase, 優先度, 所要時間, 対象ファイル, 前提案件）

## 目的
（1-3文で簡潔に。何を・なぜ変更するか）

## 現在のコード
（問題箇所のコードスニペット。ファイル名+行番号を明記）

## 修正方針
（変更内容を具体的に記述。コード例を含める。
  大規模案件はStep分割: Step 1/2/3...）

## 影響範囲
（変更ファイル・変更量・既存動作への影響）

## 注意事項
（実装時の罠・既存制約。番号付きリスト）

## エッジケース（計算式がある場合は必須）
（テーブル形式で以下の観点を網羅:
  | 条件 | 表示値 | 理由 |
  - ゼロ除算（売上=0、分母=0 等）
  - 比率の異常値（100%超、負値）
  - マスタ未設定時のフォールバック（保守的推計の方向を明記）
  - isActualOnly 時のフィルタ整合性:
    - 加算可能指標（金額合計）→ filterWithRecalcTotal
    - 非加算指標（比率、BEP等）→ filterValues + Total独自計算
    - 判断基準:「月別値を合算してTotalになるか」）

## 実データ検証（MCP でのデータ確認が必要な場合）
（実装前に MCP 等で確認すべき項目:
  - マスタのプルダウン値（DDLコード値 vs 実際の格納値の乖離）
  - 列インデックス（DDL定義とシート実態の一致）
  - テスト対象月のデータ有無（売上ゼロ月、未承認INV等の存在））

## 関連ドキュメント
（テーブル: 仕様書リンク | 関連箇所）

## 人間が検討すべき事項
（TODO_future.mdから転記 + 調査で判明した追加事項。
  なければ「なし（即実装可）」）

## 実装プロンプト（Claude Code 用）
（後述のフォーマットに準拠）

## 推奨実行モデル
（テーブル: 工程 | 推奨モデル | 理由）

## 変更履歴
（テーブル: 日付 | 変更内容）

## 仕様書作成プロンプト（再現性・監査性のため必ず記録）
（この仕様書を生成する際に Claude Code に投入したプロンプトの全文を
  `<details><summary>展開して表示</summary>` ブロックで囲んで記載する。
  メタプロンプト由来の場合はメタプロンプト本文ではなく、
  生成されたプロンプト案（実際に投入したもの）を記載する。
  目的: 将来の再生成・プロンプト改善のトレース、AI ガバナンス対応）
```

### 分割実行ガイド（タイムアウト回避・必須）

仕様書 1 本の作成は以下の 5 Step に分けて tool_use すること。各 Step 内では拡張思考を最小限に抑え、Phase 1 で確定した内容の清書に徹する。

| Step | 内容 | ツール | 目安行数 |
|:---:|---|---|:---:|
| 2-1 | MDTM YAML フロントマター + 骨格（見出しのみ。本文空で可） | Write | ~25 |
| 2-2 | 概要・目的・現在のコード・修正方針・影響範囲・注意事項 | Edit or Bash heredoc | ~300 |
| 2-3a | エッジケース・実データ検証・関連ドキュメント・人間が検討すべき事項 | Edit or Bash | ~200 |
| 2-3b | 実装プロンプト・推奨実行モデル・変更履歴 | Edit or Bash | ~250 |
| 2-4 | `<details>` に仕様書作成プロンプト全文を記録 | Edit or Bash | プロンプトサイズ依存 |

**Step 2-3a と 2-3b を 2-3 としてまとめない理由**: 実装プロンプトは行頭 4 スペースインデント制約があり、インデント生成でトークン消費が嵩む。単独 Step にすることでストリーム idle リスクを回避する。

**Step 2-4 の重要性**: `<instruction>` タグ内の原文をそのまま記録する工程は出力トークンが最も嵩む。必ず独立 Step で tool_use すること。Step 2-3b と結合すると timeout 圏内に入りやすい。

### 実装プロンプトのフォーマット

**【注意】マークダウンのコードブロック（バッククォート3つ以上）で囲まないこと。**
コピー時のマークダウン崩れを防ぐため、以下の内容は**すべて行頭にスペース4つのインデント**をつけて出力すること。

    あなたはGAS会計システム(bizlp-gas-accounting)のシニア開発者です。
    案件 {ISSUE_ID}「{案件名}」を実装してください。
    （大規模案件の場合: 「の Step N（{ステップ名}）を実装してください。」）

    ## 実行前タスク
    （読み込むべきファイルのリスト。各ファイルで確認すべきポイントを明記）

    ## 修正対象ファイル
    （ファイルパスと「のみ」or「への追記」を明示）

    ## 実装内容
    （具体的な変更手順。コード例を含める）

    ## 制約
    （やってはいけないこと。既存コードの変更禁止箇所など）

    ## エッジケース
    （計算式がある場合、以下の観点でテーブルを作成:
      - ゼロ除算: 分母がゼロになるケース → 表示値と理由
      - 境界値: 比率が100%超、負値になるケース → 表示値と理由
      - データなし: マスタ未設定、対象レコードなし → フォールバック動作
      - フィルタ整合性: isActualOnly 時の Total 再計算方法
        - 加算可能指標（金額合計等）→ filterWithRecalcTotal
        - 非加算指標（比率、BEP等）→ filterValues + Total独自計算
        - 判断基準:「月別値を合算してTotalになるか」）

    ## 実データ検証
    （MCP 等で実データを事前確認すべき項目:
      - マスタのプルダウン値（DDLコード値 vs 実際の格納値）
      - 列インデックス（DDL定義とシート実態の一致確認）
      - テスト対象月のデータ有無（売上ゼロ月の存在等））

    ## 動作確認
    （npm run push:dev 後の検証手順。番号付きリスト）

    ### 拡張思考の使用状況
    （テーブル: フェーズ | 拡張思考(あり/なし) | 備考）

### 推奨実行モデルの判定基準

| 条件 | 推奨モデル |
|------|----------|
| 仕様書でコードが完全定義済み、判断要素なし | **Claude Haiku 4.5** |
| 中程度の判断が必要（挿入位置の特定、既存パターンの適用等） | **Claude Sonnet 4.6** |
| 複数ファイル横断の設計判断、会計ロジックの理解が必要 | **Claude Opus 4.7 (1M context)** |

### 品質チェックリスト

仕様書完成前に以下を確認してください:

- [ ] 修正対象ファイルが全て特定され、行番号まで記載されているか
- [ ] コード例が実際のコードと整合しているか（変数名・関数名の正確性）
- [ ] 既存パターンがある場合、そのパターンへの準拠を明記しているか
- [ ] 実装プロンプトが自己完結的か（別セッションにコピペしても動作するか）
- [ ] CLAUDE.md の規約に違反する指示がないか
- [ ] 「人間が検討すべき事項」が TODO_future.md + 調査結果の両方を含んでいるか
- [ ] エッジケース・異常系の振る舞いが定義されているか（ゼロ除算、データなし、境界値等）
- [ ] マスタデータの実値を MCP 等で確認し、DDL定義のコード値と実データに乖離がないか
- [ ] 出力値に加算可能/非加算の区別があり、フィルタ関数の選択基準が明記されているか
- [ ] **「仕様書作成プロンプト」セクションが末尾にあり、投入したプロンプト全文が `<details>` で囲まれて記録されているか**
- [ ] **（v1.9）各 Step の「アーキテクトからの指示」が最低 5 項目以上で列挙されているか**
- [ ] **（v1.9）エッジケースが最低 10 件以上テーブル化されているか**
- [ ] **（v1.9）コアコード 4 ファイル以外の架空関数が混入していないか（failure_patterns #18-#20）**
- [ ] **（v1.9）該当する failure_patterns #1-#27 が注意事項 or 実装プロンプトに引用されているか（該当なしの場合はその旨明記）**
- [ ] **（v1.14）UC スライス案件の場合、仕様書フロントマターに `slice_id: UC-{N}-S{NN}` が記入されているか（ADR-0025）**
- [ ] **（v1.14）Walking Skeleton 4 要素（認証 / DDL / 監査ログ / Feature Flag）が仕様書の「動作確認」セクションに明記されているか（ADR-0028/0029）**
- [ ] **（v1.14）`test_{slice_id}_{condition}_()` 形式のテスト関数命名が実装プロンプトに明記されているか（ADR-0027）**
- [ ] **（v1.14）Feature Flag キー名が `FF_UC{N}_S{NN}_{verb}` 形式かつ 30 文字以内か（failure_patterns #38）**
- [ ] **（v1.14）6 分制限の推定実行時間が仕様書内に明記されているか（failure_patterns #39）**

---

## Phase 3: 保存と記録

### 3-A: ファイル保存

仕様書を `docs/dev/dev_{ISSUE_ID}_{短い英語名}.md` に保存。

### 3-B: _config.json にナビゲーション登録（必須）

`docs/_config.json` の `nav` 配列の適切なセクションに仕様書を追加。**この手順を省略するとドキュメントサイトに表示されない。**

```json
{ "file": "dev/dev_{ISSUE_ID}_{名前}.md", "title": "E.X.X {ISSUE_ID} {案件名}" }
```

セクションの判定基準:
- 基盤・DevOps → §E.1
- バグ修正・バリデーション → §E.2
- テスト → §E.3
- データマート・財務諸表 → §E.4
- FP&A・レポーティング → §E.5
- パイプライン・RPA・外部連携 → §E.6

### 3-C: changelog 追記

`docs/_internal/changelog.md` の先頭行（ヘッダーの直後）に追記:

```
| {日付} | [dev_{ISSUE_ID}_{名前}.md](../dev/dev_{ISSUE_ID}_{名前}.md) | 初版作成。{1行要約} |
```

### 3-C: コミット＆プッシュ

```
git add docs/dev/dev_{ISSUE_ID}_*.md docs/_internal/changelog.md docs/_config.json
git commit -m "docs: {ISSUE_ID} {案件名}の開発仕様書を作成

{2-3行の概要}

https://claude.ai/code/session_XXXXX"
git push -u origin {現在のブランチ}
```

パターン分析メモ（プロンプト作成時の知見）

↑ トップに戻る

案件タイプ別の調査深度

仕様書の成功パターン

1. コード例は「挿入位置」を明示する: 「L761の直前に追加」のように既存コードのランドマークを指定
2. 既存パターン踏襲を明記する: 「P/LのfilterWithRecalcTotalと同一ロジック」のように参照先を特定
3. やってはいけないことを繰り返す: 書き込み禁止、既存コード変更禁止等を実装プロンプトで再度強調
4. 推奨モデルは具体的理由付き: 「コード完全定義済み→Haiku」のように判断根拠を明記
5. 発見事項は即記載する: 調査中に見つけた未定義関数やバグは仕様書に含める（MAS-080のgenerateNextIdForAssist_未定義など）

過去の実装で発見された失敗パターン

変更履歴

↑ トップに戻る

詳細は 変更履歴詳細（バージョン別） を参照。要約表は以下。

バージョン番号の付与ルール（遡及付与含む）:

• Major (x.0): 構造的変更（初版・パラダイムシフト）
• Minor (x.y): 機能追加（新セクション・新メカニズム導入）
• Patch (x.y.z): 小改訂（文言調整・軽微な追加・命名統一）

変更履歴詳細（バージョン別）

v1.0 (2026-04-14 00:33) — 初版作成

契機: Phase 1 一括作業（PR #24）で 13+ 件の開発仕様書を短期間に作成した際、品質のばらつき・調査漏れが頻発。毎回「何を確認すべきか」を思い出す非効率を解消するため、ノウハウを汎用化。

本文プロンプト変更:

• ゼロから新設
• Phase 1（案件情報の収集）/ Phase 2（仕様書の作成）/ Phase 3（保存とコミット）の3フェーズ構成
• セクション構成定義（概要 / 目的 / 現在のコード / 修正方針 / 影響範囲 / 注意事項 / 関連ドキュメント / 実装プロンプト 等）
• 実装プロンプトのフォーマット（行頭 4 スペースインデント規則）
• 案件タイプ別の参考テンプレート選択ガイド（バグ修正 → dev_mas-076_idempotency_fix.md 等）
• パターン分析メモ（案件タイプ別の調査深度、仕様書の成功パターン）
• 品質チェックリスト

メタプロンプト変更: なし（v1.3 で後日導入）

解説: 「仕様書を作る」行為自体がAIエージェントにとっての反復タスクであり、ノウハウを言語化・再利用可能化することで品質が安定することを狙った。初版の時点では失敗パターン・エッジケース観点はまだ組み込まれていない（v1.2 で追加）。

v1.1 (2026-04-15 12:12) — プロンプト本文の改訂

契機: v1.0 を実運用に投入した後、Claude Code が仕様書を生成する際の曖昧さ（指示の強弱・順序）を観測。

本文プロンプト変更: 全体的な文言調整・構造改訂（コミット d8315f8）。大きな構造変更はないが、v1.2 の大規模拡張のための地ならし。

メタプロンプト変更: なし

解説: 小改訂。単体の効果よりも v1.2 とのセットで効果を発揮する前段整備。

v1.2 (2026-04-15 23:33) — エッジケース / 実データ検証 / 失敗パターン / モデル判定基準の追加

契機: MAS-024（BEP）と MAS-001（予実差異）の実装で 4 件のバグ（失敗パターン #1-#4）が発生。「仕様書段階で防げたはず」と事後分析され、仕様書品質に直接組み込む方針へ転換。

本文プロンプト変更:

• ## エッジケース（計算式がある場合は必須） セクション構成を追加。ゼロ除算・比率異常値・マスタ未設定フォールバック・isActualOnly フィルタ整合性（加算可能 vs 非加算）を網羅
• ## 実データ検証（MCP でのデータ確認が必要な場合） セクション構成を追加
• ### 推奨実行モデルの判定基準 テーブル追加（Haiku / Sonnet / Opus の使い分け）
• ファイル末尾に ### 過去の実装で発見された失敗パターン 表を新設（初期 6 件）

メタプロンプト変更: なし

解説: 「実装してから直す」から「書く前に観点を強制する」へのパラダイムシフト。非加算指標の Total 破壊や売上ゼロ月のゼロ除算など、MAS-024 / MAS-001 で顕在化した典型的な落とし穴を仕様書テンプレートに恒久的に組み込んだ。

v1.3 (2026-04-16 13:50) — メタプロンプト（仕様書作成プロンプトの自動生成）を導入

契機: 汎用プロンプト単体では案件固有の設計要件を十分に引き出せないケースがあり、「案件ID → Claude Code に投げるプロンプト案自体を生成する」2 段階方式が有効と判断。

本文プロンプト変更: なし

メタプロンプト変更:

• ファイル末尾に ## メタプロンプト: 仕様書作成プロンプトの自動生成 セクションを新設
• Step 1（案件要件分析）/ Step 2（関連ファイル・類似機能の特定）/ Step 3（固有の設計要件とエッジケースの洗い出し）/ Step 4（プロンプト案の出力）の 4 ステップ構造

解説: 「ユーザー → メタプロンプト → プロンプト案 → Claude Code → 仕様書」の 2 段生成パイプラインを確立。案件固有の考慮点（後に v1.4.4 でマッチングロジック類型を拡張）を、メタ側で事前に抽出する仕組みになった。

v1.3.1 (2026-04-16 13:54) — ISSUE_ID プレースホルダーの統一

契機: v1.3 メタプロンプト内で ID プレースホルダーが {ISSUE_ID} と {案件ID} で混在し、読み違えが発生。

本文プロンプト変更: なし

メタプロンプト変更: 全箇所を {ISSUE_ID} に統一

解説: リテラルの整備。微修正。

v1.3.2 (2026-04-16 13:55) — ISSUE_ID を対話入力方式に変更

契機: v1.3 までは「プロンプト冒頭で ISSUE_ID を事前記入」方式だったが、貼り付け時に差し替え忘れる事例が発生。

本文プロンプト変更: 冒頭の ISSUE_ID 入力を「まず最初に対象の案件IDをユーザーに質問する」方式に変更

メタプロンプト変更: 同様に対話入力方式へ

解説: 「プロンプトを貼り付けた直後にAIが案件IDを聞き返す」動線にすることで、ユーザーが案件IDを明示的に宣言するステップが生まれ、取り違えを減らす。

v1.4 (2026-04-16 20:25) — Phase 3 に _config.json ナビ登録を必須化

契機: MAS-073 等の仕様書で docs/_config.json への登録漏れが複数発生し、docs サイトのサイドバーに表示されない問題が頻発（失敗パターン #11）。

本文プロンプト変更:

• Phase 3 に ### 3-B: _config.json にナビゲーション登録（必須） を新設
• 登録 JSON フォーマット { "file": "dev/dev_{ISSUE_ID}_{名前}.md", "title": "E.X.X {ISSUE_ID} {案件名}" } を明記
• セクション判定基準（§E.1 基盤 / §E.2 バグ修正 / §E.3 テスト / §E.4 データマート / §E.5 FP&A / §E.6 パイプライン・RPA・外部連携）を記載

メタプロンプト変更: なし

解説: 「仕様書を書いても読まれなければ価値ゼロ」という前提に立ち、docs 配下の新規ファイル追加と _config.json 更新をペアで必ず実行させる強制装置。

v1.4.1 (2026-04-16 20:45) — プロンプト冒頭にも _config.json 指示を追加

契機: v1.4 の Phase 3 だけでは、途中中断したセッションで見落とされる事例あり。

本文プロンプト変更: 役割定義直後に「開発仕様書を新規作成した場合は、docs/_config.json の nav 配列の適切なセクションにも必ず追記してください」を明示

メタプロンプト変更: なし

解説: 冒頭（すぐ読む場所）と Phase 3（完了時の場所）の二重指示で、どのタイミングでセッションが中断しても気づける構造にした。

v1.4.2 (2026-04-16 21:15) — 失敗パターン一覧を独立ページ化

契機: 失敗パターン表が 12 件に達し、本文プロンプト末尾の「ノイズ」になり始めた。また、仕様書作成以外の場面（実装時のデバッグ参照等）でも失敗パターンを引きたいニーズが発生。

本文プロンプト変更: 末尾の ### 過去の実装で発見された失敗パターン 表は要約版として残し、詳細は別ページへ分離

関連ファイル変更（本ファイル外）: docs/_internal/failure_patterns.md を新設し、12 件をカテゴリ分類（計算ロジック / データ不整合 / スコープ・変数 / テスト回帰 / Git 運用 / ドキュメント）付きで完全記載。docs/_config.json §F.4 として登録。

メタプロンプト変更: なし

解説: 「本文プロンプト = 作業手順」「失敗パターン独立ページ = 辞書」という役割分担を確立。Phase 1-D からも参照可能にし、仕様書作成時の参照系と、実装時のデバッグ参照系を分離した。

v1.4.3 (2026-04-16 23:43) — 失敗パターン #13-#17（MAS-162 合算マッチ関連）追加

契機: MAS-162（銀行CSV 合算マッチング）の実装・デバッグで 5 件の新規失敗パターンを観測:

• Pass 順序の逆転（合算前に単一候補提案が発火）
• 全STL合計での照合ミス（取引先グルーピング不在）
• 部分集合探索の不足（全件合計のみ）
• 合算マッチ成功時の STL 二重消費（matched フラグ欠如）
• Date オブジェクトの文字列ソート崩れ

本文プロンプト変更: 末尾の失敗パターン要約表に #13-#17 を追記

関連ファイル変更（本ファイル外）: failure_patterns.md 側に詳細を展開（カテゴリ「計算ロジック」配下、MAS-162 関連 5 件セクションとして整理）

メタプロンプト変更: なし（直後の v1.4.4 で対応）

解説: マッチングロジック案件特有の落とし穴が揃い、次の v1.4.4 でメタプロンプト側への逆輸入動機が発生。

v1.4.4 (2026-04-16 23:50) — メタプロンプト Step 3 にマッチングロジック類型を追加

契機: v1.4.3 で顕在化した MAS-162 系失敗パターンを、次のマッチング系案件で再発させないよう、メタプロンプトの案件分析時点で自動的に類型を検出する必要があった。

本文プロンプト変更: なし

メタプロンプト変更: Step 3（固有の設計要件とエッジケースの洗い出し）に「マッチングロジックがある場合」のサブ項目として以下 5 点を追加:

• マッチング優先順位の明記（完全一致 > 合算完全一致 > 部分一致）
• 合算マッチ時の取引先グルーピングと部分集合探索方式
• matched=true で二重消費防止を必須要件に
• 処理順序のソート（日付昇順）による整合性確保
• Date オブジェクトの比較は Utils.parseDateToYm() で正規化

解説: 案件タイプ別の「典型的な考慮点リスト」がメタプロンプトに組み込まれ、マッチング案件では Claude が自動的に 5 点を検出・抽出するようになった。「失敗パターン → 対策の類型化 → メタプロンプトへの逆輸入」という学習ループの最初の成功例。

v1.4.5 (2026-04-17 00:05) — 変更履歴の日付書式を HH:MM 化 + 時系列整理

契機: 変更履歴の日付が「YYYY-MM-DD」のみで、同日内の複数改訂（例: 04-16 に 6 件）の順序が不明瞭だった。

本文プロンプト変更: 既存の 変更履歴 テーブルの全エントリを「YYYY-MM-DD HH:MM」形式に統一、時系列順にソート

メタプロンプト変更: なし

解説: 変更履歴のメタ管理改善。微修正だが、次の変更者（今回の v1.5 等）が「どのエントリがどの順で適用されたか」を正しく追えるようにする基盤。

v1.4.6 (2026-04-17 00:10) — メタプロンプト Step 4 に Phase 2 準拠指示を追加

契機: メタプロンプトから生成されたプロンプト案が、本文プロンプト Phase 2 のセクション構成とずれる事例を観測（セクションの欠落・順序違い等）。

本文プロンプト変更: なし

メタプロンプト変更: Step 4（プロンプト案の出力）の冒頭に「まず docs/_internal/dev_spec_prompt_template.md の『Phase 2: 仕様書の作成』セクション構成と『実装プロンプトのフォーマット』を読み込み、出力するプロンプト案がこの構成に完全準拠するようにしてください」を追加

解説: メタプロンプトが生成する「プロンプト案」が本文プロンプト（Phase 2）の構成と一致することを、Step 4 の前提として強制した。メタ側と本文側の整合性を保証する仕組み。

v1.5 (2026-04-17 18:00) — 「Grep vs Read」原則 + 失敗パターン #18-#20（MAS-003 起因）

契機: MAS-003 Step 1 仕様書で 3 件の固有名詞・型誤記が同時発生（SHEET_DEFAULTS 型誤認 / シートキー登録先を 03_sys_params と誤記 / 実在しないメニュー「MST_CONF_SHEETS 初期化」を参照）。いずれも該当コードを Read せず Grep の部分マッチと記憶で書いたことが共通原因。

① 本文プロンプト / Phase 1-D「関連コードの調査」— 新サブセクション追加

場所: dev_spec_prompt_template.md の Phase 1-D 末尾（既存の 1〜5 項目の直下）に #### 読み方のルール（Grep vs Read） を新規追加。

追加した内容:

• 仕様書が「既存のパターンに倣って」「L440 付近の XXX と同じ形で」と指示する全箇所で、記述前に該当コードを Read で開いて以下を確認することを必須化:
  • データ構造の型（配列 vs オブジェクト、要素の形。例: { pattern, prefix, defaults } のように明示）
  • 固有名詞（変数名・関数名・シート名・メニュー名・定数名）をそのままの文字列で引用
  • 呼び出し経路（その定数/シート/メニューがどこから参照されているか）
• 原則の1文化: 「Grep は『どこにあるか』の発見まで、『どう書くか』の判断は必ず Read」
• 「〜用の配列だろう」「〜というメニューがあったはず」と推測した瞬間に手を止めて Read することをルール化
• MAS-003 失敗例（付録 F.4 #18-#20）を inline で引用し、具体的に何が誤記されたかを明示

変更の解説:

従来の Phase 1-D はコード調査の観点（修正対象関数、影響範囲、既存テスト等 5 項目）を列挙していたが、調査方法（どのツールで、どの粒度で読むか）が規定されていなかった。結果として「Grep の部分ヒット → 該当行だけ見る → 名前・記憶から構造を類推 → 仕様書に固有名詞を書く」という経路でミスが発生しやすく、MAS-003 Step 1 仕様書では1 回のコード未読から 3 件の固有名詞誤記が同時に発生（SHEET_DEFAULTS 型誤認 / シートキー登録先を 03_sys_params と誤記 / 実在しないメニュー名を造語）。今回「どう調査するか」を手順より先に原則として置くことで、類推による記述を源流で塞ぐ。

② 本文プロンプト / 末尾「過去の実装で発見された失敗パターン」表 — 3 行追加

場所: ## パターン分析メモ（プロンプト作成時の知見） 配下の ### 過去の実装で発見された失敗パターン 表の末尾（04-16 | Date のソートで順序が壊れた（I-20）... の直後）に以下 3 行を追加。

変更の解説:

既存の失敗パターン表 17 件（#1-#17）は実装工程の失敗（計算ロジック、データ不整合、Git 運用、テスト回帰）に偏っていた。今回の MAS-003 事例は仕様書生成工程そのものの失敗（コード未読で書いた固有名詞・型誤記）という新カテゴリで、従来とは原因レイヤーが異なる。3 件を個別行に分離したのは、類似のパターン（型誤認 / シート名混同 / メニュー名造語）を後続案件が参照する際に、各々独立した教訓として使えるようにするため。失敗パターンの独立ページ（docs/_internal/failure_patterns.md）側には #18-#20 として登録し、「仕様書記述」カテゴリを新設、共通の根本原因と対策（Phase 1-D への参照）を整理済み。

③ メタプロンプト — 今回は無変更

判断理由:

メタプロンプトは「仕様書生成プロンプトの自動生成器」として、現状の Step 2（関連ファイル特定）が「事前に読み込むべきファイル」を列挙する構造、Step 4（プロンプト案出力）が「Phase 2 セクション構成に準拠」と明記する構造になっており、Phase 1-D の原則は本文プロンプト経由で間接的に継承される。つまり「メタプロンプトから生成されたプロンプト案を Claude Code が実行する際、本文プロンプトの Phase 1-D が読み込まれるので原則が伝播する」想定。

ただしこの伝播は間接的で、メタプロンプト生成物の品質は生成時の Claude の判断に依存する。将来、メタプロンプト出力が「Read 原則」を取り込まない事例が観測されたら、Step 2/Step 4 の指示文にも明示的に「プロンプト案は Read/Grep の使い分けを明記すること」を加える改訂（v1.6 候補）を検討する。

④ 関連ドキュメントの同時更新（本ファイル外）

同 PR（#133）で以下も同時更新:

• docs/_internal/failure_patterns.md — 新カテゴリ「仕様書記述」追加、#18-#20 登録、「仕様書記述で防げたもの」サマリー追加
• docs/dev/dev_mas-003_kpi_dashboard.md — 本改訂の直接の契機となった誤記 3 件を訂正
• ~/.claude/projects/-Users-ts-kuma-projects-my-gas-project/memory/feedback_spec_read_before_write.md — 将来セッションへの伝播（Claude Code の auto memory）

v1.5.1 (2026-04-17 19:30) — 変更履歴をバージョン番号 + 詳細付き構成に改訂

契機: v1.5 の変更履歴エントリだけ詳細展開されていたが、v1.0〜v1.4.6 の過去エントリも「なぜ / 何を / 効果」が遡及的に辿れる状態にしたいというニーズ。

本文プロンプト変更:

• ## 変更履歴 要約テーブルに Ver 列を追加（v1.0 〜 v1.5 を遡及付与）
• テーブル直下に ### 変更履歴詳細（バージョン別） サブセクションを新設
• 各バージョンの詳細（契機 / 本文プロンプト変更 / メタプロンプト変更 / 解説）を v1.0 から v1.5 まで時系列順に展開
• バージョン番号の付与ルール（Major / Minor / Patch）を明文化

メタプロンプト変更: なし

解説: 変更履歴の要約テーブル（= 俯瞰）と詳細セクション（= 深堀り）を二層化。テーブルだけで時系列と依存関係が追え、詳細セクションで各改訂の「なぜこの設計か」を遡及可能。今後の v1.6 以降は詳細サブセクション末尾に追記する運用。

v1.7 (2026-04-18 15:00) — タイムアウト回避の実行原則を明文化

契機: MAS-152 仕様書作成時に「API Error: Stream idle timeout - partial response received」が 2 回連続発生。観察された失敗パターンは 2 系統:

• (a) 空 turn の連続: 「仕様書を作成します」「一気に進めます」等の短い text のみを返し、tool_use を発行せずに turn を終了。次ターンまでに時間が空きハーネス側で idle timeout が発火
• (b) 単一巨大 Write の拡張思考中 idle: 1 回の Write で仕様書全体（1000 行超）を出力しようとして、拡張思考で設計中にストリームが idle。tool_use の先頭トークンが流れる前にタイムアウト

根本原因は「拡張思考は品質を上げるが、出力フェーズで働くと timeout を誘発する」という Phase とモードのミスマッチ。対策として「設計フェーズでは拡張思考を使い、清書フェーズでは使わない」の役割分担を明文化した。

① 本文プロンプト / Phase 2 冒頭 — 新サブセクション「出力フェーズの実行原則」

場所: ## Phase 2: 仕様書の作成 の直下、### 出力先 の前に新規追加。

追加した内容:

• 拡張思考の使い分け:
  • Phase 1（設計）: 拡張思考フル活用。ファイル名形式・エッジケース一覧・Step 分割粒度・固有名詞（関数名/シート名/列名/行番号）をここで完全確定。Read による裏取りを妥協しない（失敗パターン #18-#20 の直接対策を継承）
  • Phase 2（清書）: 各 Step 内では拡張思考を最小限。Phase 1 確定内容の書き下しに徹する。出力途中で再考しない
• テキストでの状況報告の禁止:
  • text のみで tool_use なしに turn を終了しない
  • 説明は 1 文以内。直ちに tool を呼ぶ
• 出力の分割原則:
  • 1 回の Write/Edit は概ね 300 行以内
  • 仕様書 1 本を 1 回の Write で書き切らず、骨格 → 前半 → 後半 a → 後半 b → プロンプト記録 の最低 4-5 分割
  • 実装プロンプト（行頭 4 スペース制約）はインデント生成のトークン消費が大きいため独立 Step
  • <details> 内のプロンプト全文記録は最重量工程のため最後尾の独立 Step

② 本文プロンプト / Phase 2 — 新サブセクション「分割実行ガイド」

場所: ### セクション構成（必須） の直後、### 実装プロンプトのフォーマット の前に新規追加。

追加した内容: 5 Step テーブル（2-1 骨格 / 2-2 概要〜注意事項 / 2-3a エッジケース〜人間検討事項 / 2-3b 実装プロンプト〜変更履歴 / 2-4 プロンプト記録）と、2-3a/2-3b を分離する理由（実装プロンプトのインデント制約）、2-4 を独立 Step にする必要性（最重量工程）を明記。

③ メタプロンプト Step 4 — 「タイムアウト回避・実行原則」の逆輸入

場所: 【出力フォーマット】と【重要な制約】の間に新ブロック【タイムアウト回避・実行原則（v1.7・必ずプロンプト案に含めること）】を追加。

追加した内容:

• 生成するプロンプト案の冒頭に、4 原則（拡張思考の使い分け / テキスト報告禁止 / 4-5 分割実行 / 各 Step 具体指示）を必ず明記する指示
• 【重要な制約】にも「上記 4 原則は省略・要約せずにそのままプロンプト案の冒頭に転記すること」を追加し、圧縮・省略を防止

変更の解説:

v1.4.4 でマッチングロジック類型をメタプロンプト Step 3 に逆輸入した成功パターンの踏襲。今回は「設計品質」ではなく「出力効率（タイムアウト回避）」という非機能要件を、メタ側で自動継承させる。これにより次回以降のマッチング系・大規模案件でも、生成プロンプト案の冒頭に 4 原則が自動的に含まれるようになる。

④ 関連ドキュメントの同時更新（本ファイル外）

• docs/_internal/failure_patterns.md — 新カテゴリ「出力フェーズ」追加、MAS-152 で観測された 2 系統の timeout を失敗パターン #25-#26 として登録予定（後続 PR）
• docs/dev/dev_mas-152_evidence_filename_rename.md — 本改訂の直接の契機となった仕様書（5 分割 Write/Edit で完走した実例）

v1.8 (2026-04-18 16:00) — ドキュメント可読性の改善（セクション順再構成・TOC・ナビゲーション）

契機: ファイル全体が 800 行超に膨張し、目的のセクションへの到達コストが高くなった。また、利用フロー上「メタプロンプト → 案件固有プロンプト案 → 仕様書」が推奨経路にもかかわらず、ファイル上は汎用プロンプト本文（L20）が先で、メタプロンプト（L352）が後ろに配置されており、初見ユーザーが推奨経路に辿り着きにくかった。

本文プロンプト変更:

• セクション順の再構成: 利用フローに沿って並べ替え
  • 旧: 使い方 → プロンプト本文 → パターン分析メモ → メタプロンプト → 変更履歴
  • 新: 使い方 → 目次 → メタプロンプト → プロンプト本文 → パターン分析メモ → 変更履歴
• 目次セクションを新設: 各 H2 セクションへのアンカーリンク表
• <a id="top"></a> をファイル冒頭に追加: トップへのアンカー
• 各 H2 セクション冒頭に [↑ トップに戻る](#top) リンクを追加: 長文ドキュメントでの回遊性向上
• 各 H2 に明示的 <a id="..."> アンカーを設定: docs-build.mjs の Markdown プロセッサ依存を回避し、日本語見出しでもリンク確実に機能
• 「使い方」を書き換え: 「A. メタプロンプト経由（推奨）」「B. 汎用プロンプト直用」の 2 択フローに整理

メタプロンプト変更: なし

解説: v1.7 までで内容面の品質保証は強化された一方、ナビゲーション設計が手付かずだった。v1.8 はファイルを「読み物」から「リファレンス」へ昇格させる回遊性改善。セクション順の入れ替えにより、初見ユーザーが推奨経路（メタプロンプト経由）に最初に触れる動線になり、汎用プロンプト直用は「メタを使わない場合の fallback」という位置付けが明確化された。

v1.9 (2026-04-22 12:00) — メタプロンプトの数値要件・failure_patterns 反映・コアコード引用を明文化

契機: MAS-216（Vertex AI 移行）仕様書を scripts/B2_generate_prompts_gemini.js + scripts/B3_run_writers.sh パイプラインで生成した際、Gemini Pro が返したメタプロンプトのアーキテクトからの指示が 2〜3 行の薄い概要に留まり、仕様書の完成度が低下する事象を観測。PR #283 でスクリプト側のメタプロンプトを強化したが、手動経路 (本テンプレート) にも同等の基準を明文化し、script1 経路と直用経路の品質差を解消する必要があった。

メタプロンプト変更 (Step 3):

• 【数値要件】ブロックを新設: 各 Step の指示 5 項目以上 / エッジケース 10 件以上 / Phase 1 調査 4 件以上を必須化。薄い指示を返すリスクを機械的に遮断
• 【コアコード引用の必須化】ブロックを新設: 002_constants.js / 003_contracts.js / 004_utils.js / 202_repository.js に実在する関数のみ使用、行番号・シグネチャ併記を推奨。failure_patterns #18-#20 (MAS-003 で同日発生した 3 件の造語起因バグ) の再発を構造的に予防
• 【failure_patterns 反映の明示化】ブロックを新設: #18-#20 / #21-#24 / #25 / #26 / #27 を実装プロンプト・注意事項にインライン引用させる。該当なしの場合は「該当なし（理由: ○○）」を明記させて調査の痕跡を残す

本文プロンプト変更:

• 品質チェックリストに 4 項目追加: 数値要件 (5+/10+) / コアコード引用 / failure_patterns 反映チェック。各項目に (v1.9) マークを付与して追加時期を追跡可能に
• 推奨実行モデルを Claude Opus 4.6 → Claude Opus 4.7 (1M context) に更新。本プロジェクトで environment.md の §7.1 が 2026-04-20 に既に更新済であり、本ファイルの表記と整合させた

関連:

• scripts/B2_generate_prompts_gemini.js — PR #283 で同等の指示を systemContext 先頭に実装済。手動経路 / 自動経路で同一の品質基準
• docs/_internal/failure_patterns.md — #25 (並列実装対称性) / #26 (oauthScopes 部分宣言) / #27 (Admin SDK API 変動) の最新 3 件を網羅
• docs/environment.md §7.1 — Opus 4.7 (1M context) の記載と整合

解説: v1.2 (エッジケース / 失敗パターン観点の組み込み) で始まった「仕様書段階で品質保証する」方針を、数値要件と実在関数チェックで定量化した改訂。v1.7 がタイムアウト回避 (非機能要件) を組み込んだのに対し、v1.9 は品質基準 (機能要件) を定量化し、「何件以上書けば合格か」を自動判定可能にした。script1 自動経路との品質バラつきを解消する運用整合パッチでもある。

v1.10 (2026-04-27) — 新規案件起票時の ID 重複チェック前処理を Phase 1-A-pre として明文化（failure_patterns #31 反映）

契機: 2026-04-27 main 側 MAS-057 Phase 3 実装 (PR #379) 後の振り返りで派生した「配当ミックス最適化」案件を main 側プロンプトが「MAS-060 として起票」と指示したが、MAS-060 は既に「組織構成シミュレーター」(2026-04-25 起票) として確定使用済 → 番号衝突 → sub 側で MAS-066 に振り直し（PR #382）。複数ワークスペース（main / sub）並行開発時の TODO_future.md 同期遅延が root cause。

本文プロンプト変更:

• Phase 1-A の直前に「Phase 1-A-pre: 案件 ID 重複チェック」を新設: git fetch origin main → grep -nE '\| (F|S|N|I|G|DS)-[0-9]+ \|' docs/_internal/TODO_future.md で全案件 ID 使用状況を一覧化 → 次空き番号を確定する 4 ステップを必須化
• 並行開発チェックリスト 4 項目 を追加: origin/main fetch 済 / 使用済 ID 一覧確認済 / sub 側未マージ起票 PR を gh pr list で確認済 / 次空き番号確定済
• 既存案件のリビジョン作業（v1.0 → v1.1 等）では本前処理は不要である旨を明記（新規案件起票時のみ必須）

関連:

• docs/_internal/failure_patterns.md — #31 (案件 ID 採番衝突 / TODO_future.md 同期遅延) の対策として本変更を参照
• CLAUDE.md §複数ワークスペースでの並行開発ルール — TODO_future.md は sub 専属だが、新規案件 ID 予約は両側で発生しうる旨を補完
• tasks/prompts/task_F-66.md — 本テンプレートの v1.10 ルールを最初に適用した起票プロンプト（MAS-060 → MAS-066 振り直し事例）

解説: v1.7 がタイムアウト回避（非機能要件）/ v1.9 が品質基準（機能要件）を組み込んだのに続き、v1.10 は**並行開発時の同期失敗回避（プロセス要件）**を組み込む位置付け。失敗パターンが failure_patterns.md に記録 → テンプレートの該当 Phase に対策ステップを追記する 「失敗 → 教訓 → プロセス改善」の閉ループ運用 の一例として確立。

v1.11 (2026-04-29 14:30) — MDTM YAML フロントマター必須化（MAS- ID 体系移行に伴う仕様書フォーマット改訂）

契機: 開発案件 ID を機能別プレフィックス（F-/S-/I-/N-/G-/DS-）から単一プレフィックス MAS-NNN（3 桁ゼロ埋め）+ MDTM (Markdown-Driven Task Management) 方式に一括刷新。docs/dev/*.md 全 141 ファイルにフロントマターを挿入し、ID マッピング表 (docs/_internal/id_mapping_table.csv) を導入。

本文プロンプト変更:

• 「セクション構成（必須）」冒頭にフロントマターブロック追加: id / aliases / type / status / parent（任意）の 5 キーを必須化。新規仕様書は雛形に従ってフロントマターを必ず付与する
• Step 2-1 の内容を更新: 「骨格（見出しのみ）」→「MDTM YAML フロントマター + 骨格」へ変更し、目安行数を ~20 → ~25 に微調整
• 新規採番ルール: MAS-NNN は docs/_internal/id_mapping_table.csv を Single Source of Truth として参照・追記する。aliases には旧ID表記（F-NN / F-0NN / F-00NN の桁数揺れも全て）を配列で含める

関連:

• docs/_internal/id_mapping_table.csv — 旧ID → MAS-NNN マッピング表（334 件、本ガイドの SSoT）
• scripts/_migration_id_scan.mjs — マッピング表生成スクリプト（再現可能）
• scripts/_migration_id_apply_frontmatter.mjs — フロントマター挿入スクリプト

解説: v1.10 までは ID 採番ルール（衝突防止）に焦点を当てたが、v1.11 は ID 体系そのものを刷新する大型変更。MDTM 化によりフロントマター内の構造化メタデータ（status / parent 等）を grep / プログラマブルに参照可能にし、後続の自動化（バックログ可視化・進捗集計・依存関係グラフ）の基盤を提供する。

v1.12 (2026-05-11 12:00) — スクリプトパイプラインを推奨経路として「使い方」冒頭に明示

変更内容:

• 「使い方」冒頭に「推奨: スクリプトパイプライン経由」セクションを新設
  • scripts/B2_generate_prompts_gemini.js → scripts/B3_run_writers.sh → scripts/B5_review_specs_by_gemini.js の 3 ステップをコマンド例として追記
  • 前提条件（GEMINI_API_KEY / todo_master_tables.md / claude CLI）を明記
• 既存の A/B 手動経路を「手動経路（フォールバック）」に位置づけ直し
• option B の TODO_future.md 参照を todo_master_tables.md に修正（PR #420 で移行済みのため）
• CLAUDE.md の Progress tracking と References にも対応する記述を追加

解説: スクリプト1・2パイプラインは v1.9 (2026-04-22) 以降の推奨経路として既に実装済みだったが、CLAUDE.md に言及がなく Claude が直接仕様書を書いてしまう事例が発生（MAS-364）。CLAUDE.md の Progress tracking に「直接書かない」旨を明記し、本テンプレートをその参照先として位置づけることで閉ループを確立する。

v1.13 (2026-05-13 JST) — Walking Skeleton slice_id 割当手順を「使い方」に追加

契機: ADR-0021 (UC スライス × Walking Skeleton 開発) / ADR-0025 (slice_id 命名規則) / ADR-0027 (実行時計測基盤) の採択を受け、新規仕様書作成時に slice_id を紐付けるフローが未定義だった。

本文プロンプト変更:

• 「使い方 → 推奨: スクリプトパイプライン経由」内に Phase 1-A-pre2: slice_id 確認 ステップを新設:
  1. docs/_internal/usecase_dev_mapping.md の §4/§5 テーブルで対象 MAS を検索
  2. 該当行の slice_id 列を確認（未割当なら UC-{N}-S{NN} 形式で新規採番）
  3. walking_skeleton_status が pending → skeleton に移行する作業かどうかを判定
  4. 仕様書フロントマターの slice_id フィールドに値を記入（ADR-0025 準拠）
• Walking Skeleton 4 要素チェックリスト を「完了条件」セクションのテンプレートに追加:
  • Input: 最小データを与えると関数が起動する
  • Output: 期待する列・シートに値が書き込まれる
  • Log: Utils.auditLog に PASS エントリが記録される
  • Error: 不正入力で適切に例外が発生する
• Utils.measureRuntime_ でラップするテスト関数の命名規則を明記: test_{slice_id}_{condition}_()（ADR-0027 準拠）

関連:

• docs/_internal/usecase_dev_mapping.md §2 命名規則 — slice_id / walking_skeleton_status / now_next_later の SSoT
• docs/adr/0025-uc-slice-id-system-and-naming-convention-unification.md — 命名規則の決定根拠
• docs/adr/0027-implement-walking-skeleton-runtime-metrics.md — 計測ラップ実装の決定根拠

解説: v1.12 まではスクリプトパイプラインの「経路」を整備したが、新規仕様書が Walking Skeleton のどのスライスに対応するかを記録する仕組みが未整備だった。v1.13 で slice_id を仕様書フロントマターに必須化することで、仕様書 → 実装 → テスト → RUNTIME_METRICS の 4 点計測まで一気通貫で追跡可能にする。

v1.14 (2026-05-13 18:00) — Walking Skeleton 4 要素チェックリスト・品質チェックリスト拡充（ADR-0028/0029 反映）

契機: ADR-0028 (UC スライス 6 段ワークフロー) / ADR-0029 (Spec/Impl Pipeline) の採択を受け、v1.13 で changelog には記録したが本文への反映が未実施だった。

本文への追記内容:

• 「Phase 1-A-pre2: slice_id 確認」を ### 1-A-pre の直後に新設: usecase_dev_mapping.md での slice_id 確認 / 未割当時の採番 / Walking Skeleton 4 要素チェックリスト表 / 6 分制限見積もり明記
• 品質チェックリストに 5 項目追加（(v1.14) マーク付き）:
  • UC スライス: slice_id フロントマター記入確認
  • Walking Skeleton 4 要素の「動作確認」セクション明記確認
  • test_{slice_id}_{condition}_() 命名規則確認
  • Feature Flag キー名 30 文字制限確認（failure_patterns #38）
  • 6 分制限推定実行時間明記確認（failure_patterns #39）

関連:

• scripts/B4_inject_walking_skeleton.js — 動作確認セクション直前に Walking Skeleton チェックリストを自動挿入するツール
• docs/_internal/failure_patterns.md #37-#39 — Walking Skeleton 準拠漏れパターン 3 件

解説: v1.13 はスクリプトパイプライン側（scripts/1 メタプロンプト・scripts/4 レビュー観点）の強化が主体だったが、仕様書テンプレート本文には Walking Skeleton の具体的な確認事項が不足していた。v1.14 で本文・品質チェックリスト・ツール参照を揃え、仕様書作成者が 4 要素の抜けなく仕様書に記載できるようにする。