화면정의서, AI로 자동 생성할 수 있나요? 실무 파이프라인과 품질 기준

화면정의서는 AI로 자동 생성할 수 있습니다. 단, 조건이 있습니다. "빈 문서에 화면 설명을 써내려가는 방식"이 아니라 "실제 구현된 화면 위에 정의를 겹쳐 그리는(오버레이) 방식"일 때 실무 품질이 나옵니다. 저는 50개 이상 라우트 규모의 B2B SaaS에서 이 방식으로 화면정의서를 운영하고 있습니다. 이 글은 그 파이프라인과, AI에게 맡기면 안 되는 검수 포인트를 정리합니다.

화면정의서 자동화에는 어떤 방식이 있나요?

AI 화면정의서 자동화는 크게 세 방식으로 나뉩니다.

방식	동작	강점	한계
문서 생성형	요구사항 텍스트를 주면 화면 설명 문서를 생성	빠름, 기획 초기에 유용	실제 화면과 어긋나기 시작하면 유지보수 불가
코드 스캔형	코드베이스의 컴포넌트·라우트를 스캔해 명세 추출	실제 구현과 일치	기획 의도·정책이 코드에 없으면 공백
오버레이형	실행 중인 화면 위에 번호·설명을 겹쳐 표시	화면과 정의가 물리적으로 분리 불가능	초기 구축 비용, 구현 후에만 가능

기획 초기(화면이 없을 때)는 문서 생성형이 맞고, 운영 중인 제품의 정의서는 오버레이형이 맞습니다. 가장 흔한 실패는 문서 생성형으로 만든 정의서를 운영 단계까지 끌고 가는 것입니다. 화면이 바뀔 때마다 문서가 낡고, 세 달 뒤에는 아무도 안 믿는 문서가 됩니다.

오버레이형 파이프라인은 어떻게 구성하나요?

제가 실무에서 쓰는 파이프라인은 4단계입니다.

1. 컴포넌트·라우트 스캔: AI가 코드베이스에서 라우트 목록과 각 화면의 컴포넌트 구성을 추출합니다. 여기서 화면 인벤토리(전체 화면 목록)가 자동으로 나옵니다.
2. 정의 매핑: 각 화면 요소에 번호를 부여하고, 요소별 정의(명칭·동작·데이터 출처·상태·정책)를 AI가 초안으로 채웁니다. 이때 기존 기획 문서(PRD·정책서)를 컨텍스트로 주면 초안 품질이 크게 올라갑니다.
3. 오버레이 렌더: 실행 중인 화면 위에 번호 배지와 정의 패널을 겹쳐 표시합니다. 정의서가 별도 파일이 아니라 화면 자체에 붙어 있으므로, 화면과 문서가 어긋날 수 없습니다.
4. 사람 검수·확정: 초안을 기획자가 검수하고 확정합니다. 확정본은 저장되어 다음 스캔 때 기본값보다 우선 적용됩니다.

이 구조에서 AI가 하는 일은 "빈 칸을 빠르게 채우는 것"이고, 사람이 하는 일은 "정책과 의도를 확정하는 것"입니다.

어느 정도 규모까지 검증됐나요?

제 운영 사례 기준으로, 라우트 50개 이상·정의 대상 화면 60개 이상 규모의 B2B SaaS에서 이 파이프라인으로 화면정의서를 유지하고 있습니다. 이 규모를 수작업 문서로 유지하려면 화면당 유지보수 비용 때문에 사실상 "최초 1회 작성 후 방치"가 됩니다. 오버레이형의 실질 가치는 최초 작성 속도보다 변경을 따라가는 능력에 있습니다.

AI에게 맡기면 안 되는 검수 포인트는 무엇인가요?

자동 생성 초안에서 사람이 반드시 확인해야 하는 지점이 있습니다. 실제로 AI가 자주 틀리는 순서대로입니다.

• 저장본과 기본값의 우선순위: 사람이 확정한 정의와 AI가 새로 생성한 기본값이 충돌할 때, 병합 규칙이 명확하지 않으면 확정본이 조용히 덮어써집니다. 파이프라인 설계에서 가장 먼저 못 박아야 할 규칙입니다.
• 권한·등급별 분기: 같은 화면이라도 관리자와 일반 사용자에게 다르게 보이는 요소를 AI는 코드만 보고 놓치기 쉽습니다. 등급별로 실제 계정 접속 상태에서 검수해야 합니다.
• 정책성 정의: "삭제 시 30일 보관 후 파기" 같은 정책은 코드 어디에도 명시적으로 없을 수 있습니다. 정책서가 진실원천이고, AI 초안은 후보일 뿐입니다.
• 예외·에러 상태: 정상 흐름 정의는 AI가 잘 채우지만, 실패·빈 데이터·권한 없음 상태의 정의는 누락되기 쉽습니다. 상태별 정의 항목을 템플릿으로 강제하는 것이 안전합니다.

품질 기준 체크리스트

자동 생성이든 수작업이든, 화면정의서가 실무 품질인지 이 기준으로 확인할 수 있습니다.

• 화면 인벤토리가 실제 라우트 전수와 일치한다 (누락 화면 0)
• 요소마다 명칭·동작·데이터 출처·상태·권한이 채워져 있다
• 정상 외 상태(빈 값·에러·로딩·권한 없음)가 정의되어 있다
• 화면 변경 시 정의서가 따라 바뀌는 경로가 있다 (사람이 기억하는 방식이면 실패)
• 확정본과 자동 초안이 시각적으로 구분된다
• 개발자가 "이 문서 최신인가요?"라고 묻지 않는다

자주 묻는 질문

Q. 화면이 아직 없는 신규 기획 단계에도 쓸 수 있나요?

A. 신규 기획 단계는 문서 생성형이 맞습니다. 요구사항과 정책 초안을 주고 화면 목록·요소 정의 초안을 생성한 뒤, 구현이 시작되면 오버레이형으로 전환하는 이원 운영이 실무적입니다.

Q. 디자이너가 없는 팀인데 적용 가능한가요?

A. 가능합니다. 오히려 디자이너 없이 기획에서 개발로 바로 가는 팀일수록 효과가 큽니다. 기존 컴포넌트를 스캔해 재사용을 강제하므로, 화면마다 새 UI를 발명하는 문제도 함께 줄어듭니다.

Q. 어떤 도구가 필요한가요?

A. 특정 상용 도구가 필수는 아닙니다. 핵심은 도구가 아니라 구조입니다: 코드 스캔으로 인벤토리를 만들고, 정의를 데이터로 저장하고, 화면 위에 겹쳐 보여주고, 사람 확정본을 우선하는 병합 규칙. 이 네 가지를 갖추면 사내 구축도 가능합니다.