document-engine

Document Engine

Rails エンジンのドキュメントを作成またはメンテナンスするときに、このスキルを使用します。

基本的なプロセスと制約

手順	セクション	内容
1	インストール	gem の追加、bundle、インストールジェネレーターの実行 — 最小限の動作手順を最初に示します
2	ホスト側の前提条件	ホストモデル、ジョブバックエンド、認証連携に関する前提条件を明記します
3	設定	すべてのオプションとデフォルト値、必須か任意か
4	マウント	ルートに mount MyEngine::Engine, at: '/path' を明記します — 一度だけ示します
5	使用方法	一般的なワークフローでコピーして使えるコード
6	マイグレーション	インストールジェネレーター、初回セットアップ、アップグレードに影響する変更

必須条件： 生成するすべてのドキュメントは、任意のセクションに進む前に、上記の手順 1、2、3 を満たす必要があります。

README のスニペット（インストール＋マウント）：

## Installation

Add to your Gemfile:

    gem 'my_engine'

Run:

    bundle install
    rails generate my_engine:install

This creates `config/initializers/my_engine.rb`. Mount the engine in `config/routes.rb`:

    mount MyEngine::Engine, at: '/admin'

設定セクション：

## Configuration

In `config/initializers/my_engine.rb`:

    MyEngine.configure do |config|
      config.user_class = "User"       # required: host model for current user
      config.widget_count = 10         # optional, default 10
    end

拡張リソース

推奨される README の全体構成と、ドキュメントの不足項目チェックリストについては、CHECKLIST.md を参照してください。そこに記載されている重要な不足項目は、インストール手順、デフォルト値を含むすべての設定オプション、明示的なマウントパス、マイグレーションのタイミング、ホストモデル／認証に関する前提条件です。

• assets/configuration.md — 型情報、検証ルール、サポートされるすべてのデフォルト値を含む、詳細な設定オプション一覧
• assets/examples.md — 一般的なホストアプリとの連携ワークフローを網羅した、実践的なエンドツーエンドの使用例
• assets/installation.md — インストール手順とジェネレーターのリファレンス、およびインストール後に必要なセットアップ作業

出力スタイル

1. セクションは簡潔にし、タスクに重点を置きます。
2. CHECKLIST.md に照らして確認します。チェック項目は、対応するセクションにコピー可能なコード例が少なくとも 1 つあるか、明示的な説明が記載されていれば 合格 です。項目がない、不完全、または具体例がない場合は 不合格 です。不合格の項目をすべて修正し、最初から再確認してください。重要な項目がすべて合格するまで、完成としないでください。
3. セクションの明示： 必須の「必須条件」セクション（インストール、設定、ホスト側の前提条件）と「任意」セクション（拡張ポイント、使用例）を明確に表示します。
4. アップグレードに関する注意事項： アップグレードに関する注意事項のセクションには、コピーして使えるコード例を少なくとも 1 つ含めます。
5. 言語 — 明示的に別の言語を求められていない限り、英語で記述します。

避けるべき一般的な落とし穴：

• 複数のセクションに mount MyEngine::Engine ... を重複して記載しないでください。インストール／マウントの主要セクションに一度だけ記載します。
• Ruby／Rails のコード例に構文エラーがないか確認してください。ルートのマウントや認証ブロック（例：authenticate :user, ->(u) { u.admin? } do）を念入りに確認します。

連携

スキル	連携するタイミング
create-engine	ドキュメントに記載するホストアプリの契約、構造、拡張ポイント
create-engine-installer	ドキュメントに記載するインストールジェネレーター、セットアップ手順
release-engine	変更履歴、アップグレードに関する注意事項、バージョンドキュメント
generate-api-collection	API エンドポイントをドキュメント化または追加するとき（Postman コレクションとの同期を維持）