본문으로 건너뛰기
시골프로그래머의 블로그
블로그 메뉴

AI 에이전트가 부르기 좋게 만든 파일 내용 검색기 — qfind

Rust로 만든 콘솔 파일 내용 검색기입니다. 기본은 입력한 문자열 그대로 찾고, 결과를 NDJSON으로 내보내며, 결과 개수·출력 크기·시간 상한과 분명한 종료 코드를 둬 AI 에이전트가 호출하기 좋습니다.

풀빛컴퓨팅3분 읽기#오픈소스#Rust#CLI#AI 에이전트

AI 에이전트가 코드를 고치기 전에 가장 많이 하는 일 중 하나가 파일 내용 검색입니다. 사람이 쓰던 검색 도구를 그대로 쓰면 몇 가지가 걸립니다. 검색어의 .이나 (가 정규식으로 해석되고, 결과가 수천 줄 쏟아져 대화 창을 채우고, 검색이 끝까지 됐는지 중간에 끊겼는지 출력만 보고는 알기 어렵습니다.

qfind는 이런 점을 고려해 만든 콘솔 검색기입니다. 기본은 입력한 문자열 그대로 찾고, 결과를 한 줄에 JSON 하나씩(NDJSON) 내보내며, 결과 수와 출력 크기에 상한을 둘 수 있습니다.

무엇을 하나

find, findstr, rg를 안에서 부르지 않는 독립 실행 파일입니다. 파일 탐색에는 ignore 라이브러리, 문자열 검색에는 memchr::memmem, 정규식에는 Rust regex를 씁니다. 여러 파일을 병렬로 검색합니다.

자주 쓰는 옵션은 이렇습니다.

옵션 하는 일
-r 정규식으로 검색 (기본은 문자열 그대로)
-i 대소문자 구분 없이
-e 검색어 여러 개를 OR로
-w / -x 단어 전체 / 줄 전체 일치
-C, -A, -B 앞뒤 문맥 줄
-g 파일 종류 제한·제외 (glob)
-l / -c / -q 파일 경로만 / 파일별 일치 줄 수 / 존재 여부만
--files 내용은 읽지 않고 검색 대상 경로만 나열
--json NDJSON 출력
--sort path 경로 순으로 검색해 결과를 매번 같게

기본 검색 범위에서는 .gitignore, .ignore, .qfindignore 규칙을 따르고, 숨김 파일과 .git, node_modules, target, dist, build 같은 폴더를 뺍니다. --no-ignore나 --all로 풀 수 있습니다.

써 보기

Rust 1.88 이상이 필요합니다.

cargo build --release --locked
.\target\release\qfind.exe --help
.\target\release\qfind.exe '검색할 문자열' .
# a.b는 정규식이 아닌 문자열 그대로 검색
qfind 'a.b' .

# 정규식은 명시적으로 활성화
qfind -r 'fn\s+\w+' src

# 파일 종류 제한 및 제외
qfind -g '*.rs' -g '!generated/**' 'TODO' .

AI 에이전트에서 부를 때

에이전트에서는 이렇게 부릅니다. 결과 수, 출력 바이트, 시간, 파일 크기, 줄 길이에 모두 상한을 걸었습니다.

qfind --json -C 2 --max-results 100 --max-output-bytes 65536 --timeout-ms 5000 --max-file-bytes 16777216 --max-line-buffer-bytes 1048576 '검색할 문자열' 'E:\works\projects\example'
{"type":"match","path":"src/main.rs","line":12,"column":5,"text":"    // TODO: implement"}
{"type":"summary","schema_version":1,"records_emitted":1,"matched":true,"scan_complete":true,"stop_reason":"completed","error_count":0}

JSON 모드는 결과가 없거나 오류가 나도 마지막에 summary를 하나 출력합니다. 여기의 scan_complete와 stop_reason으로 검색이 끝까지 됐는지, 어떤 상한에 걸려 멈췄는지 알 수 있습니다.

stop_reason 뜻
completed 요청한 검색을 끝냄(일치가 없는 경우 포함)
result_limit 결과 개수 상한에서 멈춤
output_limit 출력 바이트 상한에서 멈춤
time_limit 시간 상한에서 멈춤
resource_limit 파일·줄 크기 상한 때문에 일부를 건너뜀
error 인수, 검색어, glob, 읽기, 탐색 오류

종료 코드는 0(일치 있음), 1(일치 없음), 2(오류 또는 상한 때문에 불완전한 검색) 세 가지입니다. 오류는 stderr에 code와 stage가 들어간 JSON으로 나가므로, 메시지 문장을 파싱하지 않고 분기할 수 있습니다. 한 줄이 아주 긴 파일은 --max-line-bytes(기본 4096) 기준으로 일치 위치 주변만 잘라 보여 줍니다.

알아 둘 점

  • UTF-8 파일을 찾습니다. UTF-16이나 CP949 파일은 자동으로 변환하지 않습니다.
  • 정규식은 줄 단위로 적용합니다. 여러 줄에 걸친 검색은 안 됩니다.
  • 파일 단위로 병렬 처리하므로 큰 파일 하나만 검색할 때는 여러 코어로 나누지 않습니다.
  • 성능은 디스크, 파일 구성, 검색어, 백신, 출력량에 따라 달라지며 rg보다 항상 빠르지는 않습니다. 측정 스크립트는 scripts/benchmark.py, 측정 조건과 결과는 BENCHMARK.md에 정리해 두었습니다.
  • 라이선스는 MIT입니다.

옵션 전체와 JSON 필드 설명은 GitHub 저장소 README에 정리해 두었습니다.

함께 읽으면 좋은 글