Working with AI on Long Software Projects

개요

AI 코딩 도구를 사용하여 장기간의 소프트웨어 프로젝트를 진행할 때 발생하는 복잡성, 기술 부채, 설계 불일치 등의 문제를 피하고 효율적으로 협업하기 위한 실용적인 가이드라인을 제시합니다.

주요 내용

* AI의 한계점 인식:
* 에피소드적 기억 부재: AI는 세션 간의 이전 작업 내용, 컨벤션, 실패 경험 등을 기억하지 못하므로, 매 세션마다 컨텍스트 창에 제공되는 정보나 영구적인 아티팩트(프로젝트 지시 파일, 설계 문서 등)에 의존해야 합니다. 이로 인해 코드 중복, 컨벤션 불일치, 동일한 실수 반복 등의 문제가 발생할 수 있습니다.
* "더 많이 하기" 편향: AI는 불확실할 때 더 많은 코드 생성, 불필요한 유틸리티 함수 추가, 과도한 테스트 작성 등의 경향을 보이며, 이는 유지보수가 어려운 코드베이스로 이어질 수 있습니다. 이러한 편향은 완료도에 초점을 맞춘 검토 워크플로우나 강력한 도구를 적극적으로 사용하려는 AI의 특성에 의해 더욱 증폭됩니다.
* 명세와 현실의 괴리: 시간이 지남에 따라 설계 문서와 실제 시스템 간의 차이가 발생하며, AI가 오래된 문서를 기준으로 작업하면 현실과 동떨어진 시스템을 구현할 수 있습니다.

* 유효한 영구 아티팩트:
* 프로젝트 지시 파일 (Project Instruction File): "항상 ~하기"와 같은 명령형 규칙을 포함하여 AI의 행동을 제어합니다. 최소한의 코드 변경, 3회 이상 호출 시 헬퍼 함수 추출, 실제 버그를 잡는 테스트 작성, 불필요한 정보 제거 등의 구체적인 지침이 중요합니다.
* 메모리 인덱스 (Memory Index): 설계 결정, 학습 내용, 과거 세션 규칙 등을 요약하여 저장합니다. 최신 상태를 유지하기 위해 정기적인 검토 및 삭제가 필수적입니다.
* 코드베이스 내 참조 예제: 주요 패턴에 대한 모범 사례 예제를 만들어 AI가 이를 참조하도록 합니다.

* 피해야 할 안티 패턴:
* 검증 전 과도한 명세 작성: 검증되지 않은 기능에 대한 상세한 구현 계획은 잘못된 시스템 구현으로 이어질 수 있습니다.
* 단계별 적대적 QA: 모든 구현 단계마다 검토 게이트를 두는 것은 완료도에 대한 압박으로 작용하며, 실제 버그를 잡는 것보다 과도한 코드를 생성하게 만듭니다.
* 유사 문제에 대한 여러 병렬 원시 구현: 중복적인 기능 구현 대신 기존 코드를 리팩토링하거나 통합하는 것이 좋습니다.
* 커버리지로서의 테스트: 코드 라인 수를 늘리는 테스트 작성보다 실제 회귀를 방지하는 테스트에 집중해야 합니다.
* 플래그된 모든 항목 구현: 검토자 또는 QA 에이전트가 제기한 모든 사항을 실제로 문제인지 판단하고 해결해야 합니다.

* 효과적인 경량화 프로세스:
* 사용자가 목표를 설명하면, AI는 관련 참조 예제와 문서를 바탕으로 최소 구현을 제안합니다.
* 사용자 승인 후 AI는 최소한의 코드를 구현하고 테스트를 실행합니다.
* 이 프로세스는 설계 긴장을 조기에 드러내고, 오류 발생 시 영향을 최소화하며, 사용자를 지속적으로 참여시킵니다.

시사점

AI 코딩 도구를 효과적으로 활용하기 위해서는 AI의 한계를 이해하고, 프로젝트 지시 파일, 메모리 인덱스, 코드베이스 내 참조 예제와 같은 영구 아티팩트를 통해 AI의 행동을 명확하게 제어해야 합니다. 또한, 사용자가 QA 역할을 수행하며 AI의 생성 결과를 판단하고, 최소한의 코드로 문제를 해결하는 데 집중하는 것이 중요합니다.