Claude Code로 MVP 만들 때 설계는 어디까지 해야 하나

Claude Code가 구현 속도를 높일수록 설계는 더 중요해진다. 다만 모든 요구사항과 미래 구조를 먼저 확정하려 하면 AI의 속도도 사라진다. 그렇다면 MVP를 시작하기 전에 무엇을 고정하고, 무엇을 구현 과정에서 바꿔야 할까.

설계 범위는 문서 분량보다 검증할 위험이 결정한다

MVP는 완성품의 축소판이 아니다. 가장 불확실한 가정을 적은 비용으로 확인하는 작동 가능한 제품이다. SVPG는 제품 위험을 가치, 사용성, 구현 가능성, 사업 적합성으로 나눈다. GOV.UK 서비스 매뉴얼도 가장 위험한 가정을 시험할 만큼만 프로토타입을 만들라고 권한다.

Claude Code를 쓸 때도 위험부터 한 문장으로 적어야 한다. 고객이 기능을 원하는지 모른다면 사용 흐름을 검증한다. 외부 API가 불안하다면 연동 경로부터 시험하고, 복잡한 승인 규칙이 문제라면 화면보다 판정 로직을 먼저 만든다.

커뮤니티에서는 목적과 현장 맥락을 충분히 전달해야 한다는 의견이 많았다. 처음부터 전체 아키텍처를 완성하려 들면 수정 비용만 커진다는 지적도 나왔다. 두 관점은 충돌하지 않는다. 목적과 제약은 일찍 고정하되 구현 구조는 학습에 맞춰 움직이면 된다.

SOP와 KPI를 코드가 검증할 수 있는 조건으로 바꾼다

Claude Code는 조직의 암묵지를 알지 못한다. 담당자가 어떤 순서로 판단하는지, 예외를 누가 승인하는지, 실패가 무엇인지 입력해야 한다. 현업의 SOP와 KPI는 배경 설명이 아니라 기능의 경계이자 테스트 조건이다.

환불 승인 도구를 예로 들면 docs/problem.md에 사용자, 현재 절차, 해결할 병목, 제외 범위를 적는다. docs/sop.md에는 입력 자료, 처리 순서, 승인 권한, 예외 상황을 기록한다. docs/metrics.md에는 처리 시간, 재작업률, 오류율처럼 관찰할 지표를 둔다. 목표 수치는 Claude가 만들게 하지 말고 업무 책임자가 채워야 한다.

기능 단위 요구사항은 SPEC.md로 옮긴다. Atlassian은 사용자 스토리가 사용자와 목적을 설명하고 인수 조건은 성공 상태를 검증할 수 있게 만든다고 설명한다. Martin Fowler가 소개한 Given-When-Then 형식을 쓰면 SOP를 테스트로 바꾸기 쉽다.

조건은 다음과 같이 좁힐 수 있다. 유효한 주문이 있고 담당자가 정책 범위 안의 환불을 요청하면 시스템은 승인 결과와 판단 근거를 저장해야 한다. 권한 밖의 금액이면 승인하지 않고 상위 담당자에게 넘겨야 한다. 이 정도면 Claude Code가 구현과 테스트를 같은 목표에 맞출 수 있다.

CLAUDE.md에는 변하지 않는 규칙만 남긴다

Anthropic 공식 가이드는 /init으로 초기 CLAUDE.md를 만들고 계속 다듬으라고 안내한다. 이 파일은 매 세션마다 읽히므로 빌드 명령, 테스트 방법, 폴더 경계, 특별한 코딩 규칙을 넣는 곳이다. 긴 업무 매뉴얼과 자주 바뀌는 기획서는 별도 문서나 Skill로 분리하는 편이 낫다.

MVP 저장소라면 CLAUDE.md에 네 종류만 남겨도 충분하다. 사용 중인 실행·검사 명령, 현재 아키텍처의 경계, 반드시 지켜야 할 업무 규칙, 작업 완료 전에 돌릴 검증 절차다. 결제 코드는 services/payments 밖에서 작성하지 않는다처럼 구체적으로 써야 한다.

써본 사람들 사이에서는 거대한 지침 파일이 오히려 중요한 규칙을 묻어버린다는 반응도 있다. Anthropic 역시 짧고 구체적인 지침을 권한다. 코드에서 바로 알아낼 수 있는 내용은 빼라고도 설명한다. 현황과 다음 작업까지 모두 CLAUDE.md에 누적하는 방식은 빠르게 한계에 닿는다.

Plan Mode에서는 전체 제품이 아니라 다음 조각을 설계한다

Anthropic이 권하는 기본 흐름은 탐색, 계획, 구현, 검증이다. claude --permission-mode plan으로 시작하거나 세션에서 Plan Mode를 켜면 Claude는 파일을 읽고 계획을 세우되 수정하지 않는다. 여러 파일을 바꾸거나 낯선 영역을 건드릴 때 특히 유용하다.

첫 프롬프트에서는 구현을 맡기지 않는다. docs/problem.md, docs/sop.md, docs/metrics.md를 읽고 기존 코드에서 관련 흐름을 찾게 한다. 이어 빠진 업무 규칙을 질문하고 이번 단계에서 수정할 파일과 테스트를 제안하게 한다. 계획에 범위 밖 항목도 명시하면 기능이 새는 일을 줄일 수 있다.

승인한 뒤에는 하나의 세로 조각만 구현한다. 입력부터 저장과 결과 표시까지 사용자가 가치를 확인할 수 있는 작은 흐름이어야 한다. 화면 전체를 만든 뒤 API를 붙이는 수평 분할보다 피드백을 빨리 얻는다.

작업 지시는 이 계획의 첫 조각만 구현하고, 인수 조건을 테스트로 작성한 뒤 실행 결과를 보여줘처럼 준다. Anthropic 가이드는 테스트, 빌드, 린터, 화면 비교처럼 Claude가 읽을 수 있는 검증 수단을 제공하라고 강조한다. 반복 검사가 필요하면 PostToolUse hook으로 편집 뒤 포매터나 테스트를 실행할 수도 있다.

유연한 아키텍처는 추상화보다 작은 변경에서 나온다

변경 가능성에 대비한다며 범용 플러그인 구조나 복잡한 계층부터 만들 필요는 없다. Fowler의 YAGNI 원칙은 확인되지 않은 미래 기능을 미리 구현하지 말라고 한다. 그렇다고 코드를 바꾸기 쉽게 만드는 리팩터링과 자동화 테스트까지 생략하라는 뜻은 아니다.

스키마에도 같은 기준을 적용한다. 처음부터 모든 속성을 담는 거대한 JSON 필드를 만드는 대신 현재 흐름에 필요한 명확한 테이블을 만든다. 변경은 작은 마이그레이션 파일로 남겨 애플리케이션 코드와 함께 버전 관리한다. 진화형 데이터베이스 설계는 큰 개편보다 작고 연속적인 마이그레이션을 권한다.

실제 작업 루프는 짧다. 업무 문서에서 위험 하나를 고른 뒤 Plan Mode로 관련 코드를 탐색한다. SPEC.md에 한 조각의 인수 조건을 적고 구현과 테스트를 진행한다. 사용 결과가 KPI를 움직였는지 확인한 다음 문서와 스키마를 고쳐 다음 조각으로 넘어간다.

Claude Code 시대의 설계는 미래를 모두 맞히는 작업이 아니다. 다음 실험이 틀렸을 때 무엇을 배울지 정하고 코드와 데이터가 그 학습을 견디게 만드는 일이다.