클로드 코드 대규모 코드베이스 전략: 전역 규칙·훅·스킬·LSP로 만드는 AI 레이어

핵심 메시지

• 모델 성능보다 모델을 둘러싼 '하네스', 즉 코드·테스트에 이어 세 번째 구성 요소가 된 AI 레이어가 대규모 코드베이스 작업의 성패를 가른다.
• 전역 규칙 파일은 짧게 유지하되 하위 디렉터리마다 나눠 두면, 에이전트가 작업 중인 위치에 맞는 규칙만 단계적으로 불러온다.
• 훅을 쓰면 세션이 끝날 때 규칙 문서가 낡지 않았는지 스스로 점검하고 수정안을 제안하는 자기 개선 구조를 만들 수 있다.
• 탐색과 편집을 분리해 탐색은 서브에이전트에게 맡기면, 본 세션의 컨텍스트가 조사 자료로 오염되지 않는다.
• 조직에서는 소수 인원이 먼저 AI 레이어를 표준으로 구축한 뒤 확산해야 각자 제각각인 설정이 난립하지 않는다.

쉽게 이해하기

AI 코딩 도구 사용법을 다루는 콘텐츠는 넘치지만, 정작 수만~수십만 줄 규모의 실제 코드베이스에서 어떻게 쓰느냐를 다루는 자료는 드물다. 영상은 앤트로픽이 공개한 '대규모 코드베이스에서 클로드 코드를 쓰는 법' 문서를 짚으면서, 문서가 높은 수준에서만 설명하고 넘어간 전략들을 데모 저장소에 직접 구현해 보여준다. 출발점은 탐색 방식인데, 별도의 인덱싱이나 의미 검색 없이 엔지니어처럼 grep과 디렉터리 구조로 훑어 나가므로 따로 동기화할 인덱스가 없다. 대신 어디를 봐야 할지 알려주는 초기 맥락이 부실하면 넓은 저장소에서 방향을 잃기 때문에, 전략 대부분이 '앞단의 맥락을 어떻게 큐레이션할 것인가'로 수렴한다.

핵심 개념은 '하네스가 모델만큼 중요하다'는 명제다. 발표자는 이를 'AI 레이어'라 부르며, 기존에 코드와 테스트 두 축으로 이뤄지던 저장소에 추가된 세 번째 구성 요소로 정의한다. 전역 규칙, 훅, 스킬, LSP, MCP 서버, 서브에이전트, 플러그인 등 에이전트에게 맥락과 도구를 주는 모든 장치가 여기에 속한다. 이 가운데 전역 규칙만이 세션 내내 항상 실려 있고, 나머지는 필요할 때만 산발적으로 호출된다는 점이 설계의 출발점이 된다. 규칙 문서를 짧게 유지해야 하는 이유도 여기에 있다.

규칙 문서는 짧고 층층이 두는 편이 낫다. 수천 줄짜리 규칙 파일은 오히려 성능을 해치므로, 저장소가 무엇을 하는지, 기술 스택과 아키텍처 개요, 공통 관례와 함정, 테스트·개발 서버 실행 명령 정도만 남긴다. 대신 하위 디렉터리마다 규칙 파일을 두면 해당 영역의 파일을 만질 때 그 규칙이 자동으로 더해지고, 작업 위치를 알고 있다면 아예 그 하위 디렉터리에서 세션을 시작해 범위를 좁힐 수도 있다. 이때도 상위 디렉터리를 거슬러 올라가며 루트 규칙을 함께 불러오므로 전체 맥락은 유지된다.

훅은 흔히 위험한 작업을 막는 안전장치로 쓰이지만, 영상은 더 값진 용도로 '지속적 개선'을 든다. 세션이 끝날 때 실행되는 훅이 별도 세션을 띄워 방금 바뀐 코드와 현재 규칙을 대조하고, 규칙을 손봐야 할 곳을 마크다운 문서로 제안하는 데모가 나온다. 반대로 세션 시작 훅은 커밋 이력이나 미스테이징 변경 같은 맥락을 자동으로 주입해, 개발자마다 수동 설정을 반복하지 않게 한다.

탐색 역량도 별도로 보강한다. 발표자는 IDE의 정의 이동·참조 찾기 기능을 제공하는 언어 서버를 MCP 서버로 감싸, 문자열이 아니라 심벌 단위로 검색하게 만들었다. 여섯 자릿수 줄 수의 저장소에서는 grep만으로는 느리고 토큰 낭비가 크기 때문이다. 여기에 더해 웹 조사나 코드베이스 정찰처럼 수십만 토큰을 잡아먹을 수 있는 작업은 서브에이전트에게 맡기고 요약만 돌려받아, 실제 편집에 들어갈 때 본 세션의 창이 이미 부풀어 있는 상황을 피한다.

주요 인사이트

• 규칙을 길게 쓸수록 좋아진다는 직관은 틀렸다. 규칙은 '항상 실려 있는' 유일한 요소이므로, 분량을 늘리는 순간 모든 요청의 비용과 잡음이 함께 늘어난다.
• 규칙 파일과 스킬은 기능이 겹쳐 보이지만, 발표자는 규칙은 '지켜야 할 관례', 스킬은 '반복하는 작업 절차'로 구분한다. 어느 쪽이든 핵심은 해당 코드 영역에서만 활성화되도록 범위를 좁히는 것이다.
• 스킬은 이름과 설명만 미리 노출되고 본문은 필요할 때 읽히는 점진적 공개 구조라, 작업 유형이 수십에서 수백 가지로 늘어나는 큰 저장소일수록 효과가 커진다.
• 규칙 문서가 코드 변화를 못 따라가 낡는 것이 큰 저장소의 실질적 위험인데, 이를 사람의 성실함이 아니라 세션 종료 훅이라는 자동 절차로 막는 발상이 눈에 띈다.
• 도입 방식에 대한 조언도 실용적이다. 소수 인원이 조용히 AI 레이어를 만들어 표준을 세운 뒤 확산해야, 첫 사용에서 실망하는 사람과 제각각 진화한 설정이 동시에 줄어든다.

자주 묻는 질문

관련 AI 소식