---
name: poodle-knowledge-guide
description: |
  Poodle のナレッジ検索・提案を高精度に行うためのガイドスキル。
  検索オプションの使い分け、提案に必要な情報の構成、kind の選び方を
  エージェントに教える。「Poodle で検索して」「ナレッジを提案して」
  「コンテキストを作って」のように Poodle 操作を依頼されたら自動的に
  参照する。
---

# Poodle Knowledge Guide

## Purpose

Poodle のナレッジ検索と提案を精度高く行うためのリファレンス。
エージェントがこのガイドに従うことで、適切なオプションで検索し、
レビュアーが承認しやすい質の高い提案を作成できる。

## When to use

- Poodle で検索するとき（`poodle search` / MCP `search_context`）
- ナレッジを提案するとき（`poodle propose` / MCP `propose_context`）
- 「この知識を Poodle に入れて」と依頼されたとき
- 検索結果が少ない・的外れなとき（クエリ改善のヒント）

---

## 検索ガイド

### 基本: まずシンプルに検索する

```bash
poodle search "SSO 監査ログ"
```

Poodle はベクトル検索 + 全文検索を自動的に組み合わせる。まずは自然文で検索し、
結果を見てから絞り込む。

### 検索オプションの使い分け

| やりたいこと | オプション | 例 |
|-------------|-----------|---|
| 特定領域に絞る | `--area <nodeId>` | `poodle search "認証" --area node_dom_engineering` |
| 種別で絞る | `--kind <kind>` | `poodle search "デプロイ" --kind howto` |
| 日付で絞る | `--since` / `--until` | `poodle search "障害" --since 2026-06-01` |
| ソースで絞る | `--source <id>` | `poodle search "設計" --source src_col_xxx` |
| AI でリランク | `--instruction "..."` | `poodle search "権限" --instruction "ポリシーを優先"` |
| 件数を増やす | `--limit N` | `poodle search "API" --limit 20` |

### 検索のコツ

1. **具体的な用語で検索する** — 「設計」より「レイヤリング設計」「route service repository」
2. **結果が少なければ別の言い回しを試す** — 日本語/英語の両方、略語/正式名称
3. **`--area` で領域を絞ると精度が上がる** — まず `poodle map` でツリーを確認
4. **`--instruction` でリランクの方向を指示する** — 「ポリシーや制約を優先」「最新を優先」「実装例を優先」
5. **`--kind` で種別を絞る** — ルールを探すなら `--kind rule`、手順なら `--kind howto`

### MCP の search_context

```
search_context({
  query: "SSO 監査ログ",
  kind: "rule",
  area: "node_dom_engineering",
  instruction: "ポリシーや制約を優先",
  limit: 10
})
```

### 結果が的外れなときのチェックリスト

- [ ] クエリが抽象的すぎないか → 具体的な用語に
- [ ] 対象領域が正しいか → `poodle map` で確認して `--area` 指定
- [ ] 種別が合っているか → `--kind` で絞る
- [ ] リランク指示を使っているか → `--instruction` で方向を明示
- [ ] 知識がまだ登録されていない可能性 → `poodle propose` で提案する

---

## 提案ガイド

### 良い提案の構成

提案がレビュアーに承認されるためには、以下の要素が揃っていることが重要。

| 要素 | 必須 | 説明 |
|------|------|------|
| title | 必須 | 結論を1行で。「〇〇は△△する」の形式が理想 |
| body | 必須 | 根拠・背景・具体例を含む。3-5文以上 |
| kind | 必須 | 内容に最も合った種別（下記参照） |
| area | 推奨 | taxonomy ノード。`poodle map` で確認 |
| summary | 任意 | 検索結果に表示される要約。body が長いときに有効 |

### kind の選び方

| kind | いつ使う | title の例 |
|------|---------|-----------|
| `rule` | チームが守るべきルール・規約 | 「DB クエリは必ずパラメータ化する」 |
| `decision` | 設計判断とその理由 | 「ORM を使わず raw pg にした理由」 |
| `fact` | 確認された事実・仕様 | 「better-auth のセッション有効期限は 30 日」 |
| `howto` | 手順・やり方 | 「Cloud Run への本番デプロイ手順」 |
| `issue` | 既知の問題・罠 | 「psqldef の check 制約と vector(n) の同居問題」 |
| `reference` | 参考情報・用語定義 | 「actor = 操作主体（user または service account）」 |

### 提案の悪い例と良い例

**悪い例（承認されにくい）:**
```bash
poodle propose \
  --title "DB について" \
  --body "DB のクエリに注意する" \
  --kind fact
```
問題: タイトルが曖昧、body が薄い、kind が不適切（ルールなのに fact）

**良い例（承認されやすい）:**
```bash
poodle propose \
  --title "DB クエリは必ずパラメータ化する（SQL インジェクション防止）" \
  --body "raw pg を使うときは必ず query(sql, [params]) で値をバインドする。\
文字列補間で値を組み立てない。これは全 repository メソッドで徹底する。\
PR レビューでも最重点チェック項目。違反があれば即修正を求める。" \
  --kind rule \
  --area node_dom_engineering
```
ポイント: タイトルに結論、body に根拠と具体例、正しい kind、適切な area

### MCP の propose_context

```
propose_context({
  title: "DB クエリは必ずパラメータ化する（SQL インジェクション防止）",
  body: "raw pg を使うときは...",
  kind: "rule",
  taxonomyNodeId: "node_dom_engineering"
})
```

### 提案前のチェックリスト

- [ ] **タイトルに結論があるか** — 読むだけで何のナレッジか分かる
- [ ] **body に根拠があるか** — なぜそうすべきか、どこで決まったか
- [ ] **body に具体例があるか** — コード例、手順、条件
- [ ] **kind は適切か** — 上の表を参照
- [ ] **重複していないか** — まず `poodle search` で既存を確認
- [ ] **area を指定したか** — `poodle map` で適切なノードを確認

---

## プライベートコンテキスト

`--visibility private` で作成すると、レビューなしで即時保存・検索できる個人メモになる。
自分だけに見え、他のメンバーの検索には出ない。

### いつ使う

- 作業中のメモ・気づきをすぐに記録したいとき
- まだ確信がないがとりあえず残しておきたいとき
- 自分だけの参照用（個人のランブック、覚書）

### 使い方

```bash
# プライベートコンテキストを作成（即時検索可能、レビュー不要）
poodle propose \
  --title "psqldef の migration 手順メモ" \
  --body "1. schema.sql を編集 2. pnpm db:diff で差分確認 3. pnpm db:apply で適用" \
  --kind howto \
  --visibility private
```

```
# MCP
propose_context({
  title: "psqldef の migration 手順メモ",
  body: "...",
  kind: "howto",
  visibility: "private"
})
```

### 組織に共有（昇格）

プライベートコンテキストが他のメンバーにも有用だと判断したら、組織に昇格できる。
昇格するとレビュー待ちになり、承認されると全メンバーの検索に出る。

```
# MCP
promote_to_org({ id: "ctx_01..." })
```

### org（デフォルト）との違い

| | org（デフォルト） | private |
|---|---|---|
| 作成後 | レビュー待ち（proposed） | 即時承認（approved） |
| 検索露出 | 承認後に全メンバー | 作成者のみ |
| レビュー | 必要 | 不要 |
| 用途 | チーム知識 | 個人メモ・下書き |

---

## 変更フィードの活用

```bash
# 前回から更新されたナレッジを確認
poodle changes --since 2026-06-25

# 特定領域の更新だけ
poodle changes --since 2026-06-25 --area node_dom_engineering
```

初回は現在日時を `--since` に渡してカーソルを発行。レスポンスの `asOf` を次回の
`--since` に使えば漏れなし。

---

## コンテキストマップの活用

```bash
poodle map
```

ツリー構造と各領域の件数が表示される。検索の `--area` に渡す nodeId はここで確認。
知識が足りない領域を見つけたら、提案で補充する。