Claude Code를 이용해 문서를 검색했을 때, 파일이 실제로 존재함에도 불구하고 검색에서 누락되는 경우가 있었습니다. 그 원인 중 하나는 동일한 대상이 가타카나와 영문 등 여러 표기로 작성되어 있었기 때문입니다.
이에 저는 검색 시 사용할 표기 조합을 AGENTS.md에 정리하여, Claude Code와 Codex가 참조할 수 있도록 했습니다. 이는 검색 재실행의 번거로움을 줄이기 위한 작은 개선점입니다.
이 글에서 언급된 회사명, 서비스명, 문서는 설명을 위한 가상의 것입니다. 아래 건수 역시 샘플을 사용한 결과이며 실제 업무 데이터는 아닙니다.
- ripgrep User Guide
- Codex: Custom instructions with AGENTS.md
- Claude Code: How Claude remembers your project
제 개인 리포지토리에는 조사 내용이나 작업 기록을 Markdown으로 남기고 있습니다. 문서가 늘어날수록, 무엇을 어떤 파일에 작성했는지 이름만으로는 기억하기 어렵습니다. 그래서 AI에게 “이 서비스에 대해 작성한 문서를 찾아줘”라고 요청할 때가 있습니다.
그런데 같은 내용이라도 문서마다 “미나토”, “Minato”, “MINATO”와 같이 다르게 적혀 있다면, 하나의 표기만으로 검색했을 경우 결과에서 누락이 발생합니다. 실제로 표기의 차이로 인해 참조하는 곳을 찾지 못하거나, 존재하지 않는 경로가 남아 있는 경우가 있었습니다.
rg (ripgrep)를 사용할 수 있는 환경에서 다음 가상 데이터를 만듭니다. 기존 파일을 덮어쓰지 않도록 빈 작업 디렉터리에서 실행해 주세요.
mkdir -p search-demo
printf '%s\n' '미나토의 설계 메모' > search-demo/01.md
printf '%s\n' 'Minato의 운영 메모' > search-demo/02.md
...
가타카나 이름으로 검색하면, 영문으로 작성된 파일은 찾아지지 않습니다.
rg -l '미나토' search-demo
# search-demo/01.md
-l 옵션은 일치하는 줄이 아닌 파일명을 표시하는 옵션입니다. 영문을 대소문자를 구분하지 않고 검색하면, 이번에는 가타카나가 남게 됩니다.
rg -il 'minato' search-demo
# search-demo/02.md
# search-demo/03.md
-i가 처리하는 것은 대소문자 차이입니다. 가타카나 이름과 영문 이름이 같은 대상인지는 알 수 없습니다. 표시 순서는 환경에 따라 달라질 수 있습니다.
정규 표현식의 |를 사용하면, 여러 표기 중 어느 하나와 일치하는 파일을 찾을 수 있습니다.
rg -il 'ミナト|minato' search-demo
# search-demo/01.md
# search-demo/02.md
...
이 샘플에서는, 가타카나만으로는 1건, 영문만으로는 2건, 둘 다 포함하면 3건입니다. AI에게 검색을 맡길 때도 이 패턴을 알고 있다면 같은 방법으로 찾을 수 있습니다.
다만, 표기 대응 관계를 매번 요청문에 적는 것은 번거롭습니다. 이름만으로 다른 표기를 추측할 수 없는 서비스도 있습니다.
그래서 프로젝트의 AGENTS.md에 검색어와 사용하고 싶은 패턴을 정리했습니다. 다음은 가상의 예시입니다.
## 문서 검색의 표기 변화
본문을 검색할 때는 대상의 표기를 모아서 검색합니다.
아래는 `rg -i`에 전달하는 정규 표현식의 예시.
...
+는 정규 표현식의 특수 문자입니다. 반각의 +를 문자로 그대로 검색하기 위해 라고 씁니다. 전각의 ＋는 다른 문자이므로, 필요한 경우 별도로 나열합니다.
Codex는 프로젝트의 AGENTS.md를 지시 파일로 사용할 수 있습니다. Claude Code에서도 같은 내용을 사용하려면, 프로젝트의 CLAUDE.md에 다음과 같이 작성하여 불러올 수 있습니다.
기존의 CLAUDE.md가 있는 경우 덮어쓰지 않고 필요한 행을 추가합니다. 각 도구의 지시 파일 탐색 범위나 읽는 방법은 실제 실행 위치/설정에 따라 공식 문서를 확인해 주세요.
처음부터 관련성이 있을 법한 이름을 모두 나열할 필요는 없습니다. 저는 “찾는 경우가 많고, 실제로 여러 표기가 사용되는 것”부터 시작했습니다.
예를 들어, 가상의 “미나토”가 별명으로 “みなとノート”라고 불리는 경우, 추측하여 minato
단순히 붙이는 것만으로는 별명으로 쓰인 문서를 찾을 수 없습니다. 먼저 알려진 자료나 디렉터리 이름에서 실제 표기를 가져와, 그 관계를 사람이 확인해야 합니다. 검색 누락에気づいたときに사전을 수정하면, 다음에 같은 이름을 찾을 때부터 사용할 수 있습니다.
대소문자 차이는 명령어 쪽에 -i를 붙이거나, minato를 한 번만 적어주면 됩니다. 반면에 카타카나, 읽는 법이 다른 별명, 반각/전각 기호는 별도의 문자열로 간주합니다. 사전에는 '어떤 검색 옵션으로 사용할 패턴인지'도 함께 적어두면 나중에 다시 볼 때 헷갈리지 않습니다.
사전에 있는 또 다른 예시로 정규 표현식(regex)의 +를 확인해 보겠습니다. 이 역시 가상의 이름입니다.
printf '%s\n' 'note+ 의 설정' > search-demo/04.md
printf '%s\n' 'note＋ 의 조작' > search-demo/05.md
printf '%s\n' 'noteee 의 설명' > search-demo/06.md
다음 note+는 'e가 1회 이상 연속되는' 정규 표현식이므로, note+라는 문자열만 지정했다고 해도 noteee에도 일치합니다.
rg -n 'note+' search-demo
# 04.md, 05.md, 06.md의 행이 일치함
+ 자체까지 이름의 일부로 검색하려면, 반각과 전각을 각각 지정합니다.
rg -n 'note\+|note＋' search-demo
# 04.md와 05.md의 행이 일치함
정규 표현식을 사용하지 않고 단순히 하나의 문자열만 찾으면 rg -F 'note+' search-demo로도 괜찮습니다. -F는 패턴을 고정된 문자열(fixed string)로 취급합니다. 다만, |로 여러 패턴을 연결한 것도 그대로 문자열로 취급되므로, 사전에 있는 정규 표현식과 조합할 때는 사용 구분이 필요합니다.
검색 패턴을 넓히면 원하는 결과뿐만 아니라 다른 단어도 걸릴 수 있습니다. 예를 들어 minato는 minatoya라는 별명에도 부분 일치합니다. 검색 결과는 후보일 뿐이며, '사전에 적은 이름이므로 모두 같은 대상'이라고 할 수는 없습니다.
결과를 목록으로 확인하고 싶을 때는 -l을 빼고 일치한 행을 표시합니다.
rg -in '미나토|minato' search-demo
-n은 행 번호를 표시합니다. 문맥을 좀 더 보고 싶다면 -C 2를 추가하면, 일치한 행의 앞뒤 2행도 표시할 수 있습니다. 헷갈리는 이름이 실제로 나왔다면, 주변 문자까지 포함하는 패턴으로 하거나 대상에 맞춰 조정해야 합니다. 짧은 이름에 경계 조건을 기계적으로 붙이면, 오히려 본래 표기를 놓칠 수도 있으므로, 알려진 정답 문서를 사용해서 테스트합니다.
사전을 배치한 후 AI에게 요청할 때는, 최종 답변뿐만 아니라 검색 과정도 확인할 수 있도록 합니다. 다음은 가상의 요청 예시입니다.
미나토와 관련된 문서를 찾아주세요.
AGENTS.md의 표기 변화 사전을 확인하고, 카타카나와 영문 두 가지를 모두 대상으로 해주세요.
사용된 검색 패턴과 발견한 파일 경로를 보여주세요.
'찾은 문서를 요약해 줘'라고 요청하기 전에 경로를 먼저 받으면, 읽어줬으면 했던 파일이 후보에 들어갔는지 확인할 수 있습니다. 검색 대상이 방대한 경우라면, 우선 대상 디렉터리를 지정하고, 부족하면 범위를 넓힙니다.
다만, AI가 출력한 검색어가 실제 실행 결과와 항상 동일시될 수는 없습니다. 작업 기록을 확인할 수 있는 환경이라면, 실행된 명령어도 확인합니다. 직접 rg를 재실행하여 알려진 파일이 결과에 들어가는지 확인하면, 사전 자체의 문제인지 AI 사용법의 문제인지를 구분할 수 있습니다.
사전을 배치했다면, 먼저 패턴 자체가 목적 문서들을 찾아내는지, 또는 직접 rg를 실행해서 확인합니다. 그 후에 AI에게도 '해당하는 문서를 찾고, 사용한 검색어와 발견된 경로를 보여줘'라고 요청하여 기대했던 패턴이 사용되었는지 확인합니다.
지시 파일에 적는 것만으로 매번 반드시 같은 명령어가 선택될 것이라는 보장은 없습니다. 검색 대상의 위치, 무시 설정(ignore setting), 숨김 파일 등에 따라서도 결과는 달라집니다. ripgrep은 보통 .gitignore로 제외된 파일이나 숨김 파일 등은 자동 검색에서 제외합니다. 찾지 못한다면, 표기뿐만 아니라 검색 범위도 확인해야 합니다.
하나의 이름이 하나의 표기로 통일되어 있다면 문제가 없었겠지만, 오래 사용하는 리포지토리에서는 그렇게 할 수 없습니다.
자주 찾는 이름만으로도, 실제로 사용되는 표기를 검색 패턴으로 만들어 지시 파일에 넣습니다. 대규모 검색 기반 시설을 만들지 않아도, 우선 이것만으로 검색 누락(search omission)을 발견하기 쉬워졌습니다.
