knowledge のスタイルガイド作成

builtins/ja/KNOWLEDGE_STYLE_GUIDE.md

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

builtins/ja/STYLE_GUIDE.md

@@ -6,6 +6,7 @@
 |---------|--------|--------|
 | ペルソナ | [PERSONA_STYLE_GUIDE.md](PERSONA_STYLE_GUIDE.md) | system prompt（`{{agentDefinition}}`） |
 | ポリシー | [POLICY_STYLE_GUIDE.md](POLICY_STYLE_GUIDE.md) | user message（instruction 内） |
+| ナレッジ | [KNOWLEDGE_STYLE_GUIDE.md](KNOWLEDGE_STYLE_GUIDE.md) | user message（instruction 内） |
 | インストラクション | [INSTRUCTION_STYLE_GUIDE.md](INSTRUCTION_STYLE_GUIDE.md) | Phase 1 メッセージ（`{{instructions}}`） |
 | 出力契約 | [OUTPUT_CONTRACT_STYLE_GUIDE.md](OUTPUT_CONTRACT_STYLE_GUIDE.md) | `report.format` |
 
@@ -61,7 +62,8 @@ User Message (Phase 1):
 ```
 この内容は…
 ├── 特定のエージェントだけが必要 → ペルソナ
-├── 複数のエージェントが共有 → ポリシー
+├── 「〜すべき」行動規範 → ポリシー
+├── 「〜はこう動く」「〜はこういう設計にすべき」ドメイン知識 → ナレッジ
 ├── ムーブメント固有の手順 → インストラクション
 └── エージェント出力の構造定義 → 出力契約
 ```

builtins/ja/policies/testing.md

@@ -77,6 +77,7 @@ test('ユーザーが存在しない場合、NotFoundエラーを返す', async
 | パラメータ連動 | テストの入力パラメータに応じてフィクスチャ・設定を生成する |
 | 暗黙の前提排除 | 特定の環境（ユーザーの個人設定等）に依存しない |
 | 整合性 | テスト設定内の関連する値は互いに矛盾しない |
+| プロセス終了保証 | テストランナーにタイムアウトと強制終了を設定し、プロセスリークを防ぐ |
 
 ```typescript
 // ❌ ハードコードされた前提 — 別のバックエンドでテストすると不整合になる