AI 코딩 도구 쓰실 때 토큰 아끼는 법 (코드맵) + 무료 스크립트

Claude Code나 Cursor 같은 걸 실무에 쓰기 시작하면 두 가지에 부딪힙니다.

1. 토큰이 생각보다 빨리 녹는다
2. "완료했습니다"인데 실제로는 안 되어 있다

1번 원인은 단순합니다. 에이전트가 파일이 어디 있는지 몰라서 전수로 뒤집니다.
"결제 재시도 고쳐줘" 한 마디에 파일 40개를 열어보고 2개를 고칩니다.
나머지 38개 값도 청구됩니다. 그리고 다음 요청 때 또 뒤집니다.

해결은 지도를 만들어 저장소에 넣는 겁니다.
경로 / 한 줄 책임 / export / 라우트만 뽑아서 표로 만듭니다.

제 프로젝트 실측입니다.
- Python 백엔드 212파일: 1,260KB → 42KB (97%)
- React 프론트 144파일: 692KB → 20KB (98%)

스크립트 무료 공개했습니다. Python 3.9 외에 설치할 것 없고 네트워크도 안 씁니다.
https://github.com/blue0826/agent-codemap

중요한 건 도구가 아니라 CLAUDE.md에 넣는 두 줄입니다.

- 작업 전 docs/codemap/INDEX.md 를 읽고 타겟 파일만 열어라.
- 코드베이스 전수 읽기 금지.

맵만 만들어두고 이 지시가 없으면 효과가 0입니다.

2번(거짓 완료)은 글이 길어져서 따로 정리했습니다.
핵심만 말하면 "존재 ≠ 배선"입니다. 파일이 있고 테스트가 통과해도
그 코드를 부르는 곳이 없으면 기능은 없는 겁니다.

grep -rn "새로만든함수" --include=*.ts . | grep -v test

정의부 한 줄만 나오면 배선이 안 된 겁니다. 단위 테스트로는 안 잡힙니다.