@unlaxer/dde-toolkit 0.1.0 → 0.1.2

package/flows/quick.yaml

@@ -5,7 +5,6 @@ trigger_keywords: ["DDE して", "DDE", "ドキュメントレビュー", "用
 
 defaults:
   exclude_dirs: ["dde", "dge", "node_modules", ".git", ".claude"]
-  reader_level: beginner
   article_length: medium   # short / medium / long / custom
 
 workflow:
@@ -14,24 +13,25 @@ workflow:
       display_name: "対象ドキュメント群を選択"
       mode: confirm
       note: "md 一覧（多い場合はフォルダ一覧）を出してユーザーが除外指定"
-    - id: level
-      display_name: "読者レベル設定"
+    - id: reader_context
+      display_name: "読者コンテキスト設定"
       mode: confirm
-      note: "LLM がドキュメントから推定して提案、ユーザーが確認"
+      note: "誰が読むか（記事のトーンに使用。抽出フィルターには使わない）"
     - id: article_length
       display_name: "記事の分量設定"
       mode: confirm
       note: "short（〜200字）/ medium（〜500字）/ long（〜1000字）/ 文字数直指定"
     - id: extract
-      display_name: "用語抽出（LLM）"
+      display_name: "用語抽出（LLM）— 全レベル対象"
       actor: llm
-      note: "対象ドキュメント群から一括抽出。既存 docs/glossary/ は除外"
+      note: "レベルで絞らず、誰かが分からない可能性がある用語を全て抽出"
     - id: confirm_terms
       display_name: "用語一覧を確認"
       mode: confirm
     - id: articleize
-      display_name: "記事生成（LLM）"
+      display_name: "記事生成（LLM）— 3セクション構成"
       actor: llm
+      note: "1用語1ファイル。expert / beginner / grandma の3セクションを1ファイルに"
     - id: save
       display_name: "単語帳保存"
     - id: link
@@ -49,27 +49,35 @@ 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: single_file_multi_level
   output_dir: docs/glossary/
   filename_rule: "<slug>.md（英語）, <slug>.ja.md（日本語）"
+  sections:
+    - id: summary
+      display_name: "1行サマリー（冒頭 blockquote）"
+    - id: expert
+      display_name: "詳細（開発者向け）"
+    - id: beginner
+      display_name: "かんたん説明（初学者向け）"
+    - id: grandma
+      display_name: "ひとことで（技術ゼロ向け）"
   length:
-    short:  "〜200字。定義1文 + 例1文"
-    medium: "〜500字。定義 + 説明 + 例。デフォルト"
-    long:   "〜1000字。定義 + 詳細 + コード例 + 関連用語"
+    short:  "〜200字。サマリー + 各セクション1-2文"
+    medium: "〜500字。サマリー + 各セクション3-5文。デフォルト"
+    long:   "〜1000字。サマリー + 各セクション充実 + コード例 + 関連用語"
 
 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,59 @@
 
 - **必要なもの**: LLM（Claude, GPT-4, Gemini 等）へのアクセス
 - **推奨**: Claude Code（skills/ で自動発動）
-- **入力**: レビュー対象のドキュメント（README, API 仕様, 設計書など）
-- **出力**: 用語集記事 + 単語帳（dictionary.yaml）+ クリッカブルリンク
+- **入力**: レビュー対象のドキュメント群
+- **出力**: 用語集記事（3セクション構成）+ 単語帳 + クリッカブルリンク
 
 ---
 
 ## 最低限これだけ読め（3分版）
 
-> **TL;DR** — 以下を読めば DDE を始められる。
+**DDE とは**: ドキュメントを読む人全員に対して用語を抜き出して、誰でも分かる記事を作り、リンクにする。
 
-**DDE とは**: 読者レベルを決めて、ドキュメントの用語を抜き出して、記事化する。それを単語帳にして、ドキュメントをクリッカブルにする。
-
-**4 ステップ**:
-1. **Level** — 想定読者のレベルを決める（expert / beginner / grandma）
-2. **Extract** — そのレベルで「分からない用語」をドキュメントから抽出する
-3. **Articleize** — 用語ごとに glossary 記事を生成する
-4. **Link** — dde-link で用語をクリッカブルにする
-
-**最初にやること**:
-1. ドキュメントを用意する（README.md など）
-2. 「DDE して」と Claude Code に言う
-3. 読者レベルを確認または指定する
-4. 生成された記事をレビューして承認する
+**フロー**:
+1. **Select** — 対象ドキュメント群を選ぶ（除外フォルダを確認）
+2. **Context** — 誰が読むかを把握する（記事トーンの調整に使う）
+3. **Extract** — 全用語を一括抽出（レベルで絞らない）
+4. **Articleize** — 1用語1ファイル・3セクション記事を生成
+5. **Link** — dde-link でリンクを埋め込む
 
 ---
 
 ## 原理
 
-普通のドキュメントレビューは「書いてあることの検証」。
-DDE は「読者には分からない用語の洗い出し」。
+同じドキュメントをエンジニアも業務担当者も読む。
+「このレベルの人には不要」を抽出段階で判断するより、
+**記事の中に全レベルのセクションを書いてしまう**方がシンプルで漏れがない。
 
-書いた側には自明な用語が、読者には不透明なまま残っている。
-この「前提の非対称」を、読者レベルを明示して LLM に検出させる。
+```
+抽出: レベルで絞らない（誰かが分からなければ抽出する）
+記事: 1ファイルに3セクション（誰が読んでも分かる）
+リンク: 常に同じファイルを指す（レベル分岐なし）
+```
 
 ---
 
-## DDE の 4 ステップ
+## 記事フォーマット（1用語1ファイル・3セクション）
 
-```
-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) に自動置換する。
-```
+```markdown
+# JWT
 
----
+> 認証に使うトークン形式（1行サマリー）
 
-## 3 段階の読者レベル
+## 詳細（開発者向け）
+JSON Web Token（RFC 7519）は...
 
-```
-expert   — 同分野の開発者（定義 + 技術詳細 + コード例）
-beginner — 初学者（やさしい説明 + 具体例）
-grandma  — 技術ゼロ（身近な例えだけ）
+## かんたん説明（初学者向け）
+JWTはログイン状態を安全に...
+
+## ひとことで（技術ゼロ向け）
+銀行のキャッシュカードみたいなもの。
 ```
 
-同じ用語でも、レベルによって抽出される用語も記事のトーンも変わる。
+読者コンテキストは**セクションの厚み**を調整するためだけに使う:
+- エンジニアが主な読者 → 「詳細」を充実させる
+- 業務担当者が主な読者 → 「かんたん説明」「ひとことで」を充実させる
+- 混在 → バランスよく
 
 ---
 
@@ -80,6 +66,7 @@ grandma  — 技術ゼロ（身近な例えだけ）
 1. docs/glossary/ の .md ファイル名から用語を自動推定
 2. dictionary.yaml があれば上書き（日本語用語・別名対応）
 3. 最長一致、段落ごとに 1 回 → [用語](docs/glossary/xxx.md) に置換
+   （リンク先は常に単一ファイル。レベル指定なし）
 スキップ: コードブロック / インラインコード / 見出し / 既存リンク
 ```
 
@@ -89,5 +76,4 @@ grandma  — 技術ゼロ（身近な例えだけ）
 
 - 241 の用語集記事（120 EN + 121 JA）
 - README に 334 のクリッカブルリンク
-- 11 の mermaid フロー図
 - 3 段階の読者レベル対応

package/package.json

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

package/skills/dde-session.md

@@ -16,22 +16,24 @@
 テーマなしで「DDE」「DDE って何」と呼ばれたとき:
 
 ```
-DDE toolkit v0.1.0 — Document Deficit Extraction
+DDE toolkit v0.1.2 — Document Deficit Extraction
 
-読者レベルを決めて → 用語を抽出して → 記事化 → 単語帳 → クリッカブルなドキュメント
+読者コンテキストを把握して → 用語を全抽出して → 3レベル記事を生成 → クリッカブルなドキュメント
 
 📖 フロー:
-  1. ドキュメント群を選択（対象ファイル・除外フォルダを確認）
-  2. 読者レベルを設定（LLM が推定して提案）
+  1. ドキュメント群を選択（除外フォルダを確認）
+  2. 読者コンテキストを設定（記事のトーンに使用）
   3. 記事の分量を設定（short / medium / long）
-  4. 用語を LLM が一括抽出 → 一覧確認
-  5. 用語ごとに glossary 記事を生成 → docs/glossary/
+  4. 全用語を一括抽出（レベルで絞らない）→ 一覧確認
+  5. 1用語1ファイル・3セクション記事を生成 → docs/glossary/
   6. dde-link が対象ドキュメント群にリンクを埋め込む
 
-👥 3 段階の読者レベル:
-  expert   — 同分野の開発者
-  beginner — 初学者（デフォルト）
-  grandma  — 技術ゼロ
+📄 記事フォーマット（1ファイル・3セクション）:
+  # JWT
+  > 認証に使うトークン形式
+  ## 詳細（開発者向け）...
+  ## かんたん説明（初学者向け）...
+  ## ひとことで（技術ゼロ向け）...
 
 🔗 dde-link（LLM 不要）:
   npx dde-link README.md            # 自動リンク実行
@@ -47,7 +49,7 @@ 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/`）。
+`defaults.exclude_dirs` を確認（デフォルト: `dde/`, `dge/`, `node_modules/`, `.git/`, `.claude/`）。
 
 ### Step 1: 対象ドキュメント群の選択（MUST: ユーザーに確認）
 
@@ -57,12 +59,11 @@ DDE toolkit v0.1.0 — Document Deficit Extraction
 
 ```
 対象ドキュメントを選択してください。
+（dde/, dge/, node_modules/ は除外済み）
 
-フォルダ一覧（dde/, dge/, node_modules/ は除外済み）:
   ✅ docs/          (12 ファイル)
   ✅ README.md
   ✅ CONTRIBUTING.md
-  ⬜ docs/internal/ (除外候補)
 
 除外したいファイル・フォルダがあれば指定してください。
 なければそのまま進みます。
@@ -70,30 +71,30 @@ DDE toolkit v0.1.0 — Document Deficit Extraction
 
 確定したファイルセットが「抽出元 = リンク適用先」になる。
 
-### Step 2: 読者レベルの設定（MUST: LLM が推定してから確認）
+### Step 2: 読者コンテキストの設定（MUST: ユーザーに確認）
 
-対象ドキュメントの語彙・トーンを見て LLM がレベルを推定し、ユーザーに提案する。
+**ここで聞くのは「誰が読むか」であり、抽出フィルターには使わない。**
+記事の各セクションのトーン・深さを調整するためだけに使う。
 
 ```
-ドキュメントを読みました。推定: beginner
+このドキュメントを読む人を教えてください（複数可）:
 
-根拠: 専門用語が多いが説明がない。初学者には伝わらない箇所が目立つ。
+  [ ] プログラマー・エンジニア
+  [ ] 業務ドメインの担当者（非エンジニア）
+  [ ] 初学者・新人
+  [ ] その他: ___
 
-読者レベルを確認してください:
-1. expert   — 同分野の開発者
-2. beginner — 初学者 ← 推定
-3. grandma  — 技術ゼロ
-
-このまま beginner で進めますか？
+→ 各読者が「詳細」「かんたん説明」「ひとことで」のどのセクションを
+  主に使うかを想定して記事の厚みを調整します。
 ```
 
 ### Step 3: 記事の分量設定
 
 ```
 記事の分量を選んでください:
-1. short  — 〜200字（定義1文 + 例1文）
-2. medium — 〜500字（定義 + 説明 + 例）← デフォルト
-3. long   — 〜1000字（定義 + 詳細 + コード例 + 関連用語）
+1. short  — 〜200字（各セクション1-2文）
+2. medium — 〜500字（各セクション3-5文）← デフォルト
+3. long   — 〜1000字（各セクション充実 + コード例 + 関連用語）
 4. カスタム — 文字数を直接指定
 
 このまま medium で進めますか？
@@ -101,18 +102,20 @@ DDE toolkit v0.1.0 — Document Deficit Extraction
 
 ### Step 4: 用語抽出（LLM）
 
-対象ドキュメント群を読んで、選択した読者レベルで「分からない可能性がある用語」を一括抽出する。
+**レベルで絞らず、誰かが分からない可能性がある用語を全て抽出する。**
+
+理由: 同じドキュメントをエンジニアも業務担当者も読む。「このレベルには不要」の判断を抽出段階でするより、記事に全レベルのセクションを書いてしまう方がシンプル。
 
-**ルール:**
-- `docs/glossary/` に既存記事があるものは除外（スラッグが一致するもの）
-- 固有名詞（プロダクト名・企業名など）は除外
+**抽出ルール:**
+- `docs/glossary/` に既存記事があるものは除外
+- 固有名詞（プロダクト名・企業名）は除外
 - コードブロック内の識別子は除外
 - 重要度: その用語なしでは内容が理解できない → 🔴 High / 補足があると助かる → 🟡 Medium
 
 **出力（MUST: ユーザーに確認してから記事生成へ進む）:**
 
 ```
-## 抽出した用語一覧（beginner 視点）
+## 抽出した用語一覧
 
 | # | 用語 | 出現ドキュメント | 既存記事 | 重要度 |
 |---|------|----------------|---------|--------|
@@ -124,62 +127,41 @@ N 件抽出しました。記事を生成しますか？
 除外したい用語があれば番号で指定してください（例: 3,5）。
 ```
 
-### Step 5: 記事生成（LLM）
+### Step 5: 記事生成（LLM）— 1用語1ファイル・3セクション
 
 確認後、用語ごとに `docs/glossary/<slug>.md` を生成して保存する。
 
 **スラッグ規則:** 小文字、スペース → ハイフン（`json-web-token.md`）
 
-**テンプレート（expert）:**
+**テンプレート:**
 ```markdown
 # <Term>
 
-## 定義
-<1-2 文で核心を定義>
-
-## 技術詳細
-<実装・仕様の詳細>
-
-## コード例
-\`\`\`<lang>
-<example>
-\`\`\`
+> <1行サマリー — 誰が読んでも分かる核心を1文で>
 
-## 関連用語
-- [<term>](../glossary/<slug>.md)
-```
+## 詳細（開発者向け）
+<技術的な定義・仕様・実装の詳細。コード例があれば添付。>
 
-**テンプレート（beginner）:**
-```markdown
-# <Term>
+## かんたん説明（初学者向け）
+<例えを交えた3-5文。前提知識を仮定しない。>
 
-## ひとことで言うと
-<1 文でやさしく>
-
-## もう少し詳しく
-<例えを使って 3-5 文>
-
-## 使われる場面
-<具体的なシナリオ>
+## ひとことで（技術ゼロ向け）
+<日常の身近な例え1-2文。>
 
 ## 関連用語
-- [<term>](../glossary/<slug>.md)
+- [<関連用語>](<相対パス>)
 ```
 
-**テンプレート（grandma）:**
-```markdown
-# <Term>
-
-## 身近な例えで言うと
-<日常の例え 1-3 文>
-```
+**読者コンテキストの使い方:**
+- エンジニアが主な読者 → 「詳細」セクションを厚く
+- 業務担当者が主な読者 → 「かんたん説明」「ひとことで」を厚く
+- 混在 → バランスよく（デフォルト）
 
 `dde-tool save docs/glossary/<slug>.md` で保存。
 
 ### Step 6: 単語帳（dictionary.yaml）更新
 
-日本語ドキュメントが対象の場合、または日本語用語・別名を追加したい場合、
-`docs/glossary/dictionary.yaml` を生成・更新する。
+日本語ドキュメントが対象の場合、`docs/glossary/dictionary.yaml` を生成・更新する。
 
 ```yaml
 # docs/glossary/dictionary.yaml
@@ -192,32 +174,29 @@ oauth.md:
   ja: ["OAuth"]
 ```
 
-### Step 7: dde-link の実行（CLI）
+### Step 7: dde-link 実行（CLI）
 
-**適用先は Step 1 で選択したドキュメント群と同じ。** ユーザーに再確認は不要。
+**適用先は Step 1 で選択したドキュメント群と同じ。**
+リンクは常に `<slug>.md`（レベル指定なし）を指す。
 
 ```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: 省略しない）
 
 ```
 1. 別のドキュメント群も処理する
-2. 別の読者レベルで再実行する
-3. dde-link を実行する（まだの場合）
-4. 図が必要な箇所を検出する
-5. 後で
+2. dde-link を実行する（まだの場合）
+3. 図が必要な箇所を検出する
+4. 後で
 ```
 
 ---
 
 ## 注意
+- 抽出は「レベルで絞らない」— 記事の中で全レベルをカバーする
 - `docs/glossary/` に既存記事がある場合は上書きしない（差分のみ提案）
 - dde-link の `--fix` は上書き。事前に `--dry-run` を推奨
 - 将来フェーズ: HTML からの用語抽出 + ホバー表示（v0.2.0 予定）

package/version.txt

@@ -1 +1 @@
-0.1.0
+0.1.2