jargon-extractor

専門用語の抽出

複数のドキュメントを読み込み、新しい読者には分からない内部用語、略語、専門用語に印を付け、実行のたびにアルファベット順の単一の JARGON.md 用語集を維持します。

作業は、失敗のパターンと実行場所が異なる3つのフェーズに分かれます。抽出は判断を多く要する作業です。ある単語が専門用語に当たるかどうかは、ドキュメントを読んで判断する必要があります。関連付け、整理、統合も同様に判断を多く要します。候補を用語集に含めるべきか、2つの定義が同じ概念を表しているかを判断する必要があるためです。ファイルへの記録は機械的な作業です。毎回、正しく並べ替え、重複を除去し、ファイルを書き込みます。抽出と統合は、使い捨てのサブエージェントのコンテキスト内で行われ、短い要約だけを返します。ファイルへの記録は決定論的なスクリプトが担い、ファイルの内容をモデルのコンテキストに一切出力することなく、ディスク上のファイルを直接読み書きします。オーケストレーター自身のコンテキストに保持されるのはファイルパスと少量の件数だけで、抽出した用語の大部分が入ることはありません。

抽出と統合はいずれもサブエージェントで実行しますが、実行ごとに1回ずつだけで、ウェーブごとには実行しません。

実行フロー

wave 1 (up to 5 files)        wave 2 (up to 5 files)      ...
+---------+  +-----------+    +---------+  +-----------+
| file A  |->| extractor |    | file F  |->| extractor |
+---------+  +-----------+    +---------+  +-----------+
     ...          ...              ...          ...

each extractor writes its findings to a file and returns only a
one-line confirmation; waves run one after another, capped at 5
concurrent extractors at a time, purely to bound concurrency

once every wave has finished:

  all extraction file paths            +---------+     +--------------------+
  + the glossary path        ------->  | reducer | ---> | merge_jargon.py    |
                                        | (whole  |      | upserts into        |
                                        |  run)   |      | chosen JARGON.md    |
                                        +---------+      +--------------------+

  the reducer reads every extraction file and the current glossary
  itself, correlates and merges once across the whole run, and
  writes one entries file plus a short summary

1. 入力ファイルを収集し、並行処理数を制限する目的だけで、最大5ファイルずつのウェーブに分けます。
2. 対象となる用語集のパスを、最初に一度だけ特定するか、計画します。
3. 抽出：すべてのウェーブを実行します。各抽出担当は調査結果をファイルに書き込み、短い確認だけを返します。
4. 絞り込み：すべての抽出が完了した後に一度だけ、1つのサブエージェントが現在の用語集と照合し、関連付けて統合します。
5. ファイルへの記録：merge_jargon.py を1回呼び出し、絞り込み担当の出力を用語集に反映します。
6. リンク：AGENTS.md または CLAUDE.md が存在する場合、用語集への参照がまだなければ追加します。
7. ユーザーに概要を報告します。

ステップ1：入力ファイルを収集する

ユーザーから指定されたファイルパスを使います。ファイル一覧ではなくディレクトリが指定されている場合は、その中を展開します（ユーザーの意図を尊重してください。「docs フォルダーから専門用語を抽出して」のような依頼では、node_modules、dist、.git、ロックファイル、バイナリアセットを含むリポジトリ全体ではなく、その下にある読み取り可能なテキストファイルまたは Markdown ファイルすべてが対象です）。

慣例的な場所を自動検出します。 次の場所を確認し、存在する場合は対象に含めます。

• docs/、documents/、doc/（再帰的に検索し、Markdown とプレーンテキストを対象とします）
• README.md、CONTRIBUTING.md、SECURITY.md、COMPLIANCE.md、LICENSE*
• ARCHITECTURE.md、AGENTS.md / CLAUDE.md、CONSTRAINTS.md
• 意思決定記録形式のフォルダーがあれば、それらも対象にします：adr/、decisions/、rfd/、 rfcs/、notes/、spikes/ — NOTE／SPIKE／RFC 形式のドキュメントを含むフォルダーは、 重要な情報源です

抽出の並行処理のためだけに、対象ファイルの一覧を最大5ファイルずつのウェーブに分けます。5は開始時の目安であり、厳密な上限ではありません。ファイルごとに1つのサブエージェントを使う設計を維持し（これにより抽出に集中でき、JSON 出力も整理されます）、同時に実行する数を制限できます。ウェーブの負荷が明らかに高い場合は数を減らし、環境がより多くの並行処理を無理なく扱え、ファイルも小さい場合は数を増やしてください。

また、この実行の中間ファイル用の一時ディレクトリを作成し、そのパスを記録してください。以下の手順で生成される抽出結果と絞り込み結果はすべてその中に書き込み、インラインでは返しません。

プラットフォームによって既定の場所が異なり、macOS では後から見つけにくい場所に解決されることがあるため、単なる mktemp -d ではなく、保存先を明示的に /tmp の下に指定します。

mktemp -d "/tmp/jargon-extractor.XXXXXX"

ステップ 2：対象の用語集を特定する

何よりも先に、リポジトリ内に既存の JARGON.md があるか検索してください。リポジトリ全体を対象に検索し（find、rg、grep など）、ルートや docs/ だけを調べるのは避けてください。

1. リポジトリ内のどこかに JARGON.md がちょうど 1 つ存在する場合、この実行で使用する用語集のパスとして指定します。
2. JARGON.md が複数存在する場合は、そこで停止して該当ファイルを表示し、どれを正とするかユーザーに確認してください。推測で選ばないでください。
3. どこにも存在しない場合は、リポジトリのルートに新しい ./JARGON.md を作成することを既定とします。
4. 次に進む前に、選択したパスを通知してください。

パスを選ぶ時点でファイルが存在している必要はありません。merge_jargon.py が最初の書き込み時に作成します。いずれの場合も、ここで必要なのはパスだけで、ファイルの内容は必要ありません。Step 4 の reduce サブエージェントは、使い捨てのコンテキスト内でディスクから直接、現在の内容を読み取ります。オーケストレーターが用語集の内容をコンテキスト内に保持する必要はありません。

ステップ 3：抽出（サブエージェントのフェーズ。各ウェーブを順番に実行）

各ウェーブでは、そのウェーブに含まれるファイルごとにサブエージェントを 1 つ起動し、すべて同じターン内で並列実行してから、次のウェーブを開始する前に完了を待ってください。現在の環境でサブエージェントまたは Task ツールを利用できない場合は、サブエージェントの起動をすべて省略し、以下の抽出手順に従って各ファイルを 1 つずつ処理してから、Step 4 に進んでください。サブエージェントなしでは、この作業をメインコンテキストから切り離すことはできません。そのため、そのような環境でファイル数が多い場合は、すべてを一度に処理せず、複数のターンに分けて少数のファイルずつ処理することを検討してください。

抽出サブエージェントのタスクテンプレート：

Read exactly one file: <path>

Flag every term in this file that a competent outside reader would not
already know: internal terminology, shorthand, abbreviations, acronyms,
and project- or domain-specific words. This includes terms that are
central to how the system works even if they are not abbreviations.

The test: would someone new to this specific project or domain need
this explained? That includes acronyms and initialisms (expanded and
defined, not just expanded), internal tool/system/process names,
shorthand the document uses without defining, and domain terms from a
specialized field the document assumes familiarity with. It excludes
plain vocabulary and terms already standard enough that defining them
would insult the reader (e.g. "function," "database," "HTTP" used in
their standard sense). When in doubt, flag it; over-flagging is cheap
to fix later, under-flagging loses information silently.

For each flagged term, give a plain English definition. Use the file's
own explanation if it states one; otherwise infer the meaning from
context. Flag any definition you are genuinely unsure about by noting
the uncertainty inline rather than presenting a guess as settled fact.
Keep each definition to one or two sentences; if a term needs more than
that to explain, give the short version anyway rather than writing an
exhaustive one.

Write your findings as strict JSON, nothing else, no markdown fences,
to this exact path: <output-path>
[
  {"term": "sidecar", "definition": "A helper process deployed
   alongside the main service to handle a supporting concern, such as
   logging or metrics, without living in the main service's codebase."},
  ...
]
If there is no jargon worth flagging, write an empty array: []

Then reply with ONLY a one-line confirmation, for example:
Wrote 6 terms to <output-path>
Do not repeat the extracted terms in your reply; they are already on
disk at <output-path>, and repeating them here only spends context
budget that the next step does not need.

<output-path> には、実行時のスクラッチディレクトリ内にある実際のパス（例：<scratch-dir>/architecture.json）を、<path> には実際のファイルパスを指定します。ウェーブが完了するたびに、抽出結果の出力パスをすべて記録してください。この一覧が Step 4 で必要となるすべてであり、単なるファイルパスなので保持にかかるコストはほとんどありません。

ステップ 4：統合（サブエージェントのフェーズ。実行全体で 1 回）

すべてのウェーブが完了したら、実行全体を対象とする reduce サブエージェントを 1 つ起動してください。Step 3 で集めたすべての抽出結果の出力パスと、Step 2 で選択した用語集のパスを渡します。

reduce サブエージェントのタスクテンプレート：

You are the merge step for a jargon extraction run.

Read these extraction result files, each a JSON array of
{"term", "definition"}:
  <path-1>
  <path-2>
  ...

Also read the current glossary, if it exists, at:
  <glossary-path>
Treat every term already there as part of the same pool you are
correlating against, not just the newly extracted terms. If the file
does not exist yet, there is nothing existing to correlate against.

CURATE: before correlating, drop any newly extracted candidate that
does not actually earn a glossary entry. The extraction step is
deliberately biased toward over-flagging, since catching a borderline
term there is cheap and missing one silently loses information. You
are the one point in the run with enough context, every extraction
plus the existing glossary, to narrow that list back down safely.

Keep a candidate if either is true:
- It carries a meaning specific to this repo, project, or domain that
  an outside reader could not infer from the word alone (an internal
  tool, system, process, or an acronym this project coined or redefined).
- Its words are common on their own, but this repo uses them in a
  specific way that would be easy to get wrong without the definition
  (a plain word repurposed here as a term of art).

Drop a candidate if it is any of:
- A literal filename, path, config key, or CLI flag, where the name
  itself is the explanation and nothing more needs saying.
- A generic engineering term that would mean the same thing in any
  codebase, not just this one (e.g. "database," "endpoint," "cache"),
  unless this project overloads it with a distinct meaning.
- An obvious code symbol or identifier whose name is just descriptive
  English with no special behavior behind it.
- A standard industry term or acronym any practitioner in the relevant
  field already knows, used here in its ordinary sense, not redefined
  by this project.

Do not apply this bar retroactively to terms already in the glossary;
an earlier run already decided those were worth keeping, and silently
removing them is a bigger decision than this run is making. Curation
only narrows what this run is about to add, never what is already filed.

CORRELATE: group entries that refer to the same term, case-insensitively.
Two entries are the same term if they are the same word or phrase modulo
case (API / api) and trivial punctuation or spacing differences
(sub-agent / subagent) that clearly mean the same thing. Do not merge
two different concepts just because they share a substring. Do not
merge an acronym with its own expansion unless the source treats them
as one entry (CDC and "Change Data Capture" are the same entry only if
used interchangeably; keep them separate if the expansion is a
description rather than the term itself).

MERGE: for any term with more than one definition in the pool, write
one definition at least as informative as any single source, never one
that drops information, and still no more than a couple of sentences
unless a genuine multi-sense split requires it:
- If two definitions say the same thing differently, combine them into
  the clearer, more complete phrasing.
- If two definitions describe genuinely different senses of the same
  term, keep both, numbered inside one definition: "(1) ... (2) ...".
  Do not split into separate term (context) entries; the term must
  stay one stable lookup key so future runs can find and update it.
- If you are not confident two entries describe the same underlying
  concept, do not force a merge. Keep them separate and say so in your
  summary. A wrong merge is worse than a duplicate: a duplicate is easy
  to spot later, a wrong merge quietly loses information.

OUTPUT: write a JSON array containing ONLY the terms that are new, or
whose definition changed as a result of this run, and that survived
curation above, to this exact path:
  <output-path>
[{"term": "...", "definition": "..."}, ...]
Leave out any term whose meaning is unchanged from what is already in
the glossary, and any term curation dropped. Do not reproduce the
untouched glossary into this file; list only what is new or different.

Then reply with ONLY a short plain-text summary: how many terms you are
adding, how many you are updating (and one short clause why, per term),
how many you saw but left unchanged, how many you dropped during
curation (grouped by the reason above, e.g. "3 dropped: generic
engineering terms"), and any cases where you deliberately kept entries
separate instead of merging them. Do not include the full entries list
in your reply; it is already written to <output-path>.

抽出ファイルのパス一覧、実際の用語集のパス、スクラッチディレクトリ内の実際の出力パス（例：<scratch-dir>/merged.json）を指定します。

ステップ 5：結果を書き込む

reduce サブエージェントの出力に対して、マージスクリプトを実行してください。これは通常の bash 呼び出しであり、サブエージェントではありません。スクリプトはファイルを直接読み書きするため、モデルのコンテキストを通るのは小さな概要だけで、ファイルの内容がコンテキストに渡されることはありません。

scripts/merge_jargon.py はこのスキルに含まれており、作業中のプロジェクトからの相対パスではなく、この SKILL.md ファイルからの相対パスにあります。bash ツールはプロジェクトの作業ディレクトリで実行されるため、単独の scripts/merge_jargon.py が解決されるのは、そのディレクトリがたまたまスキルのフォルダーと同じ場合だけです。通常はそうなりません。まず、この SKILL.md が読み込まれたスキル自身のディレクトリの絶対パスを解決し、そのパスを使ってスクリプトを呼び出してください。

python3 "$SKILL_DIR/scripts/merge_jargon.py" <glossary-path> <scratch-dir>/merged.json

$SKILL_DIR は、このスキル自身の絶対パスを表します。実際のパスに置き換えてください。用語集のパス引数には、Step 2 で選択した、プロジェクトを基準とする相対パスまたはプロジェクト内の絶対パスを指定します。スキルディレクトリを基準にしたパスではありません。

スクリプトは、追加、更新、変更なしの用語数を報告します。また、エントリーのファイルに用語の重複がある場合や、既存の用語集のエントリー領域に解析できない行がある場合は、推測で処理せずエラーになります。正確なフラグが必要な場合は "$SKILL_DIR/scripts/merge_jargon.py" --help を確認してください。このスクリプトは意図的に厳格なため、書き込みを拒否した場合は回避策を取るのではなく、入力を修正してください。変更を適用する前に確認したい場合は、まず --dry-run を追加してください。

ステップ 6：用語集へのリンクをエージェントの動作ファイルに追加する

用語集は、後続のエージェント実行時に参照されなければ役に立ちません。JARGON.md 自体は用語だけを記載するファイルにして、エージェントの動作ファイルには言及しないようにします。一方、逆は必要です。プロジェクトに AGENTS.md または CLAUDE.md があれば、後からこのプロジェクトで作業するエージェントがコンテキストとして用語集を参照できるよう、そのファイルから用語集にリンクします。

プロジェクトのルートで、./AGENTS.md または ./CLAUDE.md が存在するか、この順に確認します。./CLAUDE.md が存在していて、その内容全体が AGENTS.md へのインポートポインター（たとえば、ファイルの内容が実質的に @AGENTS.md のみ）であり、./AGENTS.md も存在する場合は、ポインターファイルではなく AGENTS.md を編集対象にします。どちらのファイルも存在しない場合は、このステップをスキップします。このスキルの対象範囲外なので、ファイルを新規作成しないでください。

編集対象のファイルが見つかった場合は、まず全体を読み、その後、次のようにします。

• ## Related Documentation セクションがすでにある場合、そこに用語集が記載済みか（パスまたは JARGON.md を検索して）確認します。記載済みであれば、ファイルは変更しません。記載されていなければ、既存の項目を一切変更せず、そのセクションに項目を 1 つ追加します。
• そのようなセクションがない場合は、ファイルの末尾に追加します。

いずれの場合も、項目は次の形式にします。JARGON.md の部分は、ステップ 2 で確認した用語集の実際のパスに置き換えます。

- **JARGON.md**: Internal terminology, acronyms, and shorthand used in this project, with plain English definitions
  _(Reference this when a term, acronym, or piece of shorthand in this project isn't self-explanatory)_

これは 1 回の実行につき 1 回行う、項目 1 つだけの小規模な編集です。merge_jargon.py が防ぐ大量の並べ替えや統合ではないため、ここで直接編集して問題ありません。

ステップ 7：ユーザーに報告する

reduce サブエージェントの短い要約と merge_jargon.py の小さな JSON 出力を使って、追加、更新、選別時に削除した用語の合計数と削除理由、reducer が無理に統合せずに指摘した曖昧な統合、さらに AGENTS.md または CLAUDE.md を更新したか（すでに用語集への参照があったか、あるいはどちらのファイルも存在しなかったか）を要約します。ユーザーがファイル自体を見たい場合は、その時点で通常どおりファイルを読み取ります。実行途中に読み取る必要はありません。

項目の形式

レンダリングされた形式（- **Term**: Definition、並べ替え、頭字語の大文字・小文字）は merge_jargon.py が管理します。上流で重要な内容上のルールは、複数の語義を別々の term (context) 項目に分割せず、1 つの項目にまとめることです。このルールは、実際に適用する唯一の場所である reduce テンプレートにすでに記載されています。

例外的なケース

• バイナリファイルまたは読み取り不能なファイル：処理全体を失敗させず、そのファイルをスキップし、スキップしたファイル名と理由を記録します。

例

docs/architecture.md と docs/onboarding.md があるとします。2 つの抽出器が 1 つのウェーブ内で並行して実行されます。それぞれが独自のファイルを書き込み、たとえば Wrote 1 term to <scratch-dir>/architecture.json のような確認のみをオーケストレーターに返します。この時点では、オーケストレーターは定義そのものを見ません。

次に reduce サブエージェントが、両方のファイルを自分で読み取ります。

// architecture.json
[{"term": "sidecar", "definition": "A helper process deployed alongside the main service to handle logging and metrics without living in the main service's codebase."}]

// onboarding.json
[{"term": "sidecar", "definition": "Used loosely by the team for any auxiliary process that runs next to a primary one and shares its lifecycle, not just the logging/metrics helper."}]

どちらも同じ用語について記述していますが、単なる言い換えの違いではなく、特定の技術的な意味と、より広い日常的な意味という、実質的に異なる語義です。reducer はどちらかを選ばず両方を残し、統合した項目を <scratch-dir>/merged.json に書き込み、「1 term added (sidecar, two senses merged)」のような短い要約のみをオーケストレーターに返します。

[{"term": "sidecar", "definition": "(1) A helper process deployed alongside the main service to handle logging and metrics without living in the main service's codebase. (2) More loosely, any auxiliary process that runs next to a primary one and shares its lifecycle."}]

その後、オーケストレーターはそのファイルを使って merge_jargon.py を実行し、選択した JARGON.md のパスに項目をアルファベット順で挿入します。この例全体を通じて、オーケストレーター自身のコンテキストに含まれるのは、短い確認が 2 件、短い reduce の要約が 1 件、小さなスクリプトの要約が 1 件だけで、定義そのものは一度も含まれません。