2c7bd4834f
5つの関心を Persona, Policy, Instruction, Knowledge, Output Contract に統一。 ディレクトリ、YAMLキー、ソースコード、テンプレート、テスト、ドキュメントを全面更新。
274 lines
9.0 KiB
Markdown
274 lines
9.0 KiB
Markdown
# 出力契約 スタイルガイド
|
||
|
||
このガイドは `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行以内に収まっているか（認知負荷軽減ルール除く）
|