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

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

## テンプレート

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

| テンプレート | 用途 | 使用例 |
|------------|------|--------|
| `knowledge.md` | ドメイン知識 | frontend, backend, security |

---

## ナレッジとは

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

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

### 実際の配置先

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

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

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

### ポリシーとの分離

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

ナレッジにはドメイン固有の評価基準（`| 基準 | 判定 |` テーブル）を含めてよい。ポリシーの「行動規範」とナレッジの「評価基準」の違いは次の通り。

| | ポリシー | ナレッジ |
|--|---------|---------|
| 性質 | 横断的ルール | ドメイン固有の知識 |
| 例 | 「1テスト1概念」「DRY」 | 「God Component は REJECT」「Props Drilling は REJECT」 |
| 適用範囲 | 全エージェント共通 | 特定ドメイン（frontend 等）のエージェント |

---

## 抽象度の原則

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

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

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

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

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

---

## セクション詳細

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

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

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

1ファイルにベタ書きしない。必ずコンポーネント分割する。

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

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

### 評価基準テーブル（推奨）

- トピックごとに「基準 → 判定」テーブルを置く
- 判定は OK / 警告 / REJECT / 分離を検討 等
- そのドメイン固有の品質基準を具体的に

```markdown
| 基準 | 判定 |
|------|------|
| 1コンポーネント200行超 | 分割を検討 |
| 1コンポーネント300行超 | REJECT |
| 複数の責務を持つコンポーネント | REJECT |
```

### コード例（推奨）

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

```markdown
# 良い例: 原則 → コード例
子コンポーネントは自身で状態を変更しない。イベントを親にバブリングし、親が状態を操作する。

// NG - 子が自分で状態を変更
const ChildBad = ({ initialValue }) => {
  const [value, setValue] = useState(initialValue)
  ...
}

// OK - 親が状態を管理、子はコールバックで通知
const ChildGood = ({ value, onChange }) => {
  return <input value={value} onChange={e => onChange(e.target.value)} />
}
```

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

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

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

---

## フォーマット

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

## {トピック1}

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

| 基準 | 判定 |
|------|------|
| ... | ... |

### {サブトピック}

{詳細な説明}

{コード例}

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

---

## DO / DON'T

| DO | DON'T |
|----|-------|
| パターンや原則を抽象的に記述する | 特定ツールの設定値をそのまま列挙する |
| コード例は具体的なツール/言語で示す | 本文を特定ツール前提で書く |
| ドメイン固有の評価基準をテーブルで示す | 横断的なルール（DRY等）を書く（→ ポリシー） |
| 選択肢がある場合は判断基準をテーブルで示す | 1つのツールだけを正解として提示する |
| 「なぜそうすべきか」の理由を書く | 設定のコピペだけで終わる |

---

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

1. **横断的な行動規範**: DRY、Fail Fast 等の全エージェント共通ルール → ポリシー
2. **実行手順**: どのファイルを読め、何を実行しろ等 → インストラクション
3. **ピース固有の概念**: ムーブメント名、レポートファイル名
4. **ツール固有のパス**: `.takt/runs/` 等の具体的なディレクトリパス

### 例外: ドメイン固有の評価基準

ポリシーの REJECT 判定と表面的に似ていても、特定ドメインの品質基準として記載する場合は許容する。

```markdown
# 許容 — フロントエンド固有の品質基準
| 基準 | 判定 |
|------|------|
| God Component | REJECT |
| Props Drilling（3階層以上） | 状態管理の導入を検討 |

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

ドメイン固有の評価基準（「God Component は REJECT」）はナレッジ。横断的な行動規範（「1テスト1概念」）はポリシー。

---

## カテゴリ別パターン

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

- レイヤー構造・パッケージ設計から始める
- 各トピックに評価基準テーブル + コード例
- 大規模になりやすい（500-800行）

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

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

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

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

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

---

## 共通ルール

### 見出しの深さ

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

### テーブル

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

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

### 文体

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

### ファイル命名

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

### ファイルサイズ

| 種別 | 目安 | 上限 |
|------|------|------|
| 横断関心事（security 等） | 100-200行 | 300行 |
| 設計パターン（cqrs-es 等） | 200-500行 | 600行 |
| 技術スタック（frontend 等） | 500-700行 | 800行 |

---

## チェックリスト

- [ ] 原則やパターンとして抽象的に記述されているか（ツール固有の設定羅列になっていないか）
- [ ] コード例は具体的なツール/言語で示しているか
- [ ] 各トピックに評価基準テーブルがあるか
- [ ] 横断的な行動規範が混入していないか（→ ポリシー）
- [ ] インストラクション（実行手順）が混入していないか
- [ ] ドメイン固有の評価基準とポリシーの境界が明確か
- [ ] `####` 以下のネストがないか
- [ ] カテゴリに応じたファイルサイズ目安に収まっているか