library-reference-distillation

ライブラリリファレンス蒸留 — アーキタイプのプレイブック

このリポジトリで公開されているライブラリリファレンス蒸留に共通する慣例を蒸留した方法論です。外部ライブラリを、慣用的な使い方のルールパックに変換するアーキタイプです。ジェネレーターではなく、/dev-skill:new では代わりに判断できない編集上の決定事項をまとめた制約セットです。

これは /dev-skill:new と /dev-skill:ingest の上位に位置するアーキタイプ層です。ジェネレーターが構造の枠組みを作ります。このスキルは、ライブラリリファレンススキルごとに繰り返し判断する4つの事項、つまり情報源の選び方、バージョンのずれに備えた固定方法、カテゴリとルールの構成方法、メタデータを信頼できるチェックサムとして保つ方法を扱います。

適用するタイミング

次の場合にこのスキルを使用します。

• 新しいライブラリリファレンスの蒸留を始めるとき（ライブラリにドキュメントがあり、慣用的なルールとしてまとめたい安定した表面領域がある）
• 新しいアップストリームリリースやメジャーバージョンの更新に合わせて、既存のライブラリリファレンススキルを進化させるとき
• 「ドキュメントを書き直しただけのように感じる」ライブラリリファレンススキルのドラフトをレビューするとき
• 新しいスキルのカテゴリやプレフィックス方式を選ぶ際に、判断が恣意的に感じられるとき
• アップストリームのバージョンを SKILL.md の見出しに固定するか、metadata.json だけに記載するかを決めるとき
• アップストリームとのルールのずれが疑われるスキルを更新するとき（openai-codex-rust-patterns の教訓：codex-rs はスナップショット間で大きく変化します）

このスキルは次の場合には使用しません。

• コードアトラスの蒸留（例：openai-codex-rust-patterns、opencode-ts、nextjs-ppr-patterns）— 情報源はアップストリームのドキュメントではなく、HEAD を固定した実際のリポジトリです。対応するアーキタイプのプレイブックは、まだ抽出されていません。
• 方法論の蒸留（例：radical-simplification、deterministic-metric-design）— 情報源はライブラリではなく、名前の挙がった人物とその人の正典です。
• スキャフォルダー（例：expo-design-system-scaffolder）— ルールブックではなく、構成ワークフローを扱います。

使い方

4つのカテゴリは互いに独立した判断事項で、スキルごとに一度決めます。症状に応じて、該当する対応を選んでください。

症状	対応するカテゴリ	最初に読むルール
どこからルールを掘り起こせばよいかわからない	情報源	source-priority-ladder
ルールが重要な指針ではなく、API の言い換えに感じられる	情報源（失敗のギャップ）	source-failure-gap
ライブラリの変更が速く、スキルがすぐ陳腐化しそう	固定	pin-by-velocity
既存のスキルがアップストリームからずれている	固定（更新）	pin-refresh-vs-head
カテゴリが恣意的に感じられる	構成	shape-category-ladder
When-to-Apply が確実に機能しない	構成（When-to-Apply）	shape-when-to-apply-template
引用リストとルールの情報源がずれている	メタデータ	meta-references-checksum

カテゴリの概要と順序の根拠については、references/_sections.md を参照してください。

ルールのカテゴリ

#	カテゴリ	プレフィックス	対応内容	ルール数
1	情報源の選定	source	どこから情報を掘り起こすか、何が重要なルールになるか	2
2	バージョン管理	pin	API の変更速度に応じた固定方法、更新方法	2
3	ルールの構成	shape	共通の4段階ラダー、When-to-Apply のテンプレート	2
4	メタデータの規律	meta	references[] を信頼できる引用セットのチェックサムとして保つ	1

クイックリファレンス

1. 情報源の選定

• source-priority-ladder — ドキュメント → ブログ／変更履歴 → GitHub のディスカッション → 型 → 例。ライブラリが llms.txt を公開している場合（Effect）に限り、この優先順位が逆転します。
• source-failure-gap — ドキュメントに書かれていないことや、本番環境で明らかになったことを捉えるルールを優先します。API の言い換えにすぎないルールは削除してください。

2. バージョニング

• pin-by-velocity — 安定した API（Zod、RHF）→ バージョンは metadata.json のみに記載します。変化の速い API（nuqs v2.5–v2.8、Tailwind v4）→ SKILL.md の見出しに明示的な範囲を記載します
• pin-refresh-vs-head — 発展させる際は、スキルと上流の HEAD との差分を確認し、そこから得た教訓をルール化します（codex-rs の codex.rs から session/ への分割が代表例です）

3. ルールの形

• shape-category-ladder — リリースするすべてのライブラリー参照スキルは、CRITICAL のセットアップ → HIGH の分離／パフォーマンス → MEDIUM の合成／統合 → LOW のエッジケース／仕上げという段階を踏みます。これに対応するカテゴリ名を選び、新たな形式を作らないでください
• shape-when-to-apply-template — 4 つの要素：import 文によるトリガー＋問題領域を示す表現＋頻度の目安＋関連するスキルを示す、明確な「行わないこと」の境界

4. メタデータの規律

• meta-references-checksum — metadata.references[] は、ルール内で引用されている URL の正確な集合です。上位集合でも下位集合でもありません。一致しない場合、ルールかメタデータのどちらかが実態と異なっています

関連スキル

• radical-simplification — このスキルの上位にある思考レイヤーです。このプレイブック自体も、スキル作成に「削減 → 制約 → 不変条件の明示」という手順を適用した例です
• skill-authoring — アーキタイプ横断のスキル作成規約です。このスキルは、ライブラリー参照に特化したものです
• deterministic-metric-design — 方法論の抽出を扱う関連スキルです。別のアーキタイプに同じアーキタイプのパターンを適用した例を示し、アーキタイプごとのプレイブックという考え方が一般化できることを実証しています

作成上の注意

これらのルールは飾りではなく、根幹を支えるものです。リリース済みの 5 つのライブラリー参照スキル（nuqs、zod、react-hook-form、effect-ts、emilkowal-animations）で、ルールがどのように出典を引用しているかを追跡して抽出しました。それぞれのルールは、これらの規約がない場合に作成者が選びがちな誤った既定の判断を示しています。/dev-skill:new ですでに対応している内容を繰り返すルールは削除してください。網羅性はルール数ではなく、実際のライブラリー抽出プロンプトに対する /dev-skill:eval で検証します。次のアーキタイプ別プレイブック（code-atlas、methodology、scaffolder、runbook）を作成する際、ここで再び現れるパターンは汎用の skill-authoring スキルに昇格させる候補となり、異なるパターンはアーキタイプ固有のままにします。