클로드 코드 검색 도구 — 운영체제마다 다른 구성·정반대 무시 규칙

「파일을 찾는 도구를 막아 뒀는데 왜 검색이 되지」 같은 의문을 만난 적 있으신가요. 혹은 같은 폴더인데 이름으로 찾을 땐 나오고 내용으로 찾을 땐 안 나오는 경우요.

둘 다 원인이 분명합니다. 검색 도구는 운영체제마다 다르게 구성되고, 이름으로 찾는 쪽과 내용으로 찾는 쪽은 무시 규칙이 정반대입니다. 알고 나면 권한 설계도 함께 바뀝니다.

📌 30초 요약

• 맥·리눅스에서는 검색이 셸 명령으로 돕니다. 권한도 그 이름으로 잡힙니다.
• 되돌리려면 시작할 때 주는 플래그여야 합니다. 설정 파일로는 안 됩니다.
• 이름 찾기는 무시 목록을 안 지키고 내용 찾기는 지킵니다.
• 권한 확인창이 떠도 그 경로가 있다는 뜻이 아닙니다.

1. 운영체제마다 다른 구성

클로드가 코드를 뒤질 때 쓰는 길은 두 갈래입니다. 이름으로 파일을 찾는 도구와 내용에서 글자를 찾는 도구죠. 그런데 이 둘이 모든 환경에서 기본으로 켜져 있는 게 아닙니다.

환경	검색이 어떻게 도나
윈도우	이름 찾기 도구가 기본으로 들어 있음
맥·리눅스·리눅스 계층	두 도구가 빠지고 셸 명령으로 검색
셸이 빠진 세션	두 도구가 되살아남 · 거부 규칙이나 제한 모드로 셸이 없을 때

둘째 줄이 이 글의 핵심입니다. 맥과 리눅스 쪽에서는 클로드가 셸의 찾기 명령과 검색 명령을 쓰는 방식으로 일합니다. 정확히 말하면 그 자리에서 도는 것은 더 빠른 내장 구현이지만, 겉으로 드러나는 이름은 셸 명령 그대로고요. 그래서 내 훅과 권한 규칙에는 「셸 호출」로 잡힙니다.

여기서 권한 설계가 어긋나기 쉽습니다. 검색 도구 이름을 적어 막아 뒀다고 안심했는데 그 환경에서는 애초에 그 이름으로 안 돌기 때문입니다. 반대로 셸을 통째로 막으면 검색까지 같이 막히고요. 규칙이 예상과 다르게 걸리는 자리들은 권한 거부 규칙 글에 따로 모아 뒀습니다.

2. 되돌리는 세 가지 경우

맥·리눅스에서도 두 도구를 되살릴 수 있습니다. 첫째는 세션을 시작할 때 도구 이름을 플래그로 대는 것입니다. 쓰는 플래그에 따라 결과가 조금 다른데, 목록을 정하는 쪽은 적은 것만 주고 허용을 정하는 쪽은 둘 중 하나만 대도 둘 다 돌아옵니다.

여기에 놓치기 쉬운 단서가 붙습니다. 같은 허용이라도 설정 파일에 적어 둔 허용 규칙으로는 이 효과가 없습니다. 시작할 때 넘기는 플래그여야 합니다. 설정 파일에 적어 두고 「왜 안 돌아오지」 하는 상황이 여기서 나옵니다.

둘째는 셸이 세션에서 빠지는 경우입니다. 거부 규칙으로 막았거나, 금지 목록에 넣었거나, 제한 모드로 띄웠을 때죠. 검색할 다른 길이 없으니 두 도구가 자동으로 돌아옵니다. 셋째는 보조 에이전트가 자기 도구 목록에 이름을 넣고 셸을 빼는 경우입니다. 그 에이전트에만 적용되고, 그 에이전트를 본 세션으로 띄우면 세션 전체에 적용됩니다.

3. 무시 규칙이 정반대

⚠️ 이름으로 찾으면 나오고 내용으로 찾으면 안 나옵니다

두 도구의 기본값이 반대입니다. 이름으로 찾는 쪽은 무시 목록을 안 지킵니다. 버전 관리에서 빼 둔 파일도 결과에 그대로 섞여 나옵니다. 반면 내용으로 찾는 쪽은 무시 목록을 지켜서 그런 파일을 건너뜁니다.

그래서 빌드 산출물이나 의존성 폴더가 이름 검색 결과에만 잔뜩 끼어드는 일이 생깁니다. 맞추고 싶다면 이름 찾기도 무시 목록을 지키게 하는 환경 변수를 띄우기 전에 켜 두세요. 반대로 무시된 파일 안을 꼭 봐야 한다면 경로를 직접 찍어 주는 방법이 있습니다.

이름 찾기 쪽에는 결과 상한도 있습니다. 수정 시각이 최근인 순으로 정렬해 100개까지만 돌려주고, 상한에 닿으면 잘렸다는 표시를 함께 줍니다. 클로드가 그걸 보고 무늬를 좁혀 다시 찾도록 만드는 장치죠. 결과가 이상하게 적다면 상한에 걸린 건 아닌지 의심해 볼 만합니다.

내용 찾기 쪽은 문법이 흔히 쓰는 그것과 다릅니다. 유닉스 계열의 오래된 문법이 아니라 더 현대적인 도구의 정규식 문법을 씁니다. 그래서 중괄호 같은 특수문자가 든 글자를 찾으려면 앞에 표시를 붙여 줘야 합니다. 참고로 옛 판에서는 거부된 입력을 「파일 없음」으로 보고해서, 실제로는 그 글자가 있는데도 없다고 나오는 일이 있었습니다. 코드 탐색 방식 자체의 차이는 더 똑똑한 코드 분석 글에서 다뤘습니다.

4. 권한이 존재 확인보다 먼저

두 도구가 공유하는 미묘한 성질이 하나 있습니다. 검색 요청이 들어오면 그 경로가 실제로 있는지 확인하기 전에 권한부터 판단합니다. 작업 폴더 밖의 경로라면 그것이 없는 경로여도 읽기 권한 검사를 그대로 돌리고요.

돌아오는 결과	담기는 것
파일 경로만 (기본)	맞은 파일들의 경로 · 줄 내용은 없음
내용	맞은 줄과 파일명·줄 번호
개수	파일별 개수와 전체 합계 · 목록이 잘려도 합계는 전부를 셈

권한 이야기로 돌아오면, 이 순서 때문에 알아 둘 결론이 하나 나옵니다 — 어떤 경로에 대해 권한 확인창이 떴다고 해서 그 경로가 실제로 있다는 뜻은 아닙니다. 확인창의 유무로 파일 존재를 추측하면 틀립니다. 사소해 보이지만 민감한 경로를 다룰 때는 짚어 둘 만한 성질입니다.

표의 셋째 줄에도 옛 판과의 차이가 있습니다. 합계는 목록이 잘려도 전체를 셉니다만, 예전에는 나열된 것만 더해서 실제보다 적게 나왔습니다. 검색 결과 수를 근거로 판단하는 일이 잦다면 판 번호를 확인해 두세요. 셸 명령이 도는 규칙은 직전 글에 정리해 뒀고, 도입 순서는 AI 도입 한 바퀴에서 잡아 보세요.

자주 묻는 질문 (FAQ)

Q. 검색 도구를 막으면 검색이 안 되나요?

환경에 따라 다릅니다. 맥·리눅스에서는 애초에 그 이름으로 안 돌기 때문에 그 이름을 막아도 검색은 계속됩니다. 셸 명령으로 도니까요. 반대로 셸을 막으면 검색 도구가 되살아나 그쪽으로 돕니다. 즉 어느 한쪽만 막아서는 검색을 못 막습니다. 정말 막아야 한다면 두 갈래를 다 고려한 규칙이 필요합니다.

Q. 빌드 산출물이 검색에 자꾸 끼어듭니다

이름으로 찾는 쪽이 무시 목록을 안 지키기 때문입니다. 의존성 폴더나 빌드 결과물이 그대로 잡히죠. 환경 변수 하나로 무시 목록을 지키게 만들 수 있는데, 반드시 띄우기 전에 설정해야 합니다. 내용으로 찾는 쪽은 처음부터 지키므로 따로 손댈 게 없고요.

Q. 분명히 있는 글자인데 못 찾는다고 나옵니다

두 가지를 확인해 보세요. 첫째는 특수문자 이스케이프입니다. 중괄호나 괄호가 든 글자는 그대로 넘기면 정규식으로 해석됩니다. 둘째는 무시 목록이고요. 내용 찾기는 무시된 파일을 건너뛰니 그 안에 있으면 안 나옵니다. 참고로 옛 판에서는 문법 오류를 「파일 없음」으로 잘못 보고하는 문제가 있었으니 판 번호도 함께 보세요.

Q. 보조 에이전트마다 다르게 줄 수 있나요?

됩니다. 에이전트 정의에 쓸 도구 목록을 적으면 그 에이전트만 그 구성으로 돕니다. 검색 도구를 넣고 셸을 빼면 그 에이전트에서만 두 도구가 살아납니다. 다만 주의할 점이 있는데, 보조 에이전트가 쓸 수 있는 도구에는 정해진 범위가 있어서 그 밖의 이름을 적어도 주어지지 않습니다. 목록의 모든 항목이 실패하면 아예 오류가 나고요.

정리하면

• 맥·리눅스에서는 검색이 셸 이름으로 잡힙니다.
• 도구를 되살리려면 시작 플래그여야 합니다.
• 이름 찾기와 내용 찾기는 무시 규칙이 반대입니다.
• 확인창이 떴다고 그 경로가 있는 건 아닙니다.

※ 공개된 도구 참조 문서를 읽고 정리했습니다. 도구·플래그·환경 변수 이름은 우리말로 풀어 적었고, 환경별 구성을 직접 비교해 보지는 않았습니다.

※ 기본 구성과 결과 상한은 열람 시점 기준이며 판올림에 따라 달라질 수 있습니다. 옛 판과의 차이는 문서에 번호로 적혀 있으나 본문에서는 「옛 판」으로 뭉쳤으니, 해당 여부는 지금 쓰는 판 번호와 원문을 대조해 확인하세요.