"모호함을 미리 제거하는 게 리뷰 비용을 줄이는 가장 싼 방법"
Industry CRUD 기능을 진행하자는 요청을 받았을 때, 정작 스키마 구조나 enum 값, 권한 체계, 화면 범위, Project Count 처리 방식 중 확정된 게 하나도 없었습니다. 필요한 정보는 Acceptance Criteria 문서, 화면 명세, 데이터 모델 문서 세 곳에 흩어져 있었고, industry_status 같은 enum 값은 아예 명시적으로 정의된 곳이 없었습니다.
문서를 하나씩 검색하며 미확정 지점을 직접 결정해나갔습니다. industry_status는 IA 문서에 있던 "Active/Inactive" 표기를 그대로 재사용하기로 했는데, 이건 새로운 규칙을 만드는 게 아니라 이미 있는 표기를 가져다 쓰는 것이라고 판단했습니다. Hard Delete는 배제하고, 권한 판정은 새로 만들지 않고 기존 헬퍼 함수를 재사용하도록 지시했습니다. Project Count는 참조할 테이블이 아직 없어서 일단 0으로 고정하고 TODO 주석을 남기는 방식으로 정리했습니다.
이렇게 정리한 결정들을 범위, 권한, Action, 화면, 금지사항, 검증 항목이 포함된 지시서 형태로 작성해 전달했습니다. 결과적으로 Codex가 한 번의 구현 사이클로 12개 파일을 작성하고 85개 테스트가 통과했다고 보고할 만큼 구체적인 스펙이 확보됐습니다.
다만 이 시점에 확인한 건 지시서의 완성도와 구현 완료 보고 자체이지, 실제 코드 내용이나 화면 동작까지 검증한 건 아니었습니다. 구현자에게 넘기기 전에 모호함을 최대한 제거해두는 게, 나중에 검토할 때 드는 비용을 줄이는 방법이라는 걸 다시 확인한 작업이었습니다.
문서에 없는 Business Rule을 임의로 추가하지 않는다는 원칙과, Core/Vertical 구분, 기존 헬퍼 재사용이라는 프로젝트 원칙을 지키려면 구현에 들어가기 전에 애매한 지점을 전부 결정해서 넘겨야 한다고 판단했습니다. 구현자가 스스로 판단해야 하는 지점이 하나라도 남아있으면, 그 판단이 문서와 어긋날 위험이 그대로 리뷰 비용으로 돌아온다고 봤습니다.
관련 프로젝트
프로젝트 개요 비즈니스 프로세스 트랜스포메이션(BPR)을 지원하는 한국어 기반 웹 애플리케이션. 컨설팅 프로젝트의 AS-IS 프로세스 분석부터 TO-BE 설계, Blueprint 승인까지의 전체 워크플로우를 디지털화하는 플랫폼으로, EPIC 단위로 구조화된 백로그를 기반으로 개발 중. 역할 및 워크플로우 PM / Architect / Reviewer 역할 수행 Codex(구현 담당)에게 Task 단위 구현 프롬프트 설계 Codex 구현 결과를 git log, git grep, git status로 직접 검증 후 승인 승인 전에는 Codex가 commit하지 않는 엄격한 게이팅 프로세스 운영 한 번에 하나의 Backlog Task만 진행, Task 완료 전 다음 Task 착수 금지 기술적 의사결정 및 성과 워크스페이스/프로젝트 접근 권한을 DB 레벨(복합 FK, SECURITY DEFINER 트리거)과 애플리케이션 레벨(Server Action 권한 검증)의 이중 방어 구조로 설계 Hard Delete 미구현 원칙 하에 배열 필드 전체교체(replace)를 단일 트랜잭션 RPC로 처리하는 패턴 확립 및 재사용 AS-IS 프로세스 그래프의 순환 참조 탐지에 Tarjan SCC 알고리즘 적용, 차단 오류(Error)와 경고(Warning)를 분리한 이중 Validator 아키텍처 설계 도메인 규칙 위반을 커스텀 Postgres 에러 코드 체계(SIA0104)로 문서화하여 거버넌스 문서와 코드베이스 간 정합성 유지 AI 생성 데이터와 사람이 검증한 데이터를 구분하는 generatedbyai / verified 메타데이터 패턴을 여러 도메인 테이블에 일관되게 적용 진행 상태 ✅ EPIC-01 (인증 / 워크스페이스 / 프로젝트 접근) ✅ EPIC-02 (조직 / 산업 / 프로젝트) 🚧 EPIC-03 (AS-IS 프로세스 그래프) — 그래프 검증, Input/Output 스키마, Business Rule 스키마 구현 완료