3년 된 핀테크 코드베이스에서 AI의 환각 현상을 멈추게 만든 방법
AI 코딩 도구는 실제 운영 프로젝트에서 실패합니다. 새로운 코드에서는 잘 작동하지만, 히스토리가 쌓인 오래된 코드베이스에서는 무너집니다.
저는 우리 핀테크 프로젝트를 통해 이 사실을 뼈저리게 배웠습니다. 저희는 두 개의 React 프론트엔드, 관리자 패널, 그리고 FastAPI 백엔드를 보유하고 있습니다. 데이터베이스는 복잡하며, 민감한 금융 및 사용자 데이터를 담고 있습니다.
개발 속도를 높이기 위해 AI를 사용해 보았지만, 즉시 실패했습니다.
AI에게 연락처(contacts) 테이블을 만들어 달라고 요청했더니, 이름과 이메일을 위한 새로운 컬럼을 생성했습니다. 하지만 이 컬럼들은 이미 users 테이블에 존재하고 있었습니다. AI는 외래 키(foreign key)를 사용하는 대신 데이터를 중복 생성했습니다. AI는 우리에게 users 테이블이 있다는 사실조차 전혀 몰랐던 것입니다.
저는 AI에게 어떻게 하면 더 좋은 코드를 쓰게 할지 묻는 것을 그만두었습니다. 대신, AI가 올바른 결정을 내리기 위해 무엇을 알아야 하는지 묻기 시작했습니다.
AI는 여러분이 제공하는 컨텍스트(context)만큼만 똑똑합니다. 저희는 컨텍스트를 명시적이고 권위 있게 만들었습니다. 저희가 구축한 시스템은 다음과 같습니다:
• ADR 파일: docs/adrs/ 폴더를 만들었습니다. 이 파일들은 우리가 왜 이러한 아키텍처 결정을 내렸는지 기록합니다. 한 파일(ADR-001)은 AI에게 다음과 같이 지시합니다: "먼저 기존 테이블을 확인하라. 외래 키를 사용하라. 사용자 데이터를 절대 중복 생성하지 마라."
• context.md: 이 파일은 우리의 특정 용어들을 설명합니다. 시스템 내에서 서로 다른 개념들이 어떻게 연결되는지 AI에게 알려줍니다.
• plot.md: 이는 상위 수준의 지도입니다. 프로젝트의 서로 다른 구성 요소들이 어떻게 연결되는지 보여줍니다.
• 엄격한 규칙: AI에게 docs 디렉토리가 최종 권위임을 알렸습니다. AI는 반드시 이 규칙들을 순서대로 따라야 합니다.
• 필수 테스트: 모든 새로운 API 경로는 반드시 테스트 케이스를 포함해야 합니다.
이 시스템은 AI를 예측 가능하게 만듭니다.
한번은 AI가 공유 함수를 수정하는 바람에 앱의 다른 여덟 부분이 망가진 적이 있었습니다. 하지만 테스트가 있었기에 AI는 실패를 감지할 수 있었습니다. AI는 기존 요구사항과 새로운 요구사항을 모두 처리할 수 있는 함수의 새로운 버전을 생성함으로써 스스로 실수를 바로잡았습니다. 테스트가 없었다면 그 버그는 그대로 운영 환경에 배포되었을 것입니다.
AI가 코드베이스를 모른다고 비난하는 것을 멈추세요. AI를 신입 사원처럼 대하십시오. 신입 사원이 우리 규칙을 모른다고 해서 비난하지는 않지 않습니까? 대신 문서와 온보딩을 제공합니다.
저희의 구조는 다음과 같습니다:
docs/
- context.md (용어 및 연결 관계)
- plot.md (상위 수준 지도)
- adr/ (테이블 생성이나 API 구조와 같은 구체적인 규칙)
워크플로우를 위한 세 가지 팁:
- ADR을 구체적으로 작성하세요. 모호한 조언 대신 명확한 지침을 사용하세요.
- 문서를 권위 있게 만드세요. AI에게 이 규칙들이 최우선임을 알려주세요.
- 실수를 규칙으로 만드세요. AI가 실패할 때마다, 이를 방지하기 위한 새로운 ADR을 만드세요.
이것이 AI를 완벽하게 만들지는 않습니다. 하지만 일관되게 만듭니다.
Optional learning community: https://t.me/GyaanSetuAi