대규모 레거시 프로젝트를 맡은 엔지니어는 매일 2시간씩 코드 더미를 뒤집니다. grep으로 문자열을 쫓는 방식은 이제 한계에 다다랐습니다. AI 에이전트를 도입하고 싶어도 워크플로우에 어떻게 녹여야 할지 막막한 게 현실입니다. 이 글은 에이전트를 단순한 채팅 봇이 아니라, 실무 생산성을 높이는 도구로 정착시키는 구체적인 기술 프로시저를 다룹니다.
노이즈부터 걷어내십시오
에이전트에게 전체 코드베이스를 다 던져주면 컨텍스트가 오염됩니다. 불필요한 데이터를 학습하면 엉뚱한 답변을 내놓고 토큰 비용만 낭비합니다. 인덱싱 범위를 좁히는 것만으로도 응답 속도가 체감될 정도로 빨라집니다.
다음 3가지를 즉시 적용하십시오.
- 프로젝트 루트에 .cursorignore 파일을 만드십시오. /dist, /build, /target, node_modules 같이 거대한 빌드 아티팩트는 무조건 제외합니다.
- Protobuf 스텁이나 자동 생성된 *.gen.ts 파일도 제외하십시오. 에이전트가 하위 호환성을 무시한 코드를 생성하는 일을 막을 수 있습니다.
- 머클 트리 기반 동기화 도구를 사용하십시오. 전체 인덱스를 매번 다시 만들지 말고, 수정된 파일의 해시값만 업데이트하여 인덱싱 속도를 3배 이상 높입니다.
구문 트리로 의존성을 추적하십시오
텍스트 기반 검색은 복잡한 상속 관계를 절대 찾아내지 못합니다. ast-grep 같은 도구로 코드의 구문 트리(AST)를 분석해야 합니다. 이를 프롬프트에 녹이면 단순 검색보다 훨씬 정교한 질의가 가능합니다.
- 분석하려는 대상의 구문 패턴을 정의하십시오. 예를 들어 에러 처리가 빠진 비동기 함수 패턴을 ast-grep 문법으로 작성합니다.
- 에이전트에게 @codebase 도구와 이 패턴을 함께 던지십시오. 이때 외부 라이브러리는 무시하고 내부 모듈 간의 상속 관계만 찾도록 범위를 좁히는 지침을 추가합니다.
- 결과를 Mermaid 다이어그램으로 출력하게 만드십시오. 복잡한 호출 흐름을 시각화하면 이슈 해결 시간을 40% 정도 줄일 수 있습니다.
수정안을 테스트로 검증하십시오
AI가 제안한 수정안은 반쯤은 오류입니다. 이를 그대로 머지하면 기술 부채만 쌓입니다. 테스트 영향도 분석(TIA)을 CI 파이프라인에 심어 검증 루프를 자동화하십시오.
- Jest의 --findRelatedTests처럼 변경된 코드와 관련된 테스트만 골라 실행하는 스크립트를 작성합니다.
- 에이전트에게 지침을 내리십시오. 테스트가 실패하면 에러 로그를 분석해서 코드를 스스로 고치도록 루프를 설정합니다.
- CodeQL 같은 도구를 CI 단계에 넣으십시오. 사람이 보기 힘든 보안 취약점까지 자동으로 걸러냅니다.
이 루프를 구축하면 구문 유효성 검사 정확도를 비약적으로 높일 수 있습니다. 기존 툴체인을 다 버릴 필요는 없습니다. ripgrep은 여전히 단순 검색에서 에이전트보다 10배 이상 빠릅니다. 도구의 특성에 맞춰 역할을 분리하는 것이 시니어 엔지니어의 진짜 할 일입니다.
