fstack-document

/fstack-document

現在のプロジェクトに関するドキュメントを .md ファイルに書き出します。構成は 3 つのレイヤーです。平易な英語による概要、仕組みの説明、そしてより詳細なリファレンスです。一度実行するとドキュメントが作成されます。もう一度実行すると、現在のコードに合わせてドキュメントが更新されます。

使用する場面

• プロジェクトにドキュメントがほとんど、またはまったくない。
• ドキュメントは存在するが、コードから乖離している。
• ユーザーが /fstack-document を呼び出した。

手順

1. プロジェクトを読み取ります。構造、エントリーポイント、主要なモジュール、データモデル、設定、および実行とテストの方法を確認します。
2. docs/ にすでに fstack のドキュメント一式（以下の 3 ファイル）があるかどうかを確認します。
   • ない場合 — 作成モード。
   • ある場合 — 更新モード。プロジェクトを再度読み取り、既存のドキュメントと比較し、コードが変わった部分だけを変更します。今も有効な人間による編集はそのまま残します。ゼロから書き直してはいけません。
3. 以下の 3 ファイルを、平易なものから詳細なものへと書き出すか、更新します。
   • docs/overview.md — ELI5。 このプロジェクトが何であり、何を行い、誰のためのものかを、専門家でない人にもわかる言葉で書きます。専門用語は使いません。
   • docs/architecture.md — 仕組み。 主要な構成要素、それらがどう組み合わさるか、データがどう流れるか、それを形作った決定事項。
   • docs/reference.md — 詳細。 ディレクトリと主要なファイル、設定と環境、実行・テスト・ビルドの方法。
4. 書いた内容、または変更した内容の短い要約を示します。更新モードでは、何を追加し、何を改訂し、コードから削除されたように見えるものがあればそれを伝えます。

同期を保つ

• ドキュメントは現在のコードに合わせます。git の履歴や変更履歴に合わせるのではありません。
• ドキュメントが言及しているファイル、モジュール、機能がもう存在しない場合は、それを指摘し、その部分を削除します。
• ドキュメントが漏らしている新しいものが存在する場合は、適切なレイヤーに追加します。

してはいけないこと

• 多数のファイルに散らばらせること。3 つのレイヤー、3 つのファイルです。あるセクションが巨大に膨れ上がるなら、それはプロジェクト自体が複雑すぎるかもしれないというサインです。
• 挙動をでっち上げること。コードがどうあるべきかではなく、コードが何をするかをドキュメント化します。不明な点があれば、推測せずにその旨を書きます。
• コードが変わっていないドキュメントを書き直すこと。更新モードは動いた部分だけに触れます。
• シークレットを含めること。キー、トークン、.env の値を含めません。

例

ユーザー: /fstack-document

エージェント: 「まだ docs/ がないので、一式を作成します。3 つのファイルを書きました:

• docs/overview.md — このアプリが何かを平易な言葉で。
• docs/architecture.md — Astro のページ、Convex バックエンド、認証フロー。
• docs/reference.md — ディレクトリマップ、環境変数、実行・テスト・ビルドのコマンド。 ざっと目を通しますか?」

ユーザー: /fstack-document (1 週間後)

エージェント: 「ドキュメントが存在します — 更新モードです。変更点: 新しい /api/export ルートを architecture と reference に追加しました。認証セクションを改訂しました — セッションからマジックリンクに移行しています。ドキュメントが言及していた themes モジュールはコードから消えていたので、その段落を削除しました。」