extract-glossary

extract-glossary

用于从指定代码库中创建面向人工入职引导的资料，以及防止 AI 反复确认的知识库的技能。 产出内容分为“术语词典”“代码库实现地图”“技术架构”和“小型 Mermaid 图”。

目的

• 帮助新加入的成员快速了解行业术语、组织内部术语和实现专有名称。
• 让 AI Agent 无需每次都询问相同的术语或架构，而是能够参考现有资料开展工作。
• 让代码库说明基于 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 合理确定，就开始探索。

成果的标准结构

作为技能创建时，基本采用以下结构。

<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. 如果有本地 checkout，确认 git remote -v 和 git rev-parse HEAD。
3. 查看 GitHub 上的 repo 时，确认 default branch 和 URL。
4. 成果中应附上 GitHub URL，而不是特定机器上的本地路径。

可以使用本地路径进行调查，但在最终成果中应转换为以下形式。

/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 等
• 入口点和路由：main.*、routes.*、controller/resolver/handler 文件

避免以下内容：

• node_modules、vendor、生成代码、构建产物、压缩文件、lockfile 细节
• 将大量日志或 fixture 作为主要信息来源
• 仅凭名称就下结论

探索时，先使用 rg --files 和 rg。

3. 提取候选术语

术语必须分类。

分类	示例	判断标准
行业术语	RTB, SSP, VAST, OAuth, ETL	公司外部也通用的标准术语或行业术语。
领域术语	Publisher, Campaign, Order, Placement	业务领域中的概念。即使是公司外部的术语，在产品内部也有特定含义。
组织内部术语	缩写、旧称、团队专有名称	出现在 README/docs/code 中，但不是外部标准。
实现专有名称	service 名称、directory 名称、table 前缀	代码库中的组成部分。
基础设施术语	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 层级对应表，再仅对重要的 repo 拆分到 component 层级。

5. 汇总技术架构和基础设施架构

至少应分别说明以下方面：

• runtime 请求流
• config / master data 流
• batch / ETL / report 流
• auth / identity / user data 流
• DB / search / cache / object storage
• cloud 资源和 IaC 归属
• deploy / rollback / observability
• 本地开发的前置条件

云架构应分别说明“使用了哪些服务”和“由哪个 repo 管理”。

绘制 Mermaid 图

不要绘制一张庞大的图。每张图只聚焦一个主题。

推荐的小图：

图	目的
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 的流向。

图的限制：

• 每张图约 10 个节点、15 条边。
• 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 とし、根拠の弱さを明示する。

品質チェック

提出前に以下を確認する。

# ローカルパス漏れ
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 に進む。