インクリメンタル実装

概要

細い垂直スライスで構築します — 1つのピースを実装し、テストし、検証してから展開します。機能全体を1度に実装することは避けてください。各インクリメントは、システムを動作可能でテスト可能な状態に保つべきです。これは大きな機能を管理可能にする実行規律です。

使用時期

• 複数ファイルにまたがる変更を実装する場合
• タスク分解から新機能を構築する場合
• 既存コードをリファクタリングする場合
• テストする前に約100行以上のコードを書きそうになったとき

使用しない場合： スコープが既に最小限の単一ファイル、単一関数の変更。

インクリメントサイクル

┌──────────────────────────────────────┐
│                                      │
│   Implement ──→ Test ──→ Verify ──┐  │
│       ▲                           │  │
│       └───── Commit ◄─────────────┘  │
│              │                       │
│              ▼                       │
│          Next slice                  │
│                                      │
└──────────────────────────────────────┘

各スライスについて:

1. 実装 — 機能の最小限の完全なピースを実装します
2. テスト — テストスイートを実行します(またはテストがなければ作成します)
3. 検証 — スライスが期待通りに動作することを確認します(テストが成功、ビルド成功、手動確認)
4. コミット — わかりやすいメッセージで進捗を保存します(git-workflow-and-versioningでアトミックコミットのガイダンスを参照)
5. 次のスライスに移る — 引き継ぐ、再開しない

スライス分割戦略

垂直スライス(推奨)

スタック全体を通した1つの完全なパスを構築します:

スライス1: タスクを作成する(DB + API + 基本UI)
    → テストが成功、ユーザーはUIを通じてタスクを作成できる

スライス2: タスクをリストアップする(クエリ + API + UI)
    → テストが成功、ユーザーは自分のタスクを見ることができる

スライス3: タスクを編集する(更新 + API + UI)
    → テストが成功、ユーザーはタスクを変更できる

スライス4: タスクを削除する(削除 + API + UI + 確認)
    → テストが成功、CRUD機能が完成

各スライスは動作するエンドツーエンドの機能を提供します。

コントラクト優先スライス分割

バックエンドとフロントエンドが並行して開発する必要がある場合:

スライス0: APIコントラクトを定義する(型、インターフェース、OpenAPI仕様)
スライス1a: コントラクトに対してバックエンドを実装 + APIテスト
スライス1b: コントラクトに一致するモックデータに対してフロントエンドを実装
スライス2: 統合してエンドツーエンドテストを実行

リスク優先スライス分割

最もリスクが高い、または最も不確実なピースに最初に取り組みます:

スライス1: WebSocket接続が機能することを証明する(最高リスク)
スライス2: 実証された接続上でリアルタイムタスク更新を構築
スライス3: オフラインサポートと再接続を追加

スライス1が失敗した場合、スライス2と3に投資する前に発見できます。

実装ルール

ルール0: シンプルさを優先

コードを書く前に、「動作する最もシンプルなことは何か?」と自問してください。

コードを書いた後は、これらのチェックに対して確認してください:

• これはより少ない行数でできますか?
• これらの抽象化は複雑さに見合っていますか?
• スタッフエンジニアがこれを見て「なぜ単に〜しなかったのか?」と言いますか?
• 仮想的な将来の要件のために構築していないか、それとも現在のタスクのためですか?

シンプルさチェック:
✗ 1つの通知のためのミドルウェアパイプライン付き汎用EventBus
✓ シンプルな関数呼び出し

✗ 2つの類似コンポーネントのための抽象ファクトリパターン
✓ 共有ユーティリティを持つ2つの単純なコンポーネント

✗ 3つのフォームのための設定駆動フォームビルダー
✓ 3つのフォームコンポーネント

似た3行のコードは、時期尚早な抽象化よりも優れています。最初に単純で明らかに正しいバージョンを実装してください。テストで正確性が証明された後にのみ最適化してください。

ルール0.5: スコープ規律

タスクで要求されたものだけに触れます。

しない:

• あなたの変更に隣接するコードを「クリーンアップ」する
• 変更していないファイルのインポートをリファクタリングする
• 完全に理解していないコメントを削除する
• スペックにない機能を「役立ちそうだから」追加する
• 読み込むだけのファイルの構文を現代化する

タスク範囲外で改善する価値があることに気づいたら、注記してください — 修正しないでください:

気づいたが触らない:
- src/utils/format.ts に未使用のインポートがあります(このタスクと無関係)
- authミドルウェアはより良いエラーメッセージを使用できます(別のタスク)
→ これらのタスクを作成する必要がありますか?

ルール1: 一度に1つのこと

各インクリメントは1つの論理的な事柄を変更します。懸念を混ぜないでください:

悪い: 新しいコンポーネントを追加し、既存のコンポーネントをリファクタリングし、ビルド設定を更新する1つのコミット。

良い: 3つの個別コミット — 各変更に1つずつ。

ルール2: コンパイル可能に保つ

各インクリメント後、プロジェクトはビルド可能で既存テストは成功する必要があります。スライス間でコードベースを壊れた状態にしないでください。

ルール3: 不完全な機能のフィーチャーフラグ

機能がユーザーに準備できていないがインクリメントをマージする必要がある場合:

// 作業中機能のフィーチャーフラグ
const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';

if (ENABLE_TASK_SHARING) {
  // 新しい共有UI
}

これにより、不完全な作業を露出させることなくメインブランチに小さなインクリメントをマージできます。

ルール4: 安全なデフォルト

新しいコードは安全で保守的な動作にデフォルト設定する必要があります:

// 安全: デフォルトで無効、オプトイン
export function createTask(data: TaskInput, options?: { notify?: boolean }) {
  const shouldNotify = options?.notify ?? false;
  // ...
}

ルール5: ロールバック対応

各インクリメントは独立して復帰可能である必要があります:

• 追加的な変更(新しいファイル、新しい関数)は復帰が簡単です
• 既存コードへの変更は最小限で焦点を絞ったものであるべきです
• データベースマイグレーションには対応するロールバックマイグレーションが必要です
• 同じコミットで何かを削除して置き換えることは避けてください — 分離してください

エージェントの使用

エージェントにインクリメンタル実装を指示する場合:

「計画からタスク3を実装しましょう。

まずはデータベーススキーマ変更とAPIエンドポイントだけにしてください。
UIにはまだ触れないでください — 次のインクリメントで行います。

実装後、`npm test`と`npm run build`を実行して
何も壊れていないことを確認してください。」

各インクリメントについて、スコープ内とスコープ外について明確にしてください。

インクリメントチェックリスト

各インクリメント後、以下を確認してください:

• 変更は1つのことを行い、完全に行う
• 既存テストがすべて成功する(npm test)
• ビルドが成功する(npm run build)
• 型チェックが成功する(npx tsc --noEmit)
• リントが成功する(npm run lint)
• 新しい機能が期待通りに動作する
• 変更がわかりやすいメッセージでコミットされている

注: 変更に影響を受ける可能性があるコマンドの後に各検証コマンドを実行してください。成功した実行後、コード変更以降に同じコマンドを繰り返さないでください — 変更されていないコードで再実行しても情報は追加されません。

よくある言い訳

言い訳	現実
「すべて最後にテストします」	バグは複合します。スライス1のバグはスライス2-5を間違えます。各スライスをテストしてください。
「一度にやる方が速いです」	何かが壊れて、500行の変更のどれが原因かわかるまで、それは速く感じます。
「これらの変更は個別にコミットするには小さすぎます」	小さいコミットは無料です。大きいコミットはバグを隠し、ロールバックを苦痛にします。
「フィーチャーフラグは後で追加します」	機能が完全でない場合、ユーザー向けに表示すべきではありません。今すぐフラグを追加してください。
「このリファクタリングは小さいので含めても大丈夫です」	機能と混合されたリファクタリングは、両方のレビューとデバッグを難しくします。分離してください。
「念のためビルドコマンドを再度実行します」	成功した実行後、コード変更以降に同じコマンドを繰り返さない限り、同じコマンドを繰り返しても何も追加されません。後続の編集後に再度実行してください、安心のためではなく。

赤信号

• テストを実行せずに100行以上のコードを書いた
• 単一のインクリメント内の複数の無関係な変更
• 「これも素早く追加しましょう」スコープ拡大
• テスト/検証ステップをスキップして速く進める
• インクリメント間のビルドまたはテスト破損
• 大きなコミットされていない変更が蓄積する
• 3番目のユースケースが要求する前に抽象化を構築する
• タスク範囲外のファイルに「ついでに」触れる
• ワンタイムの操作のために新しいユーティリティファイルを作成する
• 中間のコード変更なしで同じビルド/テストコマンドを2回実行する

検証

タスクのすべてのインクリメントを完了した後:

• 各インクリメントは個別にテストされコミットされました
• 完全なテストスイートが成功しました
• ビルドはクリーンです
• 機能がスペック通りにエンドツーエンドで動作します
• コミットされていない変更は残りません