정의
ORM as AI-Maintainable Database Contract는 AI가 DB 앱을 생성·수정할 때 raw SQL보다 ORM schema, typed model, migration history를 중심 interface로 삼는 개발 패턴이다.
여기서 ORM은 단순히 SQL을 감추는 편의 도구가 아니다. DB table, column, relation, type, migration을 코드로 드러내 AI가 구조를 파악하고 변경 범위를 좁힐 수 있게 하는 contract다.
핵심 속성
- Schema visibility: 테이블 구조와 관계가 코드에 남아 AI가 현재 DB 모델을 읽을 수 있다.
- Type safety: 잘못된 field 접근이나 nullability 문제를 compile/lint 단계에서 일부 잡을 수 있다.
- Consistent CRUD pattern: 조회·추가·수정 코드의 형태가 일정해져 patch risk가 낮아진다.
- Migration history: column 추가, relation 변경, index 추가 같은 DB 변화가 시간 순서로 기록된다.
- Agent-friendly interface: “Prisma schema와 migration도 함께 관리”처럼 AI에게 명시적 작업 단위를 줄 수 있다.
사용 기준
Next.js나 NestJS에서 PostgreSQL을 쓰는 AI-built app이라면 다음 instruction을 기본값으로 둘 수 있다.
PostgreSQL을 사용하고, ORM은 Prisma 또는 Drizzle로 구성한다. Schema와 migration을 함께 관리하고, raw SQL은 필요한 경우에만 격리한다.
실패 모드
- ORM 없이 raw SQL만 늘어나면 AI가 schema drift를 놓치기 쉽다.
- migration 없이 DB를 직접 수정하면 local/dev/prod 상태가 갈라진다.
- ORM schema를 최신 DB와 동기화하지 않으면 contract가 오히려 거짓 문서가 된다.
- 복잡한 query를 ORM으로 억지 표현하면 성능과 가독성이 떨어질 수 있다.
연결
- 20260704-understand-to-participate-in-agentic-coding — AI가 만든 코드를 이해 가능한 구조로 유지해야 한다.
- 20260716-cognitive-debt-in-agentic-coding — 이해되지 않는 구조 변화는 나중에 cognitive debt가 된다.