며칠 전 저는 다음과 같이 보이는 Claude Code 할 일 목록을 발견했습니다: ✓ 모든 스크린샷을 읽고 식별하기 ✓ 스크린샷을 4개 그룹으로 분류하기 ◼ 폴더를 생성하고 스크린샷을 이동/이름 변경하기 ☐ 스크린샷별로 비즈니스 요구사항 문서 (BRD) 작성하기. 네 단계입니다. 깔끔하죠. 바이브 코더 (vibe coder)가 스크린샷을 찍어 X에 "지금 AI는 정말 믿기지 않을 정도다"라는 캡션과 함께 올릴 법한 계획입니다. 그리고 솔직히 말해서, 이것은 좋은 계획입니다. 제가 실제로 보는 것들의 90%보다 낫습니다. 하지만 이 계획은 서로 조용히 모순되는 30개의 아름답게 작성된 문서를 만들어내는 것으로 가는 단 한 걸음 차이이기도 합니다. 이 전략이 왜 효과적인지, 어디서 무너지는지, 그리고 AI가 단 하나의 요구사항이라도 작성하게 하기 전에 제가 추가하고 싶은 단 한 단계가 무엇인지 설명해 드리겠습니다.

전략 해독 (The strategy, decoded)
무언가를 비판하기 전에, 인정할 것은 인정합시다. 이 워크플로우는 대부분의 바이브 코딩 (vibe coding) 세션이 갖지 못한 세 가지 장점을 가지고 있습니다.

첫째, 스크린샷을 진실의 원천 (source of truth)으로 사용합니다. 대부분의 사람들은 머릿속의 막연한 아이디어에서 바이브 코딩을 시작합니다 — "ClickUp처럼 저렴한 프로젝트 관리 앱을 만들어줘". AI는 고정할 구체적인 대상이 없으므로 일반적인 CRUD 앱을 환각 (hallucinate)하고, 당신은 다음 3일 동안 이를 수정하는 데 시간을 보냅니다. 스크린샷은 이를 뒤집습니다. 스크린샷은 구체적입니다. 그것들은 실제 상태, 실제 데이터, 실제 엣지 케이스 (edge cases)를 보여줍니다. 스크린샷을 보고 있는 AI는 막연한 바람을 듣고 있는 AI만큼 멀리 벗어날 수 없습니다.

둘째, 문서화하기 전에 분류합니다. 여기서 "4개 그룹" 단계는 숨은 영웅입니다. 그룹화가 없다면, 어휘를 공유하지 않는 30개의 단절된 요구사항 문서들을 갖게 될 것입니다. 그룹화는 패턴 인식 (pattern recognition)을 강제합니다 — 이 8개의 화면은 모두 동일한 엔티티에 대한 CRUD이고, 이 5개는 보고(reporting)이며, 이 3개는 설정(settings)이라는 식입니다. 이러한 클러스터링 (clustering)은 나중에 모듈(modules)이나 경계 컨텍스트 (bounded contexts)로 자연스럽게 매핑되며, 이는 문서를 코드로 변환하기 시작할 때 정확히 당신이 원하는 것입니다.

셋째, 원자적이고 검토 가능한 산출물 (artifacts)을 생성합니다. 스크린샷 하나당 하나의 BRD를 만드는 것입니다.

작고, 독립적이며, 차이점 비교 (diff)가 쉽고, "이 명세에 맞는 Livewire 컴포넌트를 생성해줘"와 같은 프롬프트와 함께 Claude Code에 전달하기 쉬운 형태입니다. 프로젝트 전체를 다시 작성할 필요 없이 하나의 BRD(비즈니스 요구사항 문서) 단위로 반복 작업 (iterate)을 수행할 수 있습니다. 이것은 진정으로 훌륭한 토대입니다. 만약 여기서 읽기를 멈추고 바로 실행에 옮긴다 해도, 여러분은 대부분의 팀보다 앞서 나갈 것입니다. 하지만 여기서 멈추지 않겠습니다.

실패 사례 #1: 공유된 어휘 사전이 없는 BRD
분류 (categorization) 단계에서 바로 BRD 작성으로 건너뛸 때 발생하는 현상은 다음과 같습니다. Screenshot 03은 고객 목록을 보여줍니다. AI는 다음과 같이 작성합니다: "시스템은 Customers의 페이지네이션된 목록을 표시해야 한다." Screenshot 11은 고객 상세 페이지를 보여줍니다. AI는 다음과 같이 작성합니다: "Member 프로필에는 ...이 포함되어야 한다." Screenshot 19는 동일한 인물이 로그인하는 모습을 보여줍니다. AI는 다음과 같이 작성합니다: "인증 시, User는 ...로 리다이렉트된다." Screenshot 24는 B2B 연락처 보기 화면입니다. AI는 다음과 같이 작성합니다: "각 Account는 기본 연락처를 가진다..."

Customer, Member, User, Account. 네 개의 단어입니다. 동일한 엔티티 (entity)임에도 불구하고, 문서가 다르고, 작성 세션이 다르며, 바이브 (vibes)가 다릅니다. 이제 이 30개의 BRD를 모두 Claude Code에 입력하고 마이그레이션 (migrations)을 생성하라고 요청한다고 상상해 보십시오. 어떤 일이 벌어지는지 지켜보십시오. 여러분은 customers 테이블, members 테이블, users 테이블 (아마도 Laravel의 기본값), 그리고 accounts 테이블을 얻게 됩니다. 이 중 어느 것도 서로를 참조하지 않습니다. Eloquent 관계 (relationships)는 추측에 의존하게 됩니다. Actions의 절반은 Customer $customer를 받고, 나머지 절반은 User $user를 받으며, 폼 요청 (form requests)에서는 이 둘을 혼용하여 사용합니다.

이것은 제가 스크린샷 기반 워크플로우에서 보는 가장 흔한 실패 사례이며, 데모에서는 절대 나타나지 않습니다. 이것은 여러분의 코드베이스 절반이 서로 엇갈린 이야기를 하고 있다는 사실을 깨닫게 되는 3주 차에 나타납니다. 해결책은 어휘 추출 (vocabulary extraction) 단계입니다.

어떠한 비즈니스 요구사항 문서 (BRD)가 작성되기 전에, 여러분은 다음과 같은 형태의 glossary.md 파일을 생성해야 합니다:

용어 (Term)	정의 (Definition)	별칭 (Aliases)
Customer	서비스를 구매하는 조직	Account, Client
Member	Customer 내의 개별 사용자	User, Contact, Staff
Order	구매 트랜잭션	Sale, Invoice (비공식)

이제 AI가 BRD-019를 작성할 때, 이 용어 사전 (glossary)을 참조하여 "Member"와 "User"가 동일한 개념의 별칭임을 확인하고, 하나의 표준 용어 (canonical term)를 선택하게 됩니다. 갑자기 여러분의 30개 문서가 모두 동일한 언어로 말하기 시작합니다.

실패 모드 #2: 스크린샷 중심의 설계는 시스템 설계가 아니다

스크린샷은 사용자가 무엇을 보는지를 알려줍니다. 하지만 시스템이 무엇을 하는지는 알려주지 않습니다. 어떤 로그인 화면이라도 살펴보십시오. 스크린샷은 이메일, 비밀번호, 그리고 버튼이 있는 양식을 보여줍니다. BRD는 다음과 같이 스스로 작성됩니다: "사용자가 자격 증명을 입력하면, 시스템이 인증을 수행하고, 사용자는 대시보드로 리다이렉트된다."

스크린샷이 보여주지 않는 것들:

• 5회 로그인 실패 후 계정을 잠그는 속도 제한기 (rate limiter)
• 성공 여부와 관계없이 모든 로그인 시도를 기록하는 감사 로그 (audit log) 항목
• 이번 달에 새로운 사용자가 처음 로그인할 때 CRM으로 발송되는 웹훅 (webhook)
• 사용자의 권한 캐시 (permission cache)를 재계산하는 백그라운드 작업 (background job)
• 비밀번호 필드를 완전히 건너뛰는 SSO 리다이렉트 경로
• 모바일 클라이언트가 사용하며 이 양식을 전혀 렌더링하지 않는 API 엔드포인트 (API endpoint)

이 중 그 어느 것도 사진에는 나타나지 않습니다. 하지만 이 모든 것은 시스템 안에 존재합니다. 만약 여러분이 SaaS를 구축하고 있다면 — 특히 ID 제공자 (identity providers), API 게이트웨이 (API gateways), 웹훅 라우터 (webhook routers)와 같은 허브 앤 스포크 (hub-and-spoke) 패턴을 사용하는 제가 주로 작업하는 유형의 아키텍처라면 — 아키텍처의 절반은 UI 뒤에 존재합니다. 순수하게 스크린샷에만 의존하는 워크플로우는 이를 완전히 놓치게 될 것입니다.

해결책은 (스크린샷 단위가 아닌) 그룹당 하나의 단계를 추가하여, UI 이외의 고려 사항들을 명시적으로 나열하는 것입니다:

• 백그라운드 작업 (Background jobs) 및 예약된 작업 (Scheduled tasks)
• 방출 및 소비되는 웹훅 (Webhooks)
• 권한 매트릭스 (Permission matrix) (누가 무엇을 할 수 있는지)
• 감사 및 관찰 가능성 (Audit and observability) 요구 사항
• 비-UI 소비자들을 위한 API 계약 (API contracts)
• 다른 모듈과의 통합 지점 (Integration points)

이 과정이 첫 번째 시도부터 완벽하게 포괄적일 필요는 없습니다. 그저 커튼 뒤를 살펴봐야 한다는 사실을 기억할 수 있도록 존재하기만 하면 됩니다.

실패 사례 #3: 흔적을 잃어버림
기존 워크플로우는 "폴더를 생성하고 스크린샷을 이동/이름 변경하라"고 말합니다. 좋습니다. 하지만 무엇으로 이름을 변경해야 할까요? 만약 스크린샷이 screenshot_001.png, screenshot_002.png와 같이 변한다면, 당신은 인코딩할 수 있었던 유일하게 유용한 요소인 추적 가능성 (Traceability)을 잃게 됩니다. 3개월 후, Livewire 컴포넌트를 디버깅하며 "이것의 원래 요구 사항이 무엇이었지?"라고 알고 싶을 때, 다음과 같이 추적할 수 있어야 합니다:

• 코드: app/Livewire/CustomerList.php
  ↑ BRD: docs/brd/g01-s03-customer-list.md로부터 생성됨
  ↑ Screenshot: screenshots/g01-customers/s03-list-view.png로부터 추출됨

명명 규칙 (Naming convention)은 이 작업을 조용히 대신 수행해 줍니다. g01-s03-customer-list.png와 같은 이름은 즉시 다음과 같은 정보를 알려줍니다: 그룹 1, 화면 3, 고객 목록. BRD는 동일한 ID를 상속받습니다. 생성된 코드는 Docblock에서 이를 참조합니다. 이제 당신은 픽셀에서 프로덕션에 이르기까지의 관리 연속성 (Chain of custody)을 갖게 됩니다. 이는 이름을 변경할 때 비용이 전혀 들지 않지만, 이를 건너뛴다면 모든 것을 잃게 됩니다.

실패 사례 #4: 일관성 없는 BRD 구조
AI가 각 BRD를 자유롭게 작성하도록 내버려 두면, 구조가 조금씩 다른 30개의 문서를 얻게 될 것입니다. 어떤 것은 "사용자 스토리 (User Stories)" 섹션이 있고, 다른 것은 "유스 케이스 (Use Cases)", 세 번째는 "기능 요구 사항 (Functional Requirements)", 네 번째는 바로 동작의 번호 매겨진 목록으로 넘어갑니다. 이것은 바이브 (Vibe)의 문제가 아니라 파싱 (Parsing)의 문제입니다. 나중에 이 BRD들을 Claude Code에 입력하여 코드를 생성하려고 할 때, AI는 예측 가능한 구조를 가질 때 훨씬 더 잘 작동합니다. 동일한 헤딩, 동일한 순서, 섹션에 대한 동일한 어휘를 사용해야 합니다.

루프(loop)를 돌기 전, 템플릿을 한 번 정의하세요:

{Screen ID} — {Screen Name}

Purpose (목적)

이 화면이 존재하는 이유를 한 문장으로 기술합니다.

Actors & Permissions (액터 및 권한)

누가 이 화면에 접근할 수 있는지, 그리고 어떤 역할 기반 제어(role gates)가 적용되는지 기술합니다.

Entities Referenced (참조 엔티티)

이 화면이 상호작용하는 용어 사전 (glossary) 용어 목록입니다.

User Actions (사용자 액션)

각 액션에 대해: 트리거 (trigger), 유효성 검사 규칙 (validation rules), 부수 효과 (side effects), 성공 상태 (success state), 실패 상태 (failure state)를 기술합니다.

States (상태)

빈 상태 (empty state), 로딩 상태 (loading state), 에러 상태 (error state), 성공 상태 (success state).

Non-Functional Notes (비기능적 참고 사항)

성능 기대치, 접근성 (accessibility), 감사 요구 사항 (audit requirements).

Open Questions (미결 질문)

스크린샷이 알려주지 않아 확인이 필요한 사항들.

이제 모든 비즈니스 요구사항 문서 (BRD)가 동일한 형태를 갖게 됩니다. Claude Code는 "저장 버튼에 어떤 유효성 검사 규칙이 적용되는가"를 찾기 위해 정확히 어디를 봐야 할지 알게 됩니다. 리뷰어들은 어디에 코멘트를 남겨야 할지 정확히 알게 됩니다. 미래의 당신은 과거의 당신에게 감사하게 될 것입니다.

개선된 워크플로우 (The refined workflow)

이 모든 것을 종합하여, 제가 실제로 실행할 프로세스는 다음과 같습니다:

1. ✓ 모든 스크린샷을 읽고 식별합니다.
2. ✓ 그룹별로 분류합니다 (화면 유형이 아닌 기능 영역별로).
3. ◼ 폴더를 생성하고 추적 가능한 ID(g{NN}-s{NN}-{slug})로 이름을 변경합니다.
4. 신규: 공유 엔티티 (entities), 열거형 (enums), 권한 (permissions)을 추출하여 → glossary.md를 생성합니다.
5. 신규: BRD 템플릿을 한 번 정의합니다.
6. ☐ 용어 사전을 참조하여 스크린샷별로 BRD를 작성합니다.
7. 신규: 그룹별로 비-UI 관련 사항 (jobs, webhooks, audits, APIs)을 문서화합니다.
8. 신규: 합성 (Synthesise) — 도메인 모델 (domain model), 모듈 경계 (module boundaries), 액션 인벤토리 (Action inventory)를 생성합니다.

4단계, 5단계, 7단계, 그리고 8단계가 단순한 데모를 하나의 시스템으로 탈바꿈시키는 단계입니다. 참고로, 8단계야말로 이 방식이 강력해지는 지점입니다.

용어 사전, 일관된 형식의 BRD, 그리고 비-UI 관련 사항들이 매핑되어 있다면, 다음과 같은 프롬프트와 함께 이 모든 것을 Claude Code에 입력할 수 있습니다:

"이 용어 사전과 BRD들을 바탕으로, Customers 모듈에 대한 관계가 포함된 Eloquent 모델, Form Requests, invokable Actions, 그리고 Pest 테스트를 생성해줘."

그러면 출력 결과가 실제로 딱 들어맞을 것입니다. 명명 규칙 (naming)은 일관될 것이고, 관계 (relationships)는 논리적일 것이며, 테스트는 올바른 엔티티 (entities)를 참조할 것입니다.

이는 당신이 AI가 작동할 수 있도록 일관된 컨텍스트 (context)를 제공하는 상류 (upstream) 작업을 수행했기 때문입니다. 스크린샷에는 아무도 적어두지 않는 교훈: 만약 이 글에서 한 가지만 얻어 가신다면, 바로 이것입니다. AI는 추출 (extraction)에 매우 탁월합니다. 하지만 무엇을 추출할지에 대한 스키마 (schema)는 여전히 인간이 정의해야 합니다. 스크린샷에서 요구사항 정의서 (BRD)로 이어지는 워크플로우 (workflow)는 마치 AI가 모든 일을 하는 것처럼 보입니다. 하지만 그렇지 않습니다. AI는 타이핑 (typing)을 하고 있을 뿐입니다. 분류 (categorization), 어휘 (vocabulary), 템플릿 (template), 모듈 간의 경계 (boundaries between modules)와 같은 사고 (thinking) 과정은 여전히 당신의 몫입니다. 이러한 단계들을 건너뛰는 것은 속도를 높여주지 않습니다. 그저 프로젝트의 나중 단계로 비용을 미루는 것일 뿐이며, 그 시점에는 수정 비용이 10배 더 비싸집니다. 바이브 코딩 (Vibe coding)은 AI가 결정하도록 내버려 두는 것이 아닙니다. AI의 결정이 더 이상 무작위적이지 않도록, 충분히 구조화된 세계를 AI에게 제공하는 것입니다. 용어 사전 (glossary) 단계를 추가하세요. 템플릿 (template)을 정의하세요. 스크린샷이 보여주지 못하는 것을 문서화하세요. 파일 이름에 그 흔적을 인코딩 (encode)하세요. 그런 다음 거침없이 실행하세요. 만약 당신의 프로젝트에서 스크린샷 기반의 워크플로우를 시도해 보았다면, 어떤 실패 모드 (failure modes)를 겪었는지, 그리고 그것을 어떻게 해결했는지 듣고 싶습니다. 댓글을 남겨주세요.