프롬프트 명확성이 아키텍처, 데이터 모델, 유지보수성에 미치는 영향

프롬프트 명확성이 의미하는 것(그리고 왜 중요한가)

“프롬프트 명확성”은 원하는 바를 경쟁하는 해석의 여지가 적게 남도록 표현하는 것을 의미합니다. 제품 관점에서는 명확한 결과, 사용자, 제약, 성공 측정지표로 보입니다. 엔지니어링 관점에서는 입력, 출력, 데이터 규칙, 오류 동작, 비기능적 기대치(성능, 보안, 준수) 같은 명시적 요구사항이 됩니다.

연쇄 반응: 프롬프트 → 코드

프롬프트는 AI나 팀원에게 건네는 단순한 텍스트가 아닙니다. 전체 빌드의 씨앗입니다:

• 프롬프트는 의도(어떤 문제를 왜 해결하는가)를 표현합니다.
• 요구사항은 의도를 테스트 가능한 문장으로 번역합니다.
• 설계 결정은 요구사항을 아키텍처 선택(서비스, 경계, API, 데이터 저장소)으로 바꿉니다.
• 코드는 그런 선택을 구현합니다—그 과정에서 만들어진 가정들까지 포함해서요.

프롬프트가 명확하면 하위 산출물이 정렬되는 경향이 있습니다: “무엇을 의미했는가”에 대한 논쟁이 줄고, 막판 변경이 줄며, 엣지 케이스에서의 놀라움이 적어집니다.

모호함이 비싼 이유

모호한 프롬프트는 사람(또는 AI)이 빈칸을 가정으로 채우게 만듭니다—그리고 그 가정은 역할마다 거의 일치하지 않습니다. 어떤 이는 "빠르다"를 서브초 응답으로 해석하고, 다른 이는 주간 보고서에 충분하다고 생각합니다. 어떤 이는 "고객"에 체험 사용자까지 포함한다고 생각하고, 다른 이는 제외합니다.

그 불일치는 재작업을 만듭니다: 구현 시작 후 설계가 수정되고, 데이터 모델은 마이그레이션이 필요해지며, API는 깨지는 변경을 얻고, 테스트는 실제 수용 기준을 포착하지 못합니다.

명확성이 도움이 되지만 마법은 아니다

명확한 프롬프트는 깨끗한 아키텍처, 올바른 데이터 모델, 유지보수가 쉬운 코드의 확률을 크게 높이지만 보장하지는 않습니다. 여전히 리뷰, 트레이드오프, 반복이 필요합니다. 차이는 명확성이 그런 대화를 구체적(그리고 더 저렴하게)으로 만든다는 점입니다—가정이 기술 부채로 굳기 전에요.

명확성이 아키텍처 품질에 전파되는 방식

프롬프트가 애매하면 팀(사람이든 AI든)은 가정으로 빈칸을 채웁니다. 그 가정은 컴포넌트, 서비스 경계, 데이터 흐름으로 굳어지고—종종 아무도 그 결정이 내려졌는지 인지하기 전에 그렇게 됩니다.

불명확한 프롬프트는 경계 불일치를 만든다

프롬프트가 누가 무엇을 소유하는가를 말하지 않으면 아키텍처는 "지금 당장 되는 것"으로 표류하기 쉽습니다. 단일 화면이나 긴급 통합을 만족시키기 위해 즉석 서비스가 생기고, 안정적인 책임 모델 없이 만들어지는 것을 보게 됩니다.

예를 들어, “구독 추가” 같은 프롬프트는 빌링, 권한(entitlements), 고객 상태를 한 통합 모듈에 조용히 섞어 넣을 수 있습니다. 이후 모든 새 기능이 그것을 건드리고, 경계는 실제 도메인을 반영하지 않게 됩니다.

초기 선택은 되돌리기 비용이 크다

아키텍처는 경로 의존적입니다. 일단 경계를 정하면 다음도 정해집니다:

• 검증이 어디에 있는가
• 비즈니스 규칙이 어디에서 실행되는가
• 데이터가 어떻게 중복되거나 공유되는가

원래 프롬프트가 제약(예: “환불을 지원해야 한다”, “계정당 여러 요금제 허용”, “프래이션 규칙”)을 명확히 하지 않았다면 확장할 수 없는 단순화된 모델을 만들 수 있습니다. 나중에 고치려면 마이그레이션, 계약 변경, 통합 재테스트가 필요합니다.

명확성은 선택지를 줄인다

모든 명확화는 가능한 설계 트리를 압축합니다. 좋은 일입니다: "아마도"의 경로가 적을수록 우발적 아키텍처가 줄어듭니다.

정확한 프롬프트는 구현을 쉽게 만들 뿐 아니라 트레이드오프를 가시화합니다. 요구사항이 명시되면 팀은 경계를 의도적으로 선택(그리고 이유 문서화)할 수 있고, 최초로 컴파일된 해석에서 상속받지 않습니다.

모호함의 일반적 증상

프롬프트 모호성은 빠르게 드러나는 경향이 있습니다:

• 범위 확장("하는 김에 이거도…")
• 취약한 통합(파트너가 문서화되지 않은 동작에 의존)
• 중복된 로직(같은 규칙이 서비스마다 재구현)
• 혼란스러운 소유권(규칙이 어디에 속하는지 아무도 모름)

명확한 프롬프트가 완벽한 아키텍처를 보장하진 않지만, 시스템 구조가 실제 문제를 반영하고 성장하면서 유지 가능해질 확률을 크게 높입니다.

프롬프트가 시스템 경계와 책임으로 이어지는 방식

명확한 프롬프트는 단순히 "답을 얻는" 것을 넘어 시스템이 무엇을 책임질지 선언하게 만듭니다. 이것이 깨끗한 아키텍처와 어디에도 속할 수 없는 기능 더미의 차이입니다.

목표와 비목표가 서비스 경계를 정의한다

프롬프트가 "사용자가 30초 내에 송장을 PDF로 내보낼 수 있다" 같은 목표를 적으면, 이는 즉시 전용 책임을 암시합니다(PDF 생성, 작업 추적, 저장, 알림). "v1에서 실시간 협업 없음" 같은 비목표는 웹소켓, 공유 락, 충돌 해결을 조기에 도입하지 못하게 합니다.

목표가 측정 가능하고 비목표가 명시적이면 다음을 더 뚜렷하게 구분할 수 있습니다:

• 동기여야 하는 것(UI가 대기) vs 비동기여도 되는 것(백그라운드 작업)
• 강력한 일관성이 필요한 데이터 vs "결국 일관성이면 괜찮음"
• 별도 서비스에 속해야 할 것 vs API 내부 모듈에 둘 것

행위자와 워크플로를 컴포넌트에 매핑하라

좋은 프롬프트는 행위자(고객, 관리자, 지원, 자동 스케줄러)와 그들이 트리거하는 핵심 워크플로를 식별합니다. 그 워크플로는 컴포넌트로 깔끔하게 매핑됩니다:

• UI: 폼, 대시보드, 업로드/다운로드, 상태 뷰
• API: 검증, 오케스트레이션, 정책 집행, 집계
• 워커: 장기 작업, 재시도, 배치 처리
• 스토리지: 진실의 출처 테이블, 파일/오브젝트 스토리지, 감사 로그

미리 명시해야 할 횡단 관심사

프롬프트는 종종 아키텍처를 지배하는 "모든 곳에서 필요한" 요구를 놓칩니다: 인증/인가, 감사, 요율 제한, 멱등성, 재시도/타임아웃, PII 처리, 관찰성(로그/메트릭/트레이스). 지정되지 않으면 일관되지 않게 구현됩니다.

빠른 체크리스트: 프롬프트가 아키텍처적으로 완전한가?

• 명확한 목표 + 명시적 비목표
• 행위자와 상위 워크플로 목록
• 예상 규모/지연 및 실패 기대치
• 데이터 소유권(진실의 출처) 및 보존 규칙
• 횡단 관심사: 인증, 감사, 요율제한, 재시도
• 각 워크플로의 “완료” 기준(수용 기준)

프롬프트 명확성과 데이터 모델의 정확성

데이터 모델은 종종 SQL을 쓰기 훨씬 전에 잘못됩니다—프롬프트가 “자명해 보이는” 모호한 명사를 사용할 때 그렇습니다. customer, account, user 같은 단어는 여러 현실적 의미를 가질 수 있고, 각 해석은 다른 스키마를 만듭니다.

모호한 명사가 어떻게 지저분한 스키마를 만드는가

프롬프트가 “고객과 그들의 계정을 저장하라”라고 하면 다음과 같은 질문에 직면하게 됩니다:

• customer는 개인인가, 회사인가, 아니면 둘 다인가?
• account는 청구 프로필인가, 로그인인가, 은행 계좌인가, 구독인가?
• user는 고객과 같은가, 아니면 고객을 관리하는 직원인가?

정의가 없으면 팀은 nullable 칼럼, 범용 테이블, type, notes, metadata 같은 과부하 필드를 추가해 결국 "모든 것을 넣는 곳"으로 만듭니다.

정확한 정의는 키, 관계, 제약을 개선한다

명확한 프롬프트는 명사를 규칙이 있는 명시적 엔터티로 바꿉니다. 예: “Customer는 조직이다. User는 하나의 조직에 속하는 로그인이다. Account는 조직당 하나의 청구 계정이다.” 이제 자신 있게 설계할 수 있습니다:

• 키: customer_id와 user_id는 교체 불가
• 관계: 일대다 vs 다대다가 정의됨
• 제약: 유일성(조직별 이메일), 필수 필드, 유효한 상태

데이터 수명주기는 “불멸” 레코드를 방지한다

프롬프트 명확성은 또한 수명주기를 다루어야 합니다: 레코드는 어떻게 생성, 업데이트, 비활성화, 삭제, 보관되는가. “고객 삭제”가 하드 삭제인지, 소프트 삭제인지, 법적 보존(제한 접근)인지를 명시하세요. 미리 정하면 깨진 외래키, 고아 데이터, 일관성 없는 리포팅을 피할 수 있습니다.

명명 일관성과 과부하 필드 방지

같은 개념에는 일관된 이름을 사용하세요(예: 항상 customer_id, 가끔 org_id 아님). 애매한 칼럼 대신 별도 모델을 선호하세요—billing_status와 account_status를 분리하고, 다섯 가지를 의미하는 하나의 모호한 status를 피하세요.

강한 데이터 모델을 위해 무엇을 명시해야 하는가

데이터 모델은 처음에 제공하는 세부사항만큼만 좋습니다. 프롬프트가 “고객과 주문을 저장하라”만 말하면 데모에는 적합하지만 중복, 임포트, 불완전 레코드 같은 실체적 조건에서 실패할 스키마를 얻게 됩니다.

핵심 엔터티와 식별자

엔터티를 명확히 이름(예: Customer, Order, Payment)하고 각 엔터티가 어떻게 식별되는지 정의하세요.

• 기본 식별자: UUID, 이메일, 계정번호, 합성 키 중 무엇인가?
• 외부 식별자: 다른 시스템(CRM ID 등)에서 동기화되는가? 여러 외부 ID가 있을 수 있는가?
• 유일성 규칙: 이메일은 전역적으로 유일한가, 테넌트별인가, 전혀 유일하지 않은가?

상태, 전이, 라이프사이클 규칙

많은 모델이 상태가 명시되지 않아 깨집니다. 다음을 명확히 하세요:

• 허용되는 상태(Draft → Submitted → Paid → Refunded)
• 허용되는 전이와 이를 트리거하는 것
• 상태가 변경 가능한지(예: "Paid"가 되돌릴 수 있는가)와 변경을 어떻게 감사할지

검증, 필수 필드, 포맷

무엇이 반드시 있어야 하고 무엇이 없어도 되는지를 명시하세요.

예시:

• 필수 vs 선택 필드(예: 전화번호 선택, 청구지 주소는 인보이스 발행에 필수)
• 필드 제약(최소/최대 길이, 허용 문자)
• 검증 시점(생성 시, 업데이트 시, 워크플로 마일스톤 시)

시간, 통화, 로케일, 타임존

이것들을 초기에 명시하여 숨은 불일치를 피하세요.

• 타임스탬프를 UTC로 저장하는가? 원래 타임존도 저장할 것인가?
• 통화는 ISO 4217(USD/EUR)와 소수 단위 표기? 반올림 규칙?
• 로케일별 포맷팅 vs 정규화 저장

엣지 케이스: 중복, 병합, 임포트, 부분 데이터

실제 시스템은 지저분한 현실을 다뤄야 합니다. 다음을 명확히 하세요:

• 중복 감지 및 병합 규칙(어떤 필드가 우선되는가, 무엇을 보존하는가)
• 필드가 없는 임포트된 레코드(이를 "불완전"으로 허용하는가?)
• 여러 소스에서 충돌하는 업데이트와 감사 요구사항

API 계약: 프롬프트 명확성이 빨리 효과를 내는 곳

API 계약은 프롬프트 명확성의 효과를 가장 빨리 확인할 수 있는 장소 중 하나입니다: 요구사항이 명확하면 API는 오용되기 어려워지고 버전 관리가 쉬워지며 깨지는 변경을 덜 유발합니다.

깨지는 변경을 방지하려면 구체적으로

“주문을 업데이트하는 엔드포인트 추가” 같은 모호한 프롬프트는(부분 업데이트 vs 전체 교체, 필드 이름, 기본값, 비동기 vs 동기) 호환되지 않는 해석을 남깁니다. 명확한 계약 요구사항이 초기 결정을 강제합니다:

• 어떤 필드가 쓰기 가능/필수/불변인지
• 업데이트가 PUT(교체)인지 PATCH(부분)인지
• 하위 호환성 규칙(예: "새 필드는 선택적이어야; 기존 필드 의미를 변경하지 말 것")

오류 처리: 실패 모드를 설계의 일부로 만들기

“좋은 에러”의 모습을 정의하세요. 최소한 다음을 명시하세요:

• 시나리오별 상태 코드(400 검증, 401/403 인증/인가, 404 미발견, 409 충돌, 429 요율제한)
• 일관된 에러 바디(기계용 코드, 사람이 읽을 메시지, 필드 수준 세부, 상관/요청 ID)
• 재시도 기대치: 어떤 오류가 재시도 안전한지, 권장 백오프 행태

페이지네이션, 필터링, 정렬, 멱등성

여기서의 모호함은 클라이언트 버그와 불균형한 성능을 만듭니다. 규칙을 명시하세요:

• 페이지네이션 스타일(커서 vs 오프셋), 한계, 안정적인 정렬 보장
• 지원 필터와 타입(정확 일치, 범위, 열거)
• 정렬 필드 및 기본 정렬
• 쓰기 멱등성(멱등성 키, 중복 제거 윈도우, 중복 요청 시 동작)

예제와 제약으로 문서화하라

구체적인 요청/응답 샘플과 제약(최소/최대 길이, 허용 값, 날짜 포맷)을 포함하세요. 몇 가지 예시는 긴 설명보다 오해를 더 많이 예방합니다.

유지보수성: 모호함의 장기 비용

모호한 프롬프트는 단순히 "잘못된 답"을 만들지 않습니다. 그것들은 코드 경로, 데이터 필드, API 응답 전반에 퍼지는 숨은 가정을 만듭니다. 결과는 빌더가 추측한 가정들 하에서만 동작하는 소프트웨어이고, 실제 사용이 달라지는 순간 깨집니다.

숨은 가정이 취약한 코드를 만든다

프롬프트가 빈칸을 남기면(예: "환불을 지원"만 있고 규칙이 없음) 팀은 서로 다른 곳에서 다르게 채웁니다: 한 서비스는 환불을 역거래로 처리하고, 다른 서비스는 별도 거래로 다루며, 세 번째는 제약 없이 부분 환불을 허용합니다.

명확한 프롬프트는 불확실성을 줄여 불변 조건(예: "환불은 30일 내 허용", "부분 환불 허용", "디지털 상품은 재고 복원하지 않음")을 명시하고, 그 진술들이 시스템 전반에 걸쳐 예측 가능한 동작을 유도합니다.

명확성은 코드와 테스트를 단순하게 만든다

유지보수 가능한 시스템은 추론하기 쉽습니다. 프롬프트 명확성은 다음을 지원합니다:

• 읽기 쉬운 코드: 입력과 상태가 정의되어 방어적 분기가 적음
• 단순한 테스트: 테스트 케이스가 수용 기준에 직접 대응함, "무엇일까" 시나리오를 뒤쫓지 않음
• 안전한 리팩터링: 동작이 명시되어 있으면 내부를 바꿔도 결과를 검증할 수 있음

AI 지원 개발을 사용한다면, 명확한 요구사항은 모델이 일관된 구현을 생성하게 도와주어 그럴듯하지만 불일치하는 조각들을 줄입니다.

운영성: 로깅과 메트릭은 선택사항이 아니다

유지보수성에는 시스템 운영이 포함됩니다. 프롬프트는 관찰성 기대치를 명시해야 합니다: 무엇을 로그로 남겨야 하는지(그리고 무엇을 남기면 안 되는지), 어떤 메트릭이 중요한지(오류율, 지연, 재시도), 실패를 어떻게 노출할지. 그렇지 않으면 팀은 고객이 문제를 발견하고 난 뒤에야 문제를 알게 됩니다.

유지보수성 신호들

모호함은 낮은 응집도와 높은 결합도로 드러납니다: 관련 없는 책임들이 함께 붙어 있고, 모든 것을 건드리는 "헬퍼" 모듈이 있으며, 호출자에 따라 동작이 달라집니다. 명확한 프롬프트는 응집된 컴포넌트, 좁은 인터페이스, 예측 가능한 결과를 장려해 향후 변경 비용을 낮춥니다. 실무적 강제 방법은 /blog/review-workflow-catch-gaps-before-building 를 참고하세요.

더 나은 프롬프트의 전후 예시

모호한 프롬프트는 단지 모호한 텍스트를 만들지 않습니다—그것은 설계를 "일반 CRUD" 기본값으로 밀어넣습니다. 더 명확한 프롬프트는 경계, 데이터 소유권, 데이터베이스에서 반드시 참이어야 할 것을 조기에 결정하게 만듭니다.

이전: 모호한 프롬프트

“아이템을 관리하는 간단한 시스템을 설계하세요. 사용자는 아이템을 생성, 업데이트, 공유할 수 있습니다. 빠르고 확장 가능해야 하며, 깔끔한 API를 제공하세요. 변경 내역을 보관하세요.”

빌더(사람 또는 AI)가 신뢰성 있게 추론할 수 없는 항목:

• "아이템"이 무엇인가(필드, 라이프사이클, 유일성)?
• "공유"는 무슨 의미인가(공개 링크 vs 특정 사용자 vs 팀)?
• "변경 내역"은 무엇을 의미하는가(전체 스냅샷 vs diff, 누가 무엇을 변경했는가, 보존 기간)?

이후: 제약을 가진 명확한 프롬프트

“다음 규칙으로 generic items 관리를 위한 REST API를 설계하세요: items는 title(필수, 최대 120), description(선택), status(draft|active|archived), tags(0–10)를 가집니다. 각 item은 정확히 하나의 소유자(user)에 속합니다. 공유는 특정 사용자에게 항목별 접근을 부여(roles: viewer|editor); 공개 링크 없음. 모든 변경은 감사 가능해야 함: 누가 언제 무엇을 변경했는지 저장하고, 항목당 마지막 50개 변경을 조회 가능하게 할 것. 비기능: 읽기 p95 지연 < 200ms; 쓰기 처리량은 낮음. 데이터 모델 엔터티와 엔드포인트를 제공하고, 오류 케이스와 권한을 포함할 것.”

지금 아키텍처와 스키마 선택은 즉시 바뀝니다:

• 아키텍처: 전용 Authorization 컴포넌트(역할 검사)와 Audit Log 쓰기 경로; 쓰기 처리량이 낮으므로 복잡한 캐싱 불필요
• 스키마: items, item_shares(역할을 가진 다대다), item_audit_events(append-only). status는 enum, 태그는 10개 제한을 강제하기 위해 조인 테이블로 이동 가능성 높음

빠른 변환표

더 나은 설계를 위한 실용적 프롬프트 템플릿

명확한 프롬프트는 길 필요는 없습니다—구조화되어야 합니다. 목표는 설계와 데이터 모델링 결정이 추측이 아니라 명확해질 만큼의 맥락을 제공하는 것입니다.

복사/붙여넣기 템플릿

1) Goal
- What are we building, and why now?
- Success looks like: <measurable outcome>

2) Users & roles
- Primary users:
- Admin/support roles:
- Permissions/entitlements assumptions:

3) Key flows (happy path + edge cases)
- Flow A:
- Flow B:
- What can go wrong (timeouts, missing data, retries, cancellations)?

4) Data (source of truth)
- Core entities (with examples):
- Relationships (1:N, N:N):
- Data lifecycle (create/update/delete/audit):
- Integrations/data imports (if any):

5) Constraints & preferences
- Must use / cannot use:
- Budget/time constraints:
- Deployment environment:

6) Non-functional requirements (NFRs)
- Performance: target latency/throughput, peak load assumptions
- Uptime: SLA/SLO, maintenance windows
- Privacy/security: PII fields, retention, encryption, access logs
- Compliance: (if relevant)

7) Risks & open questions
- Known unknowns:
- Decisions needed from stakeholders:

8) Acceptance criteria + Definition of Done
- AC: Given/When/Then statements
- DoD: tests, monitoring, docs, migrations, rollout plan

9) References
- Link existing internal pages: /docs/<...>, /pricing, /blog/<...>

효과적으로 사용하는 방법

섹션 1–4를 먼저 작성하세요. 핵심 엔터티와 진실의 출처를 이름으로 말할 수 없다면 설계는 보통 "API가 반환하는 것"으로 흘러가고, 이후 지저분한 마이그레이션과 불명확한 소유권을 초래합니다.

NFR에서는 모호한 단어("빠르다", "안전하다")를 피하고 숫자, 임계값, 명시적 데이터 처리 규칙으로 대체하세요. 대략의 추정(예: "읽기 p95 < 300ms at 200 RPS")도 침묵보다 실행 가능성이 큽니다.

수용 기준에는 적어도 하나의 부정 케이스(예: 잘못된 입력, 권한 거부)와 하나의 운영 케이스(예: 실패가 어떻게 노출되는가)를 포함하세요. 그래야 설계가 다이어그램이 아니라 실제 동작에 근거합니다.

Koder.ai를 사용해 명확한 프롬프트를 일관된 빌드로 전환하기

프롬프트 명확성은 AI로 엔드투엔드 빌드할 때 더 중요합니다—단순히 코드 조각을 생성하는 수준을 넘어서 요구·설계·구현을 프롬프트가 좌우하는 워크플로에서 작은 모호함도 스키마 선택, API 계약, UI 동작으로 전파됩니다.

Koder.ai는 이런 스타일의 개발을 위해 설계되었습니다: 채팅에서 구조화된 프롬프트를 반복하고, Planning Mode로 가정과 오픈 질문을 명확히 한 뒤 코드가 생성되기 전에 이를 드러낼 수 있습니다. React(웹), Go + PostgreSQL(백엔드), Flutter(모바일) 같은 스택을 지원해 실작동하는 앱 스택을 배포할 수 있고, 스냅샷 및 롤백 같은 기능으로 요구사항이 바뀔 때 안전하게 실험할 수 있습니다. 소스 코드 내보내기로 팀이 소유권을 유지하고 "블랙박스"를 피할 수 있습니다.

프롬프트를 팀과 공유할 때 위 템플릿을 살아있는 명세로 취급하고 앱과 함께 버전 관리하면 경계가 더 명확해지고 우발적 깨짐이 줄어듭니다.

리뷰 워크플로: 빌드 전에 공백을 잡아내기

읽기 쉬운 프롬프트는 읽기 좋은 것으로 끝나지 않습니다. 두 사람이 그 프롬프트로부터 대체로 같은 시스템을 설계할 수 있을 때 “완료”입니다. 가벼운 리뷰 워크플로는 모호함을 조기에 찾아냅니다—아키텍처 변경, 스키마 재작성, API 깨짐으로 이어지기 전에요.

1단계: 읽어주기(2분)

한 사람(PM, 엔지니어, 또는 AI)에게 프롬프트를 목표, 비목표, 입력/출력, 제약으로 재진술하게 하세요. 그 읽어주기를 원래 의도와 비교하세요. 불일치가 있다면 그건 명시되지 않은 요구사항입니다.

2단계: 누락된 질문을 강제로 드러내기

빌드 전에 “설계를 바꿀 수 있는 미지”를 나열하세요. 예시:

• 필드의 진실의 출처는 누구인가(사용자 vs 시스템 vs 외부 API)?
• 데이터가 없거나 늦거나 중복되거나 잘못되면 어떻게 되는가?
• 성능이나 규모 기대치는 대략 얼마인가?

질문을 짧은 “오픈 질문” 섹션으로 프롬프트에 직접 적어 두세요.

3단계: 가정 목록을 유지하고 전환시키기

가정은 괜찮지만 눈에 보여야 합니다. 각 가정에 대해 하나를 선택하세요:

• 결정(Decision): 명시적으로 만들기(예: "이메일은 사용자별로 유일; 변경은 검증 필요")
• TODO: 소유자와 기한을 정해 추적할 후속 작업으로 표시(예: "TODO: 런칭 전 법무팀과 보존 정책 확인")

4단계: 작은 사이클로 반복하기

큰 프롬프트 하나 대신 2–3회의 짧은 반복을 하세요: 경계 명확화 → 데이터 모델 → API 계약. 각 패스는 모호함을 제거해야지 범위를 늘려선 안 됩니다.

빠른 승인 체크리스트(PM + 엔지니어)

• 성공 지표와 수용 기준이 작성되었는가
• 비목표가 명시되었는가
• 시스템 경계와 책임이 명명되었는가
• 핵심 엔터티/필드와 소유권이 정의되었는가
• 오류 케이스와 엣지 케이스가 설명되었는가
• 가정은 결정 또는 TODO로 전환되었는가

흔한 실수와 수정 방법

강한 팀도 작은 반복적 방식으로 명확성을 잃습니다. 다행히 대부분의 문제는 코드 작성 전에 쉽게 발견해 고칠 수 있습니다.

명확성 킬러들

모호한 동사는 설계 결정을 숨깁니다. “지원하다”, “처리하다”, “최적화하다”, “쉽게 만들다” 같은 단어는 무엇이 성공인지 말해주지 않습니다.

정의되지 않은 행위자는 소유권 공백을 만듭니다. “시스템이 사용자에게 알린다”는 어떤 시스템 컴포넌트, 어떤 사용자 유형, 어떤 채널인지 묻는 질문을 남깁니다.

누락된 제약은 우발적 아키텍처를 낳습니다. 규모, 지연, 개인정보 규칙, 감사 필요, 배포 경계를 명시하지 않으면 구현이 추측으로 이뤄지고 비용을 치르게 됩니다.

구현을 과도하게 지정하지 마라

자주 빠지는 함정은 도구와 내부를 지정하는 것입니다(“마이크로서비스 사용”, "MongoDB에 저장", "이벤트 소싱 사용")—실제로는 결과(“독립적 배포”, “유연한 스키마”, “감사 추적”)를 원할 때가 많습니다. 왜 원하는지 쓰고 측정 가능한 요구를 추가하세요.

예: "Kafka 사용" 대신 "이벤트는 7일 동안 내구성 있게 저장되고, 프로젝션 재구축을 위해 재생 가능해야 한다"고 쓰세요.

초기부터 모순을 피하라

모순은 종종 “실시간이어야 한다” + “배치로 괜찮다” 또는 "PII 저장 금지" + "이메일로 사용자에게 보여줌"처럼 나타납니다. 우선순위를 (Must/Should/Could)로 매기고 수용 기준을 추가해 동시에 성립할 수 없는 요구를 해결하세요.

안티패턴과 수정법

• 안티패턴: "온보딩을 단순하게 만들어라." 수정: "신규 사용자는 <3분 내에 온보딩 완료; 최대 6개 필드; 저장 후 재개 지원"

• 안티패턴: "관리자는 계정을 관리할 수 있다." 수정: 행동 정의(정지, MFA 재설정, 요금제 변경), 권한, 감사 로깅 명시

• 안티패턴: "높은 성능 보장" 수정: "읽기 P95 지연 <300ms at 200 RPS; 요율 제한 시 점진적 저하"

• 안티패턴: 혼용된 용어(“customer”, “user”, “account”) 수정: 작은 용어집을 추가하고 일관되게 사용

체크리스트와 다음 단계

명확한 프롬프트는 단순히 어시스턴트가 당신을 "이해"하게 만드는 것이 아닙니다. 추측을 줄여 시스템 경계가 더 깨끗해지고, 데이터 모델 충격이 줄며, 진화하기 쉬운 API를 만듭니다. 반대로 모호함은 계획하지 않은 마이그레이션, 실제 워크플로와 맞지 않는 엔드포인트, 반복되는 유지보수 작업으로 귀결됩니다.

재사용 가능한 한 페이지 체크리스트

아키텍처, 스키마, 또는 API 설계를 요청하기 전에 사용하세요:

• 목표: 어떤 사용자 결과가 일어나야 하는가? “완료”는 무엇인가?
• 범위: 무엇이 포함되고 무엇이 제외되는가? 나중에 미뤄야 할 것?
• 행위자 & 진입점: 누가 흐름을 트리거하는가(사용자, 관리자, 시스템 작업)?
• 핵심 워크플로: 2–5개의 해피패스 단계 및 주요 실패 케이스
• 데이터 정의: 중요한 엔터티, 필수 필드, ID, 관계
• 제약: 성능 목표, 개인정보 규칙, 보존, 감사 필요
• 통합: 외부 시스템, 이벤트, 큐, 소유권 경계
• API 기대치: 입력/출력, 오류 동작, 멱등성, 페이지네이션
• 수용 기준: 테스트 가능한 문장(엣지 케이스 포함)
• 비목표: 시스템이 하지 말아야 할 것을 명시
• 가정: 사실로 믿지만 확인하지 않은 것들
• 오픈 질문: 빌드 전에 답해야 할 사항들

다음 단계

1. 이번 주에 계획 중인 실제 기능 하나를 선택하세요.
2. 위 체크리스트로 프롬프트를 작성하세요.
3. 두 가지 설계를 생성하세요: "기존" 프롬프트에서 나온 것과 명확화된 프롬프트에서 나온 것.
4. 결과를 세 관점으로 비교하세요: 시스템 경계, 데이터 모델, API 계약.
5. 명확화된 프롬프트를 명세의 일부로 보관하세요(살아있는 문서가 됩니다).

더 실용적 패턴이 필요하면 /blog 또는 /docs의 지원 가이드를 확인하세요.