# ナレッジ スタイルガイド

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

## 参照元

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

| 参照ファイル | 用途 | 使用例 |
|------------|------|--------|
| `takt.md` | ドメイン知識 | frontend, backend, security |

---

## ナレッジとは

エージェントがレビュー・実装・計画時に参照するドメイン知識。ポリシー（行動規範）やインストラクション（実行手順）とは異なり、「何を知っているべきか」を定義する。

| 項目 | 内容 |
|------|------|
| 目的 | エージェントにドメイン固有の専門知識を与える |
| 配置 | user message（instruction 内） |
| 対象 | 特定ドメインに関わるエージェント全般 |
| 判断基準 | 「これはルールか、知識か？」→ 知識ならナレッジ |

### 実際の配置先

ナレッジは instruction 内に展開され、ポリシーと同じ Phase 1 メッセージに含まれる。

```
User Message (Phase 1):
  [実行コンテキスト]
  [Workflow Context]
  [User Request]
  [Previous Response]
  [Instructions]
    └── [ポリシー]      ← 共有行動規範
    └── [ナレッジ]      ← ★ ドメイン知識がここに展開される
```

ポリシーが「どう振る舞うべきか」を定義するのに対し、ナレッジは「何を知っているべきか」を提供する。同じ配置先だが役割が異なる。

ナレッジは設計・テスト・ドメインの判断材料と選択肢を説明する。探索順、検索範囲、編集命令は持たず、行数・分岐数・特定パターンだけで機械的に設計を決めない。

### ポリシーとの分離

```
この内容は…
├── 「〜すべき」「〜してはいけない」→ ポリシー（行動規範）
├── 「〜はこう動く」「〜の構造はこう」→ ナレッジ（ドメイン知識）
└── 「〜を実行しろ」→ インストラクション（手順）
```

ナレッジにはドメイン固有の判断材料、選択肢、適用条件を含めてよい。`REJECT`・`OK`・警告などの最終判定、finding 化、編集可否はポリシーの責務とし、ナレッジには置かない。単一のラベルや見た目だけで一律に結論を出す機械的な規則も、ポリシーにもナレッジにも置かない。ナレッジの判断表は、条件と理由から選択肢を比較するために使う。

| | ポリシー | ナレッジ |
|--|---------|---------|
| 性質 | 横断的ルール | ドメイン固有の知識 |
| 例 | 「観測可能な契約をテストする」「因果範囲外を編集しない」 | 「独立した変更理由は分離候補」「複数枝が同じ状態を共有すると所有者の再検討が必要」 |
| 適用範囲 | 全エージェント共通 | 特定ドメイン（frontend 等）のエージェント |

---

## 抽象度の原則

ナレッジは特定のツール・言語・フレームワークに依存せず、パターンや原則として記述する。コード例は具体的なツール/言語で示してよい。

```markdown
# ✅ 良い例: 原則 → 例示
テスト環境がグローバル状態（DOM等）に依存する場合、プロセスレベルの分離が必要。

| 環境 | 推奨 |
|------|------|
| DOM依存あり | プロセス分離 |
| 純粋ロジック | スレッド分離で十分 |

vitest の場合:
pool: 'forks'（DOM依存）/ pool: 'threads'（純粋ロジック）

# ❌ 悪い例: ツール固有の設定羅列
vitest.config.ts に以下を設定する:
pool: 'forks'
singleFork: true
teardownTimeout: 5000
forceExit: true
```

---

## セクション詳細

### トピック概要（必須）

- 各 `##` トピックの冒頭1-2文で概要を記述
- 体言止めまたは「〜する」で終わる

```markdown
# 良い例
## コンポーネント設計

コンポーネント境界は、責務、変更理由、再利用単位、状態の所有者で決める。

# 悪い例
## コンポーネント設計

コンポーネントについて説明します。  ← 丁寧語 + 情報がない
```

### 判断材料テーブル（推奨）

- トピックごとに「条件 → 意味・選択肢」テーブルを置く
- final verdict ではなく、その条件が示す責務、リスク、選択肢を具体的にする
- finding や編集の可否はポリシーへ委ねる

```markdown
| 条件 | 意味・選択肢 |
|------|-------------|
| 責務や変更理由が独立している | 分離候補 |
| 密接に協調し同じ理由で変わる | 同居可能 |
| 同じ意味・契約・変更理由を共有する | 共通所有者の候補 |
```

行数、分岐数、ファイル数のような数値は内容を読み直すきっかけにはなるが、REJECT、分割、抽象化、unit test の pass/fail を単独で決める基準にしない。

### コード例（推奨）

- 「良い例/悪い例」のペアで示す
- コメントで `// NG` `// OK` を付ける
- 原則を先に述べ、コード例は例示として配置する
- 言語は対象プロジェクトに合わせる（TypeScript が主）

```markdown
# 良い例: 原則 → コード例
親が所有する正規状態を、子が所有者の操作入口を経ずに直接変更しない。公開callbackで通知でき、親へ伝える必要がないlocal stateは子が所有する。

// NG - 親が所有する正規状態を子が直接変更
const ChildBad = ({ state }) => {
  state.value = 'changed'
  return <input value={state.value} />
}

// OK - 親の公開callbackで操作意図を通知
const ChildGood = ({ value, onChange }) => {
  return <input value={value} onChange={e => onChange(e.target.value)} />
}

// OK - 親へ伝える必要がないlocal state
const ChildLocal = () => {
  const [value, setValue] = useState('')
  return <input value={value} onChange={e => setValue(e.target.value)} />
}
```

### 選択基準テーブル（該当する場合）

- 複数の選択肢がある場合、判断基準をテーブルで示す
- 特定の1つを正解としない。条件に応じた使い分けを示す

```markdown
| 状態の性質 | 推奨配置 |
|-----------|---------|
| UIの一時的な状態 | ローカル（useState） |
| 複数コンポーネントで共有 | Context or 状態管理ライブラリ |
| サーバーデータのキャッシュ | データフェッチライブラリ |
```

---

## フォーマット

```markdown
# {ドメイン名}知識

## {トピック1}

{トピックの概要。1-2文}

| 条件 | 意味・選択肢 |
|------|-------------|
| ... | ... |

### {サブトピック}

{詳細な説明}

{コード例}

## {トピック2}
...
```

---

## DO / DON'T

| DO | DON'T |
|----|-------|
| パターンや原則を抽象的に記述する | 特定ツールの設定値をそのまま列挙する |
| コード例は具体的なツール/言語で示す | 本文を特定ツール前提で書く |
| ドメイン固有の判断材料と選択肢を示す | final verdict や横断的なルールを書く（→ ポリシー） |
| 選択肢がある場合は判断基準をテーブルで示す | 1つのツールだけを正解として提示する |
| 「なぜそうすべきか」の理由を書く | 設定のコピペだけで終わる |
| 同じ意味・契約・変更理由を判断軸にする | 行数や出現回数だけで抽象化方式を決める |

---

## ナレッジに書いてはいけないもの

1. **横断的な行動規範**: DRY、Fail Fast 等の全エージェント共通ルール → ポリシー
2. **実行手順**: どのファイルを読め、何を実行しろ等 → インストラクション
3. **workflow固有の概念**: step名、レポートファイル名
4. **ツール固有のパス**: `.takt/runs/` 等の具体的なディレクトリパス
5. **探索・編集命令**: 全文を読め、全参照を検索しろ、見つけた問題を直せ等

### ドメイン固有の判断材料

ドメイン用語のラベルだけで final verdict を決めず、実在する責務、変更理由、影響を判断材料として示す。

```markdown
# 許容 — フロントエンド固有の判断材料
| 条件 | 意味・選択肢 |
|------|-------------|
| 独立した複数の責務が同じコンポーネントで別々の理由により変わる | 分離候補 |
| 表示と副作用が同じ所有者・変更理由を共有する | 同居可能 |

# 非許容 — 横断的な行動規範（ポリシーの責務）
| 原則 | 基準 |
|------|------|
| 1テスト1概念 | 複数の関心事を1テストに混ぜない |
```

ドメイン固有の条件と選択肢はナレッジ。finding・編集権限や横断的な行動規範はポリシー。

---

## カテゴリ別パターン

### 技術スタック系（frontend, backend）

- レイヤー構造・パッケージ設計から始める
- 各トピックに評価基準テーブル + コード例

```markdown
# フロントエンド知識
## 層構造
## コンポーネント設計
## 状態管理
## データ取得
## テストインフラ
## アンチパターン検出
```

### 設計パターン系（cqrs-es, architecture）

- パターンの構造と適用条件を中心に
- 「いつ使うか / いつ使わないか」の判断基準を重視

### 横断関心事系（security）

- リスクレベル（重大 / 高 / 中 / 低）の評価基準
- 攻撃パターン → 対策 の構造
- チェックリスト形式が多い

---

## 共通ルール

### 見出しの深さ

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

### テーブル

判断材料テーブルは「条件 → 意味・選択肢」の形式で統一する。

```markdown
| 条件 | 意味・選択肢 |
|------|-------------|
| 条件A | リスクAを示す |
| 条件B | 選択肢Bを検討 |
| 条件C | 現在の責務と整合 |
```

### 文体

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

### ファイル命名

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

### 長さ

行数で合否を決めない。トピックが別の変更理由や利用者を持つ場合は分離し、同じ判断に必要な知識はまとまりを保つ。

---

## チェックリスト

- [ ] 原則やパターンとして抽象的に記述されているか（ツール固有の設定羅列になっていないか）
- [ ] コード例は具体的なツール/言語で示しているか
- [ ] 必要なトピックに条件・意味・選択肢があるか
- [ ] 横断的な行動規範が混入していないか（→ ポリシー）
- [ ] インストラクション（実行手順）が混入していないか
- [ ] ドメイン固有の判断材料とポリシーの final verdict・権限が分離されているか
- [ ] `####` 以下のネストがないか
- [ ] 行数ではなく、判断に必要な知識のまとまりで構成されているか