서론

안녕하세요. 주식회사 mediba에서 프론트엔드 엔지니어를 하고 있는 yu_ari입니다.

이 기사는, 현재도 한창 개발이 진행 중인 신규 사업 프로젝트에서 "사양이 흔들리기 쉽고 납기가 짧은 대규모 개발을 어떻게 성공시킬 것인가"를 모색한 결과, 도달하게 된 개발 플로우에 관한 이야기입니다.

결론부터 말씀드리면, AI(주로 Claude Code 등)의 파워를 120% 끌어냄으로써, 로직의 코딩은 물론이고 번거로워지기 쉬운 테스트 코드(UT/IT/E2E)에 관해서도 스스로 작성하는 일이 "거의 제로"가 되었습니다.

이 플로우를 도입함으로써 개발 효율이 비약적으로 향상되었을 뿐만 아니라, 비엔지니어(PO나 디자이너)와의 인식 차이가 설계 단계에서 거의 해소되었습니다. 단납기 개발에서 "재작업(手戻り)"으로 고통받고 계신 분, AI를 개발의 상류 단계부터 더 적극적으로 참여시키고 싶은 분들에게 참고가 된다면 좋겠습니다.

상황과 과제: 왜 단납기 프로젝트는 "재작업"으로 폭발하는가?

신규 사업 개발은 언제나 시간과의 싸움입니다.

스테이크홀더(Stakeholder)는 많고, 납기는 짧습니다. 그럼에도 불구하고 사양이 아직 확정되지 않은 상태에서 여러 팀이 병행하여 움직이는 경우가 허다합니다.

참고로, 이번 프로젝트에서는 백엔드의 "API 설계 초안(Draft)" 자체는 선행되어 존재하고 있었습니다.

데이터 구조의 베이스는 보이지만, 화면 사양이 완전히 Fix되기 전에 프론트엔드 개발을 병행하여 진행해야 했기 때문에, "프론트엔드 측에서 그 데이터를 어떻게 화면에 녹여내고, 어떤 조건으로 나누어 보여줄 것인가(화면 측의 사양이나 로직)"를 어떻게 재작업 없이 확정 짓느냐가 프로젝트 전체의 핵심이었습니다.

단납기 대규모 프로젝트에서 가장 무서운 것은 "구현이 끝난 뒤의 '생각했던 것과 다르다'로 인한 재작업"입니다. 화면 사양 변경이 일어나면, 공들여 병행해서 만들어 놓은 API까지 연쇄적으로 영향을 받아 프론트엔드와 백엔드 양측의 스케줄이 붕괴될 수 있습니다.

개발 현장을 관찰하면서, 저는 "화면 측의 로직이나 각 파트의 '의미'가 정의되지 않은 상태"야말로 재작업을 일으키는 본질적인 원인이라고 확신했습니다.

문제의 본질: 요구되는 것은 "How"가 아니라 "Why"의 언어화

재작업이 발생하는 원인을 파고들어가 보니 매우 단순한 구조가 보였습니다.

각 파트·페이지·처리가 "How(어떻게 화면에 보여줄 것인가·어떻게 구현할 것인가)"로만 이야기되고, 정작 중요한 "Why(왜 이 파트가 필요한가, 왜 이런 동작인가)"가 팀 전체 내에서 명확하게 정의되지 않은 채 구현으로 넘어가 버리는 상태가 문제입니다.

우리는 무심코 "화면의 모습이나 배치(How)"에만 눈길이 가고, 각 파트의 "존재 이유(Why)"까지 깊이 파고들어 생각하는 것을 놓치기 쉽습니다.

【구체적인 예】 "배지를 달아달라"는 오더의 함정

예를 들어, 특전 교환 서비스에서 스테이크홀더로부터 "이 영역에 주목을 끌 수 있는 배지를 달아달라(How)"라는 요청을 받았다고 가정해 봅시다.

여기서 "How"인 상태로 받아들여 버리면, "배지의 표시 조건은?", "사용자 상태에 따라 어떻게 나누어 보여줄 것인가?", "기간 외에는 어떻게 할 것인가?"와 같이 고려해야 할 복잡한 로직(사양의 팽창)이 무한히 생겨나게 됩니다.

하지만 여기서 한 걸음 멈춰서 "왜(Why)"를 파고들어 봅니다.

"Why: 왜 배지를 달고 싶은가?" ➔ "Answer: 사용자의 특전 교환을 촉진하고 싶으니까"

목적이 "교환 촉진"이라는 것을 알게 되면, "그렇다면 사용자가 실제로 교환할 수 있는 '기간 중'의 조건만 고려하면 충분하겠네요"라고 상대방의 본질적인 니즈가 깔끔하게 보입니다.

"Why"가 명확해지면, 불필요한 케이스를 고려할 필요가 없어져 구현 스코프(Scope)를 압도적으로 좁힐 수 있습니다. 나아가 만약 스케줄 공수가 박한 상황이라면, 이 Why를 베이스로 하여 "이번에는 목적을 달성하기 위해 여기까지만 구현하고, 나머지 패턴은 줄입시다"라는 논리적인 사양 축소 협상 카드로도 강력하게 기능합니다.

이처럼 인간이 먼저 "Why"를 정리하여 스코프를 적정화하고, 그 극한까지 날카롭게 다듬어진 사양을 AI에게 인계하는 것이야말로 단납기 개발을 성공시키기 위한 대전제입니다.

반대로 이 Why의 정의를 게을리하고 겉모습인 "How"만으로 어렴풋이 개발을 병행하게 되면, 인식의 차이나 불필요한 사양의 비대화가 축적되어 구현 후에 대폭발하게 된다고 생각했습니다.

왜 "Excel"로 의미를 정리했는가?

"How에 대한 논의를 그만두고, 구현 전에 철저하게 Why를 정의하면 된다"

그렇게 생각한 나는 수동으로 사양 정리를 시작했습니다. 그 과정에서 도구 선택에는 우여곡절이 있었습니다.

처음으로 시도한 것은 Figma였습니다. 하지만 Figma는 강력한 "How(어떻게 보이는가)"를 위한 도구입니다. Figma로 표현할 수 있는 것은 "어느 한 상태의 정적인 화면"이 중심이며, "로그인 상태일 때는 이렇게 표시되고, 미로그인 상태일 때는 이렇게 변한다"라는 상태의 변화나, 그 변화를 일으키는 복잡한 조건 분기(Why의 로직)를 Figma만으로 전달하기는 어려웠습니다.

외형이라는 How의 노이즈를 걷어내고, 언어로 Why를 끝까지 파고들기 위해 도달한 곳이 누구나 익숙한 Excel(Spreadsheet)이었습니다.

Excel에 정리한 「5가지 요소」

Excel에는 각 페이지, 각 파트, 각 처리에 대해 다음과 같은 내용을 철저하게 언어로 정리하여 모았습니다.

【Why】 이 파트는 무엇을 위해 존재하는가 (존재 이유·목目的)
【Why】 어떤 상태의 사용자에게 표시되는가 (대상 정의)
어떤 조건에서 표시되고, 어떤 조건에서 사라지는가 (분기 로직)
상태가 변했을 때, 무엇이 어떻게 변하는가 (변화 정의)
여러 조건이 겹쳤을 때, 무엇을 우선하는가 (우선순위)

【여기가 핵심】 「전제 조건」과 「초점이 되는 조건」을 분리하기

Excel로 정리할 때 가장 의식한 것이 「전제 조건」과 「초점이 되는 조건」을 명확하게 나누어 구조화하는 것입니다.

• 전제 조건: 해당 파트가 표시되기 위한 대전제 (예: "로그인한 사용자에게만 표시한다" 등. 충족되지 않으면 애초에 화면에 나타나지 않음).
• 초점이 되는 조건: 전제를 충족한 상태에서, 파트의 외형이나 상태를 결정하는 중심축 (예: "버튼의 활성화 여부는 권한 유무에 따라 결정된다" 등).

이 두 가지가 혼재되어 있으면 AI도 인간도 조건 분기의 구조를 오해합니다. 이곳을 깔끔하게 정리한 Excel이야말로 최강의 "AI를 위한 인풋(지시서)"이 됩니다.

AI 주도 워크플로우의 전체상 (8단계)

Excel로 「의미와 Why」를 정리하고, 그것을 AI에게 전달하여 설계와 구현을 맡긴다. 이 사이클을 반복하는 과정에서 자연스럽게 정교해진 것이 아래의 8단계 워크플로우입니다.

워크플로우 도표

중요한 방어책: 모든 단계에 「인간의 확인 게이트」를 설치하기

AI에게 한꺼번에 코드를 쓰게 하는 것은 절대 금물입니다.

Step4의 「Mock을 통한 전체 확인」은 특히 큰 이벤트이지만, 사실 그 외의 모든 단계에서도 AI가 출력한 내용을 인간이 그때마다 확인·승인하며 다음으로 진행하는 구조로 만들었습니다. 이전 단계의 작은 어긋남을 그 자리에서 바로잡음으로써, "오류가 후속 단계 전체를 오염시켜 마지막에 쓰레기 같은 코드가 만들어지는" 사태를 완전히 방지하고 있습니다.

각 단계의 상세 내용

Step1: 용어집 추출

첫 번째 단계는 Excel에 작성한 도메인 용어의 의미를 프로젝트의 「공통 사전」으로 정리하는 것입니다.

신규 사업에서는 "사용자 상태(User Status)", "교환 기간" 등 고유 용어가 난무하지만, 이 정의가 흔들리면 AI는 100% 오해합니다.

인간이 Excel 내의 「용어집 시트」에 정리한 내용을 AI가 파싱(Parsing)하여 Markdown 파일로 저장하게 합니다.

Excel 측에서는 각 화면 시트의 셀에서 [{사용자 상태}]와 같이 대괄호로 참조하는 규칙을 만듭니다. 이를 통해 이후 단계에서 AI가 이 표기법을 발견했을 때, 자동으로 용어집의 정의로 확장하여 처리할 수 있게 됩니다.

Step2: API 사양서와의 정합성 조사

"API 설계 초안(Draft)이 선행하여 존재한다"라는 이번 프로젝트의 이점이 가장 빛을 발하는 단계가 바로 이 단계입니다.

Excel에 인간이 기재한 "화면 측에서 사용하고 싶은 표시 항목"이 공유된 API 사양서 초안과 모순되지 않는지 AI가 체크하게 합니다.

AI는 다음과 같은 관점에서 대조하여 리포트를 출력합니다.

• API의 존재 확인: 상정하고 있는 엔드포인트가 실제로 존재하는지
• 필드의 존재 확인: 참조하고 있는 응답 필드(Response Field)가 존재하는지
• 부족 정보의 특정: 표시 로직을 구성하는 데 있어, API 사양서만으로 부족한 정보가 없는지

AI의 출력 리포트 예시:

「구현하면서 API 고려 누락을 깨닫는 것」은 너무 늦습니다. 이 설계 단계에서 불일치를 검지할 수 있다면, 백엔드(Backend) 팀이 API를 정식으로 Fix시키기 전에, 「프론트엔드에서 이 분기 로직을 구성하고 싶으니, 이 필드를 추가해 주세요」 또는 「타입(Type)을 이렇게 바꿔 주세요」와 같은 건설적인 피드백을 조기에 전달할 수 있습니다. 결과적으로 프론트엔드와 백엔드 양측의 재작업(Retake) 비용을 최소한으로 억제할 수 있었습니다.

Step3: 화면 사양서 작성

API와의 정합성이 맞으면, AI에게 Excel 데이터를 구조화된 Markdown 형식의 「화면 사양서」로 변환하게 합니다.

여기서 AI에게 부여하는 가장 중요한 제약(Prompt)이 이것입니다.

⚠️ 엄수 규칙: 사양서에 명시되지 않은 정보를 AI 자신의 판단으로 추측하거나 보완하는 것을 「절대 금지」한다.

현행 코드나 다른 화면을 보고 「아마 이럴 것이다」라고 AI가 선의로 보완한 사양은 높은 확률로 틀려 있습니다. 불명확한 점은 모두 「확인 필요 사항 (Todo)」으로서 인간에게 리포트하게 합니다.

## 확인 필요 사항 (사람이 판단해 주세요)
다음 항목은 Excel에 기재되어 있지 않아 설계서에 포함하지 않았습니다.
- [ ] 잔액이 부족한 경우의 버튼 표시/비활성화 로직
...

이 확인 게이트(Gate)를 통해, 모호한 사양이 그대로 코드화되는 리스크를 근절합니다.

Step4: 인터랙티브한 모크(Mock) 화면 생성

개인적으로, 이 워크플로우 중에서 가장 패러다임 시프트(Paradigm Shift)를 느낀 단계입니다.

AI에게 사양서를 읽히고, 「실제로 브라우저에서 동작하는 HTML 모크 화면」을 생성하게 합니다.

단순한 정지 영상(컴프, Comp)이 아닙니다. 화면의 표시 조건을 실시간으로 척척 전환할 수 있는, 3컬럼 구성의 인텔리전트한 모크입니다.

• 왼쪽 컬럼 (컨트롤 패널): 「미로그인/로그인 완료」, 「기간 전/기간 중/기간 후」, 「재고 있음/없음」 등의 상태를 셀렉트 박스로 전환할 수 있음. 불가능한 조건의 조합은 자동으로 disabled 처리되는 제어 기능 포함.
• 중간 컬럼 (프리뷰): 스마트폰 폭(375px)으로 실제 화면이 실시간 렌더링됨. 「왜 그렇게 표시되는가」에 대한 플로우차트(Flowchart)도 시각화 가능.
• 오른쪽 컬럼 (섹션별 상태): 각 컴포넌트가 「왜 지금 표시되지 않는가 (예: 기간 내이지만 재고가 없기 때문)」에 대한 이유를 초록색(Pass)과 빨간색(Error) 배지로 한눈에 확인 가능.

왜 이것이 인식 맞추기에 효과적인가?

말로 된 사양서를 보며 「미로그인 상태이면서 기간 외일 때는……」이라고 논의해도, 인간끼리의 뇌 내 동기화에는 한계가 있습니다.

이 움직이는 모크가 있다면, PO나 디자이너와 함께 컨트롤을 조작하면서 「아, 이 상태일 때 버튼이 사라지면 곤란하겠네」, 「이 이면 패턴은 사양을 생각하지 못했어!」와 같은 대화가 코드를 한 줄도 쓰기 전 단계에서 발생합니다. 여기서 사양을 수정하는 것이 가장 효율적입니다.

Step5: 컴포넌트 설계서 작성

모크로 합의가 이루어지면, AI에게 컴포넌트 설계서를 만들게 합니다.

저희 프로젝트에서는 선행하는 API 초안의 데이터 구조를 활용하기 위해, 프론트엔드에서도 로직과 외관을 깔끔하게 분리하는 Container-Presenter 패턴을 채택하고 있습니다.

AI는 「어떤 파일을 Server / Client Component로 할 것인가」, 「Props로 무엇을 전달할 것인가」를 자동 설계하지만, 여기서도 하나의 확인 게이트를 거칩니다. 그것은 바로 조건 분기의 「초점(관심사, Concern)」 확인입니다.

AI의 확인 메시지 예시:

「ImageContainer와 ButtonContainer 양쪽에서 『재고 소진 판정』이 사용되지만, 전자는 『오버레이 표시 여부』, 후자는 『버튼 활성화 여부』가 초점입니다. 이것들을 공통화하지 않고 개별적으로 판정을 기술해도 될까요?」

동일한 조건이라도 컴포넌트에 따라 「알고 싶은 목적(초점)」이 다를 수 있습니다. 이를 AI가 임의로 공통화하여 캡슐화 (Encapsulation)를 깨뜨리지 않도록, 인간에게 승인을 요청하게 합니다.

Step6: 테스트 시나리오 작성

컴포넌트 설계도를 바탕으로, AI가 UT (Unit Test) / IT (Integration Test) / E2E (End-to-End) 3개 계층의 테스트 시나리오 (Markdown)를 자동으로 생성합니다.

• UT: 유틸리티 함수의 경계값이나, route.ts의 리다이렉트 처리 등의 망라.
• IT: Step3에서 만든 「표시 조건 매트릭스」의 조합을 그대로 테스트 케이스로 옮기고, API의 응답 조건 (Mock 조건)을 정의.
• E2E: 사용자의 주요 일련의 스토리 (갱신계 조작 제외)에 집중하여, 환경별 설정 파일 (Placeholder 포함)도 동시에 생성.

구현 전에 「정답인 테스트 시나리오」가 AI 스스로에 의해 언어화되어 있기 때문에, 후속 구현 단계에서의 흔들림이 없어집니다.

Step7: 구현 태스크 체크리스트 작성

여기서부터 구현 페이즈로 들어갑니다. 여기서는 터미널 조작이나 로컬 파일 스캔이 가능한 「에이전트형 AI (Claude Code 등)」의 강점이 최대한 발휘됩니다.

AI는 먼저 상세한 「구현 태스크 체크리스트」를 만듭니다만, 흥미로운 점은 AI 스스로 디렉토리를 스캔하여 파일의 존재 여부나 기술 내용을 직접 확인하고, 자동으로 체크를 채워 나간다는 점입니다.

• 파일이 존재하지 않거나, 설계서와 Props 또는 로직이 괴리되어 있음 ➔ [ ]
• 설계서·사양서대로 코드가 구현되어 있음 ➔ [x]

# 구현 태스크 체크리스트
### Main 컴포넌트
- [x] src/features/feature/Main/MainContainer.tsx
...

이 체크리스트는 AI가 수정을 거듭할 때마다 「차분 대응 (2회차, 3회차…)」으로서 이력이 남기 때문에, 과거 수정의 문맥을 잃지 않고 개발을 진행할 수 있습니다.

Step8: 코드 구현

마지막으로 체크리스트를 위에서부터 순서대로, 의존 관계 (API 클라이언트 ➔ 페이지 ➔ Container ➔ Presenter ➔ 테스트 코드)에 따라 AI에게 구현하게 합니다.

각 파일의 구현이 끝날 때마다 체크리스트의 [ ]가 [x]로 바뀌며 진척도가 가시화됩니다.

모든 코드를 다 작성하면, AI 스스로 다음의 완료 정의 (DoD, Definition of Done)를 실행하게 합니다.

Lint·타입 체크 실행 및 수정 (AI가 커맨드 실행) / 자동 테스트 (UT/IT/E2E) 실행 및 전 경로 통과 확인 / 셀프 리뷰 (설계서와의 괴리, 코딩 규약 위반 여부 셀프 체크)

이 단계까지 철저히 수행함으로써, 인간이 수동으로 로직을 코딩하는 시간은 말 그대로 제로가 되었습니다. 나아가 테스트 코드 자체의 구현이나 「테스트가 통과할 때까지의 디버깅 수정」도 모두 AI가 자기 완결적으로 수행하기 때문에, 인간이 테스트 코드를 작성하는 시간도 완전히 소멸했습니다.

⚠️ 주의: 디자인 미세 조정은 아직 인간의 영역

로직이나 테스트 구현은 「사양서라는 언어를 코드로 정확하게 번역하는 작업」이기에 AI가 가장 잘합니다. 하지만 픽셀 단위의 디자인 재현이나 미세한 마진 조정 등은 아직 인간이 눈으로 보고 조정하는 것이 압도적으로 빠릅니다.

이 워크플로우에서 얻은 3가지 배움

1. 「상류는 인간, 하류는 AI」의 절대 원칙. 인간이 정의해야 할 것은 「Why」

AI가 하고 있는 일은 궁극적으로 모두 「다른 형식으로의 변환 (Excel ➔ 사양서 ➔ Mock ➔ 설계서 ➔ 코드)」입니다. 이 「형식이 정해진 변환·생성 (How의 형태로 만드는 작업)」에 있어서 AI는 인간을 훨씬 능가하는 속도와 정확성을 발휘합니다.

반면, 인간이 해야 할 일은 「의사결정과 Why (목적·의미)의 언어화」입니다.

앞서 언급한 배지(Badge)의 예처럼, 「왜 이것을 만드는가」라는 Why를 인간이 파고들면, 구현해야 할 스코프를 처음부터 최소한으로 좁힐 수 있습니다. 이는 한정된 스케줄 속에서 「어떤 기능을 덜어내고 어디에 집중할 것인가」라는 감산(Subtraction)의 협상을 논리적으로 수행하기 위한 인간만의 강력한 무기가 됩니다.

그리고 인간이 Why를 파고들어 스코프를 최소한으로 좁혀주기 때문에, AI는 망설임 없이 초고정밀 로직과 테스트 코드를 최단 속도로 뱉어낼 수 있습니다 (사양이 흔들리면 AI의 아웃풋도 흔들려 통째로 맡길 수 없게 됩니다).

이 최상류 공정이야말로 AI가 대체할 수 없는 인간만의 성역입니다. AI에게 고품질의 How(코드)를 전력으로 출력하게 만들기 위한 열쇠는, 인간이 어디까지 순도 높은 Why(의도)를 제어하여 타석에 세울 수 있느냐에 달려 있습니다.

2. 사양서의 품질이 AI 아웃풋의 품질을 100% 결정한다

이 워크플로우는 도미노와 같습니다.

첫 번째 Excel에서의 'Why(의미)' 정의가 모호하다면, 사양서도 모크(Mock)도, 최종적인 코드도 모두 모호하고 버그투성이가 됩니다. 반대로, 첫 번째 '의미의 정의'만이라도 인간이 타협하지 않고 끝까지 써 내려간다면, 그 이후 모든 단계의 품질이 보장됩니다.

3. 사양서의 '언어'가 그대로 깔끔한 코드가 된다

Excel이나 사양서에서 '사용자 상태(User Status)', '재고 상태(Inventory Status)'라고 언어를 정의하면, AI가 생성하는 변수명이나 컴포넌트명, 함수명에도 그 단어가 그대로 사용됩니다.

결과적으로 코드의 가독성이 폭발적으로 향상되며, 나중에 인간이 읽어도 '어떤 사양에 기반한 코드인지' 한눈에 알 수 있는 아름다운 코드베이스가 유지됩니다.

요약: 사양서에 '한 마디의 Why'를 덧붙이는 것부터 시작하자

납기가 짧은 가혹한 프로젝트를 살아남기 위해 만든 워크플로우이지만, 결과적으로 '겉모습이나 구현(How)으로 도망치지 않고, 목적(Why)을 철저하게 정리하는 것'의 중요성을 재인식하는 계기가 되었습니다.

현재도 이 워크플로우를 실전 운용하며 개발을 계속하고 있습니다만, 사양의 흔들림이나 스케줄 압박 속에서도 놀라울 정도로 안정적인 타율로 버그 없는 코드를 딜리버리(Delivery)하고 있습니다.

의미와 목적이 엄격하게 정의된 문서를 전달받았을 때, 현대의 AI는 마법 같은 퍼포먼스를 발휘합니다.

우선 다음 스프린트에서 사양서를 작성할 때, 화면의 모습뿐만 아니라 '이 파츠는 무엇을 위해 존재하는가(Why)'를 한 마디 덧붙이는 것부터 시작해 보세요. 그것만으로도 팀의 논의 질과 AI가 내놓는 아웃풋의 정밀도가 극적으로 변할 것입니다.

※ 이 워크플로우는 주로 Claude Code를 활용하여 구축했습니다. 각 단계를 자동화하는 프롬프트의 상세 내용이나 스크립트 구현에 대한 수요가 있다면, 별도의 기사에서 자세히 소개하겠습니다! '좋아요'나 댓글을 남겨주시면 큰 힘이 됩니다.