extract-glossary

# extract-glossary 指定されたコードベースから、人間のオンボーディング資料兼 AI の再確認防止用ナレッジを作るためのスキル。 成果物は「用語辞書」「リポジトリ実装マップ」「技術構成」「小さな Mermaid 図」に分ける。 ## 目的 - 新規参加者が、業界用語・組織内用語・実装固有名を短時間で読めるようにする。 - AI エージェントが同じ用語や構成を毎回聞き返さず、既存資料を参照して作業できるようにする。 - コードベースの説明を、推測ではなく README/docs/schema/IaC/code 上の根拠に結びつける。 ## 入力として受け取るもの 以下のどれでもよい。 - ローカル checkout のパス: `../repo`, `~/ghq/github.com/org/repo` - GitHub URL: `https://github.com/org/repo` - 複数リポジトリのリスト - GitHub organization 名と絞り込み条件 - 出力先: 既存 repo の docs、`.claude/skills/<domain>-glossary/`、任意の Markdown ファイル群 入力が曖昧な場合は、まず候補 repo と出力先を確認する。ただしローカルや GitHub から合理的に特定できる場合は探索を始める。 ## 成果物の標準構成 スキルとして作る場合は以下を基本にする。 ```text <domain>-glossary/ ├── SKILL.md ├── references/ │ ├── glossary.md │ ├── repository-map.md │ └── architecture.md └── assets/ └── architecture-diagrams.md ``` 通常の docs として作る場合も、同じ分割を保つ。 | ファイル | 役割 | | --- | --- | | `glossary.md` | 用語辞書。業界用語、ドメイン用語、組織内略称、実装固有名を分ける。 | | `repository-map.md` | repo ごとの責務、主要ディレクトリ、見るべき入口、外部依存をまとめる。 | | `architecture.md` | 技術スタック、データフロー、インフラ、デプロイ、運用上の注意をまとめる。 | | `architecture-diagrams.md` | Mermaid 図。巨大な一枚図ではなく、用途別の小さな図に分ける。 | | `SKILL.md` | AI がどの reference をいつ読むべきかだけを書く。詳細を詰め込みすぎない。 | ## 調査手順 ### 1. スコープを確定する 1. 対象 repo/org と対象 branch/commit を確認する。 2. local checkout がある場合は `git remote -v` と `git rev-parse HEAD` を確認する。 3. GitHub 上の repo を見る場合は default branch と URL を確認する。 4. 成果物には、機械固有のローカルパスではなく GitHub URL を載せる。 ローカルパスを使って調査してもよいが、最終成果物では以下のように変換する。 ```text /Users/me/ghq/github.com/org/repo/docs/foo.md -> https://github.com/org/repo/blob/<branch-or-sha>/docs/foo.md ``` ### 2. コーパスを作る 優先して読むもの: - `README.md`, `CLAUDE.md`, `AGENTS.md`, `docs/`, `adr/`, `design/`, `architecture/` - `openapi.yaml`, GraphQL schema, Protocol Buffers, SQL schema, migration, DB docs - Terraform, Packer, CDK, SAM, Helm, Kubernetes, GitHub Actions, deploy docs - package manifests: `package.json`, `go.mod`, `Cargo.toml`, `composer.json`, `pyproject.toml`, etc. - entrypoints and routing: `main.*`, `routes.*`, controller/resolver/handler files 避けるもの: - `node_modules`, `vendor`, generated code, build artifacts, minified files, lockfile details - 大量ログや fixture を主情報源にすること - 名前だけから断定すること 探索にはまず `rg --files` と `rg` を使う。 ### 3. 用語候補を抽出する 用語は必ず分類する。 | 分類 | 例 | 判断基準 | | --- | --- | --- | | 業界用語 | RTB, SSP, VAST, OAuth, ETL | 社外でも通じる標準・業界語。 | | ドメイン用語 | Publisher, Campaign, Order, Placement | 事業領域の概念。社外語でもプロダクト内の意味を持つ。 | | 組織内用語 | 略称、旧称、チーム固有名 | README/docs/code に出るが外部標準ではない。 | | 実装固有名 | service 名、directory 名、table prefix | コードベース内の構成要素。 | | インフラ用語 | ECS, Snowflake, Meilisearch, Packer | 技術基盤として理解が必要な語。 | 各用語には以下を持たせる。 - 用語 - 意味 - 分類 - 主な実装・参照 repo - 根拠 URL - 注意点または混同しやすい語 - 確度: `confirmed` / `inferred` / `needs-check` `inferred` は名前・配置からの推定。断定文にしない。 ### 4. リポジトリ実装マップを作る repo ごとに以下をまとめる。 - 何を実装しているか - 主要 component / directory - 技術スタック - 入口になる README/docs/source files - 他 repo との通信・データ依存 - DB/schema/API/protocol の境界 - 調査時に最初に見るべきファイル 複数 repo の関係は、まず粗い repo-level の対応表を作り、次に重要 repo だけ component-level に分解する。 ### 5. 技術構成・インフラ構成をまとめる 最低限、以下の観点を分けて書く。 - runtime request flow - config / master data flow - batch / ETL / report flow - auth / identity / user data flow - DB / search / cache / object storage - cloud resources and IaC ownership - deploy / rollback / observability - local development prerequisites クラウド構成は「どのサービスを使っているか」と「どの repo が管理しているか」を分ける。 ## Mermaid 図の作り方 巨大な一枚図にしない。1 図 1 トピックにする。 推奨する小図: | 図 | 目的 | | --- | --- | | repository overview | repo 間の大まかな責務と依存だけを見る。 | | config/data path | 管理画面や DB の設定が runtime に届く流れを見る。 | | request sequence | 実リクエストの runtime 通信を見る。sequenceDiagram を優先する。 | | integration entries | 外部 partner、webhook、protocol endpoint など入口別に見る。 | | infra ownership | Terraform/CDK/SAM などが何を管理するかを見る。 | | data pipeline | log/report/warehouse/search/indexing の流れを見る。 | 図の制約: - 1 図あたり 10 ノード前後、15 edge 前後を目安にする。 - Mermaid の `subgraph` を深くしすぎない。重なりや長い交差線が出たら分割する。 - edge label は短くする。説明は本文に逃がす。 - protocol/schema の詳細図は、ユーザーが明示的に求めた場合だけ作る。 - 生成物、schema、runtime 通信を同じ図に混ぜない。 - レンダリング結果が読みにくいなら、図を増やして分割する。 ## 出典・URL ルール - 成果物にはローカル絶対パスや `../repo` を載せない。 - 参照元は GitHub URL、公式 docs URL、またはユーザーが指定した永続 URL にする。 - local checkout で調査した場合も、remote URL と branch/commit から GitHub URL に変換する。 - private repo で URL が読めない可能性がある場合でも、読者が権限を持てば辿れる URL を載せる。 - 不確かな場合は `needs-check` とし、根拠の弱さを明示する。 ## 品質チェック 提出前に以下を確認する。 ```bash # ローカルパス漏れ rg -n -F '../' <output-dir> rg -n '/Users/|/home/' <output-dir> # Markdown の基本チェック git diff --check # Mermaid block 数と fence 対応 rg -n '(^```mermaid|^```$|^flowchart|^sequenceDiagram)' <diagram-file> # mmdc があればレンダリング確認 command -v mmdc && mmdc -i <diagram-file> -o /tmp/diagrams.svg ``` `mmdc` がない場合は、その旨を最終報告に書く。 ## 回答時の注意 - 「現時点の repo 上では」と「推定」を分ける。 - 業界用語と組織内用語を混ぜない。 - 成果物の用途が onboarding なら、読む順番と調査入口を必ず入れる。 - AI 用 skill にする場合、`SKILL.md` は薄く保ち、詳細は `references/` に逃がす。 - ユーザーが commit/push/PR を求めた場合だけ git publish flow に進む。