지난 글“출근하면 코드부터 짜던 개발자가 이제 봇부터 켭니다“ 끝에 코드 한 줄 안 치고 만든 결과물의 완성도를 점수로 매긴 것을 적었었다. Jest 테스트가 전부 통과했는데, 요구사항 명세 40개 중 코드에 실제로 들어간 건 25개였다. 빠진 15개는 검색 필터와 정책 분기처럼 기능의 의미를 정하는 항목이었다.

이렇게 누락이 된 게 많았지만 내가 만든 하네스 플러그인 code-forge는 “개발 완료”라고 보고했다. 테스트가 전부 통과했다는 말은 사실이었다. 작성된 테스트는 이미 구현된 동작들만 검사했고, 빠진 요구사항을 확인할 테스트가 없었으니, 검증을 모두 통과해도 누락은 드러나지 않았던 것이었다.

지난 글 마지막에 나는 “무엇을 만족해야 끝인가”를 테스트와 연결하기 시작했다고 썼다. 먼저 누락된 기능들이 어느 단계에서 빠졌는지 추적했고, 그걸 고친 뒤에도 결함이 나왔다. 두 번 다 테스트보다 앞 단계로 돌아가야 했다. 이번 글에선 실제 그 과정을 적어볼 것이다. (지난 글이 궁금하시다면, 먼저 읽고 오셔도 좋습니다.)

장인이 로봇 조수에게 설계도를 짚어가며 기어 조립 장치의 구조를 설명하는 삽화 — <출처: 작가, 제미나이로 생성>

AI는 plan.md와 Figma부터 읽는다

개발은 Figma나 티켓에서 시작했다. AI가 그 내용을 분석해 요구사항과 기능 명세를 `plan.md`에 정리하면, `/start`가 그 문서를 기준으로 구현했다. 검증 단계에서는 `/generate-test`와 `/e2e`가 같은 요구사항과 기능 명세에서 테스트 케이스(TC)와 테스트 코드를 만들고, 구현 결과가 명세대로 동작하는지 확인했다.

`/start`는 요구사항과 수용 조건, Figma를 바탕으로 구현 계획을 만들었다. `/generate-test`와 `/e2e`는 수용 조건을 “어떤 상황에서 무엇을 하면 어떻게 된다”는 BDD 시나리오로 옮기고, 시나리오마다 테스트 코드를 만들었다. 정책 분기가 복잡한 작업에는 요구사항을 정책 케이스 표로 정리하는 분석 에이전트를 필요할 때만 붙였다. 구현이 끝나면 Playwright로 실제 브라우저 화면을 확인했다.

작업이 길어져 한 세션에 대화가 쌓이면, 다음 세션으로 작업을 넘기는 `/handoff`를 썼다. 끝낸 일과 남은 일, 아직 결정하지 않은 질문을 `progress.md`에 적었고 컨텍스트를 비운 뒤 알아서 프롬프트를 작성하여 새 세션에서 그 문서를 읽고 이어 갔다. 모델의 자동 요약에만 맡기지 않고 필요한 내용을 직접 정리했기 때문에, 검증을 여러 번 반복해도 앞서 확인한 내용이 끊기지 않고 중요한 맥락들을 이어 가는 게 가능해졌다. 한 세션에 대화를 계속 쌓으며 드는 비용도 줄일 수 있었다.

작업 문서·티켓·Figma에서 요구사항 정리, 구현 계획, 테스트·mock 생성과 구현, 검증, PR 승인까지 이어지는 AI 작업 흐름도 — <출처: 작가, 제미나이로 생성>

AI가 계획과 시나리오를 만들면 내가 확인했고, 애매한 비즈니스 정책은 직접 정했다. 구현과 검증은 모두 AI가 맡았다. 커밋·푸시와 PR 생성은 내가 승인한 뒤에 진행됐고, 마지막에는 결과를 보고 작업을 끝내도 될지 판단했다.

요구사항 명세도 같은 파이프라인에서 만든 게 허점이었다. AI는 원문에서 요구사항 목록을 뽑고, 거기서 수용 조건과 BDD 시나리오를 만들었다. 검색 필터 하나가 목록에서 빠지자 수용 조건과 시나리오, 테스트에도 그 필터를 다루는 항목이 없었다. 구현은 필터 없는 화면으로 끝났고, 어느 단계도 누락을 실패로 처리하지 않았다.

신호는 보고서에 이미 있었다

돌이켜보면 당시 AI 보고서에는 P0(가장 시급한 우선순위) 미완 항목 세 개(카테고리 옵션, 담당자 표시, 저장 확인)가 이미 적혀 있었다. 하지만 파이프라인은 “작성된 테스트가 통과했는가”만 완료 조건으로 검사했고, “요구사항 명세가 모두 연결됐는가”는 검사하지 않았다. 미완 항목은 보고서에 남았지만 작업은 계속 진행됐다.

그래서 `plan.md`와 Figma에서 뽑은 요구사항을 되짚었다. AI에게 요구사항 명세의 각 항목이 수용 조건, 시나리오, 테스트, 코드 중 어디에 연결되어 있는지 한 줄씩 적은 요구사항 추적표를 만들게 하고, 나는 그 표에서 빠진 연결이 없는지 확인했다.

요구사항 명세의 각 항목이 수용 조건과 정책 분기로 이어지는가
각 수용 조건이 BDD 시나리오와 테스트를 갖는가
테스트가 실제 구현 파일과 연결되는가
확인하지 못한 항목과 스킵 이유가 드러나는가

빠진 기능이 나오면 AI에게 어느 단계에서 빠졌는지부터 분석하게 했다. 요구사항 목록에서 빠졌는지, 정책 분기가 모호했는지, Figma의 화면 상태를 잘못 읽었는지를 근거와 함께 내놓게 했다. 나는 그중 비즈니스 판단이 필요한 원인만 직접 정하고, 확정된 내용을 문서와 체크리스트에 반영한 뒤 테스트와 구현을 다시 돌렸다.

mock과 구현은 같이 틀린다

두 번째 결함은 mock에서 나왔다. 브라우저에서 사용자 흐름을 자동으로 실행하는 E2E 테스트가 mock(실제 API 대신 미리 만들어 둔 가짜 응답)으로는 전부 통과했는데, 실제 서버와 연결한 스테이지 환경에서 동작하지 않았다. 원인을 모아 보니 가장 큰 패턴은 mock을 실제 응답이 아니라 추정으로 만든 것이었다. 프론트엔드와 mock은 `id`, `category`, `state`, `businessKeyId`를 쓰고 있었는데, 실제 API는 `propertyId`, `propertyType`, `propertyStatus`, `affiliateId`를 내려주고 있었다.

같은 추정 타입으로 구현과 mock을 함께 만들었으니 둘 사이에는 모순이 없었다. 실제 API를 붙이자 `id`가 전부 비어 모든 행이 같은 행으로 취급됐고, 한 행의 체크박스를 눌러도 전체가 선택됐다. 카테고리 칸에는 영문 코드가 그대로 찍혔고, 상태 칸에는 “-”만 남았다.

타입과 mock이 같은 추정에 기대는 한 테스트는 이 차이를 잡을 수 없다. 그래서 순서를 바꿨다. 개발 서버의 실제 응답을 먼저 캡처하고, 그 구조 그대로 타입과 fixture(테스트용 준비 데이터), mock을 만들었다. mock을 고칠 때는 실제 응답과 다시 대조했다.

결함이 처음 발생한 곳은 개선해야 할 곳이다

두 사건을 겪은 뒤로는 문제가 생길 때마다 문제점을 기록하여 개선했고, 어느 단계로 먼저 돌아갈지도 함께 정했다.

발견한 이상과 먼저 돌아갈 곳을 짝지은 표: 기능 누락은 요구사항 명세·수용 조건으로, 정책·예외 분기 차이는 정책 후보·BDD 시나리오로, mock과 실제 응답 불일치는 API 계약·타입·fixture·mock으로, 화면 흐름 차이는 Figma 상태·시나리오로, 동작 차이는 구현과 영향 테스트로 돌아간다는 내용 — <출처: 작가, 제미나이로 생성>

이상이 어디서 나왔든 원본 문서, Figma, API 계약을 대조해 처음 틀린 산출물을 찾았다. AI가 수정 근거와 범위를 내놓으면 내가 원문과 정책을 확인했고, 필요하면 원본 문서부터 고친 뒤 새 `/start` 작업을 열어 그 아래 테스트, mock, 구현을 다시 만들었다.

`/test`는 바뀐 파일과 거기에 묶인 정책·테스트만 골라 다시 돌렸고, 화면이 바뀐 작업은 `/e2e`가 시나리오를 Playwright로 실행했다. 어느 쪽이든 제품 코드나 정책을 고쳐야 한다는 결론이 나오면 도구가 직접 고치지 않고 변경 범위와 재현 근거를 나에게 넘겼다. 나는 그걸 별도 `/start` 작업으로 열었다.

장인과 로봇 조수가 설계도의 부품 도면을 보며 치수와 조립 방식을 함께 확인하는 삽화 — <출처: 작가, 제미나이로 생성>

아홉 번을 시도해도 안 되면 나에게 묻는다

처음에는 테스트가 깨질 때마다 다른 모델을 붙여 끝날 때까지 돌릴 생각이었다. 하지만 틀린 전제에서 횟수만 늘려서는 해결되지 않았다. E2E 검증은 같은 시나리오가 계속 실패하면 세 단계에 걸쳐 접근법을 바꾼다. 단계마다 최대 세 번씩 시도한다. 세 단계를 모두 거쳐도 해결되지 않으면 로그와 판단 근거를 나에게 보여준다.

실행 횟수별 확인 사항을 정리한 표: 1~3회는 오류 분류와 선택자·대기 조건 수정, 4~6회는 다른 모델 검토와 소스·브라우저 동작 재확인, 7~9회는 테스트와 구현 중 원인 대조 및 접근법 변경, 이후는 로그와 판단 근거를 보여주고 선택을 기다림

아홉 번 시도해도 실패하면 나는 스킵, 힌트 제공, 시나리오 수정, 전체 중단 중 하나를 고른다. 힌트를 주면 첫 단계부터 다시 시도한다. 시나리오를 수정하면 테스트 코드를 다시 만든다.

같은 실패는 다음 작업의 규칙이 된다

검증이 실패하면 먼저 기록을 확인했다. 화면 문제는 Figma와 실제 브라우저의 캡처를 비교했다. 수정한 뒤에는 같은 화면을 다시 캡처해 무엇이 달라졌는지 AI에게 확인하게 했다. 그리고 이 근거를 바탕으로 처음 판단이 어긋난 부분을 찾게 했다.

결함을 고쳐 현재 작업을 다시 돌려도 다음 작업의 체크리스트와 완료 조건은 그대로였기에, QA에서 드러난 원인을 다음 작업의 규칙으로 옮겼다.

앞의 mock 불일치는 나의 검토를 거쳐 ‘mock은 실제 백엔드 응답과 일치해야 한다’는 규칙이 됐고, 신규 API 체크리스트의 첫 항목은 ‘실제 응답부터 캡처’로 바뀌었다. 규칙은 늘 읽는 지시문에 쌓지 않고, 그 규칙이 필요한 단계의 체크리스트와 완료 조건에만 넣었다. 지난 글에 적었듯 앞에 쌓인 규칙이 많아질수록 현재 프롬프트의 지시사항이 흐려지기 때문이다.

`code-forge`는 `quality.jsonl`에 쌓인 품질 이벤트 중 같은 내용이 세 번 이상 기록된 항목을 찾고, `forge whet --draft`로 반복 횟수와 기록을 담은 규칙 후보 문서를 만들었다. 나는 그 후보들이 다른 작업에도 적용되는지 검토한 뒤, 필요한 단계의 체크리스트와 완료 조건에 반영했다.

앞으로는 이 과정에서 쓰이는 프롬프트들도 기록하여, 실패 기록과 화면 비교 결과를 보고 원인과 다음 작업에서 먼저 확인할 항목을 제안하도록 다듬을 생각이다.

정책, 테스트, 실행 결과, 회고를 잇는 구조는 별도 도구 `flow-toolkit`에도 구현했지만, 아직 실운영 경로에는 연결하지 않았다. 품질 이벤트가 더 쌓이면 그때 다시 판단할 생각이다.

두 대의 로봇 조수가 각각 설계도를 들고 장인과 함께 부품 조립 순서를 확인하는 삽화 — <출처: 작가, 제미나이로 생성>

전체 통과 알림이 오면 요구사항부터 확인한다

요즘은 전체 PASS 보고를 받으면 요구사항 추적표를 먼저 연다. AI가 정리한 표에서 수용 조건(AC)과 테스트 케이스(TC)를 확인한 뒤, 실제 화면에서 E2E를 돌려 요구사항대로 동작하는지 본다. 확인하지 못한 항목이 있다면 이유와 함께 적는다. 그 결과를 보고 내가 완료 여부를 결정한다.

요구사항 누락을 발견하고 추적표 검토를 완료 조건에 넣었다. mock과 실제 API 응답이 달랐던 일을 겪은 뒤에는 신규 API 작업에서 실제 응답부터 캡처하도록 순서를 바꿨다. 이제 “개발 완료” 보고를 받으면 테스트 결과, 요구사항 누락 여부, 확인하지 못한 범위를 함께 본다. 실패 뒤에 고친 지침이 다음 작업에도 반영됐는지도 확인한다.

AI가 코드를 쓰는 모습을 보면 개발도 ‘딸깍’ 한 번이면 끝난다고 생각하는 사람이 많아진 것 같다. 내 경우 제품 코드를 직접 치는 시간은 줄었지만, 요구사항을 정리하고 검증 방법을 설계하고 실패 기록을 읽어 체크리스트와 프롬프트를 고치는 시간은 늘었다. 전보다 더 많이 생각하고, 키보드도 더 많이 친다.

요즘 개발자로서 내가 더 힘을 쏟는 건 기능 하나의 구현보다 전체 품질을 확인하는 과정과 시스템을 만드는 일이다. 이번에 바꾼 검증 기준이 내 다음 작업에서 통하는지 확인하고, 다른 개발자의 작업환경에서도 도움이 되는지 함께 써 보며 고치고 싶다.

AI가 코드를 쓰는 환경에서 개발자는 무엇을 해야 하고, 회사는 어떤 개발자를 필요로 할까. 요즘 자주 하는 고민이다. 내가 겪은 실패를 문서로 남기고, 다른 사람의 경험을 듣고, 내 방식을 다시 살펴보는 일부터 계속하려 한다. 이 글의 방식과 다른 의견이나 사례가 있다면 듣고 싶다. 이런 이야기를 편하게 나누는 게 특별하지 않은 개발 문화가 되었으면 좋겠다.

<참고>

code-forge 스킬 문서: /start, /generate-test, /e2e, /handoff

현재 FDE로 일하시거나, 최근 1년 내 일하셨던 분들은
“국내 FDE 현황 조사 2026” 참여하고, 리포트 & 네이버페이 포인트 받아가세요!