From 27d650fa1030df38192d10d464a7e872f305b39b Mon Sep 17 00:00:00 2001 From: nrslib <38722970+nrslib@users.noreply.github.com> Date: Tue, 17 Feb 2026 08:45:06 +0900 Subject: [PATCH] =?UTF-8?q?knowledge=20=E3=81=AE=E3=82=B9=E3=82=BF?= =?UTF-8?q?=E3=82=A4=E3=83=AB=E3=82=AC=E3=82=A4=E3=83=89=E4=BD=9C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- builtins/ja/KNOWLEDGE_STYLE_GUIDE.md | 306 +++++++++++++++++++++++++++ builtins/ja/STYLE_GUIDE.md | 4 +- builtins/ja/policies/testing.md | 1 + 3 files changed, 310 insertions(+), 1 deletion(-) create mode 100644 builtins/ja/KNOWLEDGE_STYLE_GUIDE.md diff --git a/builtins/ja/KNOWLEDGE_STYLE_GUIDE.md b/builtins/ja/KNOWLEDGE_STYLE_GUIDE.md new file mode 100644 index 0000000..148299b --- /dev/null +++ b/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 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行 | + +--- + +## チェックリスト + +- [ ] 原則やパターンとして抽象的に記述されているか（ツール固有の設定羅列になっていないか） +- [ ] コード例は具体的なツール/言語で示しているか +- [ ] 各トピックに評価基準テーブルがあるか +- [ ] 横断的な行動規範が混入していないか（→ ポリシー） +- [ ] インストラクション（実行手順）が混入していないか +- [ ] ドメイン固有の評価基準とポリシーの境界が明確か +- [ ] `####` 以下のネストがないか +- [ ] カテゴリに応じたファイルサイズ目安に収まっているか diff --git a/builtins/ja/STYLE_GUIDE.md b/builtins/ja/STYLE_GUIDE.md index 98653e0..2efc5c2 100644 --- a/builtins/ja/STYLE_GUIDE.md +++ b/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): ``` この内容は… ├── 特定のエージェントだけが必要 → ペルソナ -├── 複数のエージェントが共有 → ポリシー +├── 「〜すべき」行動規範 → ポリシー +├── 「〜はこう動く」「〜はこういう設計にすべき」ドメイン知識 → ナレッジ ├── ムーブメント固有の手順 → インストラクション └── エージェント出力の構造定義 → 出力契約 ``` diff --git a/builtins/ja/policies/testing.md b/builtins/ja/policies/testing.md index 2aca6f9..cf13a97 100644 --- a/builtins/ja/policies/testing.md +++ b/builtins/ja/policies/testing.md @@ -77,6 +77,7 @@ test('ユーザーが存在しない場合、NotFoundエラーを返す', async | パラメータ連動 | テストの入力パラメータに応じてフィクスチャ・設定を生成する | | 暗黙の前提排除 | 特定の環境（ユーザーの個人設定等）に依存しない | | 整合性 | テスト設定内の関連する値は互いに矛盾しない | +| プロセス終了保証 | テストランナーにタイムアウトと強制終了を設定し、プロセスリークを防ぐ | ```typescript // ❌ ハードコードされた前提 — 別のバックエンドでテストすると不整合になる