今回は「Next.js + Vercel」などのモダンスタックに限らず、ビルド・公開前に直面する“最も大変な局面”において、絶対に注意すべきことを7ルールの指針としてまとめました。
目次
1. 依存関係地獄は“バージョンの一貫性”と“明示的な管理”で防ぐ
・package.jsonのバージョンは固定する（^や~を避ける）
・pnpm-lock.yamlは絶対にGit管理する（環境差異を防ぐ）
・新しいライブラリを追加する前に、既存との互換性を確認する
・peerDependenciesの警告は無視しない。一見動いていても、後で壊れる。
- 💡基本思想：「依存関係は“見えないチームメンバー”。信用しすぎず、監視する」
2. 型の不一致は“型の境界”を意識して設計する
・APIレスポンスやDBスキーマはZodやTypeScript型で明示的に定義する
・Supabaseなどの自動生成型は出発点であり、最終的には人間の意図で手動で補完・調整する
・型の境界（例：外部API → 内部処理 → UI）で変換処理を挟むと安全
- 💡基本思想：型は契約。契約の境界では“翻訳者”を置く
3. 設計の不整合は“責務の分離”と“命名の一貫性”で防ぐ
・コンポーネントはUI・ロジック・データ取得を分離する
・ファイル構成は役割ベース（features/pages/components）で整理する
・命名はドメインに沿って一貫性を持たせる（例：user vs supporter）
- 💡基本思想：設計は“言語”。チームや未来の自分が読めるように書く
4. 環境差異によるバグは“環境変数とCI/CDの明示的な管理”で防ぐ
・.env.local と Vercelの環境変数は常に同期させる
・本番・ステージング・開発環境で挙動が変わる処理は明示的に分岐させる
・CI/CDのログは必ず確認する。警告でも放置しない。
- 💡基本思想：環境は“人格”。本番は神経質、開発は気まぐれ
5. ビルド時の失敗は“事前チェックと段階的な検証”で防ぐ
・pnpm exec tsc –noEmit と pnpm lint をビルド前に必ず実行
pnpm exec tsc --noEmit
pnpm lint
・next build はローカルで一度通してからVercelにpushする
・404 や 500 ページは意図的にテストしておく
- 💡基本思想：ビルドは“試験”。一発合格を狙わず、模試を重ねる
6. 公開前の混乱は“ドキュメントとチェックリスト”で防ぐ
・公開前にチェックリストを作成する（型チェック・環境変数・SEO・OGPなど）
・EADMEやdocs/に運用ルールや注意点を明記する
・GitHubのPRテンプレートやIssueテンプレートで運用を仕組み化する
- 💡基本思想：公開は“祝祭”ではなく“観察”。冷静に、慎重に
7. 心理的な焦りは“段階的リリース”と“ロールバック戦略”で緩和する
・本番公開は段階的に行う（例：一部ユーザーのみ、A/Bテスト）
・失敗時に備えてロールバック手段を用意する（旧バージョンの保持）
・公開後はログとユーザーの反応を即座に確認する
- 💡基本思想：ドキュメントは“未来の自分への手紙”。優しく、正確に
まとめ
コードは動くだけでは不十分。
未来に耐え、他者に伝わり、失敗しても立ち直れる設計こそが“良いコード”
