@unlaxer/dde-toolkit 0.1.2 → 0.1.4

package/flows/quick.yaml

@@ -5,39 +5,45 @@ trigger_keywords: ["DDE して", "DDE", "ドキュメントレビュー", "用
 
 defaults:
   exclude_dirs: ["dde", "dge", "node_modules", ".git", ".claude"]
-  article_length: medium   # short / medium / long / custom
+  article_intent: educational   # educational / reference / deep-dive
 
 workflow:
   steps:
+    - id: resume_check
+      display_name: "前回セッションの確認"
+      note: "dde/sessions/ の最新ファイルを読んで未完了の作業を検出。新規なら skip"
+    - id: scan_glossary
+      display_name: "既存 glossary をスキャン"
+      note: "docs/glossary/ の既存記事一覧を収集。相互リンク候補 + 抽出除外リストに使う"
     - id: select_docs
       display_name: "対象ドキュメント群を選択"
       mode: confirm
-      note: "md 一覧（多い場合はフォルダ一覧）を出してユーザーが除外指定"
     - id: reader_context
       display_name: "読者コンテキスト設定"
       mode: confirm
       note: "誰が読むか（記事のトーンに使用。抽出フィルターには使わない）"
-    - id: article_length
-      display_name: "記事の分量設定"
+    - 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）— 全レベル対象"
       actor: llm
-      note: "レベルで絞らず、誰かが分からない可能性がある用語を全て抽出"
     - id: confirm_terms
       display_name: "用語一覧を確認"
       mode: confirm
     - id: articleize
-      display_name: "記事生成（LLM）— 3セクション構成"
+      display_name: "記事生成（LLM）— educational narrative"
       actor: llm
-      note: "1用語1ファイル。expert / beginner / grandma の3セクションを1ファイルに"
     - id: save
       display_name: "単語帳保存"
     - id: link
       display_name: "dde-link 実行（CLI）"
       actor: cli
-      note: "対象ドキュメント群と同じファイルセットに適用"
 
 must_rules:
   - id: save
@@ -46,6 +52,10 @@ must_rules:
     text: "抽出した用語を一覧テーブルで出力してからユーザーに確認"
   - id: choices
     text: "記事生成後に番号付き選択肢を提示（省略しない）"
+  - id: crosslink_existing_only
+    text: "「さらに学ぶために」は docs/glossary/ に実在するファイル + 同一バッチ生成記事のみリンク可。存在しないファイルへのリンク禁止"
+  - id: scan_glossary_first
+    text: "セッション開始時に docs/glossary/ をスキャンして既存記事リストを作る（抽出除外 + 相互リンク候補に使用）"
 
 extract:
   actor: llm
@@ -56,22 +66,17 @@ extract:
 articleize:
   actor: llm
   per: term
-  format: single_file_multi_level
+  format: educational_narrative
   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-2文"
-    medium: "〜500字。サマリー + 各セクション3-5文。デフォルト"
-    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/
 

package/method.md

@@ -5,20 +5,21 @@
 - **必要なもの**: LLM（Claude, GPT-4, Gemini 等）へのアクセス
 - **推奨**: Claude Code（skills/ で自動発動）
 - **入力**: レビュー対象のドキュメント群
-- **出力**: 用語集記事（3セクション構成）+ 単語帳 + クリッカブルリンク
+- **出力**: educational narrative 形式の用語集記事 + クリッカブルリンク
 
 ---
 
 ## 最低限これだけ読め（3分版）
 
-**DDE とは**: ドキュメントを読む人全員に対して用語を抜き出して、誰でも分かる記事を作り、リンクにする。
+**DDE とは**: ドキュメントを読む人全員に対して用語を抜き出して、背景ごと理解できる記事にして、リンクにする。
 
 **フロー**:
-1. **Select** — 対象ドキュメント群を選ぶ（除外フォルダを確認）
+1. **Select** — 対象ドキュメント群を選ぶ
 2. **Context** — 誰が読むかを把握する（記事トーンの調整に使う）
-3. **Extract** — 全用語を一括抽出（レベルで絞らない）
-4. **Articleize** — 1用語1ファイル・3セクション記事を生成
-5. **Link** — dde-link でリンクを埋め込む
+3. **Intent** — 記事の目的を決める（「教育用」「リファレンス」など）
+4. **Extract** — 全用語を一括抽出（レベルで絞らない）
+5. **Articleize** — educational narrative 形式で記事を生成
+6. **Link** — dde-link でリンクを埋め込む
 
 ---
 
@@ -26,37 +27,49 @@
 
 同じドキュメントをエンジニアも業務担当者も読む。
 「このレベルの人には不要」を抽出段階で判断するより、
-**記事の中に全レベルのセクションを書いてしまう**方がシンプルで漏れがない。
+**誰が読んでも背景ごと理解できる記事を1つ書く**方がシンプルで漏れがない。
 
-```
-抽出: レベルで絞らない（誰かが分からなければ抽出する）
-記事: 1ファイルに3セクション（誰が読んでも分かる）
-リンク: 常に同じファイルを指す（レベル分岐なし）
-```
+文字数より**インテント**で指定する:
+- `educational` — 読んだ人が背景・動機・仕組みごと理解できる。分量は自然に決まる
+- `reference` — 定義と使い方を簡潔に
+- `deep-dive` — 実装・エッジケースまで網羅
+- 自由記述 — 「新入社員が業務背景ごと理解できるように」など
 
 ---
 
-## 記事フォーマット（1用語1ファイル・3セクション）
+## 記事フォーマット（educational）
 
 ```markdown
-# JWT
+# <用語>
 
-> 認証に使うトークン形式（1行サマリー）
+## 一言で言うと？
+<専門知識なしで分かる1-2文>
 
-## 詳細（開発者向け）
-JSON Web Token（RFC 7519）は...
+---
 
-## かんたん説明（初学者向け）
-JWTはログイン状態を安全に...
+## <身近な例え>
+<日常のアナロジー。対応表「○○ = △△」を使う>
 
-## ひとことで（技術ゼロ向け）
-銀行のキャッシュカードみたいなもの。
-```
+---
+
+## なぜ必要なの？
+<「自前でやったら？」との対比。ASCIIダイアグラム・比較表>
+
+---
 
-読者コンテキストは**セクションの厚み**を調整するためだけに使う:
-- エンジニアが主な読者 → 「詳細」を充実させる
-- 業務担当者が主な読者 → 「かんたん説明」「ひとことで」を充実させる
-- 混在 → バランスよく
+## <このプロジェクト文脈での説明>
+<抽象論ではなく、このプロジェクト固有の実装・設計を参照>
+
+---
+
+## 具体的な例
+<ステップバイステップのフロー>
+
+---
+
+## さらに学ぶために
+- [関連用語](path.md) — この文脈での関連理由
+```
 
 ---
 
@@ -65,8 +78,7 @@ JWTはログイン状態を安全に...
 ```
 1. docs/glossary/ の .md ファイル名から用語を自動推定
 2. dictionary.yaml があれば上書き（日本語用語・別名対応）
-3. 最長一致、段落ごとに 1 回 → [用語](docs/glossary/xxx.md) に置換
-   （リンク先は常に単一ファイル。レベル指定なし）
+3. 最長一致、段落ごとに 1 回 → [用語](相対パス) に置換
 スキップ: コードブロック / インラインコード / 見出し / 既存リンク
 ```
 
@@ -76,4 +88,4 @@ JWTはログイン状態を安全に...
 
 - 241 の用語集記事（120 EN + 121 JA）
 - README に 334 のクリッカブルリンク
-- 3 段階の読者レベル対応
+- educational narrative 形式（背景・動機・具体例・相互リンク）

package/package.json

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

package/skills/dde-session.md

@@ -16,29 +16,29 @@
 テーマなしで「DDE」「DDE って何」と呼ばれたとき:
 
 ```
-DDE toolkit v0.1.2 — Document Deficit Extraction
+DDE toolkit v0.1.3 — Document Deficit Extraction
 
-読者コンテキストを把握して → 用語を全抽出して → 3レベル記事を生成 → クリッカブルなドキュメント
+用語を全部抜き出して、誰でも理解できる記事にして、リンクにする。
 
 📖 フロー:
-  1. ドキュメント群を選択（除外フォルダを確認）
-  2. 読者コンテキストを設定（記事のトーンに使用）
-  3. 記事の分量を設定（short / medium / long）
-  4. 全用語を一括抽出（レベルで絞らない）→ 一覧確認
-  5. 1用語1ファイル・3セクション記事を生成 → docs/glossary/
-  6. dde-link が対象ドキュメント群にリンクを埋め込む
-
-📄 記事フォーマット（1ファイル・3セクション）:
-  # JWT
-  > 認証に使うトークン形式
-  ## 詳細（開発者向け）...
-  ## かんたん説明（初学者向け）...
-  ## ひとことで（技術ゼロ向け）...
+  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,67 +47,120 @@ DDE toolkit v0.1.2 — Document Deficit Extraction
 
 ## 手順
 
-### Step 0: flow 読み込み
+### Step 0: 前回セッション確認 + 既存 glossary スキャン
+
+**0-A: flow 読み込み**
 `dde/flows/` の YAML、なければ `kit/flows/` の YAML を読む。
-`defaults.exclude_dirs` を確認（デフォルト: `dde/`, `dge/`, `node_modules/`, `.git/`, `.claude/`）。
+
+**0-B: 前回セッション確認**
+`dde/sessions/` の最新ファイルを読む。未完了の作業（未生成の用語リスト等）があれば:
+
+```
+前回セッションが見つかりました（dde/sessions/2024-01-15_session.md）。
+未生成の用語: OAuth 2.0, リフレッシュトークン
+
+前回の続きから再開しますか？
+1. はい（前回の続きから）
+2. いいえ（最初から）
+```
+
+新規セッションの場合は skip。
+
+**0-C: 既存 glossary スキャン（MUST）**
+`docs/glossary/` の `.md` ファイル一覧を収集する。これを 2 つの目的に使う:
+
+1. **抽出除外リスト** — 既存記事がある用語は抽出対象から除外（Step 6）
+2. **相互リンク候補リスト** — 「さらに学ぶために」で使えるリンク一覧（Step 7）
+
+```
+既存 glossary: 12 記事
+  jwt.md, oauth2.md, session-management.md, ...
+→ これらの用語は抽出対象から除外
+→ 「さらに学ぶために」のリンク候補として使用
+```
+
+ファイルが存在しない場合は空リストで OK（新規プロジェクト）。
+
+**CRITICAL RULE — 相互リンク**:
+「さらに学ぶために」に書くリンクは、**記事生成時点で `docs/glossary/` に実在するファイルのみ**。
+存在しないファイルへのリンクは絶対に書かない。同一バッチで新規生成する記事同士は相互リンク可。
 
 ### Step 1: 対象ドキュメント群の選択（MUST: ユーザーに確認）
 
 プロジェクト内の `.md` ファイルを列挙する。
 - **50 ファイル未満**: ファイル一覧を表示
 - **50 ファイル以上**: フォルダ一覧を表示
+- デフォルト除外: `dde/`, `dge/`, `node_modules/`, `.git/`, `.claude/`
 
 ```
 対象ドキュメントを選択してください。
-（dde/, dge/, node_modules/ は除外済み）
 
   ✅ docs/          (12 ファイル)
   ✅ README.md
   ✅ CONTRIBUTING.md
 
 除外したいファイル・フォルダがあれば指定してください。
-なければそのまま進みます。
 ```
 
 確定したファイルセットが「抽出元 = リンク適用先」になる。
 
 ### Step 2: 読者コンテキストの設定（MUST: ユーザーに確認）
 
-**ここで聞くのは「誰が読むか」であり、抽出フィルターには使わない。**
-記事の各セクションのトーン・深さを調整するためだけに使う。
+**抽出フィルターには使わない。記事のトーン・文脈に使う。**
 
 ```
-このドキュメントを読む人を教えてください（複数可）:
+このドキュメントを読む人は？（複数可）
 
   [ ] プログラマー・エンジニア
   [ ] 業務ドメインの担当者（非エンジニア）
   [ ] 初学者・新人
   [ ] その他: ___
+```
+
+### Step 3: 言語設定（MUST: ユーザーに確認）
+
+対象ドキュメントの言語を検出し、記事の生成言語を確認する。
 
-→ 各読者が「詳細」「かんたん説明」「ひとことで」のどのセクションを
-  主に使うかを想定して記事の厚みを調整します。
 ```
+ドキュメントの言語を検出しました: 日本語
 
-### Step 3: 記事の分量設定
+記事を生成する言語を選んでください:
+1. ja のみ  — <slug>.ja.md を生成
+2. en のみ  — <slug>.md を生成
+3. both     — <slug>.md + <slug>.ja.md の両方を生成
+              （dictionary.yaml に en/ja の用語マッピングを追加）
 
+デフォルト: ドキュメントが日本語 → ja、英語 → en
 ```
-記事の分量を選んでください:
-1. short  — 〜200字（各セクション1-2文）
-2. medium — 〜500字（各セクション3-5文）← デフォルト
-3. long   — 〜1000字（各セクション充実 + コード例 + 関連用語）
-4. カスタム — 文字数を直接指定
 
-このまま medium で進めますか？
+**both の場合:**
+- 英語記事を先に生成し、日本語記事は [English version](<slug>.md) リンクを冒頭に追加
+- `dictionary.yaml` に `ja:` キーで日本語用語を登録
+- dde-link は `.ja.md` ファイルに対して日本語用語でマッチング
+
+### Step 5: 記事のインテント設定（MUST: ユーザーに確認）
+
+**文字数ではなく「読んだ人にどうなってほしいか」で指定する。**
+
+```
+記事のインテントを選んでください:
+1. educational — 背景・動機・仕組みごと理解できる記事
+                 例え話・図・なぜ？を含む。分量は目的に従って自然に決まる
+2. reference   — 定義と使い方を簡潔に。調べたい人向け
+3. deep-dive   — 実装詳細・コード例・エッジケースまで網羅
+4. 自由記述    — 例: 「新入社員が読んで業務背景ごと理解できるように」
+
+デフォルト: educational
 ```
 
-### Step 4: 用語抽出（LLM）
+### Step 6: 用語抽出（LLM）
 
 **レベルで絞らず、誰かが分からない可能性がある用語を全て抽出する。**
 
-理由: 同じドキュメントをエンジニアも業務担当者も読む。「このレベルには不要」の判断を抽出段階でするより、記事に全レベルのセクションを書いてしまう方がシンプル。
+対象ドキュメント群を読んで用語を一括抽出する。
 
 **抽出ルール:**
-- `docs/glossary/` に既存記事があるものは除外
+- `docs/glossary/` に既存記事があるものは除外（Step 0-C で収集したリストを使う）
 - 固有名詞（プロダクト名・企業名）は除外
 - コードブロック内の識別子は除外
 - 重要度: その用語なしでは内容が理解できない → 🔴 High / 補足があると助かる → 🟡 Medium
@@ -127,64 +180,105 @@ N 件抽出しました。記事を生成しますか？
 除外したい用語があれば番号で指定してください（例: 3,5）。
 ```
 
-### Step 5: 記事生成（LLM）— 1用語1ファイル・3セクション
+### Step 7: 記事生成（LLM）— educational narrative
 
 確認後、用語ごとに `docs/glossary/<slug>.md` を生成して保存する。
 
-**スラッグ規則:** 小文字、スペース → ハイフン（`json-web-token.md`）
+**記事フォーマット（educational intent の場合）:**
 
-**テンプレート:**
 ```markdown
-# <Term>
+# <用語>
 
-> <1行サマリー — 誰が読んでも分かる核心を1文で>
+## 一言で言うと？
+<1-2文でコアを定義。専門知識がない人でも分かる言葉で。>
 
-## 詳細（開発者向け）
-<技術的な定義・仕様・実装の詳細。コード例があれば添付。>
+---
 
-## かんたん説明（初学者向け）
-<例えを交えた3-5文。前提知識を仮定しない。>
+## <読者が直感的に分かる例え・タイトル>
+<日常の具体的なアナロジー。箇条書きや対応表で「○○ = △△」を示す。>
 
-## ひとことで（技術ゼロ向け）
-<日常の身近な例え1-2文。>
+---
+
+## なぜ<この用語 / このアプローチ>が必要なの？
+<「自前でやったらどうなるか」との比較で動機を説明。
+ ASCIIダイアグラムや対比表を使って直感的に。>
+
+---
+
+## <このプロジェクト / この文脈での説明>
+<抽象的な説明ではなく、このドキュメントが属するプロジェクトの文脈で具体的に説明する。
+ このプロジェクト固有の実装・設計を参照する。>
+
+---
+
+## 具体的な例
+<ステップバイステップのフロー。コードブロックや番号付きリストで。
+ 読者が「なるほど、こう動くのか」と分かるレベルまで具体的に。>
+
+---
+
+## さらに学ぶために
+- [関連用語A](<相対パス>) — この文脈でなぜ関連するか1行で
+- [関連用語B](<相対パス>) — この文脈でなぜ関連するか1行で
+```
+
+**「さらに学ぶために」のリンクルール（CRITICAL）:**
+- Step 0-C で収集した既存 glossary ファイル一覧のみを使う
+- 同一バッチで今回新たに生成する記事同士も相互リンク可（生成後に存在するため）
+- 存在しないファイルへのリンクは絶対に書かない（dead link 防止）
+- 候補がない場合はセクションを省略するか「（現在リンク先なし）」と明記する
+
+**reference intent の場合:**
+```markdown
+# <用語>
+
+<1文定義>
+
+## 使い方
+<コード例または手順>
 
 ## 関連用語
-- [<関連用語>](<相対パス>)
+- [<term>](<path>)
 ```
 
-**読者コンテキストの使い方:**
-- エンジニアが主な読者 → 「詳細」セクションを厚く
-- 業務担当者が主な読者 → 「かんたん説明」「ひとことで」を厚く
-- 混在 → バランスよく（デフォルト）
+**deep-dive intent の場合:**
+```markdown
+# <用語>
+
+## 定義
+## 内部動作
+## コード例
+## エッジケース・注意点
+## トレードオフ
+## 関連用語
+```
+
+**インテントが自由記述の場合:**
+ユーザーの言葉（例: 「新入社員が業務背景ごと理解できるように」）をそのまま
+記事の生成方針として使う。
 
 `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 で選択したドキュメント群と同じ。**
-リンクは常に `<slug>.md`（レベル指定なし）を指す。
+Step 1 で選択したドキュメント群と同じファイルセットに適用。
 
 ```bash
 npx dde-link README.md --dry-run   # 確認
 npx dde-link README.md             # 実行
 ```
 
-### Step 8: 次アクション提示（MUST: 省略しない）
+### Step 10: 次アクション提示（MUST: 省略しない）
 
 ```
 1. 別のドキュメント群も処理する
@@ -196,7 +290,7 @@ npx dde-link README.md             # 実行
 ---
 
 ## 注意
-- 抽出は「レベルで絞らない」— 記事の中で全レベルをカバーする
-- `docs/glossary/` に既存記事がある場合は上書きしない（差分のみ提案）
+- 記事の分量は文字数ではなくインテントに従って自然に決める
+- `docs/glossary/` に既存記事がある場合は上書きしない
 - dde-link の `--fix` は上書き。事前に `--dry-run` を推奨
 - 将来フェーズ: HTML からの用語抽出 + ホバー表示（v0.2.0 予定）

package/version.txt

@@ -1 +1 @@
-0.1.2
+0.1.4