Claude Code를 메인 개발 도구로 쓰면서 바뀐 개발 순서

올해 초 AI AGENT ONE 프론트엔드를 만들 때 처음으로 Cursor를 UI 개발에 써 봤습니다. 화면 마크업이나 공통 컴포넌트 초안, 반복되는 API 연동 코드를 생성하게 하고, 결과를 프로젝트 컨벤션(Zustand, TanStack Query, ky 구조)에 맞게 손보는 식이었습니다. 그러다 Claude Code로 넘어왔고, 지금은 사내 업무관리 시스템을 다시 만드는 일을 거의 Claude Code로 하고 있습니다.

처음 몇 주는 솔직히 실망스러웠습니다. 화면 하나 만들어 달라고 하면 금방 그럴듯한 게 나오는데, 두 번째 화면부터 뭔가 어긋나기 시작했거든요. 이 글에서는 그 문제를 겪고 나서 바꾼 작업 순서, 제가 "스펙 선행"이라고 부르는 방식을 정리해 보려고 합니다.

1. 두 번째 화면부터 무너지는 이유

"대시보드 만들어 줘"라고 하면 첫 화면은 꽤 괜찮게 나옵니다. 문제는 그다음입니다.

공통 버튼 컴포넌트가 있는데도 화면마다 버튼을 새로 만들었습니다. 디자인 토큰이 있는데도 색이나 간격을 숫자로 박아 넣었고요. 폴더 구조도 화면마다 조금씩 달랐습니다. 처음엔 에이전트가 말을 안 듣는다고 생각했는데, 가만히 보니 제 잘못이 더 컸습니다.

에이전트는 지금 눈앞에 보이는 맥락만 가지고 판단합니다. 규칙이 코드 어딘가에 암묵적으로만 있으면 지킬 방법이 없습니다. 사람 신입이 와도 마찬가지일 겁니다. 그래서 순서를 바꿨습니다. 규칙과 설계를 문서로 먼저 정해 두고, 구현은 그 위에 얹기로요.

2. 지금 쓰는 순서

대략 이런 흐름으로 일합니다.

1. 브레인스토밍   무엇을 왜 만드는지. 질문을 주고받으며 요구사항을 좁힌다
2. 기획서        화면 목록, 데이터 모델, 이번에 안 하는 것
3. 구현 계획      파일 단위 작업 목록과 검증 방법
4. 구현          계획 단위로 에이전트가 작성
5. 검증          typecheck(strict), e2e, 스크린샷 순서로
6. 문서 갱신      규칙이 바뀌면 문서와 코드를 같이 고친다

1번부터 3번까지는 superpowers 플러그인의 brainstorming, writing-plans 스킬 흐름을 그대로 씁니다. 스킬이 질문을 하나씩 던지면서 요구사항을 좁혀 가고, 결과를 기획서와 계획 파일로 남겨 줍니다. 이 단계에서 제가 하는 일은 질문에 답하고, 계획을 승인하거나 고치는 것뿐입니다.

3. 화면보다 문서를 먼저 썼습니다

업무관리 시스템을 새로 만들면서 가장 먼저 만든 건 화면이 아니라 문서 여섯 개였습니다.

docs/
├── architecture.md     폴더 구조(feature 단위), 데이터 흐름, 상태 관리 경계
├── style-guide.md      디자인 토큰, 타이포그래피 스케일(최소 10px), 라이트/다크
├── components.md       공용 컴포넌트 목록과 쓰임(Button, Modal, Toast, Panel 등)
├── motion.md           진입 모션 순서, 스프링 값, 동작 줄이기 대응
├── i18n.md             한/영 사전 구조, 키 이름 규칙
└── conventions.md      네이밍, import 순서, 커밋 규칙, 하지 말 것

예를 들어 components.md에는 이런 식으로 적어 둡니다.

## Button
- 위치: src/shared/ui/Button.tsx
- variant: primary | secondary | ghost | danger
- size: sm(28) | md(36) | lg(44)
- 아이콘만 있는 버튼은 `aria-label` 필수
 
## 금지
- 화면 폴더 안에 버튼·모달을 새로 만들지 않는다. 필요한 variant가 없으면 공용 컴포넌트에 추가한다.

이 문서들은 에이전트만 보는 게 아니라 사람도 같이 보는 규칙입니다. CLAUDE.md에서 이 문서들을 가리키게 해 두면, 에이전트가 새 화면을 만들기 전에 먼저 읽고 시작합니다. CLAUDE.md를 어떻게 쓰는지는 다음 글에서 따로 다룹니다.

4. 계획 파일은 이렇게 생겼습니다

구현 계획은 대충 아래처럼 생겼습니다. 작업 단위를 작게 쪼개고, 단위마다 어떻게 확인할지를 같이 적는 게 포인트입니다.

# 업무 라이브러리 화면
 
## 작업
1. `features/library/api.ts`: 목록·검색·상태 필터 쿼리(TanStack Query)
2. `features/library/LibraryTable.tsx`: 공용 Table + StatusBadge 사용
3. `features/library/LibraryPage.tsx`: 상단 필터(Segmented) + 테이블 + 빈 상태
4. 진입 모션: motion.md의 표준 순서(상단바, 타이틀, 카드, 테이블, 행)
 
## 검증
- `pnpm typecheck` 통과
- e2e: 상태 필터를 바꾸면 행 수가 바뀌는지, 검색어 입력 후 결과가 1건인지
- 스크린샷: 라이트/다크, 1440·390 폭

5. 그럼 사람은 뭘 하나요

에이전트가 코드를 쓰는 동안 제가 하는 일은 생각보다 많습니다.

먼저 결정입니다. 기획서의 "이번에 안 하는 것" 목록을 정하고, 계획의 우선순위를 바꿉니다. 이건 에이전트가 대신해 줄 수 없습니다.

그다음은 판단입니다. 결과 화면을 직접 보고 "뭔가 이상하다"를 구체적인 지시로 바꾸는 일입니다. "간격이 이상해"라고 하면 엉뚱한 데를 고치지만, "카드 사이 간격을 style-guide의 --space-4로"라고 하면 한 번에 고칩니다.

마지막이 규칙 갱신인데, 저는 이게 제일 중요하다고 생각합니다. 같은 지적을 두 번 하게 되면 그 지적을 문서나 메모리로 옮깁니다. 같은 실수를 반복하게 만드는 건 에이전트가 아니라 규칙을 문서에 안 옮긴 사람이더라고요. 저도 한동안 같은 말을 세 번, 네 번씩 하고 나서야 깨달았습니다.

6. 써 보니 달라진 것들

처음엔 오히려 느려졌습니다. 문서 쓰는 데 시간이 꽤 걸렸거든요. 그런데 화면이 열 개를 넘어가면서부터 확실히 달라졌습니다. 수정 비용이 눈에 띄게 줄었고, 무엇보다 화면끼리 일관성이 생겼습니다.

리뷰하는 방식도 바뀌었습니다. 코드를 한 줄 한 줄 보기보다 계획과 검증 결과를 먼저 봅니다. 코드 리뷰는 검증을 통과한 다음에 구조 위주로 봅니다.

그리고 에이전트가 어디서 틀릴지 예측할 수 있게 됐습니다. 대부분 문서에 없는 결정에서 틀립니다. 그러니까 틀린 지점이 곧 문서에 추가할 항목인 셈입니다.

마치며

AI 코딩 도구를 쓰다가 "처음엔 좋았는데 갈수록 엉망이 된다"고 느끼신다면, 코드보다 문서를 먼저 써 보시길 권합니다. 거창할 필요는 없고, 컴포넌트 목록 하나부터 시작해도 충분합니다. 다음 글에서는 이런 규칙을 담는 그릇인 CLAUDE.md 이야기를 해 보겠습니다.