ln-140-test-docs-creator

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

テストドキュメント作成ツール

タイプ： L2 ワーカー

このスキルは、テストドキュメントを作成し、検証します。テストドキュメントは、testing-strategy.md（汎用的なテストの理念）と、tests/README.md（tests/automated/ を含むテスト構成、およびストーリーレベルのテストタスクパターン）で構成されます。

目的

あらゆるプロジェクト向けに、汎用的なテストの理念、リスクベースのテスト戦略、自動テストのデフォルトルートとしての tests/automated/、およびストーリーレベルのテストタスクパターンを定めるテストドキュメント（testing-strategy.md + tests/README.md）を作成し、検証します。

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

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

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

• テストドキュメント（testing-strategy.md + tests/README.md）のみを作成する場合
• 既存のテストドキュメントの構成と内容を検証する場合
• 既存プロジェクト向けに、テストの理念と構成のドキュメントを設定する場合
• ドキュメント構成全体を作成しない場合（完全なセットアップには ln-100-documents-pipeline を使用してください）

ワークフロー

このスキルは、3 つのフェーズからなるワークフローに従います：作成 → 構成の検証 → 内容の検証。各フェーズは前のフェーズを引き継ぎ、構成全体と意味的な検証を確実に行います。

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

---

フェーズ 1：テストドキュメントの作成

目的：テストの理念とドキュメント構成を確立します。

手順：

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

• docs/reference/guides/ が存在するか確認し、存在しない場合は作成します
• tests/ が存在するか確認し、存在しない場合は作成します
• tests/manual/ が存在するか確認し、存在しない場合は作成します
• tests/manual/results/ が存在するか確認し、存在しない場合は作成します
• プロジェクトの .gitignore に tests/manual/results/ が記載されていない場合は追加します
• それぞれについて、次のように記録します：「✓ [directory]/ を作成しました」または「✓ [directory]/ はすでに存在します」

1.2 ドキュメントファイルの確認と作成：

• docs/reference/guides/testing-strategy.md が存在するか確認します

• 存在する場合：

  • 作成をスキップします
  • 「✓ testing-strategy.md はすでに存在するため、検証に進みます」と記録します

• 存在しない場合：

  • テンプレートをコピーします：ln-140-test-docs-creator/references/templates/testing_strategy_template.md → docs/reference/guides/testing-strategy.md
  • プレースホルダーを置き換えます：
    • [CURRENT_DATE] — 現在の日付（YYYY-MM-DD）
  • テンプレートの共有メタデータマーカーと標準の冒頭セクションを保持します
  • 「✓ testing-strategy.md をテンプレートから作成しました」と記録します

• tests/README.md が存在するか確認します

• 存在する場合：

  • 作成をスキップします
  • 「✓ tests/README.md はすでに存在するため、検証に進みます」と記録します

• 存在しない場合：

  • テンプレートをコピーします：ln-140-test-docs-creator/references/templates/tests_readme_template.md → tests/README.md
  • プレースホルダーを置き換えます：
    • {{DATE}} — 現在の日付（YYYY-MM-DD）
  • テンプレートの共有メタデータマーカーと標準の冒頭セクションを保持します
  • 「✓ tests/README.md をテンプレートから作成しました」と記録します

1.3 出力：

docs/reference/guides/
└── testing-strategy.md           # Created or existing

tests/
├── README.md                     # Created or existing
└── manual/
    └── results/                  # Created, added to .gitignore

---

フェーズ 2：構造の検証

目的：テストドキュメントファイルが構造上の要件に準拠していることを確認し、違反を自動修正します。

プロセス：

2.1 SCOPE タグを確認する：

• 両方のファイル（testing-strategy.md、tests/README.md）を読み込みます。最初に冒頭ブロックを確認します
• 各ファイルで `` タグとメタデータマーカーを確認します
• 期待される SCOPE タグ：
  • testing-strategy.md：``
  • tests/README.md：``
• どちらかのファイルで不足している場合：
  • Edit ツールを使用して、最初の見出しの前の 1 行目に SCOPE タグを追加します
  • 違反を記録します：scope_tags_added += 1

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

• references/questions.md から期待されるセクションを読み込みます
• testing-strategy.md の必須セクション：
  • 「テストの理念」
  • 「テストレベル」
• tests/README.md の必須セクション：
  • 「テストの構成」
  • 「テストの実行」
• 各ファイルについて：
  • ファイルの内容を読み込みます
  • ## [セクション名] ヘッダーがあるか確認します
  • 存在しない場合：
    • Edit ツールを使用して、テンプレートに基づく具体的な最小限のガイダンスを含むセクションを追加します。プレースホルダーのみにはしません
    • 違反を記録します：missing_sections += 1

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

• 各ファイル（testing-strategy.md、tests/README.md）について：
  • ## Maintenance ヘッダーを検索します
  • 存在しない場合：
    • ファイル末尾に以下を追加します：

      ## メンテナンス
      
      **最終更新日：** [現在の日付]
      
      **更新の契機：**
      - テストフレームワークの変更
      - テストの構成の変更
      - 新しいテストパターンの導入
      
      **検証：**
      - [ ] すべてのテスト例が現在のフレームワークの構文に準拠している
      - [ ] ディレクトリ構成が実際の tests/ と一致している
      - [ ] テストランナーのコマンドが最新である
      

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

2.4 POSIX ファイル終端を確認する：

• 各ファイルについて：
  • ファイルが単一の空行（LF）で終わっているか確認します
  • 不足している場合：
    • Edit ツールを使用して末尾に改行を追加します
    • 修正を記録します：posix_fixed += 1

2.5 検証結果を報告する：

• 概要を記録します：

  ✅ Structure validation complete:
    - SCOPE tags: [added N / already present]
    - Missing sections: [added N sections]
    - Maintenance sections: [added N / already present]
    - POSIX endings: [fixed N / compliant]
  

• 違反が見つかった場合：「⚠️ 構造上の違反を合計 [total] 件自動修正しました」

---

フェーズ 3：内容の検証

目的：各セクションが質問に対して意味のある内容で回答していることを確認し、自動検出した情報に基づいてテスト固有のセクションを埋めます。

プロセス：

3.1 検証仕様を読み込む：

• references/questions.md を読み込みます
• 4 つのセクション（各ファイルにつき 2 つ）の質問と検証ヒューリスティックを解析します

3.2 testing-strategy.md のセクションを検証する：

このファイルでは、標準テンプレートの内容を使用します（自動検出は不要です）。

1. テストの理念セクション：

   • セクションの内容を読み込みます
   • questions.md の検証ヒューリスティックを確認します：
     • ✅ 「リスクベーステスト」に言及している
     • ✅ テストピラミッドの説明がある
     • ✅ 優先度のしきい値（≥15）に言及している
     • ✅ ストーリーレベルのテストタスクパターンを参照している
     • ✅ 100 語を超えている
   • いずれかのヒューリスティックに合致する場合 → 内容は有効です
   • すべてに合致しない場合 → 警告を記録します：「⚠️ testing-strategy.md → テストの理念セクションの確認が必要な可能性があります」

2. テストレベルセクション：

   • セクションの内容を読み込みます
   • questions.md の検証ヒューリスティックを確認します：
     • ✅ 3 つのレベル（E2E、統合、単体）を列挙している
     • ✅ 数値の範囲（2-5、3-8、5-15）がある
     • ✅ 理由を説明している
     • ✅ 150 語を超えている
   • いずれかのヒューリスティックに合致する場合 → 内容は有効です
   • すべてに合致しない場合 → 警告を記録します：「⚠️ testing-strategy.md → テストレベルセクションの確認が必要な可能性があります」

注：testing-strategy.md は汎用的な理念を扱うため、プロジェクト固有の自動検出は不要です。

3.3 自動検出を使用して tests/README.md のセクションを検証する：

セクション：テストの構成

1. テストフレームワークの自動検出:

   • package.json の「devDependencies」と「dependencies」を確認します:
     • Node.js フレームワーク: jest、vitest、mocha、ava、tap、jasmine
     • 見つかった場合: 名前とバージョンを抽出します
   • requirements.txt を確認します（Python プロジェクトの場合）:
     • Python フレームワーク: pytest、nose2、unittest2
     • 見つかった場合: 名前とバージョンを抽出します
   • go.mod を確認します（Go プロジェクトの場合）:
     • Go は組み込みの testing パッケージを使用します
   • フレームワークが検出された場合:
     • ログ: 「✓ テストフレームワークを検出しました: [framework]@[version]」
     • 記録: framework_detected = "[framework]"
   • 検出されなかった場合:
     • ログ: 「⚠️ テストフレームワークが検出されませんでした。汎用的なテスト構成を使用します。」
     • 記録: framework_detected = None

2. テストディレクトリ構造の自動検出:

   • Glob ツールを使用して tests/ ディレクトリをスキャンします:
     • パターン: "tests/automated/e2e/**/*.{js,ts,py,go}"
     • パターン: "tests/automated/integration/**/*.{js,ts,py,go}"
     • パターン: "tests/automated/unit/**/*.{js,ts,py,go}"
   • 各ディレクトリ内のファイル数をカウントします:
     • e2e_count = len(e2e_files)
     • integration_count = len(integration_files)
     • unit_count = len(unit_files)
   • ディレクトリが存在する場合:
     • ログ: 「✓ テスト構造: [e2e_count] E2E、[integration_count] Integration、[unit_count] Unit テスト」
   • ディレクトリが存在しない場合:
     • プレースホルダー構造を作成します:

       tests/
         automated/
           e2e/         (empty, ready for E2E tests)
           integration/ (empty, ready for Integration tests)
           unit/        (empty, ready for Unit tests)
       

     • ログ: 「✓ テストディレクトリ構造を作成しました（Story テストタスクの実行中に内容が追加されます）」

3. 命名規則の自動検出:

   • 見つかった各テストファイル（ステップ 2 から）について:
     • ファイル名のパターンを抽出します:
       • *.test.js → 「*.test.js」規則
       • *.spec.ts → 「*.spec.ts」規則
       • test_*.py → 「test_*.py」規則
       • *_test.go → 「*_test.go」規則
   • 各パターンの出現回数をカウントします
   • 最も一般的なパターンを使用します（多数決）
   • パターンが検出された場合:
     • ログ: 「✓ 命名規則: [pattern]（[count] ファイルから検出）」
   • ファイルが存在しない場合:
     • フレームワークのデフォルトを使用します:
       • Jest/Vitest → *.test.js
       • Mocha → *.spec.js
       • Pytest → test_*.py
       • Go → *_test.go
     • ログ: 「✓ 命名規則: [default_pattern]（フレームワークのデフォルト）」

4. Test Organization セクションの内容を確認:

   • tests/README.md からセクションを読み取ります
   • 検証のヒューリスティックを確認します:
     • ✅ ディレクトリ構造（tests/automated/e2e、tests/automated/integration、tests/automated/unit）を説明している
     • ✅ 命名規則に言及している
     • ✅ Story-Level Test Task Pattern を参照している
     • ✅ フレームワークへの言及がある
   • いずれかのヒューリスティックを満たす場合 → 内容は有効
   • すべて失敗した場合 → 警告をログ: 「⚠️ tests/README.md → Test Organization セクションの更新が必要です」

セクション: テストの実行

1. テストランナーコマンドの自動検出:

   • package.json → 「scripts」→ 「test」を読み取ります
   • 見つかった場合:
     • コマンドの値を抽出します
     • 例:
       • "jest" → テストランナー: 「npm test」（jest を実行）
       • "vitest" → テストランナー: 「npm test」（vitest を実行）
       • "mocha" → テストランナー: 「npm test」（mocha を実行）
       • カスタムスクリプト → テストランナー: 「npm test」（[custom] を実行）
     • ログ: 「✓ テストランナー: npm test（[command] を実行）」
   • 見つからなかった場合（package.json がない、または test スクリプトがない）:
     • 検出されたフレームワーク（ステップ 3.3.1 から）に基づいてデフォルトを使用します:
       • Jest → 「npm test」
       • Vitest → 「npm test」
       • Pytest → 「pytest」
       • Go → 「go test ./...」
     • ログ: 「⚠️ package.json にテストスクリプトが見つかりませんでした。デフォルトの「[command]」を使用します。」

2. カバレッジコマンドの自動検出（任意）：

   • package.json → "scripts" を確認し、次を探します：
     • "test:coverage"
     • "coverage"
     • "test:cov"
   • 見つかった場合：
     • コマンドを抽出します
     • ログに記録します："✓ カバレッジコマンド：npm run [script_name]"
   • 見つからない場合：
     • フレームワークのデフォルトを使用します：
       • Jest → "npm test -- --coverage"
       • Vitest → "npm test -- --coverage"
       • Pytest → "pytest --cov=src"
       • Go → "go test -cover ./..."
     • ログに記録します："✓ カバレッジコマンド：[default]（フレームワークのデフォルト）"

3. テストの実行セクションの内容を確認：

   • tests/README.md からセクションを読み取ります
   • 検証ヒューリスティックを確認します：
     • ✅ テストランナーのコマンドがある
     • ✅ カバレッジに言及している
     • ✅ 特定のテストの実行方法を示している
     • ✅ コマンド例がある
   • ヒューリスティックのいずれかに合致した場合 → 内容は有効です
   • すべてに合致しない場合 → 警告をログに記録します："⚠️ tests/README.md → テストの実行セクションを更新する必要があります"

3.4 内容の検証結果を報告：

• 概要をログに記録します：

  ✅ Content validation complete:
    - testing-strategy.md: [2 sections checked]
    - tests/README.md: [2 sections checked]
    - Test framework: [detected framework or "Not detected"]
    - Test structure: [automated/e2e, automated/integration, automated/unit counts or "Created placeholder"]
    - Naming convention: [pattern or "Framework default"]
    - Test runner: [command]
    - Coverage command: [command]
  

---

出力構成の全体

docs/reference/guides/
└── testing-strategy.md           # Universal testing philosophy (465 lines)

tests/
└── README.md                     # Test organization + Story-Level Pattern (112 lines)

注：実際のテストディレクトリ（e2e/、integration/、unit/）は、Story のテストタスクの実行時、または存在しない場合は Phase 3 で作成されます。

---

重要なルール

• ドキュメントのみ： このスキルが作成するのはテストのドキュメントであり、実際のテストコードではありません
• 3 フェーズのパイプライン： 作成 → 構造を検証 → 内容を検証（フェーズを省略しない）
• まず自動検出： デフォルトにフォールバックする前に、テストフレームワークとディレクトリ構成をスキャンします
• 冪等な実行： 作成前に存在を確認し、重複させずに実行のたびに再検証します
• 共通の冒頭の契約が必須： 両方のファイルに SCOPE、メタデータマーカー、Quick Navigation、Agent Entry、Maintenance を含める必要があります

---

参照ファイル

• リスクベースのテスト手法： references/risk_based_testing_guide.md

テンプレート

テスト戦略テンプレート：

• references/templates/testing_strategy_template.md - 次の内容を含む、汎用的なテストの考え方：
  • SCOPE タグ（テストの考え方。特定のフレームワークに依存しない）
  • 基本理念（「フレームワークではなく、自分のコードをテストする」）
  • リスクベースのテスト戦略（優先度マトリックス、テスト上限）
  • Story レベルのテストパターン
  • テストの整理（tests/automated/e2e、tests/automated/integration、tests/automated/unit の定義）
  • 分離パターン（データ削除／トランザクションのロールバック／DB の再作成）
  • テストする対象とテストしない対象（汎用的な例）
  • テストパターン（Arrange-Act-Assert、境界でのモック、テストデータビルダー）
  • よくある問題（不安定なテスト、遅いテスト、テスト間の結合）
  • カバレッジのガイドライン
  • 検証チェックリスト

Tests README テンプレート：

• references/templates/tests_readme_template.md - 次の内容を含む、テストの整理に関する説明：
  • SCOPE タグ（テストドキュメントのみ）
  • 概要（E2E／統合／ユニットテストの構成）
  • テストの考え方（簡潔な説明、testing-strategy.md へのリンク）
  • テスト構成（ディレクトリツリー）
  • Story レベルのテストタスクパターン（テストは最後の Story タスクに含め、分散させない）
  • テストの実行（プロジェクト固有のコマンド）
  • クイックナビゲーション（testing-strategy.md、kanban_board、ガイドラインへのリンク）
  • 保守セクション（更新のきっかけ、検証、最終更新日）

検証仕様：

• references/questions.md (v1.0.0) - 質問に基づく検証：
  • 各セクションで回答する必要がある質問（全 4 セクション）
  • 検証ヒューリスティック（いずれかに合致すれば有効）
  • 自動検出のヒント（テストフレームワーク、ディレクトリ構成、命名規則）
  • MCP Ref のヒント（必要に応じた外部調査）

---

ベストプラクティス

• 早すぎる検証を行わない：フェーズ 1 で構造を作成し、フェーズ 2 で検証します（重複チェックは行いません）
• パラメーター化された検証：フェーズ 3 では、2 つのファイルにまたがる 4 つのセクションを検証します（コードの重複はありません）
• まず自動検出：デフォルトを使用する前に、テストフレームワークとディレクトリ構造をスキャンします
• 冪等性：✅ 安全に複数回実行できます（作成前に存在を確認し、実行ごとに再検証します）
• 関心の分離：作成 → 構造の検証 → コンテンツの検証
• ストーリーレベルのテストタスクパターン：テストは最後のストーリータスクに集約します（テストプランナーがタスクを作成し、テスト実行者が実装します）
• 価値に基づくテスト：優先度が 15 以上の場合は必ずテストし、各テストを有用性の基準に照らして正当化します
• テストコードなし：このスキルが作成するのはドキュメントのみで、実際のテストは作成しません

ドキュメントの基準

• **NO_CODE ルール：**テストドキュメントでは、テストの実装ではなくテスト戦略を説明します
• **スタックへの適応：**フレームワークのコマンドはプロジェクトのスタックに合わせる必要があります
• **形式の優先順位：**表（テストレベル、件数）＞ リスト ＞ テキスト
• **共通の docs-quality 契約：**SCOPE タグ、メンテナンスセクション、プレースホルダーポリシー、およびスタック固有のリンク検証には、共通の docs-quality 契約／ルールが適用されます

---

前提条件

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

必要なもの：

• docs/reference/guides/ ディレクトリ（ln-120-reference-docs-creator、または存在しない場合はフェーズ 1 で作成）

作成するもの：

• docs/reference/guides/testing-strategy.md（汎用的なテストの考え方）
• tests/README.md（テストの構成）
• 検証済みの構造とコンテンツ（テストフレームワークとディレクトリ構造の自動検出）

---

戻り値の契約

ln-100 が一元化された docs-quality ゲートを実行できるよう、正規化された概要を返します。

{
  "created_files": [
    "docs/reference/guides/testing-strategy.md",
    "tests/README.md"
  ],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": [
      "docs/reference/guides/testing-strategy.md",
      "tests/README.md"
    ],
    "owners": {
      "docs/reference/guides/testing-strategy.md": "ln-140-test-docs-creator",
      "tests/README.md": "ln-140-test-docs-creator"
    }
  },
  "validation_status": "passed|passed_with_fixes|skipped"
}

---

実行時の概要アーティファクト

必須の読み込み：references/docs_generation_summary_contract.md を読み込みます

任意の summaryArtifactPath を受け付けます。

概要の種類：

• docs-generation

必須のペイロードの意味：

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

概要は、指定されたアーティファクトパスに書き込むか、構造化出力で同じエンベロープを返します。

完了の定義

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

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

• docs/reference/guides/ ディレクトリが存在する
• tests/ ディレクトリが存在する
• tests/manual/ ディレクトリが存在する
• tests/manual/results/ ディレクトリが存在する
• tests/manual/results/ が .gitignore に追加されている
• testing-strategy.md が存在する（作成済み、または既存）
• tests/README.md が存在する（作成済み、または既存）

✅ 構造の検証（フェーズ 2）：

• 両方のファイルの先頭 5 行以内に SCOPE タグがある
• testing-strategy.md に「テストの考え方」と「テストレベル」のセクションがある
• tests/README.md に「テストの構成」と「テストの実行」のセクションがある
• 両方のファイルの末尾にメンテナンスセクションがある
• POSIX ファイル終端の要件に準拠している（LF、EOF に空行が 1 行）

✅ コンテンツの検証（フェーズ 3）：

• testing-strategy.md → 「テストの考え方」セクションを確認済み（リスクベーステストへの言及）
• testing-strategy.md → 「テストの有用性基準」セクションを確認済み
• tests/README.md → 「テストの構成」セクションを確認済み、または自動検出済み
• tests/README.md → 「テストの実行」セクションを確認済み、または自動検出済み
• テストフレームワークを検出し（該当する場合）、記録済み
• テストディレクトリ構造をスキャン、または作成済み
• 命名規則を検出、またはデフォルトを使用済み
• テストランナーのコマンドを特定、またはデフォルトを使用済み

✅ レポート：

• フェーズ 1 を記録済み：作成の概要
• フェーズ 2 を記録済み：構造上の修正（該当する場合）
• フェーズ 3 を記録済み：自動検出の結果を含むコンテンツ検証の概要
• created_files、skipped_files、quality_inputs、validation_status を含む戻り値の契約を出力済み

---

技術詳細

規格：

• ストーリーレベルのテストタスクパターン
• リスクベーステスト（優先度 ≥15、有用性の基準）

言語：英語のみ

自動検出のサポート：

• Node.js：jest、vitest、mocha、ava、tap、jasmine
• Python：pytest、nose2、unittest2
• Go：標準の testing パッケージ

---

バージョン： 7.2.0 最終更新日： 2026-01-15