AI 코딩 도구는 내 저장소를 어떻게 읽는가

AI 코딩 도구를 비교할 때 대개 모델 이름부터 본다. 그런데 같은 모델을 붙여 놓고도 도구에 따라 결과가 확연히 다르다. 이유는 단순하다.

모델은 자기가 받은 것만 본다. 저장소가 10만 줄이어도 모델에 들어가는 건 그중 아주 일부다. 그 일부를 고르는 일이 도구의 진짜 기능이다.

저장소가 모델에 도착하기까지

과정을 넷으로 나눌 수 있다.

1. 인덱싱

도구는 저장소를 훑어 검색 가능한 형태로 만든다. 흔한 방식은 파일을 의미 단위로 쪼갠 뒤 각 조각을 벡터로 바꿔 저장하는 것이다. 이걸 임베딩이라고 부른다.

여기서 이미 차이가 난다.

• 쪼개는 단위: 함수 단위로 쪼개는지, 고정 길이로 자르는지. 함수 중간에서 잘리면 그 조각은 맥락을 잃는다
• 인덱싱 범위: 어떤 확장자를 포함하는지, 빌드 산출물과 의존성 디렉터리를 빼는지
• 갱신 시점: 파일을 저장할 때마다인지, 주기적인지. 오래된 인덱스는 없어진 코드를 근거로 답하게 만든다

2. 검색

질문이 들어오면 관련 조각을 찾는다. 대체로 두 방식을 섞는다.

좋은 도구는 둘을 함께 쓰고, 찾은 결과를 다시 정렬한다. 이 단계가 부실하면 모델이 아무리 좋아도 엉뚱한 파일을 근거로 답한다.

3. 컨텍스트 조립

찾아낸 조각을 모델에 넣을 순서와 분량으로 정리한다. 컨텍스트 창은 유한하므로 항상 무언가를 버려야 한다.

여기서 자주 벌어지는 일이 있다. 파일 전체를 넣으면 두세 개밖에 못 넣고, 조각만 넣으면 앞뒤 맥락이 잘린다. 도구마다 이 균형을 다르게 잡는다. 열려 있는 파일에 가중치를 주거나, 최근 편집한 파일을 우선하거나, 임포트 관계를 따라가는 식이다.

4. 반복

에이전트형 도구는 한 번에 끝내지 않는다. 답을 만들고, 테스트를 돌리고, 실패하면 다시 검색해서 컨텍스트를 갈아 끼운다. 한 작업에서 이 과정이 여러 번 돈다. 비용이 튀는 이유이자, 어려운 문제를 푸는 이유이기도 하다.

큰 저장소에서 무너지는 지점

규모가 커지면 다음 순서로 문제가 나타난다.

1. 인덱싱 시간과 비용이 늘어난다. 첫 인덱싱에 시간이 걸리고, 자주 바뀌면 계속 다시 만든다
2. 검색 정확도가 떨어진다. 비슷한 이름의 파일이 많아지고, 유틸리티 함수가 어디에나 있다
3. 컨텍스트 경쟁이 심해진다. 관련 있는 파일이 열 개면 다 못 넣는다
4. 오래된 코드가 근거가 된다. 삭제된 함수, 폐기된 모듈이 인덱스에 남아 있으면 그걸 참고해 답한다

결과를 좋게 만드는 실무 조치

도구를 바꾸는 것보다 효과가 큰 것들이다.

1. 인덱싱 제외 목록을 정리한다. 빌드 산출물, 의존성 디렉터리, 대용량 데이터, 자동 생성 코드를 뺀다. 검색 품질이 즉시 올라간다
2. 비밀값을 저장소에서 뺀다. 인덱싱은 읽을 수 있는 것을 읽는다. 제외 설정에 기대는 것보다 애초에 없는 편이 안전하다
3. 폐기 코드를 지운다. 주석 처리한 옛 구현을 남겨두면 근거로 쓰인다. 기록은 버전 관리 시스템이 한다
4. 디렉터리 구조와 명명을 일관되게 한다. 의미 검색은 이름에 크게 의존한다
5. 저장소에 규칙 파일을 둔다. 구조 설명, 컨벤션, 금지 사항을 문서로 두면 도구가 매번 이걸 컨텍스트에 넣는다
6. 질문에 파일 범위를 직접 지정한다. 어느 디렉터리인지 알면 검색 단계를 건너뛰게 만드는 것이 가장 정확하다

6번이 실무에서 가장 즉효다. “이 저장소에서 로그인 처리 고쳐줘” 보다 “auth/session.py의 만료 처리 로직을 고쳐줘” 가 훨씬 안정적으로 동작한다.

도구를 비교할 때 볼 항목

성능 표 대신 이걸 본다.

• 인덱싱 범위와 제외 설정을 어디까지 조절할 수 있는가
• 인덱스가 로컬에 남는가, 외부로 전송되는가
• 검색이 키워드와 의미를 함께 쓰는가
• 어떤 파일을 근거로 답했는지 보여주는가
• 컨텍스트에 무엇이 들어갔는지 확인할 수 있는가

특히 마지막 두 개가 중요하다. 근거를 보여주는 도구는 틀렸을 때 왜 틀렸는지 알 수 있고, 그렇지 않은 도구는 계속 추측하게 만든다.

정리

1. 도구는 저장소 전체가 아니라 고른 일부를 모델에 넣는다. 그 선택이 답을 결정한다
2. 과정은 인덱싱 → 검색 → 컨텍스트 조립 → 반복이며, 각 단계의 설계가 도구별로 다르다
3. 큰 저장소에서는 검색 정확도와 컨텍스트 경쟁에서 먼저 무너진다
4. 제외 목록 정리, 폐기 코드 삭제, 일관된 명명, 규칙 파일이 도구 교체보다 효과가 크다
5. 파일 범위를 직접 지정하는 것이 가장 확실한 개선이다

자주 묻는 질문

인덱스는 어디에 저장되나요?

도구마다 다릅니다. 로컬에만 두는 방식, 벡터를 서버에 보관하는 방식, 원문 일부를 함께 보관하는 방식이 있습니다. 사내 코드를 다룬다면 이 항목을 계약·설정에서 먼저 확인해야 합니다.

컨텍스트 창이 크면 인덱싱이 필요 없지 않나요?

창이 커져도 저장소 전체를 매번 넣는 것은 비용과 속도 면에서 비현실적이고, 관련 없는 내용이 많이 들어가면 오히려 정확도가 떨어집니다. 그래서 큰 창을 쓰더라도 고르는 단계는 계속 필요합니다.

모노레포에서 특히 결과가 나쁜 이유가 있나요?

유사한 이름의 파일과 중복 유틸리티가 많고, 서비스 경계가 디렉터리로만 구분되는 경우가 흔해 검색이 헷갈립니다. 작업 대상 패키지를 명시하거나 도구의 작업 범위를 해당 디렉터리로 한정하면 크게 개선됩니다.

인덱싱을 안 쓰는 도구는 성능이 나쁜가요?

용도가 다릅니다. 열린 파일과 지시문만으로 동작하는 방식은 가볍고 예측 가능해 작은 수정에 적합하고, 인덱싱 기반은 저장소를 넘나드는 작업에 유리합니다. 작업 성격에 따라 고르면 됩니다.