Claude code를 끼얹어 멀티스탭 폼을 개발 해보기

Agentic 코딩의 이해를 위해 AI 개발 팀을 선정하고 실제로 회원가입 폼을 구현해 봅니다.

예제

나는 LLM을 잘 쓰고 있는 걸까? 요즘 항상 하는 생각이다. 유튜브나 인터넷에는 ai를 통해 혼자서 서비스를 만드는 대단한 개발자들이 넘쳐나지만 나와 내 주변의 친구들은 오늘도 llm의 환각에서 벗어나지 못한다. 그래서 나름대로 8시간 동안 Claude code와 Claude Skill, subagent를 통한 AI 코딩을 직접 해보고 그 과정을 기록해 본다.

Problem - 왜 내 AI는 자꾸 환각을 볼까요?

몇 년 전 처음으로 Cursor를 썼었다. 코드 베이스를 모두 읽고 올바른 해결책을 제시하며 그걸 자동으로 파일에 적용까지 해준다는 설명을 들으며 실제로 인증 부분에서 간단한 버그를 고쳐달라고 맡겨 보았지만... Cursor의 모델은 새로운 라이브러리를 설치한 다음에 해당 라이브러리를 활용해 기존 로그인 로직을 모두 갈아엎어 버렸었다.

그러므로, 이번 개발에는 무엇보다

이미 정의된 라이브러리 이외에는 합의를 통해 추가해야 한다.
이미 기록된 코드에 대한 컨텍스트를 잃지 말아야 한다.
이전까지는 왠만하면 프롬프팅을 영어로 하는 편이었지만, 이제는 한글로 설명해도 충분하다는 증언들이 많았기 때문에 특별한 기술적 용어를 사용하는 것을 제외하고 한글로 지시했다.

를 엄격하게 적용해 보기로 했다.

GOAL - LLM으로 나만의 작은 개발팀 만들기

간단하게 react-hook-form과 zod를 적용한 멀티 스탭 회원가입 폼을 구현하고, 해당 워크플로우가 쓸만한지 검증해 보기로 했다.

먼저 가장 작은 단위의 프론트엔드 개발팀을 생각해 본다.

Project manager - Skill. 요구 사항 정의 및 Tasks 리스팅
UX-Resercher - Subagent. UX 흐름 정리
System Architect - Skill. 개발 아키텍쳐 정리
Test Writer - Skill. Playwright e2e 테스트
Frontend Specialist - Skills. 실제 구현

인간이 해야 할 일

기술 스택 선정
전체적인 코드 리뷰 및 단계 설정
ai가 해결하지 못하는 케이스를 직접 해결 혹은 레퍼런스 제공
git 관리

Use-cases

이 고민과 수십 번의 프롬프트를 통해 나온 첫 번째 스킬.md는 아래처럼 구성되어 있다.

1. 모든 단계는 프롬프트로 진행한다. ex) 단계 1 플래닝을 진행해 주세요. 각 에이전트와 스킬은 어떤 작업을 수행했는지 설명하고 유저의 리뷰를 기다린다.


> **Beforehand**: Explain the user what to do first. Don't jump up to next phase but return what did happened first. When a phase is done, save a doc file to its root directory.

2. 각 스킬과 에이전트의 컨텍스트 유지를 위해 md 파일을 생성한다. 각 단계에서는 이전 단계에서 만들어진 md 파일을 참조해 작업을 진행한다.


> **Beforehand**: Generated md file must be placed at root directory/_docs routing

## Glossary(for this project only!)

- root directory: root app router routing directory means where its page located. `./src/app/practices/<root>`

- root naming: `<use-something>`
...
## Phase 1 - Planning
...
4. Output: `roadmap.md`, GitHub Issues # 실제로 생성안됬음!
   
## Phase 2 — Analysis
...
4. Output: `requirements.md` with Acceptance Criteria, user flow diagrams

## Phase 3 — Design
...
1. Generate documents (always required):
   - `blueprint.md` — system scope and data flow
   - `design.md` — component/API specs (pseudocode and interfaces only, no runnable code)
   - `tasks.md` — implementation checklist (Phase 1–N)

1. Generate conditionally:
   - `validation.md` — AC-to-task traceability matrix. **Only when the task has explicit Acceptance Criteria** (e.g. forms, multi-step flows, data validation features). Skip for UI demos, refactoring, or exploratory tasks.
...

...

3. 기존 코드베이스를 수정하지 않는 규칙을 추가한다.

# phase 5: implementing에 추가

> **RULE**: Understand the existing codebase before proposing any changes. Ask for approval before adding new dependencies.

4. 환각을 보았던 부분은 인간이 직접 처리한다.

Zod superRefine으로 리렌더 없이 비밀번호 확인 필드 만들기

Drawbacks

Subagent를 통한 병렬 개발(실질적인 agentic coding)을 사용하지 않고 개발 플로우 그 자체에 초점을 두었으므로 각 단계에서 Skill들이 메인 쓰레드에서 실행되었으므로 시간이 좀 걸렸다.
Skill.md의 지시사항이 무시되는 경우가 존재했다. 이것 역시 기존 의도가 무시되는 Context Poisoning의 예시라고 생각한다. Subagent의 비중을 늘리는 것이 좋을 것 같다.
테스트 케이스 수정이 3번 있었음. 하지만 구현 대상의 의도가 단순했던 만큼 설계상으로 크게 지장이 있지 않았다.

Summary

AI 개발에서 내가 느낀 가장 큰 문제인 컨텍스트 유실과 기존 코드베이스 수정이 크게 향상된 것을 느낄 수 있었다. 실제 진행 사항과 테스트를 ai가 이해하고 진행했고, **RULE**을 통해 걸어둔 규칙도 잘 지키는 것을 확인했다. 사용량 역시 claude pro의 40퍼센트를 넘지 않은 수준이었다.

다음에는 좀 더 레퍼런스를 쌓아 더욱 복잡한 Agentic Coding에 도전해 볼 만하다고 생각한다.