takt/builtins/ja/REPORT_STYLE_GUIDE.md

レポートフォーマット スタイルガイド

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

テンプレート

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

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

---

レポートフォーマットとは

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

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

実際の配置先

レポートフォーマットは src/shared/prompts/{lang}/perform_phase2_message.md の {{reportFormat}} に展開される。

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

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

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

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

---

書き方ルール

全体構造

レポートフォーマットは以下の構造を持つ。

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

フォーマット本体

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

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

## 結果: APPROVE / REJECT

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

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

プレースホルダー

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

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

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

結果ステータス

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

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

テーブル

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

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

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

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

テーブルの頻出カラム:

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

認知負荷軽減ルール

レビュー系レポートには認知負荷軽減ルールを付加する。フォーマット本体の ``` の後に記述する。

**認知負荷軽減ルール:**
- 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）

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

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

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

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

# {種別}レビュー
## 結果: 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行以内に収まっているか（認知負荷軽減ルール除く）