オンボーディングドキュメントの生成

よいオンボーディングドキュメントは、新しいチームメンバーが初日にローカルでプロジェクトを実行し、どこからコードを読めばよいかを把握できるようにします。Specifyはリポジトリの構成と実行方法を根拠にオンボーディングドキュメントを生成し、コードが変わればあわせて更新します。

よいオンボーディングドキュメントの構成#

1. このプロジェクトは何か — 1段落の概要と主な構成要素
2. ローカルでの実行 — 必要なランタイムとバージョン、インストール、環境変数、実行・テストのコマンド
3. リポジトリの地図 — 主なディレクトリとエントリポイント、どこから読むとよいか
4. 開発の流れ — ブランチ戦略、レビュー、デプロイの手順
5. 困ったときの相談先 — 担当者、関連ドキュメント、よくつまずくポイント

生成する#

1. ドキュメントプロジェクトを作成する

   オンボーディング対象のリポジトリをソースとして接続し、オンボーディングガイドを作成するドキュメントスキルを選択します。

2. 重視する点を書く

   読者と目標を具体的に書きます。例：「入社1週目のバックエンド開発者が、ローカルでの実行と最初のPRまでたどり着けるように」。

3. 人が補完する

   コードからはわからない内容 — チームの合意事項、担当者、権限申請の手順 — は、生成されたドキュメントに直接追記します。

検証する#

生成されたドキュメントは、実際に手順どおりに試してみるのが最も確実な検証です。

• 新しい環境で、ドキュメントのコマンドだけでインストールと実行ができるかを確認します。
• 環境変数とシークレットは名前だけを記載し、値をドキュメントに含めていないかを確認します。
• つまずいた箇所はすぐにドキュメントに反映し、次の人が同じ場所でつまずかないようにします。