@unlaxer/dde-toolkit 0.1.1 → 0.1.3

package/flows/quick.yaml

@@ -5,39 +5,39 @@ trigger_keywords: ["DDE して", "DDE", "ドキュメントレビュー", "用
 
 defaults:
   exclude_dirs: ["dde", "dge", "node_modules", ".git", ".claude"]
-  reader_level: beginner
-  article_length: medium   # short / medium / long / custom
+  article_intent: educational   # educational / reference / deep-dive
 
 workflow:
   steps:
     - id: select_docs
       display_name: "対象ドキュメント群を選択"
       mode: confirm
-      note: "md 一覧（多い場合はフォルダ一覧）を出してユーザーが除外指定"
-    - id: level
-      display_name: "読者レベル設定"
+    - id: reader_context
+      display_name: "読者コンテキスト設定"
       mode: confirm
-      note: "LLM がドキュメントから推定して提案、ユーザーが確認"
-    - id: article_length
-      display_name: "記事の分量設定"
+      note: "誰が読むか（記事のトーンに使用。抽出フィルターには使わない）"
+    - id: lang
+      display_name: "言語設定"
       mode: confirm
-      note: "short（〜200字）/ medium（〜500字）/ long（〜1000字）/ 文字数直指定"
+      note: "en / ja / both。both の場合は <slug>.md + <slug>.ja.md を生成"
+    - id: article_intent
+      display_name: "記事のインテント設定"
+      mode: confirm
+      note: "educational / reference / deep-dive、または自由記述"
     - id: extract
-      display_name: "用語抽出（LLM）"
+      display_name: "用語抽出（LLM）— 全レベル対象"
       actor: llm
-      note: "対象ドキュメント群から一括抽出。既存 docs/glossary/ は除外"
     - id: confirm_terms
       display_name: "用語一覧を確認"
       mode: confirm
     - id: articleize
-      display_name: "記事生成（LLM）"
+      display_name: "記事生成（LLM）— educational narrative"
       actor: llm
     - id: save
       display_name: "単語帳保存"
     - id: link
       display_name: "dde-link 実行（CLI）"
       actor: cli
-      note: "対象ドキュメント群と同じファイルセットに適用"
 
 must_rules:
   - id: save
@@ -49,27 +49,30 @@ must_rules:
 
 extract:
   actor: llm
-  scope: document_group    # 1ファイルではなく選択されたドキュメント群全体
-  filter: "選択した読者レベルで分からない用語のみ（docs/glossary/ に既存記事があれば除外）"
+  scope: document_group
+  filter: "レベルで絞らない。誰かが分からない可能性がある用語を全て抽出（docs/glossary/ に既存記事があれば除外）"
   output: "用語一覧テーブル（用語 / 出現ドキュメント / 重要度）"
 
 articleize:
   actor: llm
   per: term
+  format: educational_narrative
   output_dir: docs/glossary/
-  filename_rule: "<slug>.md（英語）, <slug>.ja.md（日本語）"
-  length:
-    short:  "〜200字。定義1文 + 例1文"
-    medium: "〜500字。定義 + 説明 + 例。デフォルト"
-    long:   "〜1000字。定義 + 詳細 + コード例 + 関連用語"
+  filename_rule: "en → <slug>.md / ja → <slug>.ja.md / both → 両方生成"
+  multilang:
+    en:   "<slug>.md"
+    ja:   "<slug>.ja.md"
+    both: "両ファイル生成。dictionary.yaml に en/ja キーで用語マッピングを追加"
+  intents:
+    educational: "読んだ人が背景・動機・仕組みごと理解できる記事。例え話・図・なぜ？を含む。分量は目的に従って自然に決める"
+    reference:   "定義・使い方・例を簡潔に。調べたい人向けのクイックリファレンス"
+    deep-dive:   "実装詳細・コード例・エッジケース・トレードオフまで網羅"
 
 output_dir: dde/sessions/
 
 post_actions:
   - id: more_docs
     display_name: "別のドキュメント群も処理する"
-  - id: another_level
-    display_name: "別の読者レベルで再実行する"
   - id: run_link
     display_name: "dde-link でリンクを付ける（まだの場合）"
   - id: diagrams

package/method.md

@@ -4,73 +4,72 @@
 
 - **必要なもの**: LLM（Claude, GPT-4, Gemini 等）へのアクセス
 - **推奨**: Claude Code（skills/ で自動発動）
-- **入力**: レビュー対象のドキュメント（README, API 仕様, 設計書など）
-- **出力**: 用語集記事 + 単語帳（dictionary.yaml）+ クリッカブルリンク
+- **入力**: レビュー対象のドキュメント群
+- **出力**: educational narrative 形式の用語集記事 + クリッカブルリンク
 
 ---
 
 ## 最低限これだけ読め（3分版）
 
-> **TL;DR** — 以下を読めば DDE を始められる。
+**DDE とは**: ドキュメントを読む人全員に対して用語を抜き出して、背景ごと理解できる記事にして、リンクにする。
 
-**DDE とは**: 読者レベルを決めて、ドキュメントの用語を抜き出して、記事化する。それを単語帳にして、ドキュメントをクリッカブルにする。
+**フロー**:
+1. **Select** — 対象ドキュメント群を選ぶ
+2. **Context** — 誰が読むかを把握する（記事トーンの調整に使う）
+3. **Intent** — 記事の目的を決める（「教育用」「リファレンス」など）
+4. **Extract** — 全用語を一括抽出（レベルで絞らない）
+5. **Articleize** — educational narrative 形式で記事を生成
+6. **Link** — dde-link でリンクを埋め込む
 
-**4 ステップ**:
-1. **Level** — 想定読者のレベルを決める（expert / beginner / grandma）
-2. **Extract** — そのレベルで「分からない用語」をドキュメントから抽出する
-3. **Articleize** — 用語ごとに glossary 記事を生成する
-4. **Link** — dde-link で用語をクリッカブルにする
+---
+
+## 原理
+
+同じドキュメントをエンジニアも業務担当者も読む。
+「このレベルの人には不要」を抽出段階で判断するより、
+**誰が読んでも背景ごと理解できる記事を1つ書く**方がシンプルで漏れがない。
 
-**最初にやること**:
-1. ドキュメントを用意する（README.md など）
-2. 「DDE して」と Claude Code に言う
-3. 読者レベルを確認または指定する
-4. 生成された記事をレビューして承認する
+文字数より**インテント**で指定する:
+- `educational` — 読んだ人が背景・動機・仕組みごと理解できる。分量は自然に決まる
+- `reference` — 定義と使い方を簡潔に
+- `deep-dive` — 実装・エッジケースまで網羅
+- 自由記述 — 「新入社員が業務背景ごと理解できるように」など
 
 ---
 
-## 原理
+## 記事フォーマット（educational）
 
-普通のドキュメントレビューは「書いてあることの検証」。
-DDE は「読者には分からない用語の洗い出し」。
+```markdown
+# <用語>
 
-書いた側には自明な用語が、読者には不透明なまま残っている。
-この「前提の非対称」を、読者レベルを明示して LLM に検出させる。
+## 一言で言うと？
+<専門知識なしで分かる1-2文>
 
 ---
 
-## DDE の 4 ステップ
+## <身近な例え>
+<日常のアナロジー。対応表「○○ = △△」を使う>
 
-```
-Step 1: Level — 想定読者を決める
-  「beginner」「expert」「grandma」のどれか。
-  曖昧なら beginner をデフォルトにする。
-
-Step 2: Extract — 用語を抽出する
-  LLM がドキュメントを読んで、
-  そのレベルの読者が分からない用語を列挙する。
-  docs/glossary/ に既存記事があれば除外する。
-
-Step 3: Articleize — 記事を生成する
-  用語ごとに docs/glossary/<slug>.md を生成する。
-  レベルに応じてトーンを変える。
-
-Step 4: Link — dde-link を実行する
-  npx dde-link <file>
-  用語を [term](docs/glossary/xxx.md) に自動置換する。
-```
+---
+
+## なぜ必要なの？
+<「自前でやったら？」との対比。ASCIIダイアグラム・比較表>
 
 ---
 
-## 3 段階の読者レベル
+## <このプロジェクト文脈での説明>
+<抽象論ではなく、このプロジェクト固有の実装・設計を参照>
 
-```
-expert   — 同分野の開発者（定義 + 技術詳細 + コード例）
-beginner — 初学者（やさしい説明 + 具体例）
-grandma  — 技術ゼロ（身近な例えだけ）
-```
+---
 
-同じ用語でも、レベルによって抽出される用語も記事のトーンも変わる。
+## 具体的な例
+<ステップバイステップのフロー>
+
+---
+
+## さらに学ぶために
+- [関連用語](path.md) — この文脈での関連理由
+```
 
 ---
 
@@ -79,7 +78,7 @@ grandma  — 技術ゼロ（身近な例えだけ）
 ```
 1. docs/glossary/ の .md ファイル名から用語を自動推定
 2. dictionary.yaml があれば上書き（日本語用語・別名対応）
-3. 最長一致、段落ごとに 1 回 → [用語](docs/glossary/xxx.md) に置換
+3. 最長一致、段落ごとに 1 回 → [用語](相対パス) に置換
 スキップ: コードブロック / インラインコード / 見出し / 既存リンク
 ```
 
@@ -89,5 +88,4 @@ grandma  — 技術ゼロ（身近な例えだけ）
 
 - 241 の用語集記事（120 EN + 121 JA）
 - README に 334 のクリッカブルリンク
-- 11 の mermaid フロー図
-- 3 段階の読者レベル対応
+- educational narrative 形式（背景・動機・具体例・相互リンク）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/dde-toolkit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Document Deficit Extraction — find what's not understood in your docs",
   "license": "MIT",
   "type": "module",

package/skills/dde-session.md

@@ -16,27 +16,29 @@
 テーマなしで「DDE」「DDE って何」と呼ばれたとき:
 
 ```
-DDE toolkit v0.1.0 — Document Deficit Extraction
+DDE toolkit v0.1.3 — Document Deficit Extraction
 
-読者レベルを決めて → 用語を抽出して → 記事化 → 単語帳 → クリッカブルなドキュメント
+用語を全部抜き出して、誰でも理解できる記事にして、リンクにする。
 
 📖 フロー:
-  1. ドキュメント群を選択（対象ファイル・除外フォルダを確認）
-  2. 読者レベルを設定（LLM が推定して提案）
-  3. 記事の分量を設定（short / medium / long）
-  4. 用語を LLM が一括抽出 → 一覧確認
-  5. 用語ごとに glossary 記事を生成 → docs/glossary/
-  6. dde-link が対象ドキュメント群にリンクを埋め込む
-
-👥 3 段階の読者レベル:
-  expert   — 同分野の開発者
-  beginner — 初学者（デフォルト）
-  grandma  — 技術ゼロ
+  1. ドキュメント群を選択
+  2. 読者コンテキストを把握
+  3. 記事のインテントを設定（「教育用」「リファレンス」など）
+  4. 全用語を一括抽出 → 一覧確認
+  5. educational narrative 形式で記事を生成 → docs/glossary/
+  6. dde-link でリンクを埋め込む
+
+📄 記事フォーマット（educational narrative）:
+  # <用語>
+  ## 一言で言うと？
+  ## <身近な例え>
+  ## なぜ必要なの？（動機・背景）
+  ## <このプロジェクト文脈での説明>
+  ## 具体的な例
+  ## さらに学ぶために（相互リンク）
 
 🔗 dde-link（LLM 不要）:
-  npx dde-link README.md            # 自動リンク実行
-  npx dde-link README.md --check    # リンク漏れチェック（CI 用）
-  npx dde-link README.md --dry-run  # プレビュー
+  npx dde-link README.md
 
 詳しくは: dde/method.md
 ```
@@ -47,72 +49,91 @@ DDE toolkit v0.1.0 — Document Deficit Extraction
 
 ### Step 0: flow 読み込み
 `dde/flows/` の YAML、なければ `kit/flows/` の YAML を読む。
-`defaults.exclude_dirs` を確認する（デフォルト: `dde/`, `dge/`, `node_modules/`, `.git/`, `.claude/`）。
 
 ### Step 1: 対象ドキュメント群の選択（MUST: ユーザーに確認）
 
 プロジェクト内の `.md` ファイルを列挙する。
 - **50 ファイル未満**: ファイル一覧を表示
 - **50 ファイル以上**: フォルダ一覧を表示
+- デフォルト除外: `dde/`, `dge/`, `node_modules/`, `.git/`, `.claude/`
 
 ```
 対象ドキュメントを選択してください。
 
-フォルダ一覧（dde/, dge/, node_modules/ は除外済み）:
   ✅ docs/          (12 ファイル)
   ✅ README.md
   ✅ CONTRIBUTING.md
-  ⬜ docs/internal/ (除外候補)
 
 除外したいファイル・フォルダがあれば指定してください。
-なければそのまま進みます。
 ```
 
 確定したファイルセットが「抽出元 = リンク適用先」になる。
 
-### Step 2: 読者レベルの設定（MUST: LLM が推定してから確認）
+### Step 2: 読者コンテキストの設定（MUST: ユーザーに確認）
 
-対象ドキュメントの語彙・トーンを見て LLM がレベルを推定し、ユーザーに提案する。
+**抽出フィルターには使わない。記事のトーン・文脈に使う。**
 
 ```
-ドキュメントを読みました。推定: beginner
+このドキュメントを読む人は？（複数可）
 
-根拠: 専門用語が多いが説明がない。初学者には伝わらない箇所が目立つ。
+  [ ] プログラマー・エンジニア
+  [ ] 業務ドメインの担当者（非エンジニア）
+  [ ] 初学者・新人
+  [ ] その他: ___
+```
+
+### Step 3: 言語設定（MUST: ユーザーに確認）
+
+対象ドキュメントの言語を検出し、記事の生成言語を確認する。
+
+```
+ドキュメントの言語を検出しました: 日本語
 
-読者レベルを確認してください:
-1. expert   — 同分野の開発者
-2. beginner — 初学者 ← 推定
-3. grandma  — 技術ゼロ
+記事を生成する言語を選んでください:
+1. ja のみ  — <slug>.ja.md を生成
+2. en のみ  — <slug>.md を生成
+3. both     — <slug>.md + <slug>.ja.md の両方を生成
+              （dictionary.yaml に en/ja の用語マッピングを追加）
 
-このまま beginner で進めますか？
+デフォルト: ドキュメントが日本語 → ja、英語 → en
 ```
 
-### Step 3: 記事の分量設定
+**both の場合:**
+- 英語記事を先に生成し、日本語記事は [English version](<slug>.md) リンクを冒頭に追加
+- `dictionary.yaml` に `ja:` キーで日本語用語を登録
+- dde-link は `.ja.md` ファイルに対して日本語用語でマッチング
+
+### Step 5: 記事のインテント設定（MUST: ユーザーに確認）
+
+**文字数ではなく「読んだ人にどうなってほしいか」で指定する。**
 
 ```
-記事の分量を選んでください:
-1. short  — 〜200字（定義1文 + 例1文）
-2. medium — 〜500字（定義 + 説明 + 例）← デフォルト
-3. long   — 〜1000字（定義 + 詳細 + コード例 + 関連用語）
-4. カスタム — 文字数を直接指定
+記事のインテントを選んでください:
+1. educational — 背景・動機・仕組みごと理解できる記事
+                 例え話・図・なぜ？を含む。分量は目的に従って自然に決まる
+2. reference   — 定義と使い方を簡潔に。調べたい人向け
+3. deep-dive   — 実装詳細・コード例・エッジケースまで網羅
+4. 自由記述    — 例: 「新入社員が読んで業務背景ごと理解できるように」
 
-このまま medium で進めますか？
+デフォルト: educational
 ```
 
-### Step 4: 用語抽出（LLM）
+### Step 6: 用語抽出（LLM）
+
+**レベルで絞らず、誰かが分からない可能性がある用語を全て抽出する。**
 
-対象ドキュメント群を読んで、選択した読者レベルで「分からない可能性がある用語」を一括抽出する。
+対象ドキュメント群を読んで用語を一括抽出する。
 
-**ルール:**
-- `docs/glossary/` に既存記事があるものは除外（スラッグが一致するもの）
-- 固有名詞（プロダクト名・企業名など）は除外
+**抽出ルール:**
+- `docs/glossary/` に既存記事があるものは除外
+- 固有名詞（プロダクト名・企業名）は除外
 - コードブロック内の識別子は除外
 - 重要度: その用語なしでは内容が理解できない → 🔴 High / 補足があると助かる → 🟡 Medium
 
 **出力（MUST: ユーザーに確認してから記事生成へ進む）:**
 
 ```
-## 抽出した用語一覧（beginner 視点）
+## 抽出した用語一覧
 
 | # | 用語 | 出現ドキュメント | 既存記事 | 重要度 |
 |---|------|----------------|---------|--------|
@@ -124,100 +145,111 @@ N 件抽出しました。記事を生成しますか？
 除外したい用語があれば番号で指定してください（例: 3,5）。
 ```
 
-### Step 5: 記事生成（LLM）
+### Step 7: 記事生成（LLM）— educational narrative
 
 確認後、用語ごとに `docs/glossary/<slug>.md` を生成して保存する。
 
-**スラッグ規則:** 小文字、スペース → ハイフン（`json-web-token.md`）
+**記事フォーマット（educational intent の場合）:**
 
-**テンプレート（expert）:**
 ```markdown
-# <Term>
+# <用語>
 
-## 定義
-<1-2 文で核心を定義>
+## 一言で言うと？
+<1-2文でコアを定義。専門知識がない人でも分かる言葉で。>
 
-## 技術詳細
-<実装・仕様の詳細>
+---
 
-## コード例
-\`\`\`<lang>
-<example>
-\`\`\`
+## <読者が直感的に分かる例え・タイトル>
+<日常の具体的なアナロジー。箇条書きや対応表で「○○ = △△」を示す。>
 
-## 関連用語
-- [<term>](../glossary/<slug>.md)
+---
+
+## なぜ<この用語 / このアプローチ>が必要なの？
+<「自前でやったらどうなるか」との比較で動機を説明。
+ ASCIIダイアグラムや対比表を使って直感的に。>
+
+---
+
+## <このプロジェクト / この文脈での説明>
+<抽象的な説明ではなく、このドキュメントが属するプロジェクトの文脈で具体的に説明する。
+ このプロジェクト固有の実装・設計を参照する。>
+
+---
+
+## 具体的な例
+<ステップバイステップのフロー。コードブロックや番号付きリストで。
+ 読者が「なるほど、こう動くのか」と分かるレベルまで具体的に。>
+
+---
+
+## さらに学ぶために
+- [関連用語A](<相対パス>) — この文脈でなぜ関連するか1行で
+- [関連用語B](<相対パス>) — この文脈でなぜ関連するか1行で
 ```
 
-**テンプレート（beginner）:**
+**reference intent の場合:**
 ```markdown
-# <Term>
+# <用語>
 
-## ひとことで言うと
-<1 文でやさしく>
+<1文定義>
 
-## もう少し詳しく
-<例えを使って 3-5 文>
-
-## 使われる場面
-<具体的なシナリオ>
+## 使い方
+<コード例または手順>
 
 ## 関連用語
-- [<term>](../glossary/<slug>.md)
+- [<term>](<path>)
 ```
 
-**テンプレート（grandma）:**
+**deep-dive intent の場合:**
 ```markdown
-# <Term>
+# <用語>
 
-## 身近な例えで言うと
-<日常の例え 1-3 文>
+## 定義
+## 内部動作
+## コード例
+## エッジケース・注意点
+## トレードオフ
+## 関連用語
 ```
 
+**インテントが自由記述の場合:**
+ユーザーの言葉（例: 「新入社員が業務背景ごと理解できるように」）をそのまま
+記事の生成方針として使う。
+
 `dde-tool save docs/glossary/<slug>.md` で保存。
 
-### Step 6: 単語帳（dictionary.yaml）更新
+### Step 8: 単語帳（dictionary.yaml）更新
 
-日本語ドキュメントが対象の場合、または日本語用語・別名を追加したい場合、
-`docs/glossary/dictionary.yaml` を生成・更新する。
+日本語記事が必要な場合、`docs/glossary/dictionary.yaml` を生成・更新する。
 
 ```yaml
-# docs/glossary/dictionary.yaml
 jwt.md:
   en: ["JWT", "JSON Web Token"]
   ja: ["JWT"]
-
-oauth.md:
-  en: ["OAuth", "OAuth 2.0"]
-  ja: ["OAuth"]
 ```
 
-### Step 7: dde-link の実行（CLI）
+### Step 9: dde-link 実行（CLI）
 
-**適用先は Step 1 で選択したドキュメント群と同じ。** ユーザーに再確認は不要。
+Step 1 で選択したドキュメント群と同じファイルセットに適用。
 
 ```bash
-# 選択したファイルに対して順番に実行
-npx dde-link README.md
-npx dde-link docs/auth.md
-# ...
+npx dde-link README.md --dry-run   # 確認
+npx dde-link README.md             # 実行
 ```
 
-初回は `--dry-run` で差分を表示してから `--fix` を推奨する。
-
-### Step 8: 次アクション提示（MUST: 省略しない）
+### Step 10: 次アクション提示（MUST: 省略しない）
 
 ```
 1. 別のドキュメント群も処理する
-2. 別の読者レベルで再実行する
-3. dde-link を実行する（まだの場合）
-4. 図が必要な箇所を検出する
-5. 後で
+2. dde-link を実行する（まだの場合）
+3. 図が必要な箇所を検出する
+4. 後で
 ```
 
 ---
 
 ## 注意
-- `docs/glossary/` に既存記事がある場合は上書きしない（差分のみ提案）
+- 記事の分量は文字数ではなくインテントに従って自然に決める
+- `docs/glossary/` に既存記事がある場合は上書きしない
 - dde-link の `--fix` は上書き。事前に `--dry-run` を推奨
 - 将来フェーズ: HTML からの用語抽出 + ホバー表示（v0.2.0 予定）

package/version.txt

@@ -1 +1 @@
-0.1.1
+0.1.3