우리 코드베이스에서 AI의 환각 현상을 멈추게 한 방법
AI 코딩 도구는 실제 운영 프로젝트에서는 실패합니다. 새로운 코드에서는 잘 작동하지만, 히스토리가 쌓인 오래된 코드에서는 무너집니다.
우리의 핀테크 프로젝트는 3년의 히스토리를 가지고 있습니다. 두 개의 React 프론트엔드, 관리자 패널, 그리고 FastAPI 백엔드로 구성되어 있습니다. 데이터베이스는 많은 테이블과 복잡한 조인(join)으로 이루어져 매우 복잡합니다.
우리는 더 빠르게 작업하기 위해 AI를 사용하려 했습니다. 하지만 실패했습니다.
AI에게 연락처(contacts) 테이블을 만들어 달라고 요청했습니다. AI는 이름과 이메일을 위한 새로운 컬럼을 생성했습니다. 이미 users 테이블에 해당 정보가 있다는 사실을 인지하지 못한 것입니다. 외래 키(foreign key)를 사용하는 대신 데이터를 중복 생성했습니다.
AI가 멍청했던 것이 아닙니다. 컨텍스트(context)가 없었을 뿐입니다. 불완전한 정보를 바탕으로 결정을 내린 것입니다.
저는 더 나은 코드를 얻는 방법을 묻는 것을 그만두었습니다. 대신 AI가 올바른 결정을 내리는 데 어떤 컨텍스트가 필요한지 묻기 시작했습니다.
우리는 구조화된 워크플로우를 구축했습니다. AI의 성능은 제공된 컨텍스트의 수준에 달려 있습니다. 우리는 그 컨텍스트를 명시적으로 만들었습니다.
우리의 설정은 다음과 같습니다:
- ADR 디렉토리: Architecture Decision Records를 위한 폴더를 만들었습니다. 이 파일들은 우리가 왜 특정 선택을 내렸는지 설명합니다. 한 파일은 AI에게 새로운 테이블을 만들기 전에 기존 테이블을 확인하도록 지시하며, 사용자 데이터의 중복 생성을 금지합니다.
- context.md: 이 파일은 우리의 특정 용어들을 설명합니다. AI에게 우리의 고유한 단어들이 서로 어떻게 연관되는지 알려줍니다.
- plot.md: 프로젝트의 전체적인 지도와 각 구성 요소가 어떻게 연결되는지 보여줍니다.
- 필수 테스트: 모든 새로운 API 경로는 테스트 케이스를 필요로 합니다.
이것이 모든 것을 바꾸었습니다. 한 번은 AI가 공유 유틸리티 함수를 변경한 적이 있습니다. 그 변경으로 인해 시스템의 다른 여덟 부분이 망가졌습니다. 하지만 테스트 스위트가 즉시 이를 잡아냈습니다. AI는 실패를 확인하고, 기존 요구사항과 새로운 요구사항을 모두 처리할 수 있는 버전을 생성함으로써 스스로 실수를 바로잡았습니다.
테스트가 없었다면 그 버그는 운영 환경까지 도달했을 것입니다.
AI를 신입 개발자처럼 대하십시오. 신입 사원이 우리 코드베이스를 모른다고 해서 비난하지는 않습니다. 대신 문서와 온보딩 과정을 제공합니다. 우리는 AI에게도 똑같이 했습니다.
우리의 구조:
docs/context.md: 프로젝트 용어 및 연결 관계.docs/plot.md: 코드베이스의 상위 수준 지도.docs/adr/: 테이블 생성 및 API 구조와 같은 구체적인 규칙.
팀을 위한 세 가지 규칙:
- ADR을 구체적으로 작성하십시오. 모호한 조언 대신 명확한 지침을 사용하십시오.
- 문서에 권위를 부여하십시오. AI에게 이 규칙들이 최우선임을 알려주십시오.
- 실수를 규칙으로 만드십시오. AI가 실패할 때마다 새로운 ADR을 작성하십시오.
이 시스템이 AI를 완벽하게 만들어주지는 않습니다. 하지만 AI를 예측 가능하게 만듭니다. 우리는 AI가 일관되게 작동하여 팀이 더 빠르게 움직일 수 있는 코드베이스를 원합니다.