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