Claude Code 스킬로 코드베이스 전체 아키텍처를 인덱싱한 개발자 이야기
프로젝트 규모가 조금만 커져도 AI한테 전체 구조 설명하느라 토큰을 물 쓰듯 날리고, 정작 엉뚱한 레거시 파일을 건드려서 뒷목 잡은 적이 한두 번이 아니다(iOS 앱 짜다 보면 파일 수백 개 넘어가는 건 순식간이다). 그런데 r/ClaudeCode에 읽자마자 감탄이 절로 나오는 글이 올라왔다. u/ZeroTwoMod라는 개발자가 Claude Code의 ‘스킬(Skills)’ 기능 하나로 코드베이스 전체 아키텍처를 완전히 인덱싱해 버린 이야기다.
프론트엔드, 백엔드, iOS, Android, 브라우저 익스텐션까지 엮인 방대한 프로젝트를 ‘점진적 공개(Progressive Disclosure)’ 구조로 정리했더니 개발 속도가 무려 5~10배나 빨라졌단다. 심지어 몇 달 동안 AI가 시스템 간 의존성을 잘못 짚어서 삽질한 적이 단 한 번도 없다고 장담한다.
점진적 공개(Progressive Disclosure)라는 신의 한 수
보통 AI에게 대형 프로젝트를 이해시키려고 할 때 우리는 어떻게 하는가? 무식하게 관련 파일 수십 개를 한 번에 열어주거나, 몇천 줄짜리 아키텍처 문서를 통째로 프롬프트에 쑤셔 넣는다(그리고 토큰 비용 청구서를 보며 눈물을 흘린다).
문제는 비용뿐만이 아니다. 아무리 똑똑한 모델이라도 정보가 쓰나미처럼 쏟아지면 주의력이 분산돼서 정작 지금 당장 고쳐야 할 핵심 로직을 놓치기 일쑤다.
이 개발자의 접근법은 완전히 달랐다. ‘점진적 공개’라는 UI/UX 디자인 개념을 시스템 아키텍처 전달에 그대로 접목했다. 거대한 지도를 한 번에 다 던져주는 게 아니라, 최상위 인덱스부터 시작해 필요한 경로만 계층적으로 타고 들어가게 만든 거다.
최상위 시스템 스킬은 도서관의 색인 카드 역할을 한다. “plugins”, “agent stream”, “skills”, “db”, “service apis” 같은 큼직한 도메인 그룹으로 나뉘어 있고, 각 그룹은 다시 세부 상세 문서 링크로 촘촘하게 연결된다. AI 에이전트는 작업을 시작할 때 전체 코드를 뒤지는 게 아니라, 이 색인 스킬을 먼저 훑고 자기가 건드릴 영역의 상세 문서만 콕 집어서 읽는다.
마치 우리가 터미널에서 ls와 cd를 치며 디렉토리를 찾아 들어가듯 동작하는 셈이다. 불필요한 토큰 낭비를 원천 차단하면서도, 모델이 정확한 컨텍스트 한가운데로 핀포인트 착지할 수 있게 만들었다.
문서가 알아서 최신화된다고?
이 아키텍처의 진짜 백미는 따로 있다. 바로 ‘자동 갱신’ 파이프라인이다. 에이전트가 코드를 수정하고 작업을 끝낼 때마다 아키텍처 문서까지 알아서 업데이트하도록 룰을 짜뒀다.
개발자들의 영원한 거짓말 1위가 “이거 코드 짜고 문서 바로 정리할게요” 아닌가(당연히 아무도 안 한다). 손으로 쓰는 문서는 커밋 몇 번 지나면 금세 현실과 동떨어진 쓰레기 더미가 되기 마련이다. 그런데 이 개발자는 코드 수정의 주체인 AI에게 문서 최신화까지 떠넘겨서 현실 괴리 문제를 완벽하게 해결해 버렸다.
규모가 큰 모놀리스 프로젝트나 멀티 플랫폼 프로젝트를 굴려본 사람이라면 이게 얼마나 거대한 혁신인지 안다. AI가 컨텍스트만 제대로 쥐면 코딩 속도는 빛의 속도지만, 그 컨텍스트를 주입하기 위해 매번 인간이 노가다를 뛰어야 했던 그 병목을 아예 시스템으로 없애버린 거다.
왜 주목해야 할까
정말 무릎을 치게 만드는 점은, 이 모든 걸 Claude Code에 이미 내장된 ‘스킬(Skills)’ 기능만으로 구현했다는 사실이다.
대부분의 사람들은 스킬 기능을 “빌드 명령어 단축키”나 “자주 쓰는 깃 명령어 모음” 정도로 가볍게 쓴다. 그런데 이 개발자는 스킬을 프로젝트 전반의 거대한 ‘지식 관리 시스템(KMS)’으로 승화시켰다. 도구의 숨겨진 잠재력을 극한까지 끌어올린 엔지니어링 센스가 돋보인다.
모델이 똑똑해질수록 컨텍스트 관리는 덜 중요해질까? 천만의 말씀이다. 오히려 모델의 추론 체급이 올라갈수록 정확한 정보를 떠먹여 줬을 때의 폭발력이 커진다. 천재적인 두뇌를 가진 신입 엔지니어에게 엉터리 인수인계 문서를 주면 버그를 양산하지만, 잘 정리된 사내 위키를 쥐여주면 첫날부터 기능을 뽑아내는 것과 똑같다.
한 줄 요약
이 글에서 우리가 훔쳐 와야 할 코딩 인사이트는 명확하다.
- 점진적 공개 구조: 전체 코드를 한 번에 퍼먹이지 말고, 인덱스 → 그룹 문서 → 세부 문서의 계층형 스킬로 쪼개서 먹여라(내 지갑과 토큰을 살리는 길이다).
- 문서 자동 동기화: AI가 코드를 고치면 아키텍처 문서도 스스로 고치게 만들어라.
스킬 기능은 단순한 숏컷이 아니다. 내 프로젝트의 뇌 지도를 그리는 도구다. 거대한 레거시 속에서 AI와 매일 씨름하고 있다면, 당장 내일부터라도 이 점진적 인덱싱 스킬을 구축해 볼 가치가 충분하다.