Harnessを壊さずカスタマイズする方法｜仕様化・小さなPR・D1 migration

日本語の要望を画面・API・DBの実装仕様へ変換し、小さなPRと後方互換なD1 migrationで変更する方法です。 日本語の要望から、画面・API・DB・外部連携の変更点を抽出します。 既存patternに合わせ、1機能だけをbuild/test付きで完成させます。 schema直書きではなく、既存データを壊さないmigrationで変更します。

この記事はHarness Academyの教材データを基に、各Harnessの公式リポジトリにある実装箇所と照合して構成しています。秘密情報や本番データを記事・AIチャットへ貼らず、外部送信は必ず検証対象を限定してください。

最初に確認すること

• 要望を実装仕様へ変換する: AIがいきなりコードを書かず、完成条件を共有する
• AIに小さなPRとして実装させる: レビュー可能で戻せる差分を作る
• D1 migrationを安全に追加する: 既存環境と新規環境の両方が同じschemaになる

要望を実装仕様へ変換する

日本語の要望から、画面・API・DB・外部連携の変更点を抽出します。

この工程のゴール: AIがいきなりコードを書かず、完成条件を共有する

「タグを増やしたい」だけでは影響範囲が決まりません。誰が、どこで、何を操作し、どこへ保存し、失敗時にどう見えるかまで決めます。

手順

1. 要望を入力

業務上の目的と現在の困りごとを書きます。

2. リポジトリ調査

類似機能と既存patternをAIに探させます。

3. 仕様を承認

対象外とrollbackまで決めてから実装へ進みます。

完了条件

• 類似実装が根拠として示される
• DB/API/画面の影響が分かる
• 完了条件と対象外が明確

Academy教材: Harnessを壊さずカスタマイズする / Lesson 7-1

AIに小さなPRとして実装させる

既存patternに合わせ、1機能だけをbuild/test付きで完成させます。

この工程のゴール: レビュー可能で戻せる差分を作る

本家coreを直接書き換える場合でも、既存のroute/resource/component patternへ合わせ、無関係な整形や依存更新を混ぜません。

手順

1. branch

feature branchと復旧地点を作ります。

2. 実装

仕様で承認した範囲だけを変更します。

3. 検証・PR

差分レビュー、build/test、PR本文を作ります。

完了条件

• 無関係な差分がない
• 対象packageのbuild/test成功
• rollback方法が明記

Academy教材: Harnessを壊さずカスタマイズする / Lesson 7-2

D1 migrationを安全に追加する

schema直書きではなく、既存データを壊さないmigrationで変更します。

この工程のゴール: 既存環境と新規環境の両方が同じschemaになる

migrationは原則additiveにし、既存行へNOT NULLを追加する場合はdefault／backfillを設計します。適用済みSQLを書き換えません。

手順

1. 現状確認

schemaと最新migration、適用方式を読みます。

2. 新規migration

次の番号でidempotentなSQLを追加します。

3. local→remote

local DBとtest環境で検証後、本番適用前に確認します。

完了条件

• 新規migration fileが追加
• 既存データ入りDBで成功
• 本番適用前に対象DBが明示

Academy教材: Harnessを壊さずカスタマイズする / Lesson 7-3

公式ソース

• L Harness / apps/worker/src/routes — LINE API pattern
• IG Harness / apps/worker/src/routes — IG API pattern
• L Harness / package.json — LINE scripts
• IG Harness / package.json — IG scripts
• L Harness / packages/db/migrations — LINE migrations
• IG Harness / packages/db/migrations — IG migrations

関連ガイド

• Harnessシリーズ公式ガイド索引
• L Harness公式ガイド