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

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

## 参照元

`facets/output-contracts/` を参照元として使う。新規作成時は既存ファイルを参照して使う。

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

---

## 出力契約とは

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

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

### 実際の配置先

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

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

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

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

| | インストラクション | 出力契約 |
|--|-------------------|-------------------|
| 目的 | 何をすべきかの手順 | 出力の構造定義 |
| 配置 | Phase 1 `{{instructions}}` | Phase 2 `{{outputContract}}` |
| 読者 | エージェント（実行時） | 後続 step のエージェント（参照時） |
| 形式 | 自由文 + 箇条書き | ```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 → 説明を簡潔にし、同じ原因の場所は集約する。ただし確認済みの blocking finding は省略しない
```

目的: 問題がない場合の冗長さと、指摘ごとの説明量を抑制する。認知負荷軽減ルールは finding の集合を削るために使わない。

---

## DO / DON'T

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

---

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

1. **実行手順**: 「まず〜を確認し」等の手順はインストラクションの責務
2. **判断基準の詳細**: 「何をもって REJECT とするか」はペルソナまたはインストラクションの責務
3. **workflow 固有のルーティング**: 「REJECT の場合は fix step へ」等
4. **別facetへのメタ参照**: 「適用policyが選定した値」「instructionで定義した条件」等。必要な内容は要求・差分・証拠との関係を自然言語で記録させる。コードが固定値として検証または保存するschemaでない限り、`Authorization Basis`のような英語ラベルや固定分類値を出力契約のために新設しない
5. **工程内部の説明**: Phase、selector、後続step、include関係など、レポート利用者が観測できない実行機構
6. **不要な新語**: 「同じ原因の問題」「今回の修正対象」のような通常語で表せる内容に、新しい分類名・略語・英語ラベルを付けない。正式な既存schemaの項目は、そのschemaを使う専用出力契約に限定する

---

## カテゴリ別パターン

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

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

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

### レビュー系（ai-review, architecture-review, testing-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）

- 結果ステータス: 固定値「完了」
- セクション構造: タスク → 結果 → 変更内容テーブル → 検証証跡
- workflow の最終出力として使用

---

## 共通ルール

### 文体

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

### ファイル命名

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

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

### ファイルサイズ

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

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

---

## チェックリスト

- [ ] 出力契約本体が ```markdown コードブロックで囲まれているか
- [ ] プレースホルダーが `{簡潔な説明}` 形式か
- [ ] レビュー系は結果ステータス（APPROVE / REJECT 等）が明示されているか
- [ ] テーブルの場所カラムが `` `file:line` `` 形式か
- [ ] 認知負荷軽減ルールが付加されているか（レビュー系）
- [ ] 番号プレフィックスを付けていないか（ファイル名）
- [ ] 実行手順が混入していないか（インストラクションの責務）
- [ ] policy・instruction・Phase・selectorなどを逆引きさせるメタ指示がないか
- [ ] コードが固定値として検証または保存しない英語ラベルや分類値を、評価やプロンプト調整のためだけに追加していないか
- [ ] 説明部分が30行以内に収まり、確認済みの blocking finding が件数を理由に省略されていないか