양식은 올바르게 보이지만, 데이터 계약은 잘못되었습니다.

문제는 AI가 만든 양식이 프로덕션에 준비된 것처럼 보일 수 있는지가 아니라, 데이터를 받는 시스템이 이를 받아들일 수 있는가입니다.

날짜 선택기는 완벽하게 표시될 수 있지만 API가 ISO 날짜를 기대할 때 로케일에 따라 달라지는 문자열을 제출할 수 있습니다. 체크박스는 예 또는 아니오를 표시할 수 있지만 데이터베이스는 부울 값을 기대합니다. 데모는 통과하고 스크린샷은 깔끔해 보이지만, 실패는 하위 단계에서 기다리고 있습니다.

양식이 실제로 약속하는 것은 무엇인가요?

양식 디자인은 보통 인터페이스 문제로 검토됩니다. 사용자가 라벨을 이해할 수 있나요? 탭 순서가 논리적인가요? 페이지가 모바일에서 제대로 동작하나요? 이러한 질문들은 중요하지만, 전체 작업을 설명하지는 못합니다.

양식은 또한 다른 시스템이 해석할 수 있는 형태의 구조화된 데이터를 제공한다는 약속을 합니다. 이 약속은 필드 이름, 데이터 유형, 필수값, 허용 옵션, 기본값, 식별자 및 목적지 매핑을 포함합니다. 수신 시스템을 변경하지 않고 이 중 하나만 바꾸면, 깔끔한 인터페이스가 신뢰할 수 없는 통합으로 전락할 수 있습니다.

그 경계는 생성 AI 문서 자동화가 텍스트 초안을 넘어 구조화된 문서와 인터랙티브 컴포넌트를 생성하기 시작하면서 점점 보기 어려워집니다. 생성이 빠른 이유는 모델이 짧은 설명만으로도 그럴듯한 레이아웃을 추론할 수 있기 때문입니다. 그러나 그럴듯함이 호환성과 동일한 것은 아닙니다.

IETF JSON Schema 작업 그룹의 활성 인터넷 초안은 2026년 8월 26일에 마지막으로 업데이트되었으며, 스키마를 허용되는 JSON 값들을 제한하는 규칙 집합으로 설명합니다. 또한 UI 렌더러와 같은 생성적 사용에 대해서도 논의합니다. 이 조합은 문제의 핵심을 짚고 있습니다: 동일한 스키마가 인터페이스를 만드는 데 도움이 될 수 있지만, 검증은 여전히 결과 입력이 허용된 집합에 속하는지를 판단해야 합니다.

왜 계약이 변질되는가?

AI는 명백히 깨진 코드를 만들 필요 없이도 나쁜 계약을 만들 수 있습니다. 단지 시스템의 나머지 부분이 공유하지 않을 합리적인 가정을 하면 됩니다.

“Customer ID”라는 라벨이 붙은 온보딩 양식을 상상해 보세요. 모델은 해당 필드를 customer_id라고 명명하는데, 이는 타당해 보입니다. 그러나 기존 API는 여전히 account_number를 기대합니다. 모든 테스트 사용자는 해당 상자를 입력할 수 있지만, 통합이 예상치 못한 속성을 거부하거나 변환하지 않으면 식별자가 올바른 레코드에 도달하지 못할 수 있습니다.

유형도 동일한 종류의 불일치를 초래합니다. 빈 필드는 빈 문자열, null, 혹은 속성 자체가 없을 수도 있습니다. 숫자는 텍스트 형태로 도착할 수 있습니다. 드롭다운은 친숙한 라벨을 표시하지만 수신 시스템은 안정적인 코드를 기대합니다. OpenAPI 3.2.0은 입출력 데이터 유형을 정의하는 스키마 객체를 사용하여 팀에게 화면에 표시되는 내용에 의존하지 않고 양식과 비교할 수 있는 기계가 읽을 수 있는 설명을 제공합니다.

종속성은 사용자 선택 뒤에 숨겨져 있기 때문에 놓치기 쉽습니다. 국가를 선택하면 주, 지방 또는 지역 필드가 필수가 될 수 있습니다. “individual” 대신 “company”를 선택하면 등록 번호가 필요할 수 있습니다. JSON Schema의 조건부 검증은 종속 요구사항 및 조건부 서브스키마를 통해 이러한 관계를 표현할 수 있지만, 생성된 양식도 동일한 규칙을 구현해야 합니다.

필드 이름, 유형, 값 및 속성을 노출하는 개발자 도구는 PDF 양식 필드 검증을 최종 단계의 시각적 검사 대신 빌드 프로세스의 일부로 만들게 합니다. 이는 스키마 검증기나 API 계약 테스트를 대체하지는 않으며, 개발자에게 해당 테스트가 검사해야 하는 양식 측 객체에 대한 제어권을 제공합니다.

변질의 또 다른 원인이 있습니다: 양식과 계약은 처음에 일치했지만 서로 다른 일정에 따라 변경될 수 있습니다. 프롬프트가 수정되고, 필드 라벨이 이름이 바뀌며, API가 옵션을 제거하거나 새로운 필수 속성을 도입합니다. 깨진 레이아웃을 아무도 눈치채지 못하기 때문에 이러한 변경은 무해해 보입니다.

그렇지 않습니다.

행복한 경로 외에 어떻게 테스트하나요?

성공적인 제출은 특정 값 조합이 한 번 작동했음을 증명합니다. 프로덕션 양식은 더 엄격한 검증이 필요합니다.

스크린샷이 아니라 페이로드부터 시작하세요. 정상적인 예시를 제출하고 실제 직렬화된 출력과 계약을 비교합니다. 속성 이름, 유형, 중첩 구조 및 허용값을 확인합니다. 그런 다음 해당 페이로드를 실제 통합에 전달하여 동일한 값이 CRM, ERP 또는 데이터베이스를 거쳐 다시 검토 화면으로 돌아오는지 확인합니다.

다음 테스트는 실패하도록 설계되어야 합니다. 필수값이 누락된 경우, null이 기대되는 곳에 빈 문자열이 들어간 경우, 경계를 벗어난 숫자, 예상치 못한 드롭다운 옵션, 계약에서 인식하지 못하는 속성을 시도해 보세요. 유용한 검증 레이어는 단순히 요청을 차단하는 것이 아니라, 개발자, 운영자 또는 사용자가 수정할 수 있도록 실패한 필드와 규칙을 명확히 식별합니다.

조건부 분기는 자체적인 테스트가 필요합니다. 양식에 서로 다른 후속 필드를 드러내는 다섯 가지 선택지가 있다면 모두 실행해 보세요. 또한 되돌아가는 전환도 테스트하십시오: 숨겨진 필드는 사용자가 이전 답변을 변경한 후에도 오래된 값을 계속 제출해서는 안 됩니다. 여기서 문서 구조와 컨텍스트에 관한 글이 일반 소프트웨어 테스트와 만납니다. 문서 내 관계를 이해하는 것은 그 관계가 직렬화 후에도 유지될 때만 유용합니다.

필드 식별자는 필드 문구보다 더 중요합니다. 라벨은 명확성, 번역 및 브랜드 목소리를 위해 변경됩니다. 안정적인 내부 식별자는 라벨과 함께 변경되어서는 안 됩니다. 따라서 릴리스 검사는 표시 라벨, 내부 이름, 예상 유형 및 대상 매핑을 별개의 속성으로 비교해야 합니다.

마지막으로, 수신 시스템이 사용할 수 없거나 제출을 거부할 때 어떤 일이 발생하는지 주시하세요. 양식이 사용자의 작업을 보존합니까? 안전하게 재시도하거나 중복을 생성합니까? 운영자가 원시 로그를 읽지 않고도 오류를 추적할 수 있습니까? 문서 처리 워크플로와 엔터프라이즈 시스템 간에 이동하는 데이터는 인계가 완료되기 전에 표시되는 성공 메시지가 아니라 관찰 가능한 오류 경로가 필요합니다.

출시 후 계약을 누가 소유합니까?

계약 테스트는 릴리스 직전에 한 번만 수행되는 정리 작업이 될 수 없습니다. 양식, 스키마 및 하위 인터페이스는 계속 변경될 것입니다.

여러 팀이 워크플로의 일부를 담당하더라도, 한 팀은 계약에 대한 명확한 소유권을 가져야 합니다. 해당 소유자는 모든 복사본 변경을 승인할 필요는 없지만, 어떤 변경이 제출된 데이터를 변경할 수 있는지, 어떤 테스트를 실행해야 하는지, 검증 실패가 발생했을 때 누가 대응할지를 알아야 합니다.

스키마를 양식 정의와 함께 버전 관리하십시오. 템플릿, 프롬프트, 양식 코드 또는 API가 변경될 때마다 지속적 통합에서 대표적인 계약 테스트를 실행합니다. 운영 환경에서는 필드와 계약 버전별로 거부된 제출 및 매핑 실패를 모니터링합니다. 릴리스 후 하나의 오류가 증가하는 것은 “양식이 작동을 멈췄다”라는 모호한 보고보다 진단이 훨씬 쉽습니다.

스키마 검증이 증명할 수 있는 범위에는 한계가 있습니다. 값이 선언된 제약 조건을 따르는지는 보여줄 수 있지만, 사용자가 올바른 값을 선택했는지, 비즈니스 규칙이 합리적인지, 워크플로가 모든 보안, 프라이버시, 접근성 또는 규정 준수 요구사항을 충족하는지는 증명할 수 없습니다. 따라서 팀은 결과가 중요할 경우 정책 검토와 인간의 판단이 여전히 필요합니다.

그 전제 조건이 계약에 대한 주장을 약화시키지는 않습니다. 이는 계약의 역할을 정의합니다.

결론

AI는 설명에서 실제 작동하는 양식까지의 과정을 단축할 수 있습니다. 또한 아직 그 약속을 테스트하지 않은 상태에서도 인터페이스가 완성된 것처럼 보이게 만들 수 있습니다.

릴리스 결정은 명시적인 필드 의미, 실패 사례를 포함한 계약 테스트, 그리고 이후 변경에도 지속되는 소유권을 기반으로 해야 합니다. 깔끔한 화면은 환영받지만, 더 중요한 질문은 바로 다음입니다: 수락된 모든 입력이 수신 시스템에 의해 올바르게 해석될 수 있나요?