# 出力契約 スタイルガイド

このガイドは `output-contracts/` のファイルを作成・編集する際のルールを定義する。

## テンプレート

`templates/reports/` にテンプレートファイルを用意している。新規作成時は参照して使う。

| テンプレート | 用途 |
|------------|------|
| `plan.md` | タスク計画（標準 / 拡張） |
| `architecture-design.md` | アーキテクチャ設計 |
| `review.md` | 汎用レビュー結果 |
| `security-review.md` | セキュリティレビュー（重大度付き） |
| `validation.md` | 最終検証結果 |
| `summary.md` | タスク完了サマリー |

---

## 出力契約とは

エージェントが出力するレポートの構造定義。ピースYAMLの `report.format` フィールドで使用する。

| 項目 | 内容 |
|------|------|
| 目的 | エージェント出力の構造を統一し、後続ムーブメントで機械的に参照可能にする |
| 配置 | Phase 2 メッセージの `## Instructions` 内（`{{outputContract}}`） |
| 対象 | 1つのレポートファイル |
| 判断基準 | 「この出力は後続ムーブメントが `{report:filename}` で参照するか？」→ YES |

### 実際の配置先

出力契約は `src/shared/prompts/{lang}/perform_phase2_message.md` の `{{outputContract}}` に展開される。

```
## 実行コンテキスト（作業ディレクトリ）
## 実行ルール（ソース変更禁止、レポートのみ）
## Piece Context
## Instructions
  "レポートとして回答してください。ツールは使えません。"
  {{outputContract}}  ← ★ 出力契約がここに展開される
```

Phase 2 はツール使用不可。エージェントは Phase 1 のセッションを引き継いだ上で、テキスト出力のみでレポートを作成する。

### インストラクションとの違い

| | インストラクション | 出力契約 |
|--|-------------------|-------------------|
| 目的 | 何をすべきかの手順 | 出力の構造定義 |
| 配置 | Phase 1 `{{instructions}}` | Phase 2 `{{outputContract}}` |
| 読者 | エージェント（実行時） | 後続ムーブメントのエージェント（参照時） |
| 形式 | 自由文 + 箇条書き | ```markdown コードブロック |

---

## 書き方ルール

### 全体構造

出力契約は以下の構造を持つ。

```
1. ```markdown コードブロック（フォーマット本体）
2. 認知負荷軽減ルール（該当する場合）
```

### 出力契約本体

必ず ` ```markdown ` コードブロックで囲む。

```markdown
\`\`\`markdown
# レポートタイトル

## 結果: APPROVE / REJECT

## サマリー
{1-2文で結果を要約}

## 詳細
...
\`\`\`
```

### プレースホルダー

- `{波括弧}` でプレースホルダーを記述
- エージェントが実行時に埋める内容の説明を簡潔に

```markdown
# 良い例
{1-2文で結果を要約}
{タスクの1行要約}
{影響するモジュールや機能}

# 悪い例
{ここにサマリーを記述してください。サマリーは1-2文で簡潔に書いてください。}  ← 冗長
```

### 結果ステータス

レビュー系レポートは結果ステータスを持つ。使用するステータスを `/` で列挙する。

| パターン | 用途 |
|---------|------|
| `APPROVE / REJECT` | 二値判定（AI Review、Security Review 等） |
| `APPROVE / IMPROVE / REJECT` | 三値判定（Architecture Review 等） |
| `完了` | 固定値（Summary 等） |

### テーブル

構造化データはテーブルで記述する。

```markdown
# 検証テーブル（チェックリスト形式）
| 観点 | 結果 | 備考 |
|------|------|------|
| 仮定の妥当性 | ✅ | - |

# 問題テーブル（番号付き）
| # | カテゴリ | 場所 | 問題 |
|---|---------|------|------|
| 1 | 幻覚API | `src/file.ts:23` | 存在しないメソッド |

# ファイルテーブル
| 種別 | ファイル | 概要 |
|------|---------|------|
| 作成 | `src/file.ts` | 概要説明 |
```

テーブルの頻出カラム:

| カラム | 使い方 |
|--------|--------|
| `#` | 連番 |
| `スコープ` | 「スコープ内」/「スコープ外」 |
| `場所` | `` `src/file.ts:42` `` 形式 |
| `結果` | ✅ / ❌ |
| `重大度` | High / Medium / Low |
| `種別` | 作成 / 変更 / 削除 |

### 認知負荷軽減ルール

レビュー系レポートには認知負荷軽減ルールを付加する。出力契約本体の ` ``` ` の後に記述する。

```markdown
**認知負荷軽減ルール:**
- APPROVE → サマリーのみ（5行以内）
- REJECT → 問題点を表形式で（30行以内）
```

目的: 問題がない場合に冗長な出力を抑制する。後続ムーブメントの入力コストを下げる。

---

## DO / DON'T

| DO | DON'T |
|----|-------|
| ```markdown コードブロックで囲む | プレーンテキストで出力契約を書く |
| プレースホルダーは `{簡潔な説明}` | 冗長な説明をプレースホルダーに入れる |
| テーブルで構造化データを表現 | 箇条書きの入れ子で複雑な構造を表現 |
| 認知負荷軽減ルールで出力量を制御 | APPROVE でも REJECT と同量の出力を求める |
| ステータスの選択肢を明示（APPROVE / REJECT） | ステータスの定義を曖昧にする |
| 場所は `` `file:line` `` 形式 | 自然言語で場所を説明する |

---

## 出力契約に書いてはいけないもの

1. **実行手順**: 「まず〜を確認し」等の手順はインストラクションの責務
2. **判断基準の詳細**: 「何をもって REJECT とするか」はペルソナまたはインストラクションの責務
3. **ピース固有のルーティング**: 「REJECT の場合は fix ムーブメントへ」等

---

## カテゴリ別パターン

### 計画系（plan, architecture-design）

- 結果ステータスなし
- セクション構造: 元の要求 → 分析結果 → 実装ガイドライン
- テーブル: ファイル構成

```markdown
# タスク計画
## 元の要求
## 分析結果
### 目的 / スコープ / 実装アプローチ
## 確認事項
```

### レビュー系（ai-review, architecture-review, qa-review, security-review, frontend-review, cqrs-es-review）

- 結果ステータス: APPROVE / REJECT（または APPROVE / IMPROVE / REJECT）
- セクション構造: 結果 → サマリー → 検証テーブル → 問題テーブル
- 認知負荷軽減ルール付き

```markdown
# {種別}レビュー
## 結果: APPROVE / REJECT
## サマリー
## 確認した観点（テーブル）
## 問題点（REJECTの場合）（テーブル）
```

### レビュー統合系（review-summary）

- 複数レビューの結果を1つにまとめる
- セクション構造: 総合判定 → 個別結果テーブル → 要注意の問題 → 改善提案

### コーダー出力系（coder-scope, coder-decisions）

- 結果ステータスなし
- 実装前（scope）と実装後（decisions）のペア
- コンパクト: 10-20行

### 検証系（validation）

- 結果ステータス: APPROVE / REJECT
- セクション構造: 結果 → 検証サマリーテーブル → 成果物 → 未完了項目
- ビルド・テストの確認方法を含む

### サマリー系（summary）

- 結果ステータス: 固定値「完了」
- セクション構造: タスク → 結果 → 変更内容テーブル → 確認コマンド
- ピースの最終出力として使用

---

## 共通ルール

### 文体

- プレースホルダー以外はそのまま出力される見出し・ラベル
- 常体（「〜する」）
- 簡潔に

### ファイル命名

- `{role}.md` または `{role}-{modifier}.md`
  - 例: `plan.md`, `ai-review.md`, `coder-scope.md`
- ハイフン区切り
- 英語小文字のみ
- 番号プレフィックスを付けない（`01-plan.md` ではなく `plan.md`）

番号プレフィックスはピース構造に依存するため、共有ファイルでは使用しない。番号はピースYAMLの `report.name` フィールドで付ける。

### ファイルサイズ

| 種別 | 目安 | 上限 |
|------|------|------|
| コーダー出力 | 10-20行 | 25行 |
| レビュー | 15-25行 | 30行 |
| 検証・サマリー | 15-25行 | 30行 |
| 計画・設計 | 15-25行 | 30行 |

認知負荷軽減ルールを含む場合は +3-5行。

---

## チェックリスト

- [ ] 出力契約本体が ```markdown コードブロックで囲まれているか
- [ ] プレースホルダーが `{簡潔な説明}` 形式か
- [ ] レビュー系は結果ステータス（APPROVE / REJECT 等）が明示されているか
- [ ] テーブルの場所カラムが `` `file:line` `` 形式か
- [ ] 認知負荷軽減ルールが付加されているか（レビュー系）
- [ ] 番号プレフィックスを付けていないか（ファイル名）
- [ ] 実行手順が混入していないか（インストラクションの責務）
- [ ] 30行以内に収まっているか（認知負荷軽減ルール除く）