AI 코드 품질을 높이는 피드백 루프 개선기

안녕하세요. DB 개발본부 플랫폼1팀 황규민입니다. 플랫폼 1팀은 MaxGauge 제품의 개발 업무를 담당하고 있습니다. 고객사 운영 환경에서 수집되는 데이터를 안전하게 처리하고, 추이 분석과 알람 등 모니터링 서비스 운영에 필요한 핵심 기능을 제공하는 것이 주된 업무입니다. 최근 제품을 지원하면서 AI 어시스턴트를 적극적으로 활용하고 있습니다. 반복적인 코드 작성이나 스펙 검토 등의 작업에서 실제로 많은 도움을 받을 수 있었습니다. 하지만 운영 제품을 다루면서 AI가 구현한 코드를 그대로 적용하기 어려운 경우가 많았습니다. 전달된 요구사항에 맞는 코드는 빠르게 생성할 수 있었지만 제품의 세부적인 운영 맥락(Context)까지는 AI에게 충분히 전달하지 못했기 때문입니다. 예를 들어, 다음과 같은 문제가 발생했습니다.

폐쇄망 환경임에도 외부 네트워크 접근을 전제로 한 코드를 생성하는 경우

운영 환경에서 위험할 수 있는 설정을 사용하는 경우

AI 활용으로 코드 작성 속도는 빨라졌지만 반대로 코드를 검증하는 시간은 늘어났습니다. 이 글에서는 운영 환경에서 신뢰 가능한 코드를 만들기 위해 AI 피드백 루프를 개선하며 겪었던 문제와 해결 과정을 공유하고자 합니다.

1. 첫 번째 개선점: 읽기 어려운 코드

피드백을 위해서는 먼저 코드가 읽기 쉬워야 합니다. 읽기 어려운 코드로 인해 도메인 맥락이 잘 반영되었는지 확인하기 어려웠습니다. 그래서 처음에는 AI가 생성한 코드가 쉽게 읽힐 수 있도록 가이드를 작성하는 데 집중했습니다. 그 결과 팀 내에서 80건 이상의 행동 지침을 정의했고 그중 중요하다고 생각되는 기준을 세 가지 정도로 추려보았습니다.

1-1. 네이밍

좋은 이름을 사용하는 것도 중요하지만, 같은 개념을 여러 이름으로 부르지 않는 것도 중요합니다. 예를 들어 모니터링 대상이 되는 데이터베이스를 의미하는 용어가 Instance, Target, Database 처럼 다르게 사용되면 리뷰어는 매번 같은 단위를 의미하는지 확인해야 합니다.

그래서 자주 사용되는 용어는 도메인에서 익숙한 용어를 참고할 수 있도록 제공하고 있습니다.

팀과 도메인마다 익숙한 표현이 다를 수 있기 때문에 직관적인 이름보다는 팀 내에서 사용되는 용어를 권장합니다.

1-2. 패키지

패키지 구조 역시 피드백에 중요한 요소라고 생각합니다. 패키지가 도메인 단위로 구분되지 않고 한 곳에 몰려 있으면 리뷰어가 그 역할과 영향 범위를 파악하기 어렵습니다. 반대로 패키지가 잘 나뉘어 있으면 파일 위치만 보더라도 이 코드가 어떤 역할을 수행하는지 빠르게 이해할 수 있습니다.

예시로 단순히 모든 유틸을 common/util에 모으는 방식은 지양했습니다.

구현된 코드가 공통 코드인지 특정 도메인에서 사용되는 코드인지 구분하기 어려워지기 때문입니다. 대신 사용 범위와 도메인을 기준으로 위치를 나눴습니다.

작업된 파일이 패키지 구조에 맞게 배치되면서 리뷰어는 코드를 보기 전에 코드의 역할과 영향 범위를 먼저 인지하고 검증할 수 있었습니다.

1-3. 단순함

AI는 종종 요구사항을 넘어서는 복잡한 구조를 만들어냅니다. 예를 들어 단순한 조건 분기에 전략 패턴이나 추상 클래스 등을 사용하는 경우가 있습니다. 결과적으로 코드가 불필요하게 복잡해져 본래의 의도를 이해하기 어려워집니다. 반복문만으로 구현이 가능한 기능을 재귀 호출로 작성하는 것 역시 운영 관점에서는 오버 엔지니어링으로 볼 수 있습니다. 반환 조건에 따라 스택 오버플로우를 유도할 수 있기 때문에 유지보수 시 고려할 사항이 늘어나기 때문입니다. 피드백이 잘 이루어지려면 수정 범위가 좁고 명확해야 합니다. 그래서 AI에게는 단순한 구현을 기본값으로 두도록 가이드하고 있습니다.

2. 두 번째 개선점: 개인 대화 도구의 한계

코드가 읽기 쉬워지면서 AI가 작성한 코드를 쉽게 파악하고 유의미한 피드백을 제공할 수 있었습니다. 문제는 그 피드백이 개인의 대화 안에서만 남는다는 점이었습니다.

예를 들어 오늘 한 개발자가 폐쇄망 고객사 환경을 고려해야 한다는 피드백을 AI 어시스턴트에게 제공하더라도, 내일 다른 팀원의 작업에서 같은 실수가 반복될 수 있었습니다.

이를 해결하고자 팀의 규칙과 도메인 지식을 공용 공간에 관리하기 위해 GitLab 프로젝트와 RAG 환경을 구성하게 되었습니다. 코드 작성 규칙처럼 가볍고 명확한 정보는 GitLab 프로젝트로 관리하고 제품 버전별 스펙처럼 방대한 양의 정보는 RAG 데이터로 저장하여 관리하고 있습니다. 결과적으로 반복되는 피드백을 줄이고, 주요 정보와 개발 규칙을 관리할 수 있게 되었습니다.

GitLab 컨텍스트

RAG 컨텍스트

3. 세 번째 개선점: 실패 지점 예측의 어려움

3-1. 복잡한 자동화 구성의 한계

공유된 컨텍스트 정보를 활용하기 위해 MCP, 메모리 파일, 하네스 등 다중 도구 환경을 검토하고 적용해 보았습니다. 이런 방식은 AI가 더 넓은 범위의 자료를 유연하게 참조할 수 있다는 장점이 있었습니다. 하지만 구조가 복잡해질수록 오히려 실패 원인을 추적하기 어려워졌습니다. 실제로 AI가 기대한 결과를 생성하지 못했을 때

프롬프트 문제인지

RAG 컨텍스트 문제인지

서브 에이전트에서 작업이 누락되었는지

파악하는 데 많은 비용이 발생했습니다. 결국 저희 팀은 구조를 복잡하게 가져가기보다 프롬프트 중심의 단순한 입력 구조를 사용하게 되었습니다.

3-2. 프롬프트 방식을 사용하는 이유

🔍 실패 지점을 예측하기 쉽습니다

현재 사용 중인 프롬프트 구성은 다음과 같습니다.

구조 자체는 단순하지만 어떤 정보가 입력되었는지 한눈에 확인할 수 있다는 장점이 있습니다. 예를 들어 결과가 기대와 다르게 생성되었을 때

태스크 요구사항이 부족했는지

코드 컨벤션이 누락되었는지

잘못된 도메인 지식을 참조했는지

쉽게 추적해서 다음 작업에 반영할 수 있습니다.

✅ 결과 예측 가능성이 높아집니다

하네스, MCP, 메모리 파일이 도입된 다중 도구 환경에서는 내부 구조와 참조되는 컨텍스트에 따라 결과가 달라질 수 있습니다. 문제는 개발자가 그 과정을 인지하기 어렵다는 점입니다. AI가 어떤 기준으로 코드를 생성했는지 개발자가 인지할 수 없다면 AI가 작성한 코드 전체를 문제 지점으로 의심하고 검증해야 합니다 반면, 프롬프트 중심 구조에서는 구현에 사용된 정보를 미리 확인할 수 있습니다. 제공된 정보를 기반으로 AI가 생성할 결과를 예상해 볼 수 있고 우려되는 지점을 중심으로 검토를 진행할 수 있습니다. 🧪 테스트하기 쉽습니다

프롬프트 구조의 큰 장점은 여러 원인 지점을 수정하며 테스트하지 않아도 된다는 점입니다. 시스템을 재설정하거나 메모리 파일을 동기화하는 등의 부가적인 과정 없이, 프롬프트 내의 텍스트 수정만으로 결과물을 확인하고 검증할 수 있습니다. 이처럼 피드백 루프가 매우 짧기 때문에 시행착오를 빠르게 줄여 나갈 수 있습니다.

4. 네 번째 개선점: 프롬프트 작성의 어려움

프롬프트 중심 구조를 사용하면서 또 다른 문제가 생겼습니다. 컨텍스트를 상황에 맞게 조합해 긴 프롬프트를 구성하는 작업이 반복적으로 필요해졌기 때문입니다. 처음에는 수동으로 프롬프트를 구성했지만 다음과 같은 문제가 발생했습니다.

정보의 불완전성: 컨텍스트를 누락하거나 불필요한 정보가 포함됨

일관성 부족: 작성자마다 프롬프트 구조가 달라져 결과의 품질이 일정하지 않음

비효율적인 공수: 매번 컨텍스트를 확인하고 수동으로 조합해야 하는 번거로움

이를 해결하기 위해 프롬프트 생성기를 도입하여 활용하고 있습니다.

개발자가 간단한 요구사항을 입력하면 제품, 버전, 작업 범위를 분석하고 작업 유형에 맞는 프롬프트 요소(도메인 지식, 코드 규칙, 프롬프트 제안 등)를 추천합니다. 사용자는 이 요소들을 조합하고 다듬는 과정을 통해 최종적으로 완성도 높은 프롬프트를 쉽게 생성할 수 있습니다. 이를 통해 프롬프트 구성에 소요되는 시간을 줄이고, 재사용 가능한 프롬프트를 팀 내에 공유할 수 있게 되었습니다.