AI 코딩 에이전트와 일하는 법, 1년 가까이 써보고 정리

저는 사이드 프로젝트를 혼자 만듭니다. 그런데 요즘은 “혼자”라는 말이 좀 애매합니다. 코드의 상당 부분을 AI 코딩 에이전트가 쓰기 때문입니다. 블로그 글 여러 편과 약관 페이지를 한 세션에 만들거나, 포스트 수십 개의 메타데이터를 한 번에 일괄 수정하는 일이 실제로 가능해졌습니다.

1년 가까이 이렇게 일하면서 자리 잡은 워크플로우를 정리해 봅니다.

자리 잡은 워크플로우

지금은 다섯 단계로 굳어졌습니다.

문제 정의 — 내가 뭘 원하는지 명확하게 씁니다. 이 단계가 절반입니다.
에이전트에 위임 — 에이전트가 코드베이스를 조사하고 계획서를 만듭니다.
리뷰와 승인 — 계획서를 읽고 방향이 맞는지 확인합니다. 여기서 어긋나면 뒤가 전부 어긋납니다.
자동 구현 — 에이전트가 코드를 쓰고 테스트를 돌립니다.
검증 — 빌드 확인과 실제 실행. 특히 UI는 브라우저에서 직접 확인합니다.

핵심은 3번과 5번에 사람이 반드시 있어야 한다는 점입니다. 나머지는 대부분 위임해도 됩니다.

도구는 두 개를 병행

메인 에이전트 하나, 보조 에이전트 하나를 씁니다. 같은 문제라도 도구마다 접근이 달라서, 하나가 막히면 다른 쪽으로 풀리는 경우가 꽤 있습니다. 프로젝트마다 규칙 파일(마크다운)을 두고 도메인 지식과 금지 사항을 적어두면 어느 도구를 쓰든 일관성이 유지됩니다.

겪으면서 배운 함정 세 가지

컨텍스트를 아끼면 엉뚱한 방향으로 갑니다. “알아서 해줘”는 최악의 프롬프트입니다. 목표, 이미 확인한 것, 관련 파일 경로를 구체적으로 줘야 합니다. 에이전트가 이상한 결과물을 내놨다면 대부분 제가 설명을 아낀 경우였습니다.

자동 생성 코드도 리뷰는 필수입니다. 돌아가는 코드와 좋은 코드는 다릅니다. 에이전트는 가끔 필요 없는 추상화를 만들거나, 요청 범위 밖의 것을 “겸사겸사” 고칩니다. diff는 반드시 읽습니다.

세션이 끝나면 맥락이 사라집니다. 어제 나눈 논의를 오늘의 에이전트는 모릅니다. 그래서 결정 사항과 프로젝트 상태를 마크다운 문서로 남기는 습관이 생겼고, 이게 쌓이니 에이전트용 문서가 아니라 저를 위한 지식 베이스가 됐습니다.

그래서 얼마나 도움이 되나

혼자서는 엄두를 못 냈을 규모의 작업이 가능해진 건 분명합니다. 다만 “10배 생산성” 같은 말은 절반만 맞습니다. 코드 작성 속도는 확실히 몇 배가 됐지만, 문제 정의와 리뷰에 쓰는 시간은 오히려 늘었습니다. 일의 성격이 “코드를 쓰는 것”에서 “방향을 잡고 결과를 검증하는 것”으로 바뀌었다는 쪽이 정확합니다.

이 블로그도 에이전트와 함께 만들었습니다. 그 과정은 따로 정리해 볼 생각입니다.