費用・発注ガイド

引き継ぎドキュメントのテンプレートと最低限書くべき内容

本番化後の引き継ぎドキュメントに最低限必要な内容をテンプレート形式で整理します。READMEから運用手順まで解説。

引き継ぎドキュメントテンプレートREADME 書き方システム引き継ぎ手順運用ドキュメント最低限開発ドキュメント整備本番化ドキュメント必要エンジニア引き継ぎソフトウェア仕様書

「ドキュメントはあとで書きます」。この言葉を信じて本番公開した結果、半年後に担当者が変わって誰も触れなくなったシステムを何件見てきたか分からない。

引き継ぎドキュメントが後回しになる理由は単純だ。「今は動いているから問題ない」と思ってしまうから。でも、ドキュメントの価値は「今」ではなく「困ったとき」に現れる。深夜2時に本番障害が起きたとき、担当者が急に辞めたとき、半年ぶりにデプロイしようとしたとき。そのタイミングでドキュメントがないと、本当に詰む。

ドキュメントが存在しないと何が起きるか

具体的に書く。

あるスタートアップでAIツールを使って作ったWebアプリが本番公開された。リリース後3ヶ月、特に問題はなかった。ところが開発者が別プロジェクトに移った段階で、本番環境の環境変数が誰も把握していないことが発覚した。Vercelのダッシュボードを開けたのは元の開発者だけで、その人はすでに連絡がとれない状態。結局、別のエンジニアが1週間かけてコードを読み解き、環境変数を再構築することになった。費用にすると30〜50万円の損失に相当する。

ドキュメントがあれば、この問題は1時間で解決できた。

最低限必要な4種類のドキュメント

「完璧なドキュメント」を目指すと2週間かかる。そうではなく、「これだけあれば誰でも運用できる」という最低セットを2時間で仕上げることを目標にする。

必要なのは以下の4つだ。

README（セットアップと起動手順）
環境変数一覧（本番・ステージング・ローカルの差分）
デプロイ手順（本番反映の具体的な手順）
運用フロー（障害対応・バックアップ・問い合わせ対応）

1. READMEのテンプレート

README は「新しい人が明日からすぐ動ける」ことを基準に書く。インストール手順が複雑なら、コマンドをそのまま貼る。「あとは分かるよね」という省略は絶対にしない。

# プロジェクト名

## 概要
このアプリは〇〇のためのWebサービスです。
技術スタック：Next.js 14 / Supabase / Vercel

## ローカル起動手順

1. リポジトリをクローンする
   git clone https://github.com/your-org/your-repo.git
   cd your-repo

2. 依存パッケージをインストールする
   npm install

3. 環境変数ファイルを作成する
   cp .env.example .env.local
   （.env.localの値は環境変数一覧ドキュメントを参照）

4. 開発サーバーを起動する
   npm run dev

5. ブラウザで http://localhost:3000 を開く

## よくあるエラーと対処

### "Invalid API key" が出る場合
→ .env.local の SUPABASE_ANON_KEY が正しく設定されているか確認

### ビルドが失敗する場合
→ Node.js のバージョンを確認（v18以上が必要）
   node -v

## 連絡先
技術的な質問：xxx@example.com
緊急時（本番障害）：080-XXXX-XXXX

2. 環境変数一覧のテンプレート

環境変数は「どこで使っているか」と「どこで取得するか」を必ず書く。値そのものをドキュメントに書く必要はない。Vercelのダッシュボードやパスワードマネージャーのどこにあるかを書けばいい。

# 環境変数一覧

## 取得場所
- Vercel の Environment Variables（Settings > Environment Variables）
- または 1Password の「プロジェクト名 - 本番環境」ボルト

## 変数一覧

| 変数名 | 用途 | 本番 | ステージング | ローカル |
|--------|------|------|--------------|--------|
| NEXT_PUBLIC_SUPABASE_URL | Supabase接続URL | Vercelに設定済み | Vercelに設定済み | .env.localに設定 |
| NEXT_PUBLIC_SUPABASE_ANON_KEY | Supabase公開キー | Vercelに設定済み | Vercelに設定済み | .env.localに設定 |
| SUPABASE_SERVICE_ROLE_KEY | Supabase管理キー（サーバーのみ） | Vercelに設定済み | Vercelに設定済み | .env.localに設定 |
| STRIPE_SECRET_KEY | Stripe決済キー | Vercelに設定済み | テスト用キーを使用 | テスト用キーを使用 |
| RESEND_API_KEY | メール送信 | Vercelに設定済み | Vercelに設定済み | 開発用キーを使用 |

## 注意
SUPABASE_SERVICE_ROLE_KEY は絶対にフロントエンドのコードに含めないこと。
サーバーサイド（API Routes / Server Actions）からのみ使用すること。

3. デプロイ手順のテンプレート

「mainブランチにマージすれば自動デプロイ」で終わる場合もあるが、それだけ書いても「どこで確認するか」「失敗したらどうするか」がないと役に立たない。

# デプロイ手順

## 通常のデプロイ（自動）
main ブランチへのマージで Vercel が自動的に本番デプロイを実行します。

1. feature ブランチで開発・テストする
2. GitHub でプルリクエストを作成する
   → Vercel がプレビューURLを自動生成するので、そこで動作確認する
3. main ブランチにマージする
   → 2〜3分でデプロイ完了
4. Vercel ダッシュボード（vercel.com）でデプロイ状況を確認する

## デプロイ確認URL
- 本番：https://your-app.com
- Vercelダッシュボード：https://vercel.com/your-team/your-project

## デプロイ失敗時の対処
1. Vercel ダッシュボードでエラーログを確認する
2. よくある原因：
   - 環境変数の未設定
   - TypeScript のビルドエラー
   - 依存パッケージのバージョン不一致
3. 急ぎの場合は前のデプロイに戻す（Vercelの「Instant Rollback」機能を使用）

## データベースマイグレーション
Supabase のスキーマ変更がある場合は以下の手順を踏む。
1. supabase/migrations/ に新しいマイグレーションファイルを作成
2. ステージング環境で動作確認
3. 本番に適用：supabase db push --linked

4. 運用フローのテンプレート

「何か起きたときに誰が何をするか」が書いてあれば、それで十分だ。

# 運用フロー

## 障害対応フロー

### アラートを受け取ったら
1. Sentry（sentry.io）でエラー詳細を確認する
   → プロジェクト名：your-project
2. Vercel のデプロイログを確認する
3. Supabase のダッシュボードでDBの状態を確認する

### 重大障害（サービス全停止）の場合
1. 直近のデプロイに問題があれば即座にロールバックする（Vercel > Deployments > Rollback）
2. Supabase の接続状況を確認する（status.supabase.com）
3. 解決できない場合は開発担当（xxx@example.com）に連絡する

## バックアップ
- Supabase が自動で毎日バックアップを取得（保存期間：7日間）
- 手動バックアップ：Supabase ダッシュボード > Database > Backups

## 定期確認（週次）
- Sentry のエラー件数が増加していないか
- Vercel のビルド成功率
- Supabase のストレージ使用量

## 問い合わせ対応
ユーザーからの問い合わせはすべて info@your-app.com に集約する。
Notion の「問い合わせ管理」ページで管理する。

「引き継ぎ完了」の定義

多くのチームが「ドキュメントを渡した」ことを引き継ぎ完了と思っているが、それは違う。

本当の引き継ぎ完了は「引き継いだ人が1人でデプロイできた」「ドキュメントを読んだだけで環境を再現できた」状態を確認してから宣言するものだ。

具体的には、こんな確認をするといい。「このドキュメントだけを渡した状態で、別のエンジニアがローカル環境を起動できるか試してもらう」。これをやると、必ず何かが抜けていることに気づく。その抜けを埋めて、ようやく引き継ぎ完了だ。

2時間でドキュメントを完成させる手順

完璧を目指すから続かない。「あとで直す前提で、今使えるレベル」を2時間で作ることを目標にする。

0〜30分： 環境変数一覧を作る。現在の.env.localを見ながら表に転記するだけ。
30〜60分： READMEを書く。ローカル起動手順だけ完成させる。
60〜90分： デプロイ手順を書く。直近のデプロイで何をやったかを思い出しながら書く。
90〜120分： 運用フローの骨格を書く。連絡先と障害対応の一次対応だけ書けばOK。

これで「公開後に誰も触れない」状態は避けられる。本番化後の引き継ぎと並行して、契約形態も整理しておくと後のトラブルが減る。

ブログ一覧へ戻る