한 줄 요약: 탐색 → 계획 → 구현 → 검증 → 커밋의 다섯 단계를 작은 단위로 반복하라. AI는 구현 속도를 올려 주지만, 품질은 계획과 검증 단계에서 결정된다.
왜 워크플로우가 필요한가
에이전트에게 "회원가입 기능 만들어줘"라고 한 번에 시키면 보통 이런 일이 생깁니다. 파일 15개가 바뀌고, 기존 인증 미들웨어와 다른 방식으로 짜여 있고, 테스트는 통과하지만 실제로는 이메일 중복 검사가 없습니다. 리뷰하기에는 너무 크고, 버리기에는 아깝습니다.
문제는 모델의 실력이 아니라 방향 설정과 검증의 부재입니다. 사람 팀원에게도 설계 리뷰 없이 큰 기능을 맡기지 않듯, AI에게도 같은 절차가 필요합니다.
다섯 단계 워크플로우
- 탐색 (Explore): "코드는 아직 쓰지 말고, 인증 관련 코드가 어디에 있고 어떻게 동작하는지 파악해서 요약해줘." 모델이 기존 패턴을 먼저 읽게 해야 기존 코드와 어울리는 코드를 씁니다.
- 계획 (Plan): "변경할 파일, 단계별 작업, 예상 리스크를 PLAN.md로 써줘." 여기서 내가 가장 많이 개입합니다. 계획의 오류는 고치는 데 1분이지만, 구현된 오류는 1시간이 걸립니다. 어려운 설계라면 추론(생각) 수준을 높입니다.
- 구현 (Implement): 계획의 한 단계씩 진행합니다. "1단계만 구현하고 멈춰"처럼 범위를 묶어 두면 diff가 리뷰 가능한 크기로 유지됩니다.
- 검증 (Verify): 타입 체크, 린트, 테스트를 에이전트가 직접 돌리게 하고, 그다음 내가 diff를 읽습니다. UI라면 실제 화면을 확인합니다.
- 커밋 (Commit): 단계마다 작게 커밋합니다. 다음 단계가 엉망이 되면 여기로 돌아오면 됩니다.
오타 수정처럼 diff가 한 문장으로 설명되는 작업은 1~2단계를 건너뛰어도 됩니다. 반대로 여러 파일에 걸치거나 익숙하지 않은 코드라면 계획 단계는 절대 건너뛰지 마세요.
테스트 주도 개발(TDD)은 AI와 특히 잘 맞는다
3편에서 본 것처럼 코딩 모델은 "테스트 통과"를 목표로 훈련되었습니다. 명확한 테스트가 있으면 스스로 반복하며 완성도를 올립니다.
- 요구사항을 주고 테스트만 작성하게 한다. "아직 구현은 하지 마."
- 테스트를 읽고 요구사항을 제대로 표현하는지 내가 검토한다. 여기서 빠진 케이스를 추가한다.
- 테스트가 실패하는 것을 확인하고 커밋한다.
- "테스트는 수정하지 말고, 모두 통과할 때까지 구현해"라고 지시한다.
- 통과 후 테스트 파일에 diff가 없는지 확인한다.
마지막 단계가 3편의 reward hacking에 대한 방어선입니다.
diff 리뷰 체크리스트: AI가 자주 하는 실수
| 실수 유형 | 예시 | 확인 방법 |
|---|---|---|
| 없는 API 사용 | 라이브러리에 없는 메서드, 예전 버전 문법 | 타입 체크, 빌드 |
| 조용한 실패 | catch {}로 에러를 삼킴, 기본값으로 대체 | catch 검색, 에러 경로 테스트 |
| 테스트 조작 | 기대값 수정, skip 추가, 특수 케이스 하드코딩 | 테스트 파일 diff 확인 |
| 범위 이탈 | 요청하지 않은 리팩터링, 포맷 변경 | 변경 파일 목록을 계획과 비교 |
| 중복 구현 | 이미 있는 유틸을 모르고 새로 만듦 | 탐색 단계에서 기존 유틸 파악 |
| 보안 구멍 | SQL 문자열 결합, 권한 검사 누락, 비밀값 하드코딩 | 보안 관점 리뷰 요청, 정적 분석 |
| 과도한 추상화 | 한 번 쓰는 로직에 인터페이스와 팩토리 | "더 단순하게" 재요청 |
검증을 자동화하라
사람의 리뷰는 비싸고 느립니다. 기계가 잡을 수 있는 것은 기계에게 맡기고, 사람은 설계와 의도를 봅니다.
- 빠른 피드백 명령을 규칙 파일에: 에이전트가 수정 후 스스로
typecheck,lint, 단일 파일 테스트를 돌리게 합니다(7편). - 훅으로 강제: 파일을 저장할 때마다 포맷터, 커밋 전에 타입 체크(8편).
- CI가 마지막 방어선: AI가 만든 PR도 사람 PR과 같은 CI를 통과해야 합니다.
- 다른 눈으로 리뷰: 구현한 대화가 아닌 새 세션(또는 다른 모델)에게 diff 리뷰를 맡기면, 자기 코드를 감싸는 경향 없이 문제를 더 잘 찾습니다.
언제 AI를 쓰지 말아야 하나
- 배우는 중인 핵심 개념: 새 언어나 프레임워크의 기본기를 익히는 중이라면 직접 짠 뒤 AI에게 리뷰를 받는 편이 실력으로 남습니다.
- 내가 검증할 수 없는 코드: 암호화, 동시성 제어, 금융 계산처럼 틀려도 눈치채기 어려운 영역은 검증 수단이 없다면 쓰지 않거나 전문가 리뷰를 받습니다.
- 보안 정책상 코드를 외부로 보낼 수 없는 경우: 회사의 보안 정책과 폐쇄망 규정을 먼저 확인합니다(11편).
코딩 실습 (1~2시간)
이번 주에 만들 기능 하나를 골라 다섯 단계를 끝까지 돌려 봅니다.
- 탐색: 관련 코드 요약을 받고, 내가 모르던 사실 하나 찾기
- 계획: PLAN.md 작성 후 최소 한 군데 수정
- TDD: 테스트 먼저 작성·커밋 후 구현
- 검증: 위 체크리스트로 diff 리뷰, 새 세션에 리뷰 요청
- 회고: 어느 단계에서 가장 많이 고쳤는지, 규칙 파일에 추가할 줄은 무엇인지 기록
정리
- 탐색 → 계획 → 구현 → 검증 → 커밋을 작은 단위로 반복한다.
- 테스트를 먼저 쓰고, 테스트 파일은 보호한다.
- 기계가 검증할 수 있는 것은 자동화하고, 사람은 의도와 설계를 본다.
다음 편: 도구를 쓰는 입장에서 만드는 입장으로. API로 직접 AI 기능을 만들고 비용을 최적화합니다.