dido-platform-docs-writer

リポジトリの運用ドキュメント

プロジェクトを動かすためのマニュアルです。ローカルでの起動、本番環境へのデプロイ、問題が起きたときの原因の把握を扱います。読者は評価する人ではなく、保守する人です。プロジェクトがスケーラブルであることを知る必要はありません。必要なのは、正確なコマンドと正確な変数です。

黄金律：リポジトリ内のファイルで裏付けられることだけを記載します。 運用に関する記述（ポート、変数、コマンド、ドメイン、デプロイ手順）は、すべて具体的なファイルにたどれる必要があります。たどれない場合は NON DEDUCIBILE とし、これは正当で、よくある結果です。検証済みのセクションが10個あり、3個に「NON DEDUCIBILE」と記されたREADMEは、半分が作り話のREADMEよりもはるかに価値があります。6か月後もこのドキュメントの信頼性を保つ唯一の方法です。

ひとつの事実は、ひとつの場所に。 このドキュメントには、ファイルだけではわからないことを記載します。手順（必要なコマンドやURLを含む、起動、更新、修復の方法）、決定事項とその理由、各サービスの役割、不足しているものです。それ以外は情報源を参照します。ポート、バージョン、変数、イメージ、ボリュームはそれぞれのファイルに記載し、ドキュメントではどのファイルかを示します。ファイルですでに定義されている内容を再掲する表、リスト、図は複製です。書いた当日は正しくても、最初の変更が入った時点で古くなります。そのため、既存ドキュメント内で複製を見つけたら、まだ正しくても削除し、代わりに参照先を記載します。

使用しない場合

• 製品ドキュメントやエンドユーザー向けドキュメント：アプリケーションを使う人向けのガイドであり、動かす人向けではありません。目的も文体も異なります。
• コードから生成できるAPIリファレンス（OpenAPI、docstring、typedoc）：そこでは手書きせずに生成します。手書きすると、別の真実を作り、内容が食い違う原因になります。
• 読むことができなかったリポジトリ：URL、スクリーンショット、またはユーザーから口頭で説明された内容しかない場合です。ファイルがなければ推測できることは何もありません。そのことを伝えて作業を止め、内容を再構成しないでください。
• アーキテクチャや技術スタックの選定：このスキルでは現状を記述し、あるべき姿を提案しません。調査中に問題（バージョン管理されたシークレット、ヘルスチェックのないサービス、どこにも定義されていないホストを参照するスクリプト）が見つかった場合は、ドキュメント末尾の「確認事項」に記録して作業を続けます。マニュアルをレビューに変えてはいけません。
• 軽微な変更（コマンドの修正、参照先の更新）：その変更だけを行います。ここに記載されたワークフロー全体は不要です。

目標

• プロジェクトの作成者に何も尋ねずに、初めての人でも起動できるようにします。
• ローカル開発と本番環境を常に区別し、それぞれで誰が何を管理するかを説明します。
• リポジトリから実際に確認できた構成（オーケストレーター、プロキシ、デプロイエンジン、変数管理ツール）を、その正式名称で記載します。リポジトリがCoolifyとTraefikを使っているならCoolifyとTraefikと記載します。Kubernetes、Fly.io、または systemd のユニットを使っているなら、それらを記載します。想定される技術スタックはありません。
• 運用上の障害を未然に防ぎます。扱いにくい前提条件、サービス間の依存関係、よくあるエラーを記載します。

文体の制約

• すべての文は、プロジェクトの起動、更新、修復を行う人のために書きます。サービスが1つか2つの場合、READMEは約1,000語を目安とし、1,500語を超えないようにします。サービスが複数ある場合は全体像にとどめ、詳細はサービスごとのドキュメントに記載します。
• 読者が開く必要のあるファイルは、ファイル名だけで参照します。行番号は記載しません。行番号は変更のたびにずれるためです。行ごとの確認はゲートが行い、ドキュメントでは行いません。
• 文は短くし、通常の句読点を使います。段落内の長ダッシュは最大1つにし、用語とその説明の間にはコロンを使います。
• 「強力」「スケーラブル」「モダン」など、測定できない形容詞は使いません。値またはコマンドでないものは、運用ドキュメントではありません。
• すべてのコマンドは、コピーして使える完全な形で bash ブロックに記載します。文章中に断片的に記載しません。
• 環境間の比較は、段落ではなく必ず表にまとめます。
• 指示には命令形と二人称を使います（「起動する」「確認する」など）。条件法は使いません。

ステップ1. 調査（インベントリも成果物に含めます）

ファイルを読む前に、1行も書いてはいけません。読んだ内容をそのまま回答に貼り付けてはいけませんが、何を読んだかは必ず明記してください。インベントリはドキュメントの根拠となるものであり、ドキュメントと一緒に提出します。調査の記録がなければ、調査を行わなかった場合と区別できません。

調べる項目	場所	確認できる内容
スタックとランタイム	package.json、pyproject.toml、go.mod、composer.json、ロックファイル	言語、バージョン、定義済みのスクリプト
オーケストレーション	Dockerfile*、compose*.y*ml、オーバーライド、チャート、マニフェスト	サービス、内部ポート、ボリューム、依存関係、起動コマンド
設定	.env.example、config/、settings.*	変数、必須項目、デフォルト値の有無
自動化	Makefile、justfile、scripts/、.github/workflows/	実際のコマンド、CIで実行される内容、手動で行う作業
ネットワークと公開設定	プロキシのラベル、nginx.conf、リバースプロキシの設定、Ingress	TLSを終端する箇所、ルーティング、ホスト
履歴	現在のREADME、CHANGELOG、docs/	以前は正しかった内容。検証が必要であり、そのまま採用してはいけません

調査の最後に次の行を記載し、回答の冒頭に置きます。

Discovery: N file letti. Stack {…}, servizi {…}, deploy {…}. Non trovato: {elenco}.

ある項目をカバーするファイルがない場合（CI、プロキシ、バックアップなどがない場合）、それ自体が情報であり、補って埋めるべき不足ではありません。non trovato に記載し、そこから「推論不可」のセクションに反映します。リポジトリを読めない場合（URL、スクリーンショット、またはユーザーの説明しかない場合）は、そこで止めてその旨を伝えてください。ファイルがなければ、推論できることは何もありません。

判定結果とゲート

運用に関する各記述には、次の3つの判定結果のいずれかがあります。

判定結果	該当する場合	ドキュメントでの記述方法
Documentato	それを証明するファイルがある	通常のテキスト
PARZIALE	ファイルに仕組みは記載されているが、値は記載されていない（変数はあるが、値はない）	テキスト＋注記 da confermare: {cosa}
NON DEDUCIBILE	それを証明するファイルがない	明示的なブロック。もっともらしい文章は決して書かない

必須のブロック形式。以下をそのままコピーしてください。

NON DEDUCIBILE — {argomento}. リポジトリには、{cosa}を記述したファイルがありません。 確認したファイル：{elenco}。このセクションを完成させるには、{chi o cosa può fornirlo}が必要です。

提出前のゲート。 これは推奨事項ではなく、完了条件です。

1. 記述した各コマンドは、リポジトリ内のファイルに記載されているか、そこに記載された要素を組み合わせたものです。
2. 記載した各変数は、.env.example、compose、またはコード内に存在します。
3. ドキュメントに記載したすべてのポート、ホスト、パスは、記憶ではなくファイルに基づいています。
4. 要求されているものの、ファイルで裏付けられない各セクションには、NON DEDUCIBILE ブロックがあります。
5. トラブルシューティングの各項目は、実際にリポジトリ内に存在するコンポーネントに関するものです。
6. 表、リスト、図に、ファイルですでに定義されている内容（ポート、バージョン、変数、イメージ、ボリューム）を再掲していません。代わりにファイル名を記載しています。

最後に次の行を記載してください：Gate: X affermazioni riviste, Y declassate a NON DEDUCIBILE. Y = 0 で、あなたが作成したのではないリポジトリの場合は、ポート、バージョン、デプロイ、バックアップなど、思い込みやすい記述を再確認してください。すべてに裏付けとなるファイルがあるなら、Y = 0 は妥当な結果です。

典型的な合理化と必須の対応

考えていること	対応
「Postgres ならポートは 5432」	ポートを公開しているファイルを参照します。なければ：NON DEDUCIBILE。
「変数とポートの表があると読みやすい」	.env.example と compose のコピーにすぎず、最初の変更ですぐに古くなります。ファイルを参照します。
「このようなプロジェクトならバックアップがあるはず」	NON DEDUCIBILE。バックアップがないこと自体が指摘事項です。
「一般的な TLS セクションを書いておけば、後で修正してくれる」	誰も修正しません。もっともらしい文章は、何も書かないより悪いものです。
「ユーザーはパイプラインのセクションを求めている」	セクションは記述しますが、その内容は NON DEDUCIBILE ブロックにします。
「古い README にはそう書いてある」	ファイルのコピーであれば削除し、ファイルを参照します。それ以外の記述は、現在のコードで確認できた場合に限り有効です。確認できなければ、その旨を報告します。
「このフレームワークの標準コマンドは……」	規範は、このリポジトリではありません。
「このセクションがないと README が不完全に見える」	不完全なのはリポジトリであり、README にはそのことを記載する必要があります。

ユーザーから NON DEDUCIBILE ブロックの削除を求められた場合は、拒否し、それらがドキュメントの有効範囲を示すものだと説明してください。最後に「未完了」というセクションを設けてまとめることはできますが、削除してはいけません。

ドキュメントの構成

reference/struttura-documenti.md にある構成は一覧であり、すべてを埋めるための目次ではありません。次のいずれかに該当する場合に限り、セクションをドキュメントに記載します。

• Discovery で見つかった場合 → 実際の値を使い、該当するファイルを引用して記載します。
• ユーザーが明示的に求めたものの、Discovery で見つからなかった場合 → NON DEDUCIBILE ブロックのみを含むセクションを記載します。

誰からも求められておらず、ファイルにも裏付けられていないセクションは記載しません。その不在は「未完了項目」に記録し、一般的な文章で埋めないでください。

違いの例です。.env.example に BACKUP_DIR= があるものの、リポジトリ内にそれを使うスクリプトも cron もない場合、Backup セクションは次のように記載します。

推定不可 — Backup。 .env.example に BACKUP_DIR 変数がありますが、それを使用するファイルはありません。スクリプト、compose 内のサービス、ワークフローのいずれもありません。バックアップが実行されるか、いつ実行されるか、どの保持期間が適用されるか、また誰が復元するのかは推定できません。 確認したファイル：.env.example、compose.yaml、scripts/、.github/workflows/。サーバー管理者による確認が必要です。

セクションの範囲を決めたら、reference/struttura-documenti.md を読み込み、assets/ 内のテンプレートを使ってください。テンプレートは、該当するドキュメントを作成する直前に、1つずつ使います。事前に読み込む必要はありません。

トラブルシューティング

トラブルシューティング項目は、固定リストではなく、インベントリに基づいて導き出します。 原因となるコンポーネントが確認したファイルに含まれている場合に限り、項目をドキュメントに記載します。リポジトリ内に証明書を発行するものがなければ TLS セクションは設けません。ドメインに言及するファイルがなければ DNS セクションは設けません。.env.example がなければ、変数不足によるクラッシュループの項目は設けません。コンポーネント別の一覧は reference/troubleshooting.md にあり、検出された技術（リバースプロキシ、コンテナオーケストレーター、CI/CD、データベース、サーバーアクセス）ごとに整理されています。これは項目を選ぶための一覧として使い、埋めるための目次としては使わないでください。ドキュメントには、このリポジトリで起こる可能性が最も高い項目を最大5件記載します。

リポジトリで一覧に含まれていない技術を使っている場合も、その技術のファイルから導き出した項目を記載し、回答の「一覧の更新提案」で知らせてください。黙って追加してはいけません。これらの項目をスキル側に追加するのではなく、プロジェクトのドキュメントに記載します。

成果物

環境がファイルへの書き込みに対応している場合は、ファイルを書き込んでください（README.md、docs/NOME-SERVIZIO.md、.env.example 内のコメント）。回答には要約のみを記載してください。ディスクに書き込めない場合、またはユーザーから求められた場合に限り、Markdown 全文をチャットに貼り付けます。実行環境は異なる可能性があるため、どちらの環境であるかを決めつけないでください。

回答には、次の内容をこの順番で含めます。

1. Discovery の行と Gate の行をそれぞれ1行で記載します。説明ではなく、名前と数値を記載してください。
2. 作成または変更したファイルの一覧を、パス付きで記載します。
3. 未完了項目：収集した NON DEDUCIBILE ブロックを、それぞれ誰が解決できるかと併せて記載します。
4. 確認が必要な点：リポジトリ内で見つかった、メンテナーが確認すべき問題（バージョン管理されているシークレット、healthcheck のないサービス、未定義のホストを参照するスクリプトなど）を記載します。ドキュメントには、起動を妨げる、またはデータやシークレットを漏えいさせる最も重大な問題を最大5件まで記載します。それ以外は回答にのみ記載します。
5. 一覧の更新提案：提案がある場合に記載します。

各一覧項目は1行で記載します。

既存のドキュメントを書き換えることは、その内容を削除することではありません。 README を置き換える場合は、削除したセクションとその理由（ファイルのコピー、コードとの矛盾、古くなった内容）を回答に記載してください。記述が矛盾している場合は、何が書かれていたか、またそれを否定するファイルを記載します。その記述を正しいと信じていた人が把握できるようにしてください。ファイルで裏付けられていないものの、否定もされていない運用外の内容（連絡先、合意事項、経緯、チームのメモ）は、そのまま残します。これらは推定する対象ではないため、削除する対象でもありません。