Prefixer: 먼저 범위를 좁히고, 실패 시 확장하며, 변화를 기록하세요
전체 저장소를 검색하는 에이전트는 모든 관련 없는 결과값을 토큰으로 지불합니다. 네임스페이스 맵은 무엇이 어디에 있는지 알려주는 열두 줄 정도의 간단한 목록으로, 첫 호출부터 올바른 영역 안에서 검색할 수 있게 해줍니다. 이 스킬은 그 맵을 만들고, 유지하며, 에이전트가 항상 범위를 먼저 좁혀 검색하도록 강제합니다. 목표는 하나입니다: 더 저렴하고 더 나은 코드베이스 검색.
크기 임계값. 대략 파일이 100개 미만이거나 저장소 구조가 한눈에 명확할 때는 맵 없이 디렉토리 이름으로 검색 범위를 좁히십시오; 그 지점부터는 맵이 효용을 발휘합니다.
<중요> 현재 수행 중인 검색을 조금이라도 범위를 좁힐 수 있다면, 좁히십시오. 범위를 좁히지 않은 검색은 이 스킬이 존재하는 이유인 실패입니다. "단 한 번의 grep일 뿐이야"라는 생각이 토큰을 낭비하게 만듭니다. </중요>
사용 방법
- 한 번만 방향을 잡으세요.
.prefixer/namespaces.md파일이 있는지 확인하십시오. 파일이 없고 작업에 두 번 이상의 검색이 필요할 경우, 작업 중인 세그먼트를 매핑한 후(§1~§3) 그 안에서 검색하십시오. 맵이 이미 존재하면 읽고 범위를 좁혀 시작하십시오. - 범위를 좁혀 검색하고, 실패 시 확장하십시오. 첫 검색은 저장소 루트가 아니라 가장 좁은 범위의 네임스페이스로 보내십시오(§4~§6).
- 기록하십시오. 작업 종료 시
.prefixer/metrics.jsonl에 한 줄을 추가하고, 기준선이 있을 경우 변화량(delta)을 기록하십시오(§7~§8). 필수 출력이며, 선택 사항이 아닙니다.
효용이 높은 상황
- 크거나 익숙하지 않은 저장소에서의 첫 세션. 트리를 스캔하는 대신 맵 열두 줄을 읽으십시오; 첫 검색부터 이미 범위가 좁혀집니다.
- 모노레포. 패키지당 하나의 네임스페이스: 검색 시 형제 패키지의 노이즈가 컨텍스트에 끌려 들어오지 않습니다.
- 다수의 코드베이스. 조직 수준 맵이 코드베이스를 선택하고, 저장소 맵이 그 안의 네임스페이스를 선택합니다. 두 단계, 통합 검색은 절대 하지 않습니다.
- 반복적인 탐색. "X가 어디 있지?", 리팩토링, 익숙하지 않은 기능 영역; 첫 시도 적중률이 맵의 효용을 증명합니다.
- 다시 방문할 저장소. 맵은 세션 간에 유지됩니다; 이후 모든 에이전트가 재스캔 없이 방향을 잡고 시작합니다.
A. 네임스페이스 맵
1. 전체가 아닌 세그먼트를 매핑하세요
규칙: 저장소에 .prefixer/namespaces.md가 없고 작업에 두 번 이상의 검색이 필요할 경우, 이 작업이 다루는 저장소의 일부를 매핑하십시오: 3~5개의 네임스페이스; 전체 트리를 매핑하지 마십시오. 오늘의 검색 범위를 좁혀주는 부분 맵이 한 시간 걸린 완전한 맵보다 낫습니다. 실제 검색이 맵 밖으로 나갈 때만 확장하고, 미리 대비하여 확장하지 마십시오.
bash scripts/init_namespaces.sh(이 스킬의 디렉토리 내)를 실행하여 뼈대를 만든 후, 그 추측을 수정하십시오: 각 네임스페이스가 무엇을 위한 것인지 이름을 붙이십시오.
이유: 채택은 의도적으로 점진적입니다. 맵은 인구 조사가 아닌 작업 파일이며; 검색이 해당 행을 필요로 할 때 그 행이 효용을 냅니다.
초안은 맵이 아닙니다. 접두사나 contains가 여전히 TODO라고 적혀 있는 행은 완료되지 않은 것입니다; 맵에 의존하기 전에 완료하거나 제거하십시오. 뼈대는 남은 초안 행이 몇 개인지 알려줍니다.
기존 문서를 먼저 활용하세요. AGENTS.md, CLAUDE.md, 또는 README가 이미 레이아웃을 설명하고 있다면, 그 내용을 contains에 채우고(뼈대가 이 작업을 합니다) namespaces.md를 검색 범위의 표준으로 취급하십시오; 두 개의 표류하는 목차를 유지하지 마십시오.
세션 시작 시 읽는 것이 기억하는 것보다 낫습니다. 세션당 한 번 맵을 읽는 것이 가장 자주 건너뛰는 단계입니다. 시작 시 파일을 주입할 수 있는 도구를 사용한다면 namespaces.md를 내보내도록 설정하십시오: 그러면 모든 검색이 규율 없이도 자동으로 범위가 좁혀집니다. 제공된 스크립트: scripts/install_hook.sh가 훅을 작성해줍니다(scripts/session_start.sh가 맵과 상태 확인 결과를 내보냄); 수동 스니펫은 integrations/에 있습니다. 레시피와 근거: references/namespaces.md.
2. 작게 유지하고 글로브(glob) 패턴 사용
규칙: 5~12개의 네임스페이스. 각 행은 짧은 접두사, 경로 글로브, 그리고 명확성을 위한 한 줄짜리 목적 설명으로 구성됩니다. 두 행이 동일한 검색에 동일한 빈도로 매칭된다면 병합하십시오. 실제 검색 범위를 좁히는 데 사용되지 않는 행은 제거하십시오.
형식:
# namespaces
repo: acme-payments
| prefix | scope | contains |
|--------|--------------------|-----------------------------|
| api: | src/api/** | REST 핸들러, 라우트 |
| auth: | src/auth/** | 로그인, 세션, 토큰 |
| sso: | src/auth/sso/** | SSO 하위 팀 영역 |
| test: | tests/**, **/*.test.* | 테스트 스위트, 픽스처 |
repo: 헤더는 이 코드베이스의 고유 식별자입니다(git 원격 주소에서 가져옴); 조직이 여러 코드베이스를 운영할 때 모든 접두사를 전역적으로 고유하게 만듭니다: acme-payments:auth:와 checkout-service:auth:는 절대 충돌하지 않습니다.
행은 중첩됩니다: 들여쓰기된 행은 상위 네임스페이스에 속하며, 모듈 내 하위 팀이나 서비스 내 패키지를 나타냅니다. 태그는 auth:sso:와 같이 조합되며, 동일한 이름이라도 상위가 다르면 구별됩니다(orders:checkout: vs payments:checkout:).
이름은 선언하지 않고 유도합니다. 접두사와 contains 텍스트는 코드베이스 자체의 어휘에서 가져옵니다: 디렉토리 이름, 행이 범위로 하는 파일들의 주요 용어를 사용하며, 절대 사용자가 발명한 카테고리를 사용하지 않습니다. 유도된 이름은 저장소의 변화를 따라가지만, 발명된 이름은 표류합니다. 뼈대가 이 작업을 자동으로 수행합니다: 잘못된 부분을 수정하고, 올바른 부분은 유지하십시오.
형식 세부 사항 및 다른 저장소 구조를 위한 맵: references/namespaces.md.
3. 업데이트하고, 절대 재생성하지 마십시오
규칙: 맵이 오래되었을 때는 오래된 행을 편집하십시오. 파일을 다시 작성하지 마십시오. 전체 재생성은 유용하게 쌓인 세부 정보를 잃게 만듭니다. 죽은 행을 제거하고, 누락된 행을 추가하며, 나머지는 바이트 단위로 동일하게 유지하십시오; 다시 작성된 맵은 해당 맵을 로드한 모든 세션의 프롬프트 캐시 접두사를 깨뜨립니다. 정리 후 bash scripts/check_namespaces.sh를 실행하십시오: 글로브가 아무것도 찾지 못하는 행은 맵이 모든 미래 세션에 거짓말을 하고 있는 것입니다. 맵이 낡았다고 느껴지거나 로그가 커졌을 때는 bash scripts/suggest_map.sh를 실행하십시오: metrics.jsonl과 트리를 읽고 실제 검색이 이미 요청한 행을 제안합니다.
다수의 코드베이스: 동일한 방법이 계층적으로 적용됩니다. 조직 수준 맵이 코드베이스를 선택하고(pay: services/payments/**), 저장소 맵이 그 안의 네임스페이스를 선택합니다. 각 맵의 repo: 헤더는 코드베이스 간 접두사를 고유하게 유지합니다; 40개의 서비스가 모두 auth/를 가질 수 있지만, payments:auth:라는 한정된 태그는 정확히 하나를 가리킵니다. 모든 저장소를 하나의 검색으로 통합하지 마십시오; 그것은 조직 규모에서 루트 grep의 실패입니다. references/namespaces.md를 참조하십시오.
B. 검색 범위 지정
4. 가장 좁은 범위부터 먼저
규칙: 모든 검색은 답을 찾을 수 있는 가장 좁은 네임스페이스에서 시작합니다. grep "expire" src/auth/가 grep "expire" .보다 낫습니다. 실패는 한 번의 호출 비용이 들지만, 광범위한 검색은 모든 결과 목록을 토큰으로 소모합니다.
스크립트가 규칙을 수행하게 하십시오: bash scripts/search.sh auth "expire"는 태그를 글로브로 변환하고, 그 안에서 검색하고, 실패 시 한 단계 확장하며, 메트릭 라인을 기록합니다; §4부터 §8까지 자동 실행됩니다. --scope <ns>는 글로브 목록을 출력하고, --paths <ns>는 확인된 파일을, --list는 모든 태그를 출력합니다; 이 맵은 다른 명령이 질의할 수 있는 인덱스 역할을 합니다.
주의: "혹시 몰라" 저장소 루트를 검색하는 행위, **/*와 같은 경로 제약 없는 글로브 패턴, 네임스페이스 글로브로 충분한 상황에서의 find 사용.
5. 실패 시 한 단계 확장
규칙: 네임스페이스 안에서 실패했다면? 한 단계 확장하십시오: 네임스페이스, 그 다음 상위 영역, 그 다음 저장소, 마지막으로 벤더 및 생성된 디렉토리. 실패에서 바로 전체 저장소 검색으로 건너뛰지 말고, 작업 대상이 아니라면 node_modules, vendor, dist, build, 또는 잠금 파일을 검색하지 마십시오.
6. 네임스페이스 태그로 답변
규칙: 결과를 prefix:path:line 형식으로 보고하십시오 (auth:src/auth/session.ts:42). 그러면 다음 검색(여러분의 것이든 미래 세션의 것이든)이 이미 범위가 좁혀진 상태로 시작됩니다. 파일이 모든 네임스페이스를 거부한다면 이는 맵에 공백이 있다는 신호입니다; 태그를 임의로 만들지 말고 이 사실을 언급하십시오.
C. 추적
7. 주장 전에 기준선 확보
규칙: 검색 변경을 권장하기 전에 현재 행동을 측정하십시오: 작업당 검색 수, 작업당 도구 호출 수, 첫 시도 적중률. 기준선이 없으면 변화량(delta)도 없고, 그저 이야기만 있을 뿐입니다. 고정된 프로브를 실행하여 기준선을 기록하십시오: bash scripts/measure_search.sh --baseline orientation -- grep -rn "TODO" . (저장소 루트에서), 또는 맵이 존재하기 전 첫 몇 개 작업을 세어보십시오. 기록할 내용과 점수 산정 방법은 references/metrics.md를 참조하십시오.
8. 모든 작업 로깅
규칙: 각 작업이 끝날 때마다 .prefixer/metrics.jsonl에 한 줄의 JSON을 추가하십시오:
{"ts":"2026-10-26T14:03:11Z","task":"세션-만료-찾기","searches":3,"tool_calls":4,"first_try_hit":true,"est_tokens":1400}
est_tokens은 문자 수/4로 계산된 추정치입니다; 정확히 측정할 수 없어도 이 필드를 유지하십시오. 세션 종료 시 기준선 대비 변화량을 보고하십시오. scripts/measure_search.sh는 검색을 래핑하고 저장소 루트에 검색당 한 줄을 기록합니다(hits, scope; --baseline은 프로브를 표시하고, --hit|--miss는 first_try_hit을 기록합니다). 수동으로 작성된 작업 라인은 tool_calls와 first_try_hit을 추가합니다. 하나의 스키마, 선택적 필드; 목록은 references/metrics.md에 있습니다. scripts/report_metrics.sh는 로그를 다시 읽어 적중률, 범위별 비용, 범위 대비 기준선 변화량을 보여줍니다.
Git 처리. namespaces.md는 커밋하십시오: 이는 모든 미래 세션이 혜택을 받는 공유 접두사입니다. metrics.jsonl은 로컬 텔레메트리이므로 뼈대가 .prefixer/.gitignore를 작성합니다. 팀이 추세 데이터를 원하는 경우에만 커밋하십시오.
위험 신호
다음 생각이 들면 멈추십시오. 여러분은 합리화하고 있는 것입니다.
| 생각 | 현실 |
|---|---|
| "한 번쯤 넓게 grep 해도 괜찮겠지" | 넓은 grep이 이 스킬이 제거하려는 비용입니다. 범위를 좁히십시오. |
| "아마 거기 있을 거야" | 네임스페이스에서 확인하십시오. 잘못된 추측은 범위 검사보다 비용이 더 듭니다. |
| "전체 저장소를 먼저 매핑하자" | 현재 작업 중인 세그먼트를 매핑하십시오. 나머지는 검색이 필요할 때 행을 추가합니다. |
| "이 작업에 맵은 과잉이다" | 부분 맵도 세 번째 검색쯤이면 효용을 냅니다. |
| "기준선 생략하고 바로 적용하자" | 기준선이 없으면 증거도 없습니다. 먼저 측정하십시오. |
| "전체 맵을 재생성하는 게 더 빠르다" | 재생성은 정성껏 쌓은 세부 정보를 버리고 캐시를 깨뜨립니다. 오래된 행을 편집하십시오. |
| "뼈대로 만든 맵도 맵이다" | TODO 행으로 가득 찬 맵은 초안이지 맵이 아닙니다. 완료하거나 제거하십시오. |
| "철저하게 vendor 디렉토리도 검색하자" | 생성된 코드는 토큰이 죽는 곳입니다. 작업 대상일 때만 검색하십시오. |
접두사를 사용하지 말아야 할 때
- 단일 파일 스크립트와 일회용 저장소: 범위를 좁힐 대상이 없습니다.
- 하나의 명확한 파일이 있는 작업: 그 파일을 열기만 하면 되며, 인프라를 구축할 필요가 없습니다.
- 경로가 이미 대상을 명시하는 경우:
src/auth/안에서 검색하는 데auth:같은 꾸밈말이 필요하지 않습니다. - 벤더링되거나 생성된 코드(작업 대상이 아닌 경우).
- 구조가 명확하고 파일이 약 100개 미만인 저장소: 디렉토리 이름으로 범위를 좁히고 맵은 건너뛰십시오.
참고 자료
references/namespaces.md: 맵 형식, 저장소 구조, 다중 저장소 계층화references/metrics.md: 메트릭 정의, JSONL 스키마, 변화량 보고scripts/init_namespaces.sh: 현재 저장소의 네임스페이스 맵 뼈대 생성scripts/check_namespaces.sh: 맵 린트: 죽은 범위, 중복 태그, 초안scripts/search.sh: 범위 검색 명령어: 태그 해석, 검색, 확장, 로깅scripts/suggest_map.sh: 로그 + 트리 읽고 맵 편집 제안scripts/measure_search.sh: 검색 실행과 로깅을 한 번에 수행scripts/report_metrics.sh: 로그 읽기: 적중률, 범위별 비용, 변화량scripts/session_start.sh: 세션 시작 훅을 위한 맵(+상태) 내보내기scripts/install_hook.sh: Devin/Claude를 위한 SessionStart 훅 설정scripts/doctor.sh: 저장소 설정 상태 확인: 맵, 린트, 훅, 설치 기록scripts/eval_scope.sh: 범위 검색과 루트 검색의 토큰 차이 측정scripts/eval_repo.sh: 맵의 모든 네임스페이스 린트 + 평가, 평균 절감율(%)scripts/visualize.py: 파일 트리에 맵을 렌더링하고 측정된 절감액을 HTML 보고서로 표시SPEC.md: namespaces.md 형식 계약, 맵을 읽거나 쓰는 도구용integrations/: 소비자 저장소를 위한 세션 시작 훅 스니펫 + PR 린트 워크플로우
이 스킬의 핵심 작업 외에 파이프라인 및 프롬프트 작성자를 위한 인접 플레이북: references/index-prefixes.md, references/prefix-library.md, references/cache-ordering.md.