문제는 AI가 나쁜 코드를 쓰는 게 아니다
AI 코딩 도구를 단발성 세션에서 쓸 때는 대부분 만족스럽다. 명확한 요청에 빠르고 구조적인 구현이 나온다. 문제는 그다음이다. 같은 도구로 3개월, 6개월짜리 프로젝트를 함께 굴릴 때 어느 순간 코드베이스가 조용히 이상해진다. 필요하지 않은 헬퍼 함수가 쌓이고, 비슷한 패턴의 구현이 세 벌 생기고, 설계 문서는 현재 시스템과 점점 어긋나기 시작한다. dev.to에 올라온 「Working with AI on Long Software Projects」는 이 실패 경험을 1년 치 데이터로 정리한 실전 가이드다. 이론이 아니라 실제 코드베이스에서 부딪힌 실패 모드와 그 구조적 해법을 담고 있다.
에피소드 메모리가 없다는 것의 진짜 의미
가장 중요한 전제부터 짚자. AI 코딩 도구는 세션 간 기억이 없다. 지난주에 어떤 컨벤션을 정했는지, 어떤 접근을 시도했다가 포기했는지, 어느 코드가 핵심 로직이고 어느 코드가 임시방편인지—모델은 아무것도 모른다. 새 세션이 시작될 때마다 컨텍스트 윈도우 안에 있는 것만이 전부다.
이 구조적 한계는 세 가지 방식으로 코드베이스를 망가뜨린다. 첫째, 기존 코드를 신뢰하지 않으니 수정 대신 새 헬퍼를 추가하는 쪽을 택한다. 블로트가 쌓인다. 둘째, "지난달에 X 패턴으로 가기로 했다"는 기억이 없으니 세션마다 약간씩 다른 선택이 누적된다. 일관성이 흐트러진다. 셋째, "그 방식은 시도해봤는데 안 됐다"는 맥락이 없으니 같은 실수를 6주 후에 다시 반복한다. 팀이 이 한계를 이해하지 못하면, 코드베이스는 보기엔 인상적이지만 아무도 전체를 머릿속에 담을 수 없는 시스템이 된다.
AI의 기본값은 '더 하기'—이게 장기 프로젝트를 죽인다
두 번째 실패 모드는 더 교묘하다. AI 모델의 기본 행동 편향은 '철저함'이다. 버그 하나 고쳐달라고 하면 주변 코드도 같이 정리한다. 기능 하나 추가해달라고 하면 '미래 유연성'을 위한 설정 변수를 덧붙인다. 함수 하나 써달라고 하면 '모듈성'을 위해 헬퍼 세 개를 함께 만든다. 각 인스턴스는 무해하다. 그 누적 효과가 유지보수 불가능한 코드베이스를 만든다.
특히 QA 에이전트가 리뷰 루프에 들어가는 경우 이 문제가 심화된다. QA는 빠진 것을 잡아낼 수 있지만, 과도한 것은 잡아내지 못한다. "이건 너무 많다"는 판단은 설계 감각이 필요한데 QA 에이전트는 그걸 갖고 있지 않다. 결과적으로 리뷰 패스마다 추가만 될 뿐 제거가 없다. 코드베이스는 단조롭게 성장한다.
컨텍스트를 구조로 고정하는 세 가지 아티팩트
이 두 실패 모드의 해법은 같다. 세션 간에 살아남는 구조를 미리 설계하는 것이다. 원문은 세 가지 아티팩트를 제시한다.
첫째, 프로젝트 인스트럭션 파일(CLAUDE.md). 매 세션 자동으로 로드되는 이 파일이 가장 높은 레버리지를 가진다. 핵심은 '설명'이 아니라 '명령'으로 작성하는 것이다. "이 프로젝트는 React와 TypeScript를 쓴다"는 정보다. "새 컴포넌트는 스토리가 있어야 하며, as any 는 사용 금지"는 운영 규칙이다. 후자만이 일관된 행동을 만들어낸다. 특히 실전에서 검증된 규칙들이 있다. "불확실할 때는 더 적게 만들어라", "헬퍼 함수는 호출처가 3곳 이상일 때만 추출하라", "테스트는 실제 버그를 잡을 수 있을 때만 작성하라", "아직 존재하지 않는 미래 호출자를 위한 API는 만들지 말아라". 이 규칙들은 AI의 기본 '더 하기' 편향을 명시적으로 역전시킨다.
둘째, 메모리 인덱스. 과거 세션의 설계 결정, 시도했다가 포기한 접근, 학습한 교훈을 담은 문서들의 포인터 목록이다. 각 항목은 한 줄로 관리한다. "인증 토큰은 절대 로그에 남기지 않는다—이유: 2024-Q3 PII 노출 사고; 적용 위치: 로그 호출 지점이 아니라 미들웨어에서 강제". 중요한 것은 정기적으로 가지치기하는 것이다. 6개월 전 항목의 대부분은 이미 구식 상태를 가리키고 있고, 오래된 메모리는 없는 것보다 나쁘다.
셋째, 설계 문서의 역할 재정의. 장기 프로젝트에서 설계 문서는 시스템이 어떻게 되어야 하는지를 설명할 수도 있고, 현재 어떤 상태인지를 설명할 수도 있다. 충분한 시간이 지나면 아무도 어느 쪽인지 구분하지 못한다. 원칙은 단순하다. 설계 문서는 '기술(describe)'하되 '처방(prescribe)'하지 않는다. 의도, 컴포넌트, 상호작용을 담되 의사코드나 "정확히 이렇게 구현하라"는 섹션은 없어야 한다.
메타 엔지니어링: 규칙이 규칙을 감사하는 구조
같은 맥락에서 주목할 만한 접근이 있다. 「The portfolio IS the product: recursive meta-engineering with Claude Code」에서 소개된 재귀적 메타 엔지니어링 패턴이다. 핵심 아이디어는 프레임워크가 자기 자신에게 동일한 규칙을 적용한다는 것이다. "모든 규칙은 WHY 태그와 폐기 조건을 가져야 한다"는 규칙이 있다면, 그 규칙 파일 자체가 그 기준으로 감사된다. push 전에 integrity-check 스크립트가 자동으로 돌면서 규칙과 실제 아티팩트 사이의 일관성을 검증한다.
이 패턴이 장기 프로젝트에서 의미 있는 이유는 명확하다. 선언만 있고 검증이 없는 규칙은 시간이 지날수록 현실과 멀어진다. CLAUDE.md에 "테스트는 실제 버그를 잡을 수 있을 때만 작성하라"고 써 있어도 그 규칙이 실제로 지켜지는지 누구도 확인하지 않으면, 몇 달 후 그 파일은 그냥 참고용 텍스트로 전락한다. 규칙이 스스로를 감사하는 구조가 있어야 규칙이 살아있는 운영 도구로 남는다.
팀에 적용하기 전에 짚어야 할 것들
솔직하게 말하자. 이 접근들이 효과적이려면 선제 조건이 있다. 팀 전체가 아티팩트를 관리하는 규율을 유지해야 한다. CLAUDE.md가 있어도 아무도 업데이트하지 않으면 6개월 후 그건 거짓말 문서가 된다. 메모리 인덱스를 정기적으로 가지치기하지 않으면 오히려 AI를 잘못된 방향으로 유도한다.
또한 이 구조는 AI의 과잉 생산 편향을 억제하는 데 집중하지만, AI가 아예 잘못된 방향으로 설계 결정을 내리는 경우는 별개의 문제다. 아티팩트 전략은 일관성을 유지하는 데 강하지만, 근본적으로 잘못된 설계 방향을 수정하는 건 여전히 사람의 판단이 필요하다. AI-First 워크플로우에서 팀 리드의 역할이 줄어드는 게 아니라, 코드를 직접 쓰는 비중이 줄고 설계 판단과 아티팩트 관리에 집중하는 방향으로 이동한다는 뜻이다.
내일 팀에서 시작할 수 있는 것
이론이 아니라 실행 기준으로 정리하면 세 가지다.
첫째, CLAUDE.md를 지금 당장 검토하라. 파일이 없다면 만들고, 있다면 '설명문'이 아니라 '명령문'으로 구성되어 있는지 확인하라. "React를 사용한다"는 문장은 지우고 "새 컴포넌트는 반드시 스토리가 있어야 한다"로 바꿔라.
둘째, "더 하기" 규칙을 명시적으로 역전시켜라. CLAUDE.md 상단에 "불확실할 때는 요청된 것만 만들어라. 미래 호출자를 위한 추가는 하지 않는다"를 넣어라. AI의 기본 편향을 파일 레벨에서 명시적으로 제어하는 것이다.
셋째, 설계 문서의 최종 갱신일을 확인하라. 3개월 이상 갱신되지 않은 설계 문서가 AI의 컨텍스트로 로드되고 있다면, 그건 현재 시스템이 아닌 과거의 의도를 재현하는 지침으로 작동하고 있을 가능성이 높다.
결국 컨텍스트 설계가 팀의 경쟁력이다
AI 코딩 도구의 단기 생산성은 이미 증명됐다. 이제 차별점은 장기 프로젝트에서 코드베이스의 일관성과 유지보수성을 얼마나 지켜내느냐다. 그 능력은 AI 도구 자체에 있지 않다. AI가 세션마다 의존하는 구조—인스트럭션 파일, 메모리 인덱스, 살아있는 설계 문서—를 팀이 얼마나 잘 설계하고 유지하느냐에 달려 있다.
컨텍스트 엔지니어링은 더 이상 프롬프트 기법이 아니다. 장기 프로젝트를 AI와 함께 굴리는 팀의 핵심 인프라 설계다.