engineering-senior-developer

シニア開発ガイド

概要

このガイドでは、Web、バックエンド、モバイル、プラットフォームの開発全般において、本番環境に耐えうるソフトウェアを提供するためのワークフロー、標準、パターンを説明します。実装の計画、アーキテクチャ上のトレードオフの検討、コード品質の改善、安全なリリースに活用してください。

提供ワークフロー

1. 問題を理解する

• 目標、制約、成功指標、期限、対象外の事項を明確にします。いずれかが不明な場合は、コードを書く前に確認してください。決して推測してはいけません。
• 不明点を特定します。不明点が2つを超える場合は、見積もりを確定する前にスパイクタスク（最大2時間、具体的な成果物を定義）を追加します。
• まず、実現可能な最小限の技術的アプローチを提案します。5日を超える作業が必要な場合は、より簡単な代替案を探すか、フェーズに分割します。
• 実装前に受け入れ条件を定義します。すべての条件は検証可能でなければなりません。「正しく動作する」は条件になりません。「user_id クレームを含む JWT とともに 200 を返す」は条件になります。

2. 実装を計画する

• 作業を、小さくテスト可能なマイルストーンに分割します。各マイルストーンは個別にマージ可能でなければなりません。マイルストーン B をマイルストーン A なしではリリースできない場合、両者を1つのマイルストーンにまとめます。
• 変更が5ファイルを超える場合は、着手前に1段落の計画を書きます。15ファイルを超える場合は、設計ドキュメントを書きます（references/design-docs.md を参照）。
• ロールバックを計画します。データベースのマイグレーションはすべて元に戻せる必要があります。マイグレーションでカラムを削除する場合は、まずそのカラムを読み取らないコードをデプロイし、次のリリースでカラムを削除します。
• 新しい外部依存関係（API、サービス、データベース）を導入する場合は、タイムアウト（デフォルト5秒）、再試行ポリシー（指数バックオフで3回試行）、サーキットブレーカーのしきい値（60秒間に5回失敗）、フォールバック動作を定義します。

3. 実装して検証する

• 40行を超える関数は分割します。300行を超えるファイルは分割します。関数のパラメーターが4つを超える場合は、config/options オブジェクトを導入します。
• 適切なレベルでテストします。純粋なロジックにはユニットテスト、API エンドポイントには結合テスト、重要なユーザーフローには E2E テストを使います（機能ごとに最大5件。実行に時間がかかり、不安定になりやすいためです）。
• 新しい API エンドポイントにはすべて、入力検証（Zod/Pydantic/class-validator）、エラーレスポンスのスキーマ、レート制限、および少なくとも1件の結合テストを用意します。
• 1万行を超えるテーブルに対するデータベースクエリには、すべてインデックスが必要です。EXPLAIN ANALYZE を実行し、大規模なテーブルに対するシーケンシャルスキャンは却下します。
• エラーを捕捉して、何もせずに握りつぶしてはいけません。コンテキスト（操作、入力、相関 ID）とともにログに記録するか、再スローします。対処できるエラーのみを捕捉してください。
• 後方互換性：共有型または API レスポンスの形式を変更する場合は、grep ですべての利用箇所を確認します。旧形式に依存する利用箇所が1つでもある場合は、拡張・移行・契約の手順（新しいフィールドを追加し、利用箇所を移行してから、古いフィールドを削除）を採用します。

4. リリースして安定化する

• マージ前に、テストスイート全体をローカルで実行し、lintや型のエラーがないことを確認します。該当する場合は、バンドルサイズ／バイナリサイズも確認します。
• 可観測性を確保してデプロイします。すべてのデプロイは、5分以内にメトリクスで確認できる必要があります。ダッシュボードでデプロイの健全性を判断できない場合は、デプロイ前に計測機能を追加します。
• デプロイ後は、30分間にわたりエラー率と p95 レイテンシを監視します。エラー率が2倍を超えるか、p95 が2倍になった場合は、直ちにロールバックします。本番環境で先にデバッグしてはいけません。
• 技術的負債を見つけたら、48時間以内に記録します。負債項目には、説明、影響（レイテンシ／信頼性／開発速度）、見積もり工数、担当者を必ず記載します。担当者のいない負債は修正されません。

エンジニアリング標準

• すべての API エンドポイントには、リクエスト／レスポンススキーマ、意味を含むエラーコード、認証要件、レート制限を記載する必要があります。これらが不足しているエンドポイントは、レビューの準備ができていません。
• すべてのデータベースマイグレーションは、マージ前に本番データのコピー（または現実的なシードデータ）を使ってロールバックをテストする必要があります。本番規模のデータで30秒を超えるマイグレーションは、デプロイをブロックせず、バックグラウンドジョブとして実行する必要があります。
• すべてのクリティカルパス（認証、決済、コア CRUD）には、レイテンシーヒストグラム、エラー率カウンター、p95 がベースラインの2倍を超えるか、エラー率が1％を超えたときに発火するアラートが必要です。
• セキュリティ対応は後回しにする作業ではありません。認証チェック、入力検証、CSRF 対策は、初期実装に含める必要があります。PR で認証のないエンドポイントを追加した場合、レビューの準備ができていません。
• パフォーマンス予算：API レスポンスの p95 は、読み取りで200ms未満、書き込みで500ms未満です。新機能がこの基準を超える場合は、マージ前に最適化してください。マージ後ではありません。

アンチパターンの検出

コードのレビュー時または作成時に、次の項目を検出したら、すぐに指摘して修正してください。

• N+1 クエリ： ループの各反復でデータベースを呼び出しています。バッチクエリ、JOIN、または DataLoader で解決してください。
• 上限のないクエリ： ユーザー向けエンドポイントでの SELECT *、または LIMIT のないクエリです。必ずページネーションを行い、必要な列だけを選択してください。
• 共有可変状態： 複数のリクエストハンドラーが変更するグローバル変数です。リクエストスコープのコンテキストまたは依存性注入を使用してください。
• 文字列型に依存するコード： ステータス、タイプ、ロールの値に生の文字列を使用しています。列挙型またはユニオン型を使用してください。
• 神関数： パース、検証、ビジネスロジック、データベース処理、レスポンス整形をすべて行う関数です。レイヤーに分割してください。
• エラーコンテキストの不足： catch (e) { throw new Error("failed") } のようなコードです。元のエラーと操作のコンテキストを必ず含めてください。
• 時期尚早な抽象化： 1か所でしか使わないものに汎用フレームワークを作成しています。同じパターンが3回繰り返されるまで待ってください。
• コード内の設定： URL、API キー、機能フラグ、環境固有の値がハードコードされています。環境変数または設定サービスに移してください。

技術選定の判断基準

言語の選定

• Go：サービスが I/O バウンドで高い同時実行性（同時接続数が1万超）を必要とする場合、単一バイナリでのデプロイが必要な場合、またはインフラツール（CLI、プロキシ、サイドカー）の場合に選択してください。迅速なプロトタイピングや ORM を多用する場合は避けてください。
• Node.js（TypeScript）：チームがフルスタック JS を使用している場合、サービスが BFF（Backend for Frontend）の場合、リアルタイム機能（WebSocket、SSE）が中心の場合、またはその分野に成熟したライブラリがある場合に選択してください。CPU バウンドの処理（画像／動画、ML 推論）には避けてください。
• Python：対象分野がデータ／ML の場合、チームが Python を主に使用している場合、またはランタイム性能より迅速な反復開発が重要な場合に選択してください。FastAPI と uvloop を使用する場合を除き、レイテンシーに敏感なサービス（p95 の目標が10ms未満）には避けてください。
• Java／Kotlin：組織に JVM の専門知識がある場合、成熟したエンタープライズライブラリ（Spring、Hibernate）が必要な場合、または高スループットと強い型付けが必要な場合に選択してください。JVM の起動時間（2～5秒）が許容されるコールドスタート時間を超える小規模なサービスでは避けてください。
• Rust：サービスに厳しいレイテンシー要件（p99 が1ms未満）がある場合、大規模に信頼できない入力を処理する場合、またはパフォーマンスが重要なライブラリである場合に限り選択してください。開発時間が2～3倍になることを、具体的かつ測定可能な必要性によって正当化する必要があります。

データベース選定（クイックリファレンス）

• PostgreSQL（デフォルト）：10TB 未満のリレーショナルデータには、どのような場合でも使用します。JSON、全文検索、地理空間データに対応しているため、可能であれば2つ目のデータベースは不要です。
• Redis：キャッシュ（TTL <24h）、セッションストレージ、レート制限、リアルタイムランキングに使用します。プライマリデータストアとしては決して使用しないでください。再起動時にデータが失われることを前提としています。
• MongoDB：ドキュメントごとにスキーマが実際に異なる場合にのみ使用します（CMS、多相型のペイロードを扱うイベントストアなど）。事前にスキーマを定義できる場合は、PostgreSQL を使用します。
• SQLite：CLI ツール、モバイルアプリ、組み込みシステム、ローカルファーストアプリに使用します。複数のプロセスが同時に書き込みを行う場合は、PostgreSQL を使用します。

API スタイルの選定

• REST：デフォルトの選択肢です。CRUD 中心の API、公開 API、キャッシュが重要な場合に使用します（HTTP キャッシュがネイティブで機能します）。
• GraphQL：クライアントが5種類を超えるエンティティにまたがる柔軟なフィールド選択を必要とし、かつフロントエンドチームがスキーマを管理している場合にのみ使用します。エンティティの種類が3未満なら、REST のほうがシンプルです。サーバー間通信に GraphQL を使用しないでください。
• gRPC：レイテンシ <5ms が重要な場合、ストリーミングが必要な場合、または3つを超える言語間で厳格な契約適用が必要な場合に、内部のサービス間通信に使用します。ゲートウェイなしで gRPC をブラウザーに直接公開しないでください。
• tRPC：フロントエンドとバックエンドが TypeScript のモノレポを共有している場合に使用します。スキーマを重複させることなく、エンドツーエンドの型安全性を実現します。複数の言語を使うバックエンドには適していません。

見積もりの判断基準

タスクの種類別見積もり

• CRUD エンドポイント（ルート＋バリデーション＋DB クエリ＋テスト）：2～4時間。ページネーション、フィルタリング、ソートが必要な場合は、2時間追加します。
• 認証＋レート制限＋キャッシュを備えた CRUD エンドポイント：1日。
• サードパーティ API 連携（OAuth、Webhook、SDK）：1～2日。サードパーティのドキュメントの質が低い場合は、必ず見積もりを2倍にします。見積もりの前にドキュメントを読んで確認してください。
• データベースマイグレーション（列の追加、インデックスの追加）：テーブルが100万行未満なら1～2時間。100万行を超える場合は、オンラインマイグレーションツールとテストに4時間追加します。
• データベースマイグレーション（スキーマの再設計、データのバックフィル）：デュアルライト期間と検証を含めて2～3日。
• サービスをゼロから新規作成（リポジトリ＋CI/CD＋ヘルスチェック＋最初のエンドポイント＋モニタリング）：3～5日。
• 認証システム（サインアップ＋ログイン＋パスワードリセット＋セッション管理）：実績のあるライブラリ（NextAuth、Passport、Django auth）を使えば3～5日。独自に実装する場合は2～3週間かかるため、強く推奨しません。
• ファイルのアップロード／ダウンロード（署名付き URL＋バリデーション＋ストレージ）：1～2日。
• リアルタイム機能（WebSocket/SSE＋接続管理＋再接続）：2～3日。
• 検索（3つを超えるフィールドを対象とした全文検索とフィルタリング）：PostgreSQL の tsvector を使えば1日、Elasticsearch を使えば2～3日。

見積もりの倍率

• ライブラリ／フレームワークを初めて使用する場合：見積もりの2倍。
• テストがないレガシーコードベースの場合：1.5倍（変更を検証するためにテストを書く必要があります）。
• 複数のタイムゾーン、または i18n 要件がある場合：1.3倍。
• コンプライアンス要件（監査ログ、暗号化、アクセス制御）がある場合：1.5倍。
• 見積もりが5日を超える場合は、サブタスクに分割し、それぞれを見積もります。サブタスクが3日を超える場合は大きすぎるため、さらに分割します。

リファクタリングの判断基準

リファクタリングするタイミング

• 循環的複雑度が15を超える（scripts/review_checklist.pyまたはESLintのcomplexityルールで測定）：分岐を名前付き関数に切り出します。各関数の複雑度は10未満にしてください。
• 異なるフラグの組み合わせで、5か所を超える呼び出し元から関数が呼び出されている：ブール値フラグをストラテジーパターンまたは個別の関数に置き換えます。processOrder(order, true, false, true)は読みにくいため、processStandardOrder()とprocessExpressOrder()に分割します。
• 同一のコードブロックが3回以上登場する：共有関数に切り出します。2回の場合は重複を許容します。早すぎる抽象化は重複よりも悪いためです。
• モジュールが他のモジュールを10個より多くインポートしている：結合度が高い状態です。各モジュールがインポートする先を最大5個に抑えられるよう、ファサードを導入するか、モジュールの境界を再編成します。
• テストのセットアップに20行を超えるコードが必要：テスト対象のコードには依存関係が多すぎます。依存関係を注入し、テストダブルを用意してください。データベースを起動せずに関数をテストできない場合、その関数は処理を詰め込みすぎています。
• 1つの機能を変更するのに、2つを超えるディレクトリにまたがる5つを超えるファイルの修正が必要：ショットガン手術が発生しています。関連するロジックを1つのモジュールにまとめるか、機能モジュールのパターンを導入します。

リファクタリングしないタイミング

• コードが安定していて、6か月を超えて変更されておらず、保留中の機能作業もありません。手を加えないでください。
• 測定可能な問題（複雑度、結合度、テストの難しさ）を解決するのではなく、スタイルの好みに合わせるためにリファクタリングしている場合は、やめてください。
• リファクタリングに3日を超える作業が必要で、それによって恩恵を受ける機能作業もない場合は、先送りして技術的負債として記録します。

コードレビューの判断基準

検出されたパターン別

• EXPLAIN ANALYZEの出力がない新しいデータベースクエリ：出力を求めます。本番環境に近いデータ量で実行計画を確認できないクエリはマージしません。
• エラーレスポンスのテストがない新しいエンドポイント：ブロックします。すべてのエンドポイントで、正常な入力（200）、認証情報の欠落（401）、アクセス拒否（403）、無効な入力（400）をテストする必要があります。
• ログを出力して処理を続けるcatchブロック：関数が実際に復旧できるか確認します。復旧できない場合は再スローしてください。catchしてログを出力した後に処理を続けると、バグが連鎖するまで隠れてしまいます。
• ネストの階層が3を超える関数：内部ブロックを名前付き関数に切り出すよう求めます。深いネストは、早期リターンで反転するか、分解すべきロジックの兆候です。
• マジックナンバー／文字列：名前付き定数を使うよう求めます。if (retries > 3) → if (retries > MAX_RETRIES)。ただし、0、1、および一般的なHTTPステータスコード（200、404、500）は例外です。
• 課題へのリンクがないTODO/FIXME：ブロックします。すべてのTODOにはチケットへの参照が必要です。追跡されないTODOは修正されず、放置されます。
• toBeTruthy()またはnot.toThrow()だけをアサートするテスト：アサーションが弱い状態です。具体的な値をアサートするよう求めます。出力が間違っていても成功するテストは、テストがないよりも悪い状態です。
• 新しい依存関係の追加：バンドルサイズへの影響（bundlesizeまたは同等のツールを実行）、最終コミット日、ダウンロード数、ライセンスの互換性、および標準ライブラリで代替できるかを確認します。2時間未満で実装できる機能のために依存関係がバンドルサイズを50KB超増加させる場合はブロックします。

アーキテクチャに関する指針

• チームが5人未満ならモノリスを使います。5～15人なら、明確なドメインモジュールを備えたモジュラーモノリスを使います。独立したリリースサイクルを持つチームが15人を超える場合は、サービスの切り出しを検討します。
• ドメインロジック、データアクセス、トランスポート層の境界を明確に保ちます。ドメインロジックがHTTPリクエスト型やデータベースクライアント型をインポートしている場合、境界が破られています。
• 新しい依存関係（ライブラリ、サービス、またはツール）を追加する際は、最終コミット日（12か月を超えて更新がなければ却下）、週間ダウンロード数（JSでは1,000未満、Pythonでは500未満なら却下）、未解決のセキュリティ勧告を確認します。
• 1,000人を超えるユーザーに影響する変更や、新しいインフラストラクチャを伴う変更には、フィーチャーフラグを使います。各段階で24時間の安定稼働期間を設け、1% → 10% → 50% → 100%の順にロールアウトします。
• 新しい外部依存関係、データベーススキーマの変更、APIコントラクトの変更、インフラストラクチャの変更、技術選定については、アーキテクチャ決定記録（ADR）を作成します。作成に10分を超えるADRは長すぎます。

自己検証プロトコル

実装を完了したら、タスクを完了とみなす前にこのチェックリストを実行してください。

• テストスイート全体を実行します。失敗はゼロである必要があります。変更していないテストが失敗した場合は、そのテストが main でも失敗することを確認してください。失敗しない場合は、変更によって不具合が生じています。
• 新しい API エンドポイントごとに、実際の HTTP リクエスト（curl または統合テスト）を実行し、レスポンスがドキュメントに記載されたスキーマとフィールドごとに一致することを確認します。
• データベースのマイグレーションごとに、新しいデータベースと本番環境に近いシードデータの両方で、適用とロールバックを実行します。どちらの方向も成功する必要があります。
• リファクタリング後は、変更前後のテスト出力を比較します。意図しない動作の変更があれば、リファクタリングによって不具合が生じています。変更を元に戻し、やり直してください。
• 変更したファイルすべてに対して scripts/review_checklist.py を実行します。レビューを依頼する前に、指摘事項をすべて修正してください。
• 本番コードのパスに console.log、print()、debugger、TODO が残っていないことを確認します。
• 新しい依存関係がすべてヘルスチェックに合格することを確認します。最終コミットから12か月未満、ダウンロード数が週あたり1,000件超（JS）または500件超（Python）、未解決の重大な CVE がゼロである必要があります。
• 変更がユーザー向けのフローに影響する場合は、ブラウザーまたはアプリで最初から最後まで手動で操作します。自動テストではリグレッションを検出できますが、UX の問題を検出できるのは手動テストです。

失敗からの復旧

• 変更後にビルドが失敗する場合：最後の行だけでなく、エラー全体を読みます。型エラーの場合は修正します。変更していないコードのテストが失敗する場合は、git stash && npm test を実行し、main でも失敗することを確認します。失敗するなら既存の問題です。失敗しないなら、変更によって不具合が生じています。
• ローカルではテストが成功するのに、CI で失敗する場合：Node/Python のバージョン、環境変数の不足、タイムゾーン、OS の大文字・小文字の区別、Docker とホストのファイルシステムの違いなど、環境の違いを確認します。CI のテストを skip してはいけません。根本原因を修正してください。
• 2時間経ってもアプローチがうまくいかない場合：いったん止めます。（1）試したこと、（2）失敗した理由、（3）誤っていた前提を書き出します。最も簡単な代替策を特定します。代替策がない場合は、具体的な阻害要因を説明してエスカレーションします。
• デプロイ後にパフォーマンスが低下した場合：まずロールバックし、その後で調査します。プロファイリングを使ってローカルで再現します（references/performance-profiling.md を参照）。ユーザーに影響が及んでいる間、本番環境でパフォーマンスのデバッグをしてはいけません。
• 大規模な PR でマージコンフリクトが発生した場合：コンフリクトが5ファイルを超える場合は、確認せずに解決してはいけません。各コンフリクトの両方の変更を読み直します。相手のブランチで同じ関数が変更されている場合は、解決後に両方の動作をテストします。
• 依存関係のアップグレードで問題が発生した場合：動作するバージョンに固定し、正確なエラーを記載して課題を起票し、作業を続けます。サードパーティのリグレッションに1時間を超えて費やしてはいけません。
• 不安定なテストがマージを妨げている場合：ローカルで5回実行します。結果が安定しない場合は、競合状態またはタイミング依存があります。テストを修正します（適切な待機処理の追加、時間のモック、共有状態の削除など）。成功するまで再試行してはいけません。

既存のコードベースを把握する

見慣れないコードベースに取り組むことになったら、コードを書く前に次の手順を完了してください。

1. README と設定ファイルを読む（5分）— 言語、フレームワーク、ビルド／テスト／デプロイのコマンド、エントリーポイントを確認します。
2. アプリをローカルで実行する（10分）— 実行に失敗する場合は、開発環境のセットアップ修正が最初のタスクです。アプリが動くまでは、ほかのことに取り組んでも意味がありません。
3. テストスイートを実行する（5分）— テストの総数、所要時間、失敗数を記録します。main ブランチで失敗するテストがあれば、記録すべき危険信号です。
4. 重要な処理の経路をたどる（15分）— 中心となるユーザー操作を選びます。HTTP ハンドラー → ビジネスロジック → データベース → レスポンスの順にたどり、各段階のファイルと関数を記録します。
5. アーキテクチャのレイヤーを把握する（10分）— エントリーポイント（ルート／コントローラー）、ビジネスロジック、データアクセス、外部サービスを確認します。境界が明確な部分と、複雑に絡み合っている部分を記録します。
6. 依存関係の健全性を確認する（5分）— npm outdated / pip list --outdated を実行します。メジャーバージョンが2つ以上遅れているものに印を付けます。
7. 直近20件のコミットを読む（5分）— 活発に作業されている領域とコミットの規約を把握します。
8. テストの不足箇所を特定する（5分）— どの種類のテスト（ユニット／統合／E2E）があるか、どこに見落としがあるかを確認します。

こうした把握を済ませてから、変更の計画を立ててください。この1時間の投資によって、存在を知らなかった機能を壊さずに済みます。

スクリプト

• scripts/review_checklist.py — ソースファイルを分析し、一般的なコードレビュー上の懸念事項（TODO／FIXME の数、長い関数、例外の無条件捕捉、ハードコードされたシークレット、残存するデバッグ文）を調べます。オプションは --help で確認できます。

参考資料

• コード例 — TypeScript の API ハンドラー、Python のリトライラッパー、安全に移行できる SQL、CI の品質ゲート。
• 設計ドキュメントと ADR — 記入済みの決済処理の例を含む設計ドキュメントのテンプレート、アーキテクチャ決定記録の例、簡易 RFC テンプレート。
• 本番環境のパターン — パーセンテージによる段階的ロールアウトを伴う機能フラグ、グレースフルシャットダウン、拡張・移行・契約型のデータベース移行、相関 ID を使った構造化ログ、サーキットブレーカー、指数バックオフによるリトライ。すべて TypeScript です。
• コードレビューとインシデント対応 — コードレビューのチェックリスト、インシデント対応のランブック、事後分析テンプレート、オンコール引き継ぎテンプレート。
• パフォーマンスのプロファイリング — clinic.js と Chrome DevTools を使った Node.js のプロファイリング、EXPLAIN ANALYZE のワークフロー、pg_stat_statements による上位クエリの確認、N+1 の検出、メモリリークの調査（3スナップショットのヒープ差分）、ワーカースレッドを使った CPU プロファイリング、「エンドポイントが遅い」状態から根本原因の修正までを示す詳細な例。
• デバッグ戦略 — 自動テストスクリプトを使った Git bisect、サービス間の構造化ログの相関、HTTP トラフィックのキャプチャと再生、シード値に基づく再現可能なテストデータ、タイムスタンプ分析とロック競合クエリを使った競合状態のデバッグ、本番環境のデバッグ用エンドポイント、詳細ログの機能フラグ、カナリアデプロイ、よくあるバグパターンの特徴。
• アーキテクチャの決定 — モノリスとマイクロサービス、データベースの選定（PostgreSQL と MySQL、MongoDB、DynamoDB、Redis）、キューの選定（SQS と RabbitMQ、Kafka）、ヒット率のしきい値とスタンピード防止を考慮したキャッシュ戦略、API のスタイル（REST と GraphQL、gRPC）、セキュリティチェックリストを含む認証戦略（セッションと JWT、OAuth2）について、スコアとしきい値を用いた具体的な判断表を掲載しています。
• チームのパターン — PR の規模ごとのレビュー所要時間 SLA、レビューコメントの分類（必須修正／提案／学び／称賛）、重要度スコア付きの技術的負債台帳、トリアージの判断ツリーを含むオンコール用ランブックテンプレート、参照ストーリーを使ったストーリーポイントの調整、ベロシティの追跡式、ブラウンバッグと意思決定ログのテンプレート、ペアリングの進行段階を含むメンタリングフレームワーク、Renovate の設定を使った依存関係のアップグレード戦略。