AI 코딩 에이전트가 시니어 개발자처럼 일하게 만드는 법 (addyosmani.com)

한줄 요약

AI 에이전트는 코드를 만들지만, 납품 가능한 결과물은 워크플로우가 만든다.

---

AI 코딩 에이전트를 실무에 투입하면 처음에는 생산성이 폭발하는 것처럼 느껴진다. 그런데 납품 직전에 현실이 찾아온다. 스펙 문서가 없다. 테스트가 빠져 있다. PR 하나가 수정해야 할 파일의 3배를 건드렸다. 에이전트는 "완료"를 선언했지만, 아무도 그 결과물을 검증하지 않았다.

이건 에이전트가 멍청해서가 아니다. 에이전트는 태생적으로 최단 경로를 선택한다. "기능을 만들어라"는 명령을 받으면 기능만 만든다. 그 기능이 요구사항을 충족하는지 확인하고, 엣지 케이스를 테스트하고, 리뷰어가 읽을 수 있는 단위로 쪼개는 일은 명령 범위 밖이다. IT 개발 에이전시 입장에서는 이게 치명적이다. 클라이언트에게 납품하는 건 코드가 아니라 검증된 결과물이기 때문이다.

왜 에이전트는 항상 중간 과정을 건너뛰는가

시니어 개발자가 하는 일의 대부분은 커밋 로그에 나타나지 않는다. 요구사항의 모순을 발견하고 다시 질문하는 것, 구현 전에 설계를 문서화하는 것, 변경 범위를 의도적으로 좁히는 것, 완료 기준을 명확히 정의하는 것. 이 과정들이 쌓여야 유지보수 가능한 소프트웨어가 나온다.

에이전트는 이 과정을 배우지 않았다. 정확히는, 이 과정이 보상 신호에 포함되지 않았다. "스펙 문서를 작성했는가"가 아니라 "작동하는 코드를 만들었는가"로 평가받았다. 그러니 에이전트는 항상 코드를 향해 달린다.

에이전시 환경에서는 이 문제가 더 증폭된다. 여러 프로젝트가 동시에 돌아가고, 클라이언트마다 요구사항 수준이 다르고, 인수인계나 유지보수가 나중에 발생한다. 에이전트가 맥락 없이 만들어낸 코드는 납품 가능한 산출물이 아니다.

에이전트에게 "시니어 개발자 습관"을 이식하는 방법

해결책은 에이전트를 더 똑똑한 모델로 바꾸는 게 아니다. 에이전트가 따라야 할 워크플로우를 외부에서 주입하는 것이다.

핵심 원칙은 하나다. 산문이 아닌 절차를 넣어라. "테스트를 잘 작성해라"는 텍스트를 컨텍스트에 넣으면 에이전트는 그럴듯한 문장을 생성하고 테스트를 건너뛴다. "실패하는 테스트를 먼저 작성하고, 실행해서 실패를 확인하고, 최소한의 코드로 통과시켜라"는 순서를 넣으면 에이전트는 실제로 그 순서를 따른다.

에이전시 실무에 바로 적용할 수 있는 단계는 이렇다.

1단계 — 스펙 없이 구현 금지. 에이전트가 코드를 작성하기 전에 반드시 수락 기준을 문서화하게 만든다. 다섯 줄짜리 간단한 기능이라도 "이 기능이 완료된 상태"를 명문화하는 것이 먼저다. 에이전시 입장에서는 이 문서가 클라이언트와의 분쟁을 막는 방패가 된다.

2단계 — 구현 범위를 강제로 제한. 에이전트는 한 가지를 고치다가 연관된 파일을 통째로 리팩토링하려는 경향이 있다. "요청받은 것만 수정하라"는 규칙을 명시적으로 워크플로우에 박아놔야 한다. PR 단위가 커질수록 리뷰 품질은 낮아지고 머지 리스크는 올라간다.

3단계 — 완료 기준을 증거로 정의. "잘 된 것 같다"는 완료가 아니다. 테스트가 통과했는가, 빌드가 깨끗한가, 예상한 동작이 실제로 확인됐는가. 에이전트의 모든 작업 단계 끝에 검증 증거를 요구하면 에이전시의 QA 비용이 눈에 띄게 줄어든다.

에이전시가 자주 빠지는 합리화 함정

에이전트만 지름길을 택하는 게 아니다. 개발팀도, PM도, 때로는 클라이언트도 비슷한 합리화를 한다. 그리고 그 합리화는 항상 그럴듯하게 들린다.

"이번 건은 너무 작아서 스펙이 필요 없어요." → 작은 기능일수록 수락 기준이 모호해지기 쉽다. 다섯 줄짜리 스펙이 나중에 다섯 시간의 분쟁을 막는다.

"테스트는 나중에 붙이면 돼요." → 나중은 항상 더 바쁜 때다. 구현 직후가 테스트를 작성하기 가장 쉬운 시점이다.

"에이전트가 만들었으니까 빠르게 납품할 수 있어요." → 생성 속도와 납품 가능성은 다른 문제다. 검증되지 않은 결과물을 빠르게 납품하면 유지보수 비용이 그만큼 나중에 몰린다.

이 합리화 목록을 팀 내부 문서에 명시적으로 적어두면 실제로 효과가 있다. 누군가 비슷한 말을 꺼낼 때 반박의 근거가 이미 준비돼 있다.

에이전시 워크플로우에 즉시 적용할 수 있는 다섯 가지 원칙

긴 가이드라인 문서보다 짧고 행동 가능한 원칙이 실무에서 작동한다.

첫째, 구현 전에 가정을 드러내라. 모호한 요구사항을 그냥 진행하는 게 가장 흔한 실패 원인이다.

둘째, 요구사항이 충돌하면 멈추고 물어라. 에이전트든 주니어든, 알아서 판단하게 두면 안 된다.

셋째, 필요할 때 반대해라. 빠른 납품을 원하는 클라이언트에게도 품질 기준을 설명하는 게 에이전시의 역할이다.

넷째, 단순하고 지루한 해법을 선택해라. 새로운 기술 스택이나 영리한 아키텍처보다, 팀 전체가 이해할 수 있는 코드가 장기적으로 유리하다.

다섯째, 요청받은 것만 건드려라. 범위를 지키는 것이 납품 가능성을 결정한다.