테이블 정의서·ERD 작성법 2026 — 데이터 이관과 인터페이스 정의서 연결 7단계

# 테이블 정의서·ERD 작성법 2026 — 데이터 이관과 인터페이스 정의서 연결 7단계

이 문서가 없으면 3년 뒤에 비용이 청구된다

테이블 정의서는 데이터가 어떤 표에 어떤 형식으로 담기는지를 적은 문서다. 개발사가 만들고 발주처가 받아둔다.

발주처 입장에서 당장은 쓸 일이 없어 보인다. 그런데 없으면 아래 세 시점에 비용이 발생한다.

⚠️ "소스 코드는 받았으니 괜찮다"가 흔한 오해다. 코드를 봐도 어떤 컬럼이 무슨 의미인지, 왜 그 제약이 걸려 있는지는 안 나온다. `status` 컬럼에 `1, 2, 9`가 들어 있을 때 9가 무엇인지 아는 사람은 만든 사람뿐이다.

발주 문서 전체 지도는 요구사항 정의서 작성법 — 외주 문서 7단계에 정리했다.

테이블 정의서와 ERD는 짝이다

둘 다 데이터를 다루지만 보는 각도가 다르다. 하나만 받으면 절반만 안다.

발주처가 실제로 검토할 수 있는 것은 테이블 정의서다. ERD는 받아 보관하되, 검토는 정의서로 한다.

테이블 정의서 한 줄에 들어갈 7가지

🔴 「설명」 칸이 이 문서의 전부다

타입과 길이는 코드를 보면 알 수 있다. 코드에 없는 것은 의미다.

```

❌ status CHAR(1) 상태

✅ status CHAR(1) A:정상 W:휴면 D:탈퇴 — W는 1년 미접속 시 배치로 자동 전환

```

코드값이 있는 컬럼은 값의 목록과 뜻을 반드시 적는다. 이걸 빼면 3년 뒤 아무도 모른다.

데이터 이관에서 이 문서가 하는 일

실무에서 일정이 가장 자주 밀리는 지점이 기존 엑셀을 새 시스템으로 옮기는 단계다. 기능은 다 됐는데 데이터를 못 넣어 오픈이 미뤄진다.

테이블 정의서가 있으면 이관 전에 무엇이 문제인지 미리 안다.

발주 전에 정의서 초안을 받아 기존 엑셀과 대조해 보면 정리 작업량이 나온다. 그 작업을 누가 할지(개발사 유상 / 발주처 직접)를 미리 정하는 것이 일정 사고를 막는 유일한 방법이다.

관리 프로그램 발주 전반은 관리 프로그램 제작 — 기성 SaaS vs 맞춤 개발에 정리했다.

인터페이스 정의서 — 외부와 주고받는 데이터

우리 DB 안이 테이블 정의서라면, 밖과 주고받는 데이터는 인터페이스 정의서가 다룬다.

연동마다 아래를 적는다.

• 연동 대상과 방향 (결제 PG ← 요청 / → 응답)
• 호출 시점 (주문 확정 시, 배치 매일 02:00)
• 주고받는 항목과 타입
• 실패 시 처리 (재시도 횟수, 실패 기록 위치)
• 인증 방식과 키 관리 주체

⚠️ 실패 처리가 빠진 인터페이스 정의서가 대부분이다. 결제 성공만 정의하고 타임아웃·취소 응답을 안 적으면, 그 경우 주문이 붕 뜬다. 이건 검수 때 잘 안 잡히고 오픈 후에 터진다.

외부 연동이 견적을 가르는 이유는 시스템 구성도 작성법에 따로 정리했다.

발주처가 검토할 때 볼 것 5가지

개발자가 아니어도 아래는 확인할 수 있다.

1. 코드값 컬럼에 값 목록과 뜻이 적혀 있는가 — `status`, `type`, `grade` 같은 것
2. 우리 업무 용어와 컬럼 설명이 맞는가 — 「거래처」를 「고객」으로 적어놨다면 나중에 혼란이 온다
3. 개인정보 항목이 표시돼 있는가 — 주민번호·연락처·주소의 암호화 여부
4. 삭제 방식이 정해져 있는가 — 실제 삭제인가, `deleted_at` 표시인가
5. 이력이 남는가 — 등급을 바꿨을 때 이전 값이 어디에 남는가

⚠️ 4번과 5번은 나중에 넣기 가장 비싼 항목이다. 삭제를 실제 삭제로 만들어 두면 복구가 불가능하고, 이력 테이블은 뒤에 붙이면 과거 데이터가 없다. 착수 전에 정한다.

개인정보는 정의서 단계에서 정한다

"일단 다 넣고 나중에 정리"가 가장 위험하다. 수집한 순간 관리 의무가 생긴다. 정의서 단계에서 수집하지 않을 항목을 먼저 정하는 편이 안전하다.

흔한 실수 4가지

① 설명 칸을 컬럼명 한글 번역으로 채운다

`member_name → 회원명`은 정보가 0이다. 코드값·계산식·업데이트 시점을 적어야 문서가 된다.

② 개발이 끝난 뒤에 문서를 만든다

그러면 만들어진 구조를 받아 적는 작업이 된다. 검토 기능이 사라진다.

③ ERD만 받고 정의서를 안 받는다

그림만으로는 컬럼의 의미를 모른다. 둘은 짝이다.

④ 변경 이력을 남기지 않는다

구조는 개발 중 반드시 바뀐다. 납품 시점 기준 최신본을 받는다는 조건을 계약서에 넣는다.

확보 7단계

```

[ ] 1. 우리 업무 용어 목록 정리 (거래처/고객/회원 중 무엇을 쓰나)

[ ] 2. 수집하지 않을 개인정보 항목 먼저 확정

[ ] 3. 설계 초반에 테이블 정의서 초안 수령

[ ] 4. 기존 엑셀과 대조 → 정리 작업량 산정, 담당 확정

[ ] 5. 삭제 방식·이력 보관 여부 결정 (뒤로 미루지 않는다)

[ ] 6. 외부 연동은 인터페이스 정의서로 별도 확보 (실패 처리 포함)

[ ] 7. 납품 시 최신본 + ERD 함께 인수

```

AI-Native 팀이 데이터 문서를 다루는 방식

나무숲은 AI-Native Team으로, 팀원 전원이 Claude Code Max 플랜을 기본 개발 환경으로 사용합니다. 데이터 문서에서 어려운 것은 만드는 일이 아니라 스키마가 바뀔 때 문서가 따라가는 일이다.

• 스키마와 문서 대조 — 실제 DB 구조와 정의서의 컬럼·제약이 일치하는지 확인해, 문서에만 있고 실제로는 없는 컬럼을 잡는다
• 코드값 추출 — 소스에서 실제로 쓰이는 상태값을 뽑아 정의서의 값 목록에 빠진 것을 찾는다
• 이관 전 데이터 진단 — 기존 엑셀을 정의서의 제약과 대조해 중복·형식 불일치·필수 누락 건수를 미리 센다

정의서의 가치는 3년 뒤에도 맞는가로 판가름난다. 대조를 자동화해 사람이 업무 의미 정의에 집중하게 만드는 것이 AI-Native 개발 방식의 관점이다.

AI 기능 없이 순수 웹·앱 개발이 필요하다면 포텐랩(Potenlab)도 좋은 선택이다. MVP부터 플랫폼 개발까지 전문으로 한다.

자주 묻는 질문

비개발자가 테이블 정의서를 검토할 수 있나요?

할 수 있고 해야 한다. 타입과 제약은 개발사가 정하지만, 컬럼의 의미와 코드값이 우리 업무와 맞는지는 발주처만 판단할 수 있다.

ERD는 꼭 필요한가요?

표가 10개 이하면 정의서만으로도 충분한 경우가 많다. 다만 다음 개발사에 넘길 계획이면 받아 두는 편이 낫다.

개발 중에 구조가 바뀌면요?

정상이다. 중요한 건 납품 시점 기준으로 갱신된 문서를 받는 것이다. 계약서에 명시한다.

기존 엑셀 정리는 누가 하나요?

정하기 나름인데, 정하지 않는 것이 최악이다. 개발사에 맡기면 유상이고 직접 하면 시간이 든다. 어느 쪽이든 일정에 잡아 둔다.

삭제는 실제 삭제와 표시 중 뭐가 낫나요?

대부분 표시(`deleted_at`)가 안전하다. 실수로 지웠을 때 복구되고, 통계에서 과거 데이터가 사라지지 않는다. 다만 개인정보는 파기 의무가 있으니 항목별로 나눠 정한다.

정리

테이블 정의서는 몇 년 뒤 시스템을 이어받을 사람을 위한 문서다. 당장 쓸 일이 없어 보여서 가장 자주 생략되고, 그래서 가장 비싸게 청구된다.

실무에서 결과를 가르는 지점은 셋이다.

1. 코드값의 뜻이 적혀 있는가 — 코드를 봐도 안 나오는 유일한 정보다
2. 삭제 방식과 이력 보관을 착수 전에 정했는가 — 뒤에 넣으면 과거 데이터가 없다
3. 기존 엑셀 정리를 누가 할지 정했는가 — 오픈이 밀리는 가장 흔한 원인이다

이 셋만 챙겨도 이관 사고와 인수인계 비용이 크게 줄어든다.