대규모 코드베이스에서 Claude Code가 작동하는 방식 : 모범 사례 및 시작점

“소프트웨어 엔지니어처럼” 코드베이스를 탐색한다는 표현과 결론이 서로 어긋나 보임
자동완성이나 LSP는 항상 쓰고 유용한데, 그것도 일종의 색인 아닌가? Claude가 왜 그런 걸 못 쓰는지도 의문임
소프트웨어 엔지니어는 코드베이스를 기억하기도 하는데, 그건 사실상 RAG에 가깝고, 자동완성되는 CMD+P로 필요한 파일을 찾는 근육 기억도 많음
수천 명의 엔지니어가 동시에 바꾸는 전체 코드베이스에 대해 실시간일 필요는 없고, 그냥 내가 작업 중인 브랜치만 잘 보면 됨
처음부터 파일 시스템을 순회하며 코드베이스를 탐색하는 일은 드물고, 보통 새 코드베이스일 때나 그러는데 그 경우에도 최적의 경험이라고 부르긴 어려움

내가 일하는 방식과 정확히 같음
LSP가 없던 시절부터 큰 코드베이스를 탐색하는 법을 익혔고, 오랫동안 vim을 쓰면서 grep으로 관련 파일을 찾았음
작년에 Claude Code를 처음 써봤을 때 “뭐야, 내가 하려던 그대로 하네”라는 느낌이었음

답은 글의 도입부에 있음
Claude Code는 수백만 줄짜리 모노레포, 수십 년 된 레거시 시스템, 수십 개 저장소에 걸친 분산 아키텍처에서 운영 중이라는 전제임
그래서 어디서나 동작하는 견고한 도구를 쓰는 일반 사례에 최적화되어 있고, 특히 크고 지저분한 코드베이스에서 그렇다는 얘기임
다만 잘 정리된 작은 저장소라면 더 나은 도구를 쓸 수 있고 써야 한다는 지적도 맞음
적어도 Codex는 그런 식으로 동작하고, 예를 들어 grep을 하기 전에 먼저 go doc을 사용함

정말 큰 코드베이스에서는 grep과 find가 시간 초과됨
그 규모에서 일하다 보면 Claude가 검색을 가능하게 하려고 만들어둔 도구를 쓰지 않는다는 걸 금방 알게 됨

짧은 문단 안에 그럴듯한 표현이 많지만, 실제로는 희망 섞인 주장처럼 보임
“소프트웨어 엔지니어처럼”이라는 말은 부분적으로만 맞음
사람도 심볼 검색을 쓰지만, 특정 작업 맥락에서 기억하고 있는 심볼을 검색함
지금 Claude Code가 심볼을 무차별 탐색하는 방식은 엔지니어가 일하는 방식과 다름
오타 하나로 에이전트가 뭔가를 다시 구현해야 한다고 판단할 수 있고, 운 좋게 파일을 읽더라도 쉽게 환각에 빠질 수 있음
큰 코드베이스에서 일하는 방식도 아님
“grep으로 정확히 필요한 것을 찾는다”는 부분이 특히 마음에 걸림
grep을 하려면 무엇을 grep할지 알아야 하고, 결과가 수천 개 나오면 전부 확인해야 함
그런 결과가 나오면 사람은 결과를 무식하게 훑기보다 출력을 좁히는 방법을 생각함
글의 접근은 탄탄한 권장사항이라기보다 현재 방식을 정당화하는 설명에 가까움
“코드베이스 색인이 필요 없다”는 말도 맞긴 하지만, grep-read-grep으로 문맥을 불려가며 결국 언젠가 답을 찾는다는 뜻일 뿐임
“Claude Code 없이도 개발자가 직접 구현할 수 있으니 Claude Code가 필요 없다”는 말과 비슷하게 들림
이 “필요 없다”는 메시지는 결정을 절대명제처럼 커뮤니티에 전달한다는 점에서 잘못됐다고 봄
전반적으로 조직 비용에 대해서는 솔직함
여러 조직에서 “에이전트 매니저”라는, PM과 엔지니어를 섞은 역할이 Claude Code 생태계를 관리하기 위해 생기고 있고, 팀은 3~6개월마다 의미 있는 설정 검토를 해야 한다고 말함
이는 사전 구축된 코드 지능 계층 없이 대규모 Claude Code를 쓰는 현실을 정확히 보여줌
방향은 맞게 잡았지만, 글을 읽고 나면 “문제를 풀지 못했고 여기가 우리의 한계”라는 뒷맛이 남음

코드베이스 일부를 처음부터 탐색하더라도, 절대 변하지 않는 부분도 있는데 매번 탐색하는 건 토큰 낭비가 큼
Claude와 자주 다투는 지점도 탐색을 훨씬 덜 하게 만드는 것임
거의 변하지 않는 것들을 느리고 비싼 방식으로 훑는 것보다 내가 더 잘 알고 더 빠름
그런데 매번 같은 종류의 토끼굴로 들어감

일화로, LLM 온보딩과 오케스트레이션용 프로젝트를 설계하고 있었는데 Claude가 각 파일의 처음 40줄만 읽도록 선택했음
나중에 다른 세션에서 낮은 품질의 원인을 찾던 Claude가 그 결함을 발견하고, 문서 줄과 함수 시그니처의 입력/출력을 입력으로 삼는 AST 분석을 하도록 코드를 바꿈
Claude의 초기 접근은 정말 좋지 않았음
Claude Code가 얼마나 많이 수정·검토되어야 좋아질 수 있는지, 애초에 좋은 코드를 만들 수 있는지 의문이 듦
일반화하면, Claude는 “처음 40줄만 읽기”처럼 국소적이고 식별 가능한 나쁜 결정은 고칠 수 있음
결함이 분리되어 있고 한 코드 조각으로 추적 가능하기 때문임
하지만 실제 소프트웨어 품질 문제는 개별적으로는 합리적인 작은 결정들이 모여 나쁜 결과를 만드는 경우가 많음
그때는 어느 하나가 명백한 “결함”이 아니어서, 낮은 품질의 구성요소를 조각조각 생성하는 도구는 각 조각이 따로 보면 괜찮아 보이기 때문에 좋은 코드로 수렴하지 못할 수 있음

문맥 보존을 위해 소스 코드를 좁은 구멍으로 들여다보도록 학습된 것 같음
이런 경우에는 하위 로직이나 완전한 하위 에이전트가 잘 맞을 수 있음
예를 들어 하위 에이전트에게 “이 파일을 훑고 요약해줘, X와 Y에 관련된 부분을 표시해줘. 그러면 내가 메인 문맥에서 볼게”라고 맡기는 방식임
또 메인 작업 흐름을 주기적으로 관찰하다가, 자신이 생각 중인 파일 안의 무언가가 현재 작업과 관련 있거나 방향을 바꿀 수 있다고 판단하면 끼어들게 할 수도 있음

Claude Code가 큰 코드베이스에서 어떻게 동작하냐고? 간단함
작은 프로젝트에서도 첫 프롬프트에 5시간 사용 한도의 35% 까지 먹고, 5분 안에 빨리 응답하지 않으면 캐시가 날아가서 다음 프롬프트에 또 12~15%를 내게 됨

링크된 글은 이걸 피하는 방법을 설명함
큰 코드베이스에 순진하게 풀어놓으면, 찾는 동안 토큰을 많이 태우는 게 맞음

Claude Code가 코드베이스를 검사해서 효과적인 하니스를 자동 생성해주면 안 되나? CLAUDE.md나 AGENTS.md, skills, 플러그인을 정의해봤지만 다른 사람들이 말하는 만큼의 효과는 못 얻고 있음
예를 들어 LSP 플러그인이 있어도 Claude Code는 LSP의 심볼 이름 변경을 쓰지 않고 파일을 하나씩 느리게 고치거나, 프롬프트에 특정 단서가 들어가면 skill을 호출하라고 명시해도 호출하지 않음
내가 잘못 쓰는 건가? 복사해서 쓸 만한 견고한 하니스 예제가 있는지 궁금함

이건 몇 년째 이어진 고통 지점이고 아직 전혀 해결되지 않았음
“A이면 X를 해라. B, C, D를 해라. A를 해라”라고 해도 그냥 X를 쓰지 않음
“잊어버렸기” 때문임
규칙을 만드는 데 쓴 시간이 실제로 보상받을지 믿을 수 없고, 오히려 언젠가는 실패할 거라고 믿을 수 있음
RAG, 하니스, skills가 전부 이걸 고치겠다고 했지만 현실에서는 고치지 못했음

/init 사용과 코드베이스를 설명하는 CLAUDE.md 또는 AGENTS.md 파일을 두는 걸 그만뒀음
남겨둔 건 코드베이스를 탐색하는 방법과 조사할 때 git log를 쓰라는 내용뿐인데, 이것도 아마 중복일 가능성이 큼
나도 답을 모르겠음
작업 중인 코드베이스는 대략 10만 줄 정도라 큰 편으로 치는지는 모르겠지만, 개인적으로는 일해본 저장소 중 가장 큼

어떤 경우에는 스크립트를 단 hooks가 문맥 창에 정보를 넣어주는 방식이 효과가 있어 보임
문맥을 제한하려고 불필요한 린터 메시지는 일부 제거해야 했음
운영체제 패키지 저장소로 설치하고 스크립트에서 호출할 수 있는 린터나 언어별 검사기도 도움이 됨
모델과 skill 문맥의 조합도 차이를 만들 수 있음
4.6에서 “동작하던” skill이 4.7에서는 잘 안 맞을 수 있는데, 4.7은 더 명시적인 지시가 필요하지만 4.6보다 비교적 안정적임
skill을 업데이트하는 것도 도움이 될 수 있고, 전후로 테스트와 실행을 비교해야 함
Claude Code는 불필요한 도구 호출도 문맥에 넣기 때문에, 예를 들어 beads를 좋아한다면 작업을 억제해야 할 수도 있음

코드베이스 색인에 대한 주장에는 동의하지 않음
PHPStorm이나 다른 JetBrains IDE에서는 색인이 꽤 잘 동작함

PHPStorm 색인은 굉장함
아주 드물게 손상된 적이 있지만 쉽게 고칠 수 있었고, 오래된 결과를 받은 적은 없음
Claude의 검색 도구를 써봤다면 그 팀이 색인에 대해 아무것도 모른다는 데 놀라지 않을 것임
주력 제품이 텍스트 기반 채팅인 회사가 사용자가 그 채팅에서 텍스트 검색을 쉽게 못 하게 하는 건 이해가 안 됨

Claude Code는 JetBrains의 MCP를 써서 그 색인을 사용할 수 있음

이상한 주장임
AI 쓰레기 글인가? GitHub Copilot도 꽤 좋은 로컬 색인을 가지고 있음
코드를 벡터 데이터베이스에 넣는 건 그렇게 어려운 문제가 아님

이 글은 Claude가 쓴 게 분명함 군더더기가 많고 실질적인 내용은 별로 없음

C, C++, C#, Java, PHP처럼 팀들이 AI 코딩 도구와 항상 연결해 생각하지 않는 언어도 포함된다는 표현이 이상함
왜 Claude Code가 그런 언어에서 잘 동작하지 않을 거라고 예상해야 하지? 어떤 언어를 연상해야 하는 건가, Python과 JavaScript인가?

몇 주가 아니라 몇 달 단위로도 판이 바뀌는 업계에서, 명확한 패턴이 드러날 만큼 시간이 충분했고 그 패턴이 큰 코드베이스에서 성공적이었다니 흥미로움 성공 기준이 뭔가? 운영 데이터베이스를 지우지 않았다는 건가, 팀 속도가 올랐다는 건가, 코드베이스 수명이 늘었다는 건가, 운영팀이 더 행복해졌다는 건가?

AI 도구 때문에 운영 데이터베이스가 날아갔다면, 그건 운영 리소스를 삭제할 수 있는 운영 권한을 개발자에게 준 본인과 조직의 실패라고 계속 말하고 싶음
그런 수준의 무제한 접근 권한을 받은 회사에서 일해본 적이 없음

요즘 스트레스는 전부 Claude Code가 지시를 따르지 않는 데서 오고, 코드베이스가 커질수록 더 나빠졌음
오해는 말아야 하는데 Claude는 대단하고 좋아함
하지만 Claude Code만 고용해서 코드베이스를 유지보수하거나 기능을 추가하게 할 수는 전혀 없음
과거 실수에 대한 메모리 항목을 계속 추가하지만, 중요한 지시를 무시하는 문제는 여전히 약 90% 확률로 발생함
피하는 유일한 방법은 모든 작업을 옆에서 지켜보고 결과를 엄청나게 검토하는 것뿐임
Claude Code는 문서화나 큰 코드베이스를 이해하는 데는 훌륭하지만, 전체를 이해해야 하는 변경 작업에는 약함
예를 들어 코드베이스 전반에 여러 엔티티용으로 쓰는 레지스트리 패턴이 약 10개 있는데, “이 하나의 레지스트리 패턴을 사용하라”는 명시 규칙이 있었는데도 Claude Code가 엔티티별로 독립된 레지스트리 4개를 따로 구현했음
이 단순한 작업을 맞추게 하려고 반나절 동안 Claude Code에게 소리치다시피 했고, 결국 스트레스와 시간을 아끼려고 직접 수정했음

각 CLAUDE.md 파일에 정확히 무엇이 들어가야 하는지 구체적인 용어로 설명도 안 해주는데, 그런 파일이 얼마나 중요한 건지 모르겠음