ln-120-reference-docs-creator

パス： ファイルパス（references/、../ln-*）は、このスキルのディレクトリを基準とします。

リファレンスドキュメント作成ツール

タイプ： L2 ワーカー

このスキルは、プロジェクトの TECH_STACK に基づいて、リファレンスドキュメントの構造（docs/reference/）とスマートドキュメント（ADR、ガイド、マニュアル）を作成します。ドキュメントは、代替案のある重要な技術選択について、作成が妥当と判断された場合にのみ作成されます。

目的

Context Store の TECH_STACK に基づき、リファレンスドキュメントのディレクトリ構造（docs/reference/）と README ハブを作成します。その後、妥当と判断された重要な技術選択に限り、ADR、ガイド、マニュアルを生成します。

このスキルを使用するタイミング

このスキルは、ln-100-documents-pipeline オーケストレーターによって呼び出される L2 ワーカーです。

次の場合に、このスキルを直接使用してください。

• リファレンスドキュメントの構造（docs/reference/）のみを作成する場合
• ADR、ガイド、マニュアル用のディレクトリを設定する場合
• ドキュメント構造全体は作成しない場合（完全なセットアップには ln-100-documents-pipeline を使用してください）

入力

ln-100 から（ln-110 Context Store 経由）：

{
  "context_store": {
    "PROJECT_NAME": "my-project",
    "TECH_STACK": {
      "frontend": "React 18",
      "backend": "Express 4.18",
      "database": "PostgreSQL 15",
      "orm": "Prisma 5.0",
      "auth": "JWT",
      "cache": "Redis 7"
    },
    "DEPENDENCIES": [...],
    "flags": { "hasBackend": true, "hasDatabase": true, "hasFrontend": true }
  }
}

Phase 2 でのスマートドキュメント作成には TECH_STACK を使用します。

必須の読み込み： references/docs_quality_contract.md と references/markdown_read_protocol.md を読み込みます。 任意のルールカタログ：正確なルール ID、パスマトリックス、または許可リストに登録されたプレースホルダーの例外が必要な場合に限り、references/docs_quality_rules.json を読み込みます。

ワークフロー

このスキルは、4 フェーズのワークフローに従います。構造の作成 → スマートドキュメントの作成 → 構造の検証 → 内容の検証。Phase 2 では、作成が妥当と判断された技術選択についてのみドキュメントを作成します。

---

Phase 1：構造の作成

目的：リファレンスドキュメントのディレクトリと README ハブを作成します。

手順：

1.1 ディレクトリの確認と作成：

• docs/reference/adrs/ が存在するか確認し、なければ作成します
• docs/reference/guides/ が存在するか確認し、なければ作成します
• docs/reference/manuals/ が存在するか確認し、なければ作成します
• docs/reference/research/ が存在するか確認し、なければ作成します
• 各項目について、"✓ Created docs/reference/[name]/" または "✓ docs/reference/[name]/ already exists" を記録します

1.2 README の確認と作成：

• docs/reference/README.md が存在するか確認します
• 存在する場合：
  • 作成をスキップします
  • "✓ docs/reference/README.md already exists, proceeding to validation" と記録します
• 存在しない場合：
  • テンプレート ln-120-reference-docs-creator/references/templates/reference_readme_template.md を docs/reference/README.md にコピーします
  • プレースホルダーを置き換えます：
    • {{VERSION}} — "1.0.0"
    • {{DATE}} — 現在の日付（YYYY-MM-DD）
    • {{ADR_LIST}} — - No ADRs yet. Add the first ADR when a nontrivial decision is accepted.
    • {{GUIDE_LIST}} — - No project guides yet. Add guides when patterns need project-specific explanation.
    • {{MANUAL_LIST}} — - No package manuals yet. Add manuals only for complex external APIs.
    • {{RESEARCH_LIST}} — - No research notes yet. Add research only when a concrete question is investigated.
  • テンプレートにある共通の冒頭契約と標準のトップセクションを保持します
  • "✓ Created docs/reference/README.md from template" と記録します

1.3 出力：

docs/reference/
├── README.md         # Created or existing
├── adrs/            # Empty, ready for ADRs
├── guides/          # Empty, ready for guides
├── manuals/         # Empty, ready for manuals
└── research/        # Empty, ready for research documents

---

フェーズ 2：スマートなドキュメント作成

目的：根拠のある技術選定について、ADR、ガイド、マニュアルを作成します。些細な選択や明白な選択はスキップします。

2.1 コンテキストストアを確認する：

• context_store が指定されていない場合 → フェーズ 2 をスキップして、フェーズ 3 に進みます
• context_store に TECH_STACK がない場合 → フェーズ 2 をスキップして、フェーズ 3 に進みます
• ログ：「TECH_STACK を含むコンテキストストアを受信しました：[カテゴリ数]」

2.2 根拠のルールを読み込む：

• references/tech_justification_rules.md を読み込みます
• カテゴリごとの根拠が必要な条件／スキップ条件を解析します

2.3 TECH_STACK を分析して ADR を作成する：

TECH_STACK の各カテゴリ（frontend、backend、database、orm、auth、cache）について：

1. 根拠が必要か確認する（根拠のルールに基づく）：

   • frontend：React／Vue／Angular／Svelte の場合は根拠が必要です（複数の選択肢があります）
   • backend：Express／Fastify／NestJS／Koa の場合は根拠が必要です（複数の選択肢があります）
   • database：PostgreSQL／MySQL／MongoDB の場合は根拠が必要です（複数の選択肢があります）
   • auth：JWT／OAuth／Session の場合は根拠が必要です（選定が必要です）
   • orm：Prisma／TypeORM／Sequelize の場合は根拠が必要です（複数の選択肢があります）
   • cache：Redis／Memcached の場合は根拠が必要です（選定が必要です）

2. 些細な選択の場合はスキップする：

   • jQuery のみのフロントエンド（フレームワークの選択肢がありません）
   • シンプルな HTTP サーバー（フレームワークを使用しません）
   • 開発専用の SQLite
   • 認証が不要
   • 生の SQL のみ
   • インメモリキャッシュのみ

3. 根拠が必要な場合は ADR を作成する：

   • 次の ADR 番号を決定します：adr-NNN-{category}.md
   • テンプレートを使用します：references/templates/adr_template.md
   • MCP リサーチ：mcp__context7__resolve-library-id(technology)
   • テンプレートに記入します：
     • タイトル：「ADR-NNN：{Category} の選定」
     • コンテキスト：決定が必要だった理由
     • 決定：選定した技術とバージョン
     • 根拠：リサーチに基づく主な理由 3 つ
     • 代替案：長所と短所を含む他の選択肢 2 つ
   • 保存先：docs/reference/adrs/adr-NNN-{category}.md
   • ログ：「✓ {category} の ADR を作成しました：{technology}」

4. 根拠が不要な場合はスキップする：

   • ログ：「⊘ {category} の ADR をスキップしました：些細な選択です」

2.4 TECH_STACK を分析してガイドを作成する：

複雑な設定が必要な各技術について：

1. 根拠が必要か確認する：

   • 20 行を超える設定ファイルがある
   • カスタムフック／ミドルウェア／デコレーターを使用している
   • 関連する依存関係が 3 つ以上ある

2. 根拠が必要な場合はガイドを作成する：

   • 次のガイド番号を決定します：NN-{technology-slug}-patterns.md
   • テンプレートを使用します：references/templates/guide_template.md
   • MCP リサーチ：mcp__Ref__ref_search_documentation("{technology} patterns {current_year}")
   • テンプレートに記入します：
     • 原則：リサーチに基づく業界標準
     • 実装方法：プロジェクトでの使用方法
     • パターン表：Do／Don't／When の行を 3 つ
   • 保存先：docs/reference/guides/NN-{technology}-patterns.md
   • ログ：「✓ {technology} のガイドを作成しました」

3. 標準的な使用方法の場合はスキップする：

   • ログ：「⊘ {technology} のガイドをスキップしました：標準的な使用方法です」

2.5 TECH_STACK を分析してマニュアルを作成する：

複雑な API を持つ各パッケージについて：

1. 根拠が必要か確認する：

   • パッケージがエクスポートするメソッドが 10 個を超える
   • 現在のバージョンに破壊的変更がある
   • 些細な選択のリストに含まれていない：lodash、uuid、dotenv

2. 根拠が必要な場合はマニュアルを作成する：

   • テンプレートを使用します：references/templates/manual_template.md
   • MCP リサーチ：mcp__context7__get-library-docs(topic: "API")
   • テンプレートに記入します：
     • バージョンを含むパッケージ情報
     • 最もよく使われるメソッドを 2～3 個
     • 設定セクション
   • 保存先：docs/reference/manuals/{package}-{version}.md
   • ログ：「✓ {package} のマニュアルを作成しました」

3. API が単純な場合はスキップする：

   • ログ：「⊘ {package} のマニュアルをスキップしました：API が単純です」

2.6 スマート作成の内容を報告する：

✅ Smart Document Creation complete:
  - ADRs created: [count] (justified: frontend, backend, database)
  - ADRs skipped: [count] (trivial: cache=in-memory)
  - Guides created: [count]
  - Guides skipped: [count]
  - Manuals created: [count]
  - Manuals skipped: [count]

---

フェーズ 3：構造を検証する

目的：reference/README.md が構造要件に準拠していることを確認し、違反を自動修正します。

プロセス：

2.1 冒頭の契約を確認する：

• docs/reference/README.md（最初の 5 行）を読みます
• `` タグとメタデータマーカーを確認します
• 想定値：``
• 存在しない場合：
  • Edit ツールを使用して、ファイルの先頭付近に不足している冒頭マーカーを追加します
  • 違反を記録します：opening_contract_fixed = True

2.2 必須セクションを確認する：

• references/questions.md から想定されるセクションを読み込みます
• 必須セクション：
  • "Architecture Decision Records (ADRs)"
  • "Project Guides"
  • "Package Manuals"
  • "Research"
• 各セクションについて：
  • ## [Section Name] ヘッダーが存在するか確認します
  • 存在しない場合：
    • Edit ツールを使用して、次のプレースホルダー付きセクションを追加します：

      ## [Section Name]
      
      {{PLACEHOLDER}}
      

    • 違反を記録します：missing_sections += 1

2.3 Maintenance セクションを確認する：

• ## Maintenance ヘッダーを検索します
• 存在しない場合：
  • Edit ツールを使用して、ファイルの末尾に次を追加します：

    ## Maintenance
    
    **Last Updated:** [current date]
    
    **Update Triggers:**
    - New ADRs added to adrs/ directory
    - New guides added to guides/ directory
    - New manuals added to manuals/ directory
    
    **Verification:**
    - [ ] All ADR links in registry are valid
    - [ ] All guide links in registry are valid
    - [ ] All manual links in registry are valid
    - [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
    

  • 違反を記録します：maintenance_added = True

2.4 POSIX ファイル末尾を確認する：

• ファイルが空行 1 行で終わっているか確認します
• 終わっていない場合：
  • Edit ツールを使用して、末尾に改行を追加します
  • 修正を記録します：posix_fixed = True

2.5 検証結果を報告する：

• 概要を記録します：

  ✅ Structure validation complete:
    - SCOPE tag: [added/present]
    - Missing sections: [count] sections added
    - Maintenance section: [added/present]
    - POSIX endings: [fixed/compliant]
  

• 違反が見つかった場合："⚠️ Auto-fixed [total] structural violations"

---

フェーズ 4：コンテンツを検証する

目的：各セクションに質問への有意義な回答が記載されていることを確認し、自動検出によってレジストリに情報を入力します（フェーズ 2 で作成されたドキュメントを含みます）。

プロセス：

4.1 検証仕様を読み込む：

• references/questions.md を読みます
• 3 つすべてのセクションについて、質問と検証ヒューリスティックを解析します

4.2 セクションを検証する（パラメーター化されたループ）：

セクションのパラメーターを定義します：

sections = [
  {
    "name": "Architecture Decision Records (ADRs)",
    "question": "Where are architecture decisions documented?",
    "directory": "docs/reference/adrs/",
    "empty_state": "No ADRs yet.",
    "glob_pattern": "docs/reference/adrs/*.md",
    "heuristics": [
      "Contains link: [ADRs](adrs/) or [adrs](adrs/)",
      "Mentions 'Architecture Decision Record' or 'ADR'",
      "Has actual list or empty-state note",
      "Length > 30 words"
    ]
  },
  {
    "name": "Project Guides",
    "question": "Where are reusable project patterns documented?",
    "directory": "docs/reference/guides/",
    "empty_state": "No project guides yet.",
    "glob_pattern": "docs/reference/guides/*.md",
    "heuristics": [
      "Contains link: [Guides](guides/) or [guides](guides/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  },
  {
    "name": "Package Manuals",
    "question": "Where are third-party package references documented?",
    "directory": "docs/reference/manuals/",
    "empty_state": "No package manuals yet.",
    "glob_pattern": "docs/reference/manuals/*.md",
    "heuristics": [
      "Contains link: [Manuals](manuals/) or [manuals](manuals/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  },
  {
    "name": "Research",
    "question": "Where are research/investigation documents stored?",
    "directory": "docs/reference/research/",
    "empty_state": "No research notes yet.",
    "glob_pattern": "docs/reference/research/*.md",
    "heuristics": [
      "Contains link: [Research](research/) or [research](research/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  }
]

各セクションについて、sections 内で：

1. セクションの内容を読み取る：

   • reference/README.md からセクションを抽出します

2. 内容が質問に回答しているか確認する：

   • 検証ヒューリスティックを適用します
   • いずれかのヒューリスティックに合格した場合 → 内容は有効です。次のセクションに進みます
   • すべて不合格の場合 → 内容は無効です。続行します

3. 自動検出（内容が無効、または空状態が存在する場合）：

   • Glob ツールを使用してディレクトリをスキャンします（section.glob_pattern）
   • ファイルが見つかった場合：
     • ファイル名を抽出します
     • 動的リストを生成します：

       - [ADR-001: Frontend Framework](adrs/adr-001-frontend-framework.md)
       - [02-Repository Pattern](guides/02-repository-pattern.md)
       - [Axios 1.6](manuals/axios-1.6.md)
       

     • Edit ツールを使用して、空状態のテキストを生成したリストに置き換えます
     • 変更を記録します：sections_populated += 1
   • ファイルが見つからない場合：
     • 簡潔な空状態の注記を残します
     • 記録します：empty_states_kept += 1

4. 外部 API 呼び出しをスキップする：

   • MCP Ref 検索は使用しないでください（テンプレートには形式の例がすでに含まれています）

4.3 コンテンツ検証結果を報告する：

• 概要を記録します：

  ✅ Content validation complete:
    - Sections checked: 4
    - Populated from auto-discovery: [count]
    - Placeholders kept (no files): [count]
    - Already valid: [count]
  

---

完全な出力構造

docs/
└── reference/
    ├── README.md                     # Reference hub with registries
    ├── adrs/                         # Empty or with ADR files
    ├── guides/                       # Empty or with guide files
    ├── manuals/                      # Empty or with manual files
    └── research/                     # Empty or with research files

---

参照ファイル

テンプレート

リファレンス README テンプレート:

• references/templates/reference_readme_template.md (v2.0.0) - 以下を含むリファレンスハブ:
  • SCOPE タグ (リファレンスドキュメントのみ)
  • プレースホルダーを含む 3 つのレジストリセクション
  • メンテナンスセクション

ドキュメントテンプレート (フェーズ 2 スマート作成用):

• references/templates/adr_template.md - Nygard ADR 形式 (7 セクション)
• references/templates/guide_template.md - パターンドキュメント (Do/Don't/When)
• references/templates/manual_template.md - API リファレンス形式
• references/templates/research_template.md - リサーチ/スパイクドキュメント

正当化ルール:

• references/tech_justification_rules.md - マッピング: カテゴリ → 作成/スキップ条件

検証仕様:

• references/questions.md (v2.0) - 質問駆動型の検証:

  • Q1-Q3: レジストリセクション (ADR、ガイド、マニュアル)
  • Q4-Q7: スマートドキュメントの検証 (ADR コンテキスト、代替案、パターン)
  • 自動検出のヒント

• 必読: references/research_tool_fallback.md を読み込む

---

ベストプラクティス

• 時期尚早な検証を行わない: フェーズ 1 で構造を作成し、フェーズ 3 でそれを検証します
• スマート作成: フェーズ 2 では、正当化された選択に対してのみドキュメントを作成します
• パラメトリック検証: フェーズ 4 では 3 つのセクションにループを使用します (コードの重複なし)
• 自動検出を優先: 外部 API 呼び出しの前に実際のファイルをスキャンします
• 冪等性: ✅ 安全に複数回実行できます (作成前に存在をチェック)
• 関心の分離: 作成 → スマートドキュメント → 構造の検証 → コンテンツの検証

NO_CODE_EXAMPLES ルール (ガイドに対して必須)

ガイドはパターンを文書化するものであり、実装ではありません:

• 禁止: 完全な関数実装、5 行を超えるコードブロック
• 許可: Do/Don't/When テーブル、メソッドシグネチャ (1 行)、疑似コード (1〜3 行)
• コードの代わりに: ソースの場所を参照: 「src/hooks/usePlan.ts:15-30 を参照」
• テンプレートルール: guide_template.md には `` タグが含まれています - それに従ってください

スタック適応ルール (必須)

• ADR はスタックに適した代替案を参照する必要があります (React vs Vue を比較し、React vs Django は比較しない)
• ガイドは正しいプラットフォームドキュメントにリンクする必要があります (.NET は Microsoft、JS は MDN)

フォーマット優先度 (必須)

テーブル (Do/Don't/When) > ASCII 図 > リスト > テキスト

---

前提条件

呼び出し元: ln-100-documents-pipeline オーケストレーター

必要:

• docs/ ディレクトリ (ln-111-root-docs-creator によって作成されるか、ターゲットプロジェクトにすでに存在する)

作成:

• README ハブを含む docs/reference/ ディレクトリ構造
• 検証済みの構造とコンテンツ (既存ファイルからの自動検出)

---

重要なルール

• 正当化された作成のみ: ドキュメントは、実質的な代替案を伴う非自明な技術選択に対してのみ作成されます。自明な選択はスキップされます
• NO_CODE_EXAMPLES: ガイドはパターン (Do/Don't/When テーブル) を文書化するものであり、実装ではありません。5 行を超えるコードブロックは不可です
• スタック適応: ADR の代替案はスタックに適したものでなければなりません (React vs Vue、React vs Django ではない)。リンクはプラットフォームドキュメントと一致する必要があります
• フォーマット優先度: テーブル (Do/Don't/When) > ASCII 図 > リスト > テキスト
• 冪等性: 作成前に存在をチェックします。複数回実行しても安全です

ランタイムサマリーアーティファクト

必読: references/docs_generation_summary_contract.md を読み込む

オプションの summaryArtifactPath を受け付けます。

サマリーの種類:

• docs-generation

必須ペイロードセマンティクス:

• worker = "ln-120"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

提供されたアーティファクトパスにサマリーを書き込むか、同じエンベロープを構造化出力で返します。

完了の定義

作業を完了する前に、すべてのチェックポイントを確認してください。

✅ フェーズ 1 - 構造の作成：

• docs/reference/ ディレクトリが存在する
• docs/reference/adrs/ ディレクトリが存在する
• docs/reference/guides/ ディレクトリが存在する
• docs/reference/manuals/ ディレクトリが存在する
• docs/reference/research/ ディレクトリが存在する
• docs/reference/README.md が存在する（作成済み、または既存）

✅ フェーズ 2 - スマートドキュメントの作成（コンテキストストアが提供された場合）：

• 妥当な技術選定（重要度が高いもの）について ADR を作成した
• 些細な選定について ADR の作成を省略した（記録済み）
• 複雑な設定が必要な技術についてガイドを作成した
• API が複雑なパッケージについてマニュアルを作成した
• 作成した各ドキュメントに実際の内容がある（プレースホルダーではない）

✅ フェーズ 3 - 構造の検証：

• SCOPE タグとメタデータマーカーが上部付近にある
• クイックナビゲーション、エージェントのエントリーポイント、メンテナンスの各セクションがある
• 4 つのレジストリセクション（ADR、ガイド、マニュアル、リサーチ）がある
• メンテナンスセクションが末尾にある
• POSIX ファイル終端の要件に準拠している

✅ フェーズ 4 - コンテンツの検証：

• すべてのセクションを questions.md に照らして確認した
• すべてのレジストリに空の状態を示す注記、または実際の項目がある（未処理のプレースホルダーがない）
• 検証ヒューリスティックによる失敗がない

✅ 報告：

• フェーズ 1 を記録した：作成の概要
• フェーズ 2 を記録した：スマート作成（作成数／省略数）

返却形式

正規化したステータスを ln-100 に返してください。

{
  "created_files": ["docs/reference/README.md", "docs/reference/adrs/adr-001-frontend.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/reference/README.md", "docs/reference/adrs/adr-001-frontend.md"],
    "owners": {
      "docs/reference/README.md": "ln-120-reference-docs-creator",
      "docs/reference/adrs/adr-001-frontend.md": "ln-120-reference-docs-creator"
    }
  },
  "validation_status": "passed"
}

✅ 報告（続き）：

• フェーズ 4 を記録した：コンテンツの更新（該当する場合）

メタ分析

任意の参考資料：ユーザーが実行後のメタ分析またはプロトコル形式の実行の振り返りを求めた場合に限り、references/meta_analysis_protocol.md を読み込んでください。

スキルの種類：documentation-creator。依頼された場合は、すべてのフェーズの完了後に実行してください。documentation-creator 形式でチャットに出力してください。

---

技術的な詳細

標準：

• Michael Nygard の ADR 形式（7 セクション）
• ISO/IEC/IEEE 29148:2018（ドキュメント標準）

**言語：**英語のみ

---

**バージョン：**8.2.0 **最終更新日：**2025-01-12