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. スコープを確定する
- 対象 repo/org と対象 branch/commit を確認する。
- local checkout がある場合は
git remote -vとgit rev-parse HEADを確認する。 - GitHub 上の repo を見る場合は default branch と URL を確認する。
- 成果物には、機械固有のローカルパスではなく 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 に進む。
