# ポリシー スタイルガイド

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

## 参照元

`facets/policies/` を参照元として使う。新規作成時は既存ファイルをコピーして使う。

| 参照ファイル | 用途 | 使用例 |
|------------|------|--------|
| `coding.md` | 共有行動規範 | coding, review, testing |

---

## ポリシーとは

複数のエージェントが共有する行動規範。user message（instruction 内）に配置される。

| 項目 | 内容 |
|------|------|
| 目的 | 複数エージェントが共有する行動規範 |
| 配置 | user message（instruction 内） |
| 対象 | 複数のエージェント |
| 判断基準 | 「複数のエージェントが同じルールに従うか？」→ YES ならポリシー |

ポリシーは原則、禁止事項、finding・編集を許可する因果範囲を定義する。読む順番、検索方法、コマンド、全セクション列挙などの探索手順はインストラクションへ置く。

### ペルソナとの分離

```text
このルール/知識は…
├── identity・専門性・責任境界 → ペルソナ
├── 複数のエージェントが共有 → ポリシー
└── 特定のワークフローの実行手順 → instruction（ポリシーに書かない）
```

---

## フォーマット

```markdown
# {ポリシー名}

{1文の目的説明。「〜する。」で終わる}

## 原則

| 原則 | 基準 |
|------|------|
| ... | ... |

## {ルールカテゴリ1}

{自由形式: テーブル、コード例、箇条書き}

## {ルールカテゴリ2}
...
```

---

## セクション詳細

### 目的説明（必須）

- 1文でポリシーの目的を宣言
- 体言止めまたは「〜する。」で終わる

```markdown
# 良い例
速さより丁寧さ、実装の楽さよりコードの正確さを優先する。

# 悪い例
コーディングに関するルールです。  ← 曖昧
```

### 原則テーブル（必須）

- ポリシーの核心を5-10行のテーブルで表現
- 各行は「原則名 + 1行の基準」

### ルールカテゴリ（1つ以上）

- `##` で直接カテゴリを作る（`###` を挟まない）
- テーブル、コード例、箇条書きを自由に使う
- ネストは `###` まで（`####` は使わない）

---

## DO / DON'T

| DO | DON'T |
|----|-------|
| 複数エージェントに共通するルールを記載 | 特定エージェントにしか適用されない知識を含める |
| コード例で「良い例/悪い例」を示す | 抽象的な原則だけ列挙する |
| 目的説明は1文で簡潔に | 長い説明文を書く |
| `##` でカテゴリを直接分ける | `####` 以下のネストを使う |
| 独立した不変条件の判定を1つのポリシーで所有する | 同じ判定をpersona・別policy・instructionへ言い換えて重複させる |
| finding と編集の因果範囲を明示する | 「見つけたらすべて直す」のように探索範囲を編集権限へ変換する |

---

## ポリシーに書いてはいけないもの

1. **特定エージェント固有の知識**: Architecture Reviewer だけが使う検出手法等
2. **ワークフロー固有の概念**: ステップ名、レポートファイル名
3. **ツール固有のパス**: `.takt/runs/` 等の具体的なディレクトリパス
4. **実行手順**: どのファイルを読め、何を実行しろ等
5. **無条件の探索拡大**: 全ファイル、全入口、全セクションを列挙・確認させる手順
6. **メタ参照**: 「このpolicy」「適用policy」「include元」など、規則そのものではなくプロンプト組成を参照させる記述

### workflow固有規則の分離

初回・後続、特定ラウンド、提出元、完了・差し戻し、step間の状態遷移はworkflow YAMLの責務とし、汎用policyへ入れない。

複数stepへ文章として渡すworkflow固有規則は`workflows/rules/`の別ファイルにし、`all_steps.rules`の配列で合成する。

```yaml
all_steps:
  rules:
    - ref: findings-handling
    - ref: peer-review-scope
```

workflowの状態や役割に依存せず複数stepで共有できる判断規則だけは、汎用policyと別ファイルにして`policy`配列で合成できる。実行順序はinstruction、routingとworkflow固有の適用条件は`rules`に残す。

---

## 共通ルール

### 判定規則の正本

独立して適否を判定する不変条件は、1つのポリシーだけを正本にする。personaは担当する役割、instructionは工程固有の手順、output contractは報告項目だけを記載し、正本の判定を再定義しない。別facetで必要な場合は、正本のポリシーを合成して使う。

同じstepへ正本ポリシーを複数の継承・合成経路から重ねて含めない。規則を追加・変更するときは代表的な完成プロンプトを組み立て、同義の判定が重複していないことを確認する。

### 見出しの深さ

最大 `###` まで。`####` 以下は使わない。深くなる場合は構造を見直す。

### コード例

- 「良い例/悪い例」のペアで示す
- コメントで `// REJECT` `// OK` `// APPROVE` を付ける
- 言語は対象プロジェクトに合わせる（TypeScript が主）

```typescript
// REJECT - 問題の簡潔な説明
const bad = ...

// OK - 正しい理由の簡潔な説明
const good = ...
```

### テーブル

判定基準テーブルは「基準 → 判定」の形式で統一する。

```markdown
| 基準 | 判定 |
|------|------|
| 条件A | REJECT |
| 条件B | 警告 |
| 条件C | OK |
```

### 文体

- 体言止めまたは「〜する」の常体
- 丁寧語（です・ます）は使わない
- 簡潔に。冗長な説明は避ける

### ファイル命名

- `{category}.md`（例: `coding.md`, `review.md`, `testing.md`）
- ハイフン区切り（スネークケース不可）
- 英語小文字のみ
- ディレクトリでグルーピングしない（フラット構造）

### 長さ

行数で合否を決めない。独立した不変条件の正本だけを残し、実行手順、知識、出力形式をそれぞれのfacetへ分離する。

---

## チェックリスト

- [ ] 目的説明が1文で書かれているか
- [ ] 原則テーブルがあるか
- [ ] 複数のエージェントに適用可能な内容か
- [ ] 特定エージェント固有の知識が混入していないか
- [ ] ワークフロー固有の概念が含まれていないか
- [ ] workflow固有規則をpolicyへ混ぜず、`workflows/rules/`から`all_steps.rules`の配列で合成しているか
- [ ] 親workflowから子へ継承される`all_steps.rules`に、通常のreviewerが不要な裁定・修正台帳・最終確認の規則を置いていないか
- [ ] policyやfacetの組成を本文から参照させるメタ表現がないか
- [ ] ツール固有のパスが含まれていないか
- [ ] `####` 以下のネストがないか
- [ ] 各判定規則の正本が1つに定まり、他facetへ同義の判定を重複させていないか
- [ ] 完成プロンプトで同じ正本ポリシーが複数経路から重複していないか