코딩 에이전트 사용 1년 후기: AI와 함께 개발하는 방법

지난 1년 동안 Claude Code와 Codex를 활용해 프로덕트를 개발했습니다. 에이전트는 코드를 작성하고 기능을 동작시키는 데 능숙했습니다. 하지만 그 기능이 프로덕트의 방향과 현재 상황에 맞는지 판단하는 일은 여전히 제 몫이었습니다.

개발 속도가 빨라질수록 새로운 고민도 생겼습니다. 에이전트가 “기능이 동작한다”고 보고할 때 어디까지 신뢰할 수 있을까요? 쌓여 가는 코드를 모두 한 줄씩 읽기 어렵다면 무엇을 중심으로 리뷰해야 할까요?

1년 동안 경험하며 내린 결론은 사람이 프로덕트의 구조와 설계 의도를 주도하고, 에이전트는 그 방향에 맞춰 구현하도록 해야 한다는 것입니다.

1. 최신 모델은 의도를 훨씬 잘 파악한다

초기 모델을 사용할 때는 요청하지 않은 작업을 하는 일이 잦았습니다. 특정 기능을 고쳐 달라고 했는데 정작 다른 기능까지 건드리는 식이었습니다.

제가 사용해 본 Astra 6와 Opus 5.5는 이전보다 요청의 맥락과 의도를 잘 파악했습니다. 반면 Luna, Haiku 같은 빠른 작업용 모델이나 Gemini를 사용할 때는 해야 할 작업과 범위를 더 명시적으로 적어 주는 편이 안정적이었습니다.

이것은 어디까지나 제 사용 경험입니다. 모델의 성능은 버전과 작업, 주어진 맥락에 따라 달라질 수 있습니다. 중요한 것은 모델이 좋아졌더라도 무엇을 바꾸고 왜 바꾸는지, 어디까지가 작업 범위인지 분명하게 전달하는 것입니다.

2. 동작하는 기능과 의도한 기능은 다르다

요청의 의도를 잘 이해하는 것과 프로덕트에 맞는 방식으로 구현하는 것은 다른 문제입니다. 에이전트는 기능을 동작시키고 테스트를 통과시키는 데 능숙하지만, 비즈니스 목표나 현재 서비스 규모, 앞으로의 확장 가능성까지 충분히 고려하지 않은 채 구현하기도 합니다.

실제로 에이전트가 개발과 코드 리뷰를 마쳤다고 보고한 뒤에도 데이터 흐름, 메모리 사용량, DB 트랜잭션 충돌 가능성, 아키텍처를 직접 살펴보면 문제를 발견했습니다. 주로 다음과 같은 경우였습니다.

1. 중복 코드와 불필요한 구현: 기존 인터페이스를 활용하면 단순하게 해결할 수 있는데, 당장 기능이 동작하도록 별도의 구현을 추가합니다.
2. 비용과 성능을 고려하지 않은 구조: 이미 메모리에 올라온 데이터를 활용하지 않고 다음 실행에서 다시 적재해 메모리를 중복으로 사용합니다. 이런 구조가 쌓이면 비용과 응답 속도에 영향을 주고 메모리 부족으로 이어질 수 있습니다.
3. 코드와 문서의 불일치: 오래된 문서나 잘못된 기존 코드를 기준으로 삼아 원래 의도와 다른 기능을 만듭니다.
4. 검증에 도움이 되지 않는 테스트: 커버리지 수치를 높이는 데 집중해 실제 기능이나 중요한 실패 상황을 검증하지 못하는 테스트를 작성합니다.

테스트 통과와 에이전트의 완료 보고는 유용한 신호입니다. 다만 그것만으로 설계가 적절하거나 요구한 문제를 제대로 해결했다고 판단할 수는 없습니다. 사람이 프로덕트를 직접 사용하고, 중요한 데이터 흐름과 변경의 영향을 확인해야 합니다.

3. 프로덕트의 주도권을 사람이 가져와야 한다

AI 코딩 에이전트로 개발 속도가 빨라질수록 생성된 코드를 모두 한 줄씩 검토하기는 어려워집니다. 사이드 프로젝트에서도 커밋이 쌓이면 변경량을 따라가는 것만으로 많은 시간이 듭니다.

그렇다고 판단까지 에이전트에게 맡길 수는 없습니다. 제 경험상 에이전트는 전체적인 틀과 방향을 명확하게 제시하면 세부 기능을 잘 구현합니다. 사람은 코드의 양을 따라가는 데 그치지 않고, 프로덕트의 구조와 기능이 의도한 방향으로 발전하고 있는지 살펴야 합니다.

저는 이를 위해 코드의 구조와 기능을 다이어그램과 자연어로 표현하고, 이를 중심으로 리뷰하는 접근이 필요하다고 생각합니다.

• 아키텍처 리뷰: 코드에서 도출한 다이어그램으로 전체 구조를 살펴봅니다. 서비스와 도메인의 경계가 적절한지, 중복되거나 과도하게 추상화된 부분은 없는지 확인합니다.
• 기능 설계 리뷰: 새 기능의 흐름과 시퀀스, 서비스 간 의존관계와 도메인 분리 방식을 문서로 정리합니다. 코드에 들어가기 전에 기능이 어떤 과정으로 동작하고 왜 그렇게 설계됐는지 검토합니다.

다이어그램과 문서는 코드 리뷰를 대체하지 않습니다. 전체 맥락을 파악하고, 특히 주의해서 확인할 코드를 찾는 출발점입니다. 코드와 문서가 일치하는지도 함께 확인해야 합니다.

4. 내 프로덕트를 더 쉽게 이해하고 설계하는 방법

Specify를 활용하면 코드베이스를 바탕으로 프로덕트의 아키텍처를 다이어그램으로 시각화하고, 기능별 개발 노트와 흐름도를 만들어 데이터가 어떻게 전달되고 처리되는지 살펴볼 수 있습니다. 코드를 한 줄씩 따라가기 전에 전체 구조와 기능 간 연결을 파악하는 데 도움이 됩니다.

새 기능을 개발할 때는 다음 순서로 접근합니다.

1. 현재 구조 파악: 기존 아키텍처와 관련 기능을 살펴보고, 재사용할 수 있는 서비스와 데이터를 확인합니다.
2. 기능 설계: PRD를 작성하면서 기능을 어느 도메인에 배치할지, 기존 서비스와 데이터를 어떻게 활용할지 정리합니다.
3. 구현 요청: 검토한 방향과 제약을 코딩 에이전트에게 전달하고 구현을 요청합니다.
4. 결과 검토: 구현된 기능을 직접 사용해 보고, 데이터 흐름과 변경된 구조를 설계 의도와 대조합니다. 중요한 코드와 테스트도 함께 확인합니다.
5. 결정 기록: 설계 의도와 주요 결정을 개발 노트로 남겨 다음 작업에서 참고합니다.

에이전트가 빠르게 기능을 만드는 시대일수록, 무엇을 만들고 어떤 구조로 발전시킬지 결정하는 일은 더 중요해집니다. 프로덕트의 현재 구조를 이해하고 설계부터 주도할 때, 에이전트의 구현 속도를 프로덕트가 나아가야 할 방향에 맞게 활용할 수 있습니다.