올해 초 회사에서 AI 에이전트를 사용해서 코드를 작성하는 방식을 도입했습니다. 개발자가 이슈를 등록하고, 어떤 부분은 에이전트에게 전부 작성해서 PR만, 어떤 작업은 세션을 하나 잡고 에이전트와 같이 작업하는 방식으로 작업하고있습니다. 결국 메인스트림에 머지되는건 사람이 판단하고 결정합니다.
그 과정 중에는 여러가지 부채들을 남겨두고 지나친것들이 군데군데 남아있습니다.
임시방편으로 처리해둔 예외라던가, 순서에 영향을 받는 테스트가 대표적인 예시인것 같네요.
문제는, 에이전트가 이런 코드를 의도적으로 미뤄둔 '부채'라고 구분하기 어렵습니다.
에이전트가 새 기능을 만들면서 이런 부채를 그대로 답습하는 문제를 겪기도 했었는데, 결국 에이전트에게는 현재의 코드베이스가 일종의 코드 스니펫 역할을 하는 이유로 보입니다.
한 예로, @RestControllerAdvice가 잡는 예외처리를 가시성있는 모듈을 넘어 다른 모듈에까지 참조를 넓혀서 임시방편으로 처리해둔 PR이 머지한적이 있습니다.
이후 에이전트가 프로젝트의 예외처리 기준으로 받아들여 같은 방식으로 복제해서 잘못된 구조가 전파되는 문제가 있었습니다.
이런 문제를 겪다보니 최근들어 여기저기서 많이 들려오는 "코드 품질이 더이상 예전만큼 중요하진 않은것 같다"는 주장에 의문이 생깁니다. 보통 지속적으로 관리되는 프로젝트는 시간에 흐름에따라 코드베이스가 점차 성장하고 복잡도가 늘어납니다. 기술부채 뿐만아니라 에이전트가 볼 수 있는 모든 코드는 반복해서 참고하고 확장할 수 있는 입력이라, 잘 정리된 코드일수록 필요한 파일을 빨리 찾고, 잘못된 구현을 참고할 가능성을 줄일 수 있었습니다.
그리고 이런 주장은 AI가 코드 품질의 중요성을 등한시한다기보다, 구현비용이 낮아지면서 '일단 돌아가면' 미루는 풍조에서 시작했지 않을까 합니다. "나중에 고쳐야지"하는 태도가 에이전트를 만나 더 쉽게 정당화된것일 수 있습니다. 코드를 누가 작성하는지는 달라졌지만, 코드가 계속해서 관리되어야하는 사실은 바뀌지 않았습니다. 오히려 에이전트가 기존의 코드를 빠르게 복제하기때문에 코드베이스에 남아있는 설계와 품질이 이후 코드에 미치는 영향이 더 커졌습니다.
에이전트는 왜 기존 코드를 답습할까?
에이전트는 명확한 지침이나 검증 규칙이 없다면 기존 코드를 제품에서 실제로 사용되는 규칙으로 간주하는 경향이 있습니다.
이때 새로운 패턴을 도입하려하면 확인할게 늘어납니다.
- 기존 코드와 섞여도 되나?
- 다른 모듈이 이 구조에 의존하나?
- 테스트는 어떻게 작성돼야하나?
- 이후 만들 기능도 이 패턴으로 만들어야하나?
기존 구현을 복사해서 조금 바꾸면 이런 질문을 많이 생략할 수 있고, '더 일관되어보이는' 이유로 기존 코드를 따라가게됩니다. 현재 작업만 보면 좋은 선택이 될 수 있습니다. 변경 범위가 작고, 검토자가 볼 범위도 줄어들 수 있습니다.
에이전트는 팀이 이해하지 못한 설계도 확장한다
에이전트를 도입한 초기에는 CLAUDE.md, AGENTS.md에 전반적인 컨텍스트와 기본적인 아키텍처 기조를 작성했었습니다.
작성된 항목은 여러 항목이 있었지만 크게 두 분류로 나눌 수 있었습니다.
- 팀구성원 대부분이 상대적으로 이해도가 높은 항목
- 이해도는 낮지만 도입하고싶은 항목
이해도가 높은 항목은 RDB, 트랜잭션 관리, ORM(JPA) 이었고, 이해도가 낮은 항목은 EDA, SAGA와 같은 분산환경 설계에 대한 항목이었습니다.
분산환경 설계는 경험과 레퍼런스가 부족할수록 더 다루기 어려웠습니다. 특히 에이전트가 기존 코드를 가장 가까운 참고자료로 사용하기때문에 설계 의도가 불분명해도 현재 구현을 모범답안처럼 받아들여서 해피케이스의 흐름을 빠르게 완성했습니다. 하지만 피봇트랜잭션 이후 발생하는 문제에 대해서 어떻게 보상처리해야하는지도 명확하지 않았고 에이전트가 만들어둔 코드의 문제를 검증하고 디버깅하기가 굉장히 까다로웠습니다. 분산환경 설계 자체가 문제라는점이 아니라, 팀에서 설계 의도와 실패 상황을 제대로 검증할 수 없는 상황에서 프로젝트의 기준으로 삼았기때문입니다. 팀이 설명할 수 없는 복잡한(또는 고수준의) 구조를 에이전트가 반복해서 확장하게 하면, 언젠가 그 부채가 눈덩이처럼 커져 돌아오게됐습니다.
잘 정리된 코드로 탐색 범위를 최소화
에이전트 비용은 코드를 생성할때뿐만아니라,
- 문서를 읽고
- 관련 파일을 탐색하고
- 실제 호출관계를 파악하고
- 테스트가 어떤 요구를 하는지, 어떤 동작을 보장하는지를 확인하고
- 수정에 따른 영향을 판단할때
더 많이 발생할 수 있습니다.
코드 구조가 명확하다면 이 과정을 최소화할 수 있습니다. 예를 들어 주문과 관련된 코드가 여러 화면과 유틸에 흩어져있고, 어떤곳에서는 서비스 계층을 사용하고, 어떤곳에서는 원자적인 쿼리때문에 인프라 계층에서 일부 비즈니스로직을 처리한다면 에이전트가 어떤 구현을 기준으로 삼아야하는지 모호해집니다.
에이전트에게 좋은코드란
"기능을 추가하거나 문제를 해결할때, 에이전트가 필요한 맥락을 빠르게 찾고 변경에 대한 영향을 좁혀서 안전하게 수정할 수 있는 코드"
회사에서, 사이드프로젝트에서 에이전트를 사용해보면서 느낀 좋은 코드의 정의라고 생각합니다. 사람이나 에이전트나 코드를 리뷰할때도 '정상 동작'을 넘어서
- 다음에 기능을 추가할때 어떻게/어디를 수정해야하는지
- 에이전트가 관련 코드를 쉽게 찾을 수 있는지
- 비슷한 기능의 구현/단위테스트 기준이 있는지
- 변경에 대한 영향을 예측할 수 있는지
- 테스트가 실제 요구사항을 설명하는지
- 임시 구현을 새로운 기능에 복제하고있는지
를 스스로에게 확인하려했습니다. 요구사항을 만족하는데 급급하지않고 앞으로의 변경 비용을 조금이나마 예측하기위한것이었습니다. 종합적으로 판단했을때 에이전트에 좋은코드란
- 책임과 역할이 분명한
- 데이터 흐름이 명확한
- 테스트의 요구사항이 분명한
- 불필요한 추상화 계층을 없앤
- 네이밍 형식이 일관된
코드로, 사람이 지난 수십년동안 쌓아왔던 프로그래밍 원칙과 겹치는 부분이 많아보였습니다. 결국, 방대한 문서 트리나 제약조건보다 코드베이스에 실존하는 한줄이 더 큰 영향으로 작동할때가 더 많았습니다.
마무리
사람이 직접 모든 코드를 읽고 수정할때는 좋은 코드가 개발자의 이해를 돕고 빠른 온보딩에 기여했습니다. 이제는 AI가 기존 코드베이스를 스캔하고 압축된 보고서형태로 개발자에게 보고하는 형태로 인지부하를 줄였고, 대부분의 코드를 작성하면서 개발자의 업무를 크게 줄였습니다.
하지만, 에이전트가 코드 작성을 대신 해준다고해서 산출물인 코드의 품질이 경시되면 안되는것 같습니다. 오히려 에이전트가 이슈를 받아 PR 까지만들고 언젠가는 리뷰조차도 사람의 병목을 해결하는게 일반적인 날이 가까워지고있습니다. 코드리뷰는 PR이 동작하는지를 넘어서 빈 컨텍스트를 가진 새로운 세션이 참고해서 사용해도되는 기준인지 판단하는 일에 가까워지고있습니다.
결국 중요한것은 개발자가 에이전트에게 어떤 코드베이스와 규칙을 물려주고, 어떻게 검증할지가 중요합니다. 에이전트가 얼마나 적은 비용으로 현재와 요구사항을 이해하고, 안전하게 변경할 수 있도록 기반을 마련했느냐가 더 중요해질거라 생각합니다.