---
name: poodle-project-scan
description: >-
  プロジェクトの CLAUDE.md / README / スキーマ / コード構造を読み取り、仕様・用語・
  規約・設計判断をナレッジとして Poodle に提案する。poodle-github-research がリポジトリの
  PR/Issue 履歴から知識を抽出するのに対し、project-scan はプロジェクトの「今の状態」
  から基本知識を抽出する。
  Fire when the user asks (in any language) to scan a project for knowledge,
  プロジェクトをスキャンして, コードベースの知識を抽出, extract knowledge from codebase,
  scan project conventions.
---

# Project Scan: コードベースからナレッジを抽出

プロジェクトの CLAUDE.md、README、スキーマ、コード構造から仕様・用語・規約・設計判断を
抽出し、Poodle へのナレッジ提案（Import Packet の findings）として提出するスキル。

## Prerequisites

- **Poodle API key**: `POODLE_API_KEY` を取得済みであること（`poodle login` または Settings > サービスアカウント で発行）
- **Source Collection**: 提出先の Source Collection が登録済みであること。未登録の場合は
  スキルがガイドする

## Phase 1: スキャン対象の特定

以下のファイルを優先度順にスキャンする。存在しないファイルはスキップ。

### Tier 1（最優先 — プロジェクトの正本）
- `CLAUDE.md` — コーディング規約・レイヤリング・規律の正本
- `docs/roadmap.md` — 計画・設計の正本（先頭200行で構造を把握）
- `db/schema.sql` — データモデルの正本（テーブル定義・制約・コメント）
- `README.md` — プロジェクト概要

### Tier 2（補完 — 実装パターンの証拠）
- `package.json` — スタック・依存関係・npm scripts
- `.claude/skills/*/SKILL.md` — 既存スキルの仕様と発火条件
- `lib/` の主要ディレクトリ構造（ls で把握、ファイル中身は必要な箇所のみ）
- `app/api/` のルート一覧（API surface の把握）

### Tier 3（深掘り — 必要に応じて）
- `lib/auth/permissions.ts` — RBAC ロール定義
- `lib/validators/*.ts` — 入力バリデーション規約
- `lib/services/*.ts` — サービス層のパターン（先頭のコメント・型定義のみ）
- `tests/` のディレクトリ構造 — テスト戦略

**コンテキスト節約ルール**: ファイルは全文読みせず、構造把握に必要な部分のみ Read する。
大きなファイル（schema.sql 等）は Explore subagent で要約取得する。

## Phase 2: Finding の抽出

スキャンした内容から以下の4カテゴリで Finding を抽出する。

### カテゴリと `suggestedKind` の対応

| カテゴリ | suggestedKind | 例 |
|---------|---------------|-----|
| 用語定義 | `reference` | 「actor = 操作主体（user or service account）」 |
| コーディング規約 | `constraint` | 「テーブル名は必ず snake_case」 |
| 設計判断 | `decision` | 「ORM を使わず raw pg + パラメータ化クエリ」 |
| 実装パターン | `implementation_note` | 「ID 採番は newId() (ULID 互換)」 |

### 抽出ルール

1. **転記ではなく合成**: ファイルの文章をそのままコピーせず、1行の `claim` + 背景を含む
   `body` に再構成する。evidence には元テキストの該当箇所を引用する。

2. **粒度**: 1 Finding = 1 つの独立した知識単位。「レイヤリングは route → service →
   repository → db」は 1 Finding。各層の詳細は別 Finding にする。

3. **confidence の判定**:
   - `high`: CLAUDE.md に明記されている規約・用語
   - `medium`: コードから読み取れるパターン（明文化されていない）
   - `low`: 推測を含む設計意図

4. **topics**: 2-4 個のタグ（例: `["database", "naming"]`, `["auth", "rbac"]`）

5. **sourceUrl**: `file://` + 絶対パス（例: `file:///path/to/CLAUDE.md`）

## Phase 3: ユーザー確認

抽出した Finding を番号付きで一覧表示する:

```
## 抽出結果（N 件の Finding）

1. [reference] actor = 操作主体（user or service account）
   Source: CLAUDE.md 認証認可セクション
   Confidence: high

2. [constraint] テーブル名は必ず snake_case（psqldef の制約）
   Source: CLAUDE.md スキーマ設計セクション
   Confidence: high

3. [decision] ORM を使わず raw pg + パラメータ化クエリを採用
   Source: CLAUDE.md コーディング規約
   Confidence: high

...

除外する項目があれば番号で指定してください（例: 3,5,8）。
なければ「OK」で全件提出します。
```

AskUserQuestion で確認。ユーザーが除外番号を指定したらその Finding を除外する。

## Phase 4: Import Packet 作成・提出

### 4-1. Packet 構築

承認された Finding を Import Packet JSON に組み立てる:

```json
{
  "origin": "agent_research",
  "documents": [
    {
      "sourceUrl": "file:///path/to/CLAUDE.md",
      "title": "CLAUDE.md: <project-name> 開発ガイド",
      "retrievedAt": "<ISO 8601>",
      "summary": "<ファイルの概要 1-2 文>",
      "headings": ["スキーマ設計", "コーディング規約", ...]
    }
  ],
  "findings": [
    {
      "claim": "...",
      "body": "...",
      "sourceUrl": "file:///path/to/CLAUDE.md",
      "evidence": "...",
      "suggestedKind": "constraint",
      "confidence": "high",
      "topics": ["..."]
    }
  ],
  "agent": {
    "name": "project-scan"
  }
}
```

### 4-3. 提出

```bash
curl -sf -X POST "${POODLE_URL:-https://app.thepoodle.ai}/api/import-batches" \
  -H "x-api-key: ${POODLE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/project-scan-packet.json
```

成功したら batch ID を表示し、Poodle の提案レビュー画面での承認を促す。

## Phase 5: 結果サマリー

```
--- Project Scan Summary ---
Files scanned:  N
Findings:       M (submitted) / K (excluded by user)
Batch:          <batch-id>
Collection:     <collection-name>
---
提出された Finding は Poodle の「提案レビュー」画面で承認してください。
```

## Safety rules

- スキャン対象のファイル内容をそのまま `body` にコピーしない（転記ではなく合成）
- `.env` やシークレットを含むファイルはスキャンしない
- `evidence` フィールドには必要最小限の引用のみ（著作権配慮）
- 提出前に必ずユーザー確認を取る
- Import Packet の JSON を `/tmp/` に書き出す（コミットしない）