10만 LOC 코드베이스에서 AI 에이전트 사용의 실용적인 교훈

대규모 AI 지원 개발을 위한 여섯 가지 구체적인 기술

한 개발자가 최근 AI 에이전트(Claude Code + Cursor)를 사용하여 chDB 분석 엔진 위에 pandas 호환 API 레이어를 구축한 경험을 문서화했습니다. 이 프로젝트는 두 시스템 간 600개 이상의 메서드를 정렬하는 작업을 포함했으며 약 $20k 상당의 토큰 비용이 소요되었습니다. 개발자가 공유한 구체적이고 실행 가능한 교훈은 다음과 같습니다.

주요 구현 세부사항

• CLAUDE.md 규칙 파일 유지: AI는 세션 간 메모리가 없기 때문에, 그들은 AI가 계속 틀리는 모든 패턴, 금지한 모든 단축키, 확정된 모든 아키텍처 결정을 포함하는 규칙 파일을 저장소에 커밋했습니다. 이 파일은 팀 협업 인터페이스 역할도 했습니다. 이 파일이 AI가 무시하기 시작할 "500줄짜리 선언문"이 되지 않도록 주의해야 한다고 경고합니다.
• 출력뿐만 아니라 추론 과정을 살펴보라: 초기 단계에서는 AI가 무엇을 배송하는지보다 어떻게 생각하는지 읽는 것이 더 가치 있습니다. AI의 논리가 당신의 논리에서 벗어날 때, 내 생각이 틀렸는지 아니면 제대로 전달하지 못했는지 물어보세요.
• 주기적으로 제로 컨텍스트 에이전트를 비평가로 활용하라: 그들은 프로젝트 메모리가 전혀 없는 새로운 에이전트(claude.ai/code, Claude Code CLI 아님)를 사용하여 자신의 작업을 비판적이고 합리적인 외부인의 관점에서 평가하기 시작했습니다. 두 가지 키워드가 중요합니다: critical(AI의 기본 수용 모드 재정의)과 rational(감정이 아닌 구조화된 추론 요구).
• 테스트 오라클로 대상 시스템을 사용하라: 그들의 목표는 기존 API와 일치시키는 것이었기 때문에, 실제 코드(GitHub/Kaggle 노트북)를 찾아 한 줄의 import 문을 교체하고 테스트 케이스를 발명하는 대신 출력을 비교했습니다.
• 프롬프트보다 규칙: 그들은 AI가 어떻게 단축키를 사용하는지 관찰하고 명시적 금지 사항을 작성했습니다. 예를 들어: 행 순서 불일치로 인해 테스트가 실패했을 때, AI가 가장 좋아하는 방법은 테스트를 통과시키기 위해 .sort_values()를 추가하는 것이었습니다. 그들은 이를 명시적으로 금지했습니다. 진정으로 일치시킬 수 없는 경우는 XFAIL로 표시하고 절대 조용히 건너뛰지 않습니다.
• 다중 에이전트 파이프라인을 위한 대화 기록보다 파일 시스템: 그들은 파일 시스템이 공유 컨텍스트 레이어인 Python 스크립트로 다중 에이전트 워크플로우를 조정합니다. 각 에이전트는 자신의 작업을 추적 디렉토리에 기록하고, 다음 에이전트는 필요한 내용을 읽습니다. 효과가 있었던 주요 패턴: 역할 분리, 구조화된 결정(결정적 제어 흐름을 위한 JSON 형식의 APPROVE/REJECT/ESCALATE), 실패 시 자동 git 롤백.

개발자는 AI가 규모 작업—수백 개의 함수 정렬, 수천 개의 테스트 생성, 회귀 포착—에 탁월하지만, 판단("이것은 버그인가 기능인가? 아키텍처가 올바른가?")은 여전히 인간의 책임이라고 언급합니다.