1. AI가 프로젝트 전체 구조를 잊는 이유
대규모 프로젝트에서 Claude와 같은 AI 에이전트가 헛다리를 짚는 건 당신 잘못이 아닙니다. 모델은 대화의 초기와 마지막 내용에만 집중하는 중간 소실(Lost in the Middle) 현상을 겪습니다. 특히 컨텍스트 윈도우가 60%를 넘어가면 응답 품질은 바닥으로 떨어집니다. 시스템 지침 파일이 너무 길면 AI는 정작 중요한 로직 대신 설정 파일만 읽느라 토큰을 다 써버립니다.
이걸 막으려면 AI의 주의력을 강제로 분산시키지 말아야 합니다.
- 시스템 지침(CLAUDE.md)을 200라인 이하로 줄이세요.
- 대화가 길어지면 /compact 명령으로 이력을 정리합니다.
- 프로젝트 전체를 훑게 하지 말고, 특정 파일의 45-80행처럼 작업 범위를 직접 지정하세요.
2. 코드베이스 다이어트와 스키마 설계
AI에게 전체 소스 코드를 던져주는 건 비효율적입니다. 대신 인터페이스를 먼저 규격화하세요. API는 OpenAPI, 데이터 모델은 Zod나 Pydantic으로 스키마 파일을 따로 만듭니다. 이렇게 하면 AI는 전체 로직을 고민할 필요 없이, 제공된 규격 안에서만 코드를 생성합니다. 제가 직접 테스트한 결과, 이렇게 스키마를 던져주면 AI가 엉뚱한 코드를 짜서 반복 수정 요청을 하는 횟수가 60% 가까이 줄었습니다.
- 모듈별로 .json 또는 .yaml 스키마를 만드세요.
- 핵심 구조만 담은 100라인 이내의 ai-context.md 파일을 프로젝트 루트에 두세요.
- 전체 검색을 시키지 말고 grep 명령으로 필요한 라인만 추출해 읽히세요.
3. 테스트 샌드박스로 AI 코드 검증하기
AI가 짠 코드는 그럴듯하지만 버그 투성이일 때가 많습니다. Husky나 pre-commit 프레임워크를 써서 품질 게이트를 통과하지 못한 코드는 아예 병합할 수 없게 막으세요.
- Pre-commit 훅에 eslint와 tsc --noEmit을 넣어 문법과 타입 오류를 원천 차단하세요.
- 코드 수정 직전에 보안 스캔을 수행하는 PreToolUse 훅을 설정해 API 키 유출을 방지하세요.
- 메인 에이전트가 코드를 쓰면, 서브 에이전트가 그 코드에 대한 실패 테스트를 작성하게 만드세요. 테스트가 성공(Green)할 때까지 루프를 돌리면 버그를 조기에 잡을 수 있습니다.
4. 브랜치 전략으로 세션 초기화하기
AI가 여러 파일을 건드리면 사이드 이펙트가 발생합니다. 이걸 막으려면 브랜치를 저장소가 아닌 작업 컨테이너로 쓰세요. 기능 단위로 브랜치를 쪼개면 AI가 최신 변경 사항만 파악하게 격리할 수 있습니다.
- 로그인 기능 하나를 짜더라도 feature/auth-validation처럼 브랜치를 쪼개세요.
- 세션을 끝낼 때는 반드시 /compact를 실행한 뒤, 남은 할 일을 current-handover.md 파일에 적어두세요.
- 새 세션을 시작할 때는 /clear로 이전 이력을 싹 비우고, 필요한 스키마 파일과 핸드오버 문서만 새로 로드하세요.
이렇게 하면 AI가 불필요한 과거 맥락 때문에 코드를 망치는 일을 피할 수 있습니다.
