ln-115-devops-docs-creator

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

DevOps ドキュメント作成ツール

タイプ： L3 ワーカー

infrastructure.md と runbook.md を作成する L3 ワーカーです。インフラストラクチャのインベントリは常に作成し、runbook は Docker の有無に応じて作成します。

目的と範囲

• infrastructure.md を作成します（常時）。宣言型のインベントリであり、何がどこにデプロイされているかを記載します
• runbook.md を作成します（hasDocker の場合）。デプロイ、再起動、トラブルシューティングの方法を記載する手順書です
• ln-110-project-docs-coordinator から Context Store を受け取ります
• 自身ではコンテキストを収集せず、コーディネーターからの入力を使用します

呼び出し（誰が／いつ）

• ln-110-project-docs-coordinator： 必ず呼び出されます（infrastructure.md は無条件で作成）
• ユーザーから直接呼び出されることはありません

入力

コーディネーターから：

• contextStore：DevOps 固有のデータを含む Context Store
  • DOCKER_COMPOSE_DEV（開発環境のセットアップ）
  • DOCKER_COMPOSE_PROD（本番環境のセットアップ）
  • ENV_VARIABLES（.env.example から取得）
  • STARTUP_SEQUENCE（サービスの起動順序）
  • DEPLOYMENT_TARGET（AWS、Vercel、Heroku）
  • CI_CD_PIPELINE（.github/workflows から取得）
  • DOCKER_SERVICES（docker-compose.yml のサービスから解析）
  • DEPLOYMENT_SCALE（"single" | "multi" | "auto-scaling" | "gpu-based"）
  • DEVOPS_CONTACTS（CODEOWNERS、package.json の author、git log から取得）
  • HAS_GPU（docker-compose の nvidia runtime から検出）
  • SERVER_INVENTORY（SSH 設定、デプロイ先から取得）
  • DOMAIN_DNS（docker-compose の VIRTUAL_HOST 変数、nginx 設定から取得）
  • ARTIFACT_REPOSITORY（.env のレジストリ URL、.npmrc、pip.conf から取得）
  • HOST_REQUIREMENTS（docker-compose の deploy.resources.limits から取得）
• targetDir：プロジェクトのルートディレクトリ
• flags：{ hasDocker }

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

作成するドキュメント（2 件：常時 1 件＋条件付き 1 件）

ファイル	条件	質問	自動検出
docs/project/infrastructure.md	常時	Q52-Q55	中
docs/project/runbook.md	hasDocker	Q46-Q51	高

ワークフロー

フェーズ 1：条件の確認

1. コーディネーターからフラグを解析します
2. infrastructure.md：常に作成を進めます（条件確認なし）
3. runbook.md：hasDocker=true の場合にのみ作成します
4. 対象ファイルがすでに存在する場合は、そのファイルをスキップします（冪等）

フェーズ 2a：infrastructure.md の作成（無条件）

1. docs/project/infrastructure.md が存在するか確認します
2. 存在する場合：ログを記録してスキップします
3. 存在しない場合：
   • references/templates/infrastructure_template.md をコピーします
   • プレースホルダーを Context Store の値に置き換えます
   • テンプレートの共通の冒頭契約と標準的な上部セクションを維持します
   • SERVER_INVENTORY から Server Inventory を記入します
   • DOCKER_SERVICES のポートマッピングから Port Allocation を記入します
   • DOCKER_SERVICES から Deployed Services を記入します
   • CI_CD_PIPELINE から CI/CD Pipeline を記入します
   • 公開するインフラストラクチャのドキュメントに、テンプレートのマーカーを残してはいけません
   • データが不足している場合は、その記述を省略するか、簡潔で中立的な代替文を使用します。ただし、[TBD: ...] は出力しないでください
4. 条件付きセクションの削除：
   • CI/CD が検出されない場合は、[TBD: ...] ではなく、簡潔な空状態の注記に置き換えます
   • ARTIFACT_REPOSITORY がない場合は、[TBD: ...] ではなく、簡潔な空状態の注記に置き換えます
   • サーバーが 1 台の場合、または SERVER_INVENTORY がない場合は、1 列の表に簡略化します
   • !HAS_GPU の場合は、Server Inventory と Deployed Services から GPU 列を削除します
   • Deployed Services は DOCKER_SERVICES からのみ記入します（一般的な例は使用しません）

フェーズ 2b：runbook.md の作成（条件付き）

1. !hasDocker の場合：完全にスキップします
2. docs/project/runbook.md が存在するか確認します
3. 存在する場合：ログを記録してスキップします
4. 存在しない場合：
   • references/templates/runbook_template.md をコピーします
   • Context Store の値でプレースホルダーを置き換えます
   • テンプレートの共通冒頭契約と標準のトップセクションを維持します
   • package.json のスクリプトからセットアップ手順を設定します
   • .env.example から環境変数を抽出します
   • 公開するランブックにテンプレートのマーカーを残さないでください
   • データが不足している場合：該当する記述を省略するか、簡潔で中立的な代替表現を使用し、[TBD: ...] は出力しないでください
5. 条件付きセクションの削除：
   • DEPLOYMENT_SCALE が "multi" または "auto-scaling" でない場合：スケーリング／ロードバランサーのセクションを削除します
   • !HAS_GPU の場合：GPU 関連のセクション（nvidia runtime、CUDA）を削除します
   • サービスが DOCKER_SERVICES に含まれていない場合：そのサービスの例を削除します
   • DEVOPS_CONTACTS が空の場合：[TBD: ...] ではなく、簡潔な空状態の注記に置き換えます
   • サービスの依存関係は DOCKER_SERVICES の情報のみを使用して設定します
   • ポートマッピングは docker-compose.yml の ports セクションの情報のみを使用して設定します

フェーズ 3：自己検証

infrastructure.md の場合：

1. SCOPE タグとメタデータマーカーを確認します
2. 必須のトップセクション（Quick Navigation、Agent Entry、Maintenance）を確認します
3. 次のセクションを検証します：サーバー一覧、ポート割り当て、デプロイ済みサービス
4. 手順の内容が混入していないことを確認します（runbook.md に記載する内容です）
5. docs-quality 契約への準拠を確認します（禁止されているプレースホルダー、漏れたテンプレートメタデータがないこと、ドキュメントの種類／役割が有効であること）

作成した場合の runbook.md：

1. SCOPE タグとメタデータマーカーを確認します
2. 必須のトップセクション（Quick Navigation、Agent Entry、Maintenance）を確認します
3. 次のセクションを検証します：ローカル開発環境のセットアップ、デプロイ、トラブルシューティング
4. 環境変数が記載されていることを確認します
5. docs-quality 契約への準拠を確認します（禁止されているプレースホルダー、漏れたテンプレートメタデータがないこと、ドキュメントの種類／役割が有効であること）

フェーズ 4：ステータスの返却

{
  "created_files": ["docs/project/infrastructure.md", "docs/project/runbook.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/project/infrastructure.md", "docs/project/runbook.md"],
    "owners": {
      "docs/project/infrastructure.md": "ln-115-devops-docs-creator",
      "docs/project/runbook.md": "ln-115-devops-docs-creator"
    }
  },
  "validation_status": "passed"
}

重要な注意事項

基本ルール

• infrastructure.md： 条件なしで常に作成します
• runbook.md： hasDocker を条件として作成します
• 広範な自動検出： ほとんどのデータは docker-compose.yml、.env.example、package.json、SSH 設定から取得します
• 再現可能： セットアップ手順はテスト可能かつ再現可能でなければなりません
• 冪等： 既存のファイルを上書きしないでください
• 公開可能な出力： DevOps ドキュメントに [TBD: ...]、TODO、漏れたテンプレートメタデータを含めないでください

NO_CODE_EXAMPLES ルール（必須）

どちらのドキュメントも一覧／手順を説明するものであり、実装を説明するものではありません：

• 禁止： Docker 設定全体、CI/CD パイプライン（5 行超）、nginx 設定全体
• 許可： コマンド例（1～3 行）、環境変数の表、手順リスト、検証コマンド
• コードの代わりに： 「docker-compose.yml を参照してください」

スタック適応ルール（必須）

• コマンドはプロジェクトのスタック（npm、pip、go など）に合わせる必要があります
• 適切なクラウドプロバイダーのドキュメント（AWS／Azure／GCP）にリンクします
• スタックの参照を混在させないでください（Python プロジェクトで npm コマンドを使わないでください）

形式の優先順位（必須）

表（環境変数、ポート、サービス、サーバー）＞リスト（セットアップ手順）＞テキスト

実行時サマリー成果物

必ず読み込む： references/docs_generation_summary_contract.md

summaryArtifactPath は任意で指定できます。

サマリーの種類：

• docs-generation

必須のペイロード意味：

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

指定された成果物パスにサマリーを書き込むか、構造化出力で同じエンベロープを返してください。

完了の定義

• infrastructure.md を作成済み（常に）
• hasDocker の場合に runbook.md を作成済み
• Infrastructure：サーバー一覧、ポート、サービスを記載済み
• Runbook：セットアップ手順、デプロイ、トラブルシューティングを記載済み
• .env.example のすべての環境変数を runbook に含めている
• 実際の情報を確認済み： すべてのドキュメントの事実が現在のコードと一致している（パス、関数、API、設定が存在し、正確である）
• ステータスを返却済み

Reference Files

• Templates: references/templates/infrastructure_template.md, references/templates/runbook_template.md
• Questions: references/questions_devops.md (Q46-Q51 runbook, Q52-Q55 infrastructure)

---

Version: 2.0.0 Last Updated: 2025-01-12