AI에게 마이그레이션을 작성하게 하기 전에 '나중에 바꾸기 어려운 4가지 항목'을 먼저 결정하라

AI 코딩 에이전트에게 "이 엔티티의 테이블을 만들어줘"라고 요청하면, 마이그레이션 (Migration)을 즉시 생성해 줍니다. 하지만 생성된 스키마에는 나중에 변경 비용이 극도로 높은 결정이 암묵적으로 포함되어 있었습니다.

• 사용자 데이터 테이블임에도 물리 삭제(IsDeleted 플래그 없음)로 생성됨
• 기본 키(Primary Key)가 long 자동 채번으로 생성되어, 외부로 공개하는 ID에 그대로 사용됨
• DateTime이 로컬 시간으로 저장되어 타임존(Timezone) 처리가 제각각임
• 필수 항목이 NULL 허용으로 생성되어, 나중에 데이터가 들어간 상태에서 NOT NULL로 변경하는 데 애를 먹음

코드의 버그는 나중에 고칠 수 있지만, 데이터 구조의 결정은 운영 환경에 데이터가 들어간 후에는 변경이 어렵습니다. 논리 삭제로 사후 이행하거나, ID 타입을 바꾸거나, 모든 레코드의 타임존을 보정하는 작업은 모두 기존 데이터의 이행(Migration)을 수반하며, 이는 코드를 수정하는 것과는 비용의 단위가 다릅니다.

AI에게 스키마를 생성하게 하기 전에, 다음 4가지 항목만은 인간이 먼저 확정한다는 게이트(Gate)를 마련했습니다.

결정 사항	내용	기본 선택 방식
삭제 방식	물리 삭제 또는 논리 삭제 (IsDeleted / DeletedAt)	사용자 데이터는 논리 삭제
ID 타입	long 자동 채번 / Guid / 복합 키	외부 공개용 ID는 Guid
타임존	UTC 저장 또는 로컬 시간	원칙적으로 UTC 저장 및 표시 시 변환
Null 허용	각 컬럼의 Nullable 필요 여부	필수 항목은 NOT NULL

이 4가지를 결정한 후 프롬프트(Prompt)에 포함하면, AI는 망설임 없이 의도대로의 스키마를 출력합니다.

"테이블 만들어줘"가 아니라, 4가지 항목을 명시하여 의뢰합니다.

이 엔티티의 마이그레이션을 작성해 주세요.
데이터 설계 전제:
- 삭제 방식: 논리 삭제 (IsDeleted bool + DeletedAt DateTime?)
...

생성 결과는 다음과 같습니다.

public class Memo
{
public Guid Id { get; set; } // ID 타입: Guid
...

AI가 출력한 스키마는 마이그레이션을 실행하기 전에 반드시 인간이 리뷰합니다. 체크 항목은 이 4가지를 축으로 합니다.

• 논리 삭제가 필요한 테이블에 IsDeleted / DeletedAt이 있는가
• 외부 공개용 ID가 추측 가능한 연속 번호가 아닌가
• DateTime이 UTC 저장으로 통일되어 있는가 (DateTimeKind.Unspecified의 혼입이 없는가)
• 필수 컬럼이 NOT NULL로 되어 있는가

특히 "기존 테이블에 컬럼을 추가하는" 변경에서는, 기존 데이터에 대한 기본값(NULL 추가 시의 처리)과 앱 측의 기존 쿼리에 미치는 영향을 확인한 후 적용합니다.

처음에는 "일단 AI에게 생성하게 하고, 이상하면 나중에 고치자"라는 방식으로 했습니다. 하지만 이는 기각했습니다. 마이그레이션은 적용하면 스키마 이력이 쌓이며, 운영 환경에 데이터가 들어가면 되돌릴 수 없습니다. "나중에 고치면 된다"가 통하지 않는 것이 데이터 구조의 결정이기에, 생성하기 전에 결정한다는 순서로 정한 것이 핵심입니다.

• AI가 생성하는 스키마에는 삭제 방식, ID 타입, 타임존(TZ), Null 허용이라는 "나중에 바꾸기 어려운 4가지 항목"이 암묵적으로 포함된다
• 이 4가지 항목만은 마이그레이션 생성 전에 인간이 확정한다
• 4가지 항목을 프롬프트에 명시하고, 생성 후에도 이 4가지 축으로 리뷰 게이트를 통과한 후 적용한다
• "생성한 뒤에 고친다"는 데이터 구조 결정에는 통하지 않는다

이 게이트는 개인 개발 코딩 규칙(zenn-articles 리포지토리 등의 rules/에서 운용)에 "데이터 설계 리뷰"로 기록하여, 엔티티를 신규 생성할 때마다 참조하고 있습니다.