ユーザーマニュアル
エビデンスベースのMarkdownソースを User-Manual/ 配下で一元管理します。3つのエディション（エンドユーザー、管理者/オペレーター、技術リファレンス）を公開します。Markdownが成果物であり、レンダリングは別の置き換え可能なステップです。
最小限のワークフローを選択
- 新しいマニュアル: ユーザーにインタビューし、リポジトリを調査し、モジュールマップを提案して承認を得た後、承認済みのJSONモジュールファイルを使用して
scripts/init_manual.pyを実行します。 - 既存のマニュアル:
User-Manual/manual.ymlを読み取り、要求されたスコープと関連するGit差分を調査し、影響を受けるページとアセットのみを更新します。 - カバレッジ監査:
scripts/audit_manual.pyを実行し、すべてのエラーと警告を説明します。 - ビルド: 監査が成功した後にのみ
scripts/build_manual.pyを実行します。各エディションをアセンブルし、manual.ymlのrenderer.kind（markdown（デフォルト）、command、mkdocs）でレンダリングします。 - 鮮度管理: 更新後に
scripts/manual_state.py record --feature <dir>を実行します。statusは、レコード作成後に入力またはマニュアル出力が変更された場合に終了コード1を返します。
init_manual.py は、ビルド、監査、状態管理スクリプト（および出荷済みスタイルシート tools/theme/）を User-Manual/tools/ にコピーしてCIで使用できるようにします。このスキルをアップグレードした後は、その scripts/ ディレクトリからコピーを更新してください。--no-tools を指定すると、CIが別の場所からスクリプトを実行する場合にコピーをスキップします。CIワークフローは --ci-policy <file> の ci: マッピングに従います。指定がない場合は、.specify/workflow.yml が存在すればそれを参照します。
このスキルは .specify/、機能仕様、またはSpec Kitコマンドを必要としません。ユーザーのリクエスト、リポジトリの証拠、バージョン管理の変更に基づいて作業範囲を決定します。
必要なものだけをルーティング
| タスク | 参照先 |
|---|---|
| 発見とインタビュー | discovery.md |
| ページ構造とMarkdown構文 | content-model.md |
| 対象読者と言語 | audience-language.md |
| 段階的な変更 | incremental-update.md |
| エンティティ、カラム、列挙型、ER図 | data-reference.md |
| レンダラー、テンプレート、ブランド、HTML、PDF、RTL | publishing.md |
| APIドキュメント | api-docs.md |
| リリースノートと移行ガイド | release-docs.md |
| UIスクリーンショット | ui-screenshots.md |
| プレビューとリリース公開 | preview-publishing.md |
非交渉ルール
- 英語を必須とする。 アラビア語はプロジェクトごとにオプションですが、ページ、レンダラー、図、PDFは初期化時点でRTLをサポートする必要があります。
- 平易で自然な英語またはアラビア語を使用する。 指定された対象読者向けに記述し、エンドユーザー向けに技術的な説明をそのまま流用しないでください。
- 主張は実装、コントラクト、テスト、観察された動作、スキーマ、または承認されたインフラソースに基づく。 不明な点は明記し、動作を捏造しないでください。
- シークレット、認証情報、トークン、秘密鍵、接続文字列、本番記録、または編集されていない個人データを絶対に含めない。 決定論的な合成例を使用してください。
- 承認された拡張可能なモジュールマップを
User-Manual/manual.ymlに保存する。 後から発見したものは、承認されるまでproposedとして追加してください。 - Markdownを正規の形式で保ち、GitHub独自の構文を使用する。 すべてのページがGitHub上で正しく読めるようにし、ビルドが他のレンダラー向けに変換します。他のフォーマットはビルドを通じてのみ生成してください。
- **
illustrateスキルがインストールされている場合にのみ、有用な図を生成する。** システム全体の概要と、読み取り可能なモジュールレベルの詳細（システムER概要と小さなモジュールER図）は分離してください。証拠のあるすべてのエンティティ、カラム、データ型、関係、制約、列挙型を文書化してください。 - 所有マーカーの外にある手書きコンテンツを保持し、再実行時に収束させる。
- ページは、その対象読者が受け取るページにのみリンクする。 ビルドは、対象読者間のページリンクや存在しないアセットを拒否し、エディションのページが到達するアセットのみをステージングします。そのため、ある対象読者が別の対象読者のスクリーンショットやサンプルを出荷することはありません。
実例
「予約プラットフォームのマニュアルを作成する」というリクエストに対して、ルート、ナビゲーション、API、テスト、スキーマファイルから予約、顧客、支払い、運用モジュールを特定します。そのモジュールマップの承認をユーザーに求めます。その後、対象読者を考慮したチュートリアル、安全なスクリーンショット、APIとデータのリファレンス、英語コンテンツとオプションのアラビア語コンテンツを User-Manual/ 配下に作成し、プロジェクトが選択した方法（GitHub上のMarkdown、Pandocを使用したチームのWordテンプレート、またはPDF付きのMkDocsサイト）でレンダリングします。