AI Agent를 사용하면 여러 파일을 가로지르는 수정이나, 기존 코드를 읽은 후의 구현안 작성 등이 한꺼번에 진행되기도 합니다.

하지만 제 경험상, AI Agent에게 맡기면 맡길수록 빨라지는 것은 아니었습니다. 어떤 시기에는 너무 많은 양을 작성하게 한 탓에 오히려 개발이 중단되기도 했습니다.

이 기사는 그 실패담과, 그로부터 제가 바꾼 구체적인 방법에 대한 이야기입니다. 먼저 결론부터 말씀드리겠습니다.

AI 활용이란 생성량을 늘리는 것이 아니라, 불확실성을 낮추는 것입니다.

이를 위해 AI에게 넘길 업무를 "내가 리뷰할 수 있는 크기"까지 작게 설계합니다.

"리뷰할 수 있는 크기란 구체적으로 무엇인가", "어떻게 작게 나눌 것인가"는 후반부에 쓰겠습니다. 우선, 무슨 일이 일어났었는지 말씀드리겠습니다.

당시 저는 참고할 수 있는 기존 프로덕트가 있는 신규 Web 앱을 만들고 있었습니다. 화면과 기능이 유사하고, 기존 측에는 이미 구현된 코드도 있었습니다. 그래서 단순하게 생각했습니다.

기존 코드가 있다면 새로운 구성으로 옮기기만 하면 된다. AI에게 맡기면 번역처럼 진행될 것이다.

실제로는 기존 측은 Express + GraphQL, 신규 측은 Hono + REST라는 구성의 차이가 있었습니다. "Express + GraphQL을 Hono + REST로 변환하기만 하면 된다"고 보였지만, 그렇지 않았습니다. 인증 연결, API의 책임 구분, 에러 핸들링 (Error Handling), 타입 정의 (Type Definition)의 위치, 프론트엔드의 데이터 취득, 디렉토리 구조——이 모든 것이 단순한 변환이 아닌 설계 판단 (Design Decision) 이었습니다.

GraphQL에서 자연스러웠던 책임의 분리 방식이 REST에서 그대로 자연스럽다는 보장은 없습니다. 기존에서 암묵적으로 성립되어 있던 인증의 전제를 신규 구성에서는 명시적으로 다시 설계해야 합니다. 자연어 번역이라면 의미를 유지하며 표현을 바꿀 수 있지만, 코드의 이식에서는 "표현"만 바꾼다고 끝나는 것이 아닙니다. 많은 판단이 개입됩니다.

그 판단을 정리하지 못한 채, 저는 AI Agent에게 꽤 큰 규모의 구현을 맡기려 하고 있었습니다.

어느 날, Agent Mode로 조금 큰 태스크를 진행했습니다. 완료 후 VSCode의 Source Control을 열어보니, 변경 파일이 15개 정도 한꺼번에 나열되어 있었습니다. 새로운 API 파일, 타입 정의, 프론트엔드 취득 로직, 유틸리티, 디렉토리 조정. diff를 스크롤해도 끝이 보이지 않았습니다.

처음에는 "엄청나게 진행되었다"고 생각했습니다. 하지만 곧 다른 느낌으로 바뀌었습니다. 어느 파일부터 봐야 할지 모르겠다는 것이었습니다.

첫 번째 diff를 열고, 관련된 두 번째 파일을 쫓고, 거기서 다시 다른 파일로 넘어갑니다. 그러다 보면 처음에 무엇을 확인하려고 했는지 잊어버리게 됩니다. 어디가 기존 코드에서 유래한 것이고, 어디가 AI의 판단인지도 구분할 수 없습니다. 동작은 합니다. 하지만 왜 동작하는지는 설명할 수 없습니다.

이때 깨달은 것은, 코드는 늘어나고 있는데 나의 이해는 늘어나지 않고 있다는 사실이었습니다. 늘어난 것은 확인해야 할 대상의 양뿐이었습니다.

그리고 이것이 핵심이었습니다. 스스로 리뷰할 수 없는 생성물은, 올바르게 동작하는 것처럼 보여도 프로덕트에 넣기에는 위험합니다. 나중에 문제가 발생했을 때 원인을 추적할 수 없습니다. 변경 의도를 설명할 수 없습니다. 어디까지가 안전하고 어디부터가 수상한지 판단할 수 없기 때문입니다.

참고로 말씀드리자면, 생성된 코드가 나빴던 것이 아닙니다. AI는 우수했습니다. 문제는 AI에게 넘기기 전의 제 설계가 거칠었고, 제가 리뷰할 수 없는 입도 (Granularity)로 넘겼다는 것——단지 그것뿐이었습니다.

여기서부터가 실패 이후에 바꾼 구체적인 방법입니다.

가장 크게 바꾼 것은, 갑자기 구현하게 하는 것을 그만둔 것입니다. Agent Mode로 만들게 하기 전에, Chat 형식으로 이해하는 단계를 반드시 거치도록 했습니다.

구체적으로는 다음과 같은 순서로 질문합니다.

1. 이 기존 코드가 무엇을 하고 있는지 설명해 주세요. 아직 구현하지 마세요.
2. 새로운 구성으로 구현한다면, 책임을 어떻게 나누어야 할지 선택지를 여러 개 제시해 주세요.
3. API 측과 프론트엔드 측에서 각각 필요한 타입을 정리해 주세요.
...

포인트는 4번까지는 한 줄의 코드도 쓰게 하지 않았다는 점입니다. 여기서 만들고 있는 것은 코드가 아니라 저의 이해입니다. 5번으로 넘어가는 것은, 1~4번에서 나온 설계 판단을 제가 직접 설명할 수 있게 된 이후입니다.

생성하게 하는 파일 수를 한 번에 1개, 많아도 2~3개로 제한했습니다.

「15개 파일은 너무 많고, 3개 파일이라면 OK」라는 기준에 절대적인 근거는 없습니다. 하지만 저의 기준은 단순합니다. 파일 수 그 자체보다, diff(차이점)를 스크롤 없이 한 화면에 다 볼 수 있는가입니다. 스크롤이 필요해지는 시점에서, 대개 저는 전체상을 놓치고 있습니다.

큰 변경을 맡기고 싶을 때도 갑자기 구현하게 하지 않고, 먼저 plan(계획)만 내놓게 합니다. "구현해줘"가 아니라, 다음과 같이 요청합니다.

- 구현 방침을 알려줘 (아직 코드는 쓰지 마)
- 수정할 파일을 나열해줘
- 예상되는 리스크를 들어줘
...

plan을 읽었는데 "수정할 파일이 10개"라고 나온다면, 그것은 한 번에 넘기기에는 너무 크다는 신호입니다. 그럴 때는 제가 범위를 3개 정도로 나눈 뒤, 하나씩 구현으로 넘어갑니다.

AI에게 구현을 맡기기 전, 스스로에게 다음 사항을 확인합니다. 하나라도 "아니오"가 있다면 아직 넘기기에는 이릅니다. 즉, 먼저 자신의 이해나 설계를 정돈하라는 신호입니다.

목적을 한 문장으로 말할 수 있는가. 말할 수 없다면 AI에게 넘겨도 무엇이 정답인지 판정할 수 없습니다.

변경해도 좋은 범위를 지정할 수 있는가. "이 파일만", "이 함수만", "이 응답 타입만"과 같이 끊을 수 있는지 확인합니다.

리뷰 관점을 하나 이상 말할 수 있는가. "기존 인증을 깨뜨리지 않았는가", "에러 발생 시 동작이 변하지 않았는가" 등입니다. 관점이 없으면 생성물을 봐도 좋고 나쁨을 판단할 수 없습니다.

실패했을 때 되돌릴 수 있는 단위인가. 범위가 크면 제대로 되지 않았을 때 어디서부터 되돌려야 할지 알 수 없게 됩니다.

이 네 가지는 결국 "생성된 diff를 보았을 때, 내가 무엇을 확인해야 하는지 사전에 알고 있는가"를 묻는 것입니다.

이 방식으로 진행하면 AI의 출력은 분명히 적어집니다. 한 번에 15개 파일이 나오지 않습니다. 언뜻 보기에는 퇴보한 것처럼 보일 수 있습니다.

하지만 실제로는 더 빨라졌습니다. 이유는 리뷰 시간 때문입니다. 15개 파일을 한꺼번에 받았을 때의 "어디부터 봐야 할지 모르겠다"는 상태는 리뷰가 진행되지 않을 뿐만 아니라, 불안한 채로 다음 단계로 넘어가게 만듭니다. 1~3개 파일이라면 그 자리에서 차이점을 이해하고 확정할 수 있습니다. 재작업(rework)이 줄어들고, 나중에 원인을 추적할 수 없는 코드가 프로덕트에 들어오는 것을 방지합니다.

생성량이 많다 = 빠르다, 가 아니었습니다. 확정할 수 있는 단위로 진행한다 = 빠르다, 였습니다.

이는 특히 경험이 적은 엔지니어에게 효과적이라고 생각합니다 (저를 포함해서).

경험이 풍부하다면 15개 파일이 나와도 어디를 봐야 하고 어디가 위험한지, 어떤 차이점은 무시해도 되는지 판단할 수 있을지도 모릅니다. 하지만 미경험 영역에서는 그렇지 않습니다. 모르는 기술이 한꺼번에 쏟아져 나오면 AI의 출력은 학습 교재인 동시에 거대한 인지 부하(cognitive load)가 됩니다.

그렇다고 해서 "경험이 적다면 AI를 쓰지 마라"는 뜻이 아닙니다. 반대입니다. 개념을 설명하게 하고, 설계 선택지를 비교하게 하고, 작은 코드를 쓰게 하고, 자신의 이해를 확인하게 하는 것—이런 방식이라면 AI는 최고의 학습 상대입니다. "크게 만드는 도구" 이전에 "작게 이해하는 도구"로 사용하는 것. 그 순서를 지킨다면 경험이 적더라도 AI를 통해 안전하고 빠르게 나아갈 수 있습니다.

AI에게 크게 맡기는 것이 반드시 AI를 잘 사용하는 것은 아니었습니다. 이해하지 못한 영역에서 크게 맡기면 생성물은 늘어나기만 할 뿐, 불확실성은 낮아지지 않습니다.

결국 제가 한 일은 이것뿐입니다.

• 만들게 하기 전에 설명하게 하기 (Chat으로 이해 → 그 후 구현)
• 한 번에 다루는 범위는 한 화면에 다 볼 수 있는 1~3개 파일로 제한
• 큰 변경은 먼저 plan을 내놓게 한 뒤 스스로 분할
• 넘기기 전 4가지 셀프 체크 (목적 · 범위 · 관점 · 되돌릴 수 있는가)

AI 활용이란 생성량을 늘리는 것이 아니라 불확실성을 낮추는 것입니다.

이를 위해 AI에게 맡길 일을 "내가 리뷰할 수 있는 사이즈"까지 작게 설계합니다.