대형 저장소에서 AI 에이전트가 흔들리는 이유는 파일 수 자체보다 현재 작업과 무관한 코드와 지침까지 한꺼번에 읽기 때문이다. “전체 구조를 파악하고 고쳐 줘”라고 하면 탐색 범위, 완료 기준, 건드리면 안 되는 영역이 모두 비어 있다. 첫 요청은 구현이 아니라 필요한 코드만 찾는 지도 만들기여야 한다.
Claude Code의 공식 안내도 시작 위치, 디렉터리별 지침, 읽기 제한으로 작업 범위를 좁히도록 설명한다. 제품 설정은 대형 코드베이스 공식 가이드에서 확인할 수 있다.
1단계. 실행 위치부터 작업 범위에 맞춘다
한 패키지나 하위 서비스만 바꾼다면 그 디렉터리에서 세션을 시작한다. 저장소 루트에서 시작하면 여러 패키지를 읽을 수 있지만 관계없는 파일과 지침까지 만날 가능성이 커진다. 반대로 공통 타입처럼 여러 패키지에 걸친 변경은 루트에서 시작하거나 필요한 형제 디렉터리만 접근 범위에 추가한다.
시작 전에 대상 디렉터리, 읽지 않을 생성 파일·벤더 코드, 비밀 파일, 수정 금지 경로를 적는다. 파일 접근과 수정 권한은 별개이므로 읽기와 쓰기 경계를 따로 선언한다.
2단계. 읽기 전용으로 저장소 지도를 만든다
첫 산출물은 코드가 아니라 근거가 붙은 지도다. 다음 항목을 파일 경로와 줄 번호로 돌려받는다.
- 요청 흐름의 진입점과 주요 호출 순서
- 데이터 저장 지점과 외부 서비스 경계
- 관련 테스트, 실행 명령, 설정 파일
- 같은 기능의 기존 구현 사례
- 확인하지 못한 가정과 추가 질문
Claude Code의 Plan 모드는 파일을 읽고 조사 명령을 실행해 계획을 만들지만, 일반적인 권한 설정에서만 승인 전 편집을 막는다. bypassPermissions 가능 세션은 이 제한의 예외다. 그 밖의 세션에서는 조사 명령도 권한 판정을 받는다. 진짜 읽기 전용으로 운영하려면 쓰기 명령을 승인하지 않거나 권한 규칙으로 차단한다. 동작은 Plan 모드 공식 문서에서 확인한다.
3단계. 지도를 사람의 설명과 대조한다
에이전트가 찾은 경로가 실제 운영 흐름인지 담당자가 확인한다. 도메인 용어, 자주 깨지는 통합 지점, 과거에 실패한 변경에는 근거가 되는 이슈나 코드 위치를 붙인다. 오래된 문서와 현재 코드를 구분하지 않으면 잘못된 지도가 다음 작업의 전제가 된다.
검증된 내용 중 매번 필요한 것만 프로젝트 지침에 반영한다. 루트에는 공통 규칙을, 하위 디렉터리에는 해당 영역의 테스트와 관례를 둔다. 하위에서 시작하면 그 위치와 모든 상위 CLAUDE.md가 시작 시 로드되고, 더 아래 지침은 그곳의 파일을 읽을 때 들어온다. CLAUDE.md는 강제 설정이 아닌 컨텍스트이므로 짧고 구체적이어야 한다. 작성 기준은 프로젝트 지침 공식 안내에서 확인한다.
4단계. 변경 계획을 파일 단위로 승인한다
계획에는 수정 파일과 이유, 수정하지 않을 영역, 테스트 순서, 실패 시 원복 방법을 넣는다. “인증을 개선한다”가 아니라 “세션 만료를 재현하는 테스트를 먼저 추가하고, 토큰 갱신 함수만 고친다”처럼 검증 가능한 문장으로 쓴다. 공식 권장 흐름도 낯선 다중 파일 작업에서는 탐색, 계획, 구현을 분리한다. 예시는 Claude Code 모범 사례에서 볼 수 있다.
사람이 지도와 계획의 파일 목록을 대조한 뒤에만 쓰기 단계로 넘어간다. 계획 밖 파일이 필요해지면 몰래 넓히지 말고 중단 사유와 새 범위를 다시 승인받게 한다.
5단계. 가장 작은 변경으로 지도를 검증한다
첫 구현은 한 흐름과 가까운 테스트로 제한한다. 버그는 기존 실패를 재현하고, 기능 추가는 기대 동작을 표현한 실패 테스트로 먼저 고정한다. 수정 후 같은 테스트와 해당 패키지의 기본 검사를 실행한다. 변경 파일, 테스트 결과, 남은 위험을 기록하면 지도가 실제 작업에 맞았는지 판단할 수 있다.
대형 코드베이스에서 좋은 첫 투입은 많은 파일을 읽은 세션이 아니다. 필요한 경계를 좁히고, 근거 지도를 사람과 확인하고, 승인한 작은 변경으로 그 지도를 검증한 세션이다. 이 기록이 쌓이면 다음 에이전트도 긴 설명 대신 확인된 출발점에서 시작할 수 있다.