코딩 에이전트는 강한 주관을 가지고 저장소에 들어오지 않습니다. 이미 존재하는 것을 읽고, 로직을 흡수하며, 발견된 형태를 반복합니다. 데이터 액세스 계층이 생 SQL과 중복된 쿼리로 뒤엉켜 있다면, 에이전트는 기꺼이 또 다른 매듭을 추가할 것입니다. 테스트 커버리지가 빈약하다면, 빈약한 테스트를 생성할 것입니다. 이것은 게으름이나 무능함이 아닙니다. 의도한 대로 작동하는 패턴 매칭의 결과입니다.

당신이 구상하는 것과 에이전트가 구축하는 것 사이의 간극을 줄이려면, 더 큰 목소리의 프롬프트나 더 똑똑한 모델에 대한 바람이 아니라 컨텍스트와 제약 조건이 필요합니다. 도구가 작동하는 환경을 엔지니어링함으로써 도구를 정렬할 수 있습니다. 이를 위한 여섯 가지 실질적인 방법을 소개합니다.

모방을 위한 리팩터링

언어 모델은 말로 된 지침을 따르는 것보다 예시로부터 일반화하는 능력이 훨씬 뛰어납니다. 만약 Claude에게 각기 다른 혼란스러운 방식으로 데이터 액세스를 처리하는 다섯 개의 서로 다른 모듈을 가리킨다면, 당신은 모델에게 실제로 어떤 패턴을 원하는지 추측하라고 요구하는 셈입니다. 그 결과는 대개 다섯 가지 패턴이 어설프게 섞인 결과물이 됩니다.

대신, 하나의 깔끔한 참조 모델을 제공하세요. 이상적인 구조를 나타내는 모듈을 하나 선택하세요. 아키텍처가 명확히 드러나도록 불필요한 노이즈를 제거하세요. 새로운 기능을 요청할 때 해당 파일을 직접 참조하세요: "/src/orders/repository.py의 패턴을 따르세요." 잘 구성된 예시 하나는 추상적인 규칙을 나열한 한 단락보다 더 많은 것을 전달합니다. 코드는 해석의 여지를 남기지 않기 때문입니다. 만약 저장소에 깔끔한 예시가 하나도 없다면, 직접 작성하세요. 간결한 참조 구현(reference implementation)은 일회성 투자이지만, 이후의 모든 요청에서 보상을 가져다줍니다. 에이전트는 당신이 가시화한 유일한 청사진인 구조, 에러 처리 스타일, 그리고 관심사 분리(separation of concerns)를 그대로 복제할 것입니다.

먼저 플랜 모드(Plan Mode)를 사용하세요

파일이 생성되거나 수정되기 전에, Claude에게 계획을 제안하라고 요청하세요. 어떤 파일이 변경될지, 어떤 함수가 추가될지, 어떤 의존성이 임포트될지, 그리고 새로운 요소들이 기존 그래프에 어떻게 맞물릴지 구체적으로 작성하게 하세요.

이 단계는 무료로 제공되는 모순 탐지기 역할을 합니다. 만약 팀에서 별도의 오케스트레이션된 작업(orchestrated job)을 통해 마이그레이션을 실행하는데, Claude의 계획이 애플리케이션 배포 파이프라인 내부에 데이터베이스 마이그레이션을 추가하는 것을 제안한다면, 코드 리뷰 단계가 아닌 몇 초 만에 불일치를 잡아낼 수 있습니다. 만약 사용 중단된(deprecated) 유틸리티를 재사용하려 한다면, 기능 구현이 절반쯤 진행되기 전에 방향을 바로잡을 수 있습니다. 계획을 세우는 과정은 모델이 아키텍처에 대해 가지고 있는 가정을 드러내도록 강제합니다. 주니어 개발자의 설계 문서를 검토하듯 계획을 검증하세요. 이는 몇 분의 시간을 소요하지만, 잘못된 코드를 되돌리는 데 드는 한 시간을 정기적으로 아껴줍니다.

초기에 전체 컨텍스트를 제공하세요

대부분의 정렬 실패는 에이전트가 작업을 오해해서가 아니라, 잘못된 제약 조건을 최적화하고 있기 때문에 발생합니다. 해결책이 기술적으로는 완벽하더라도, 당신이 언급하는 것을 잊은 예산, 지연 시간(latency) 요구 사항 또는 컴플라이언스 경계를 위반한다면 사용할 수 없는 결과물이 됩니다.

첫 번째 프롬프트에서 한계치를 명시하세요. 엔드포인트가 99퍼센타일(99th percentile) 기준 200밀리초 이내로 유지되어야 한다면 그렇게 말하세요. HIPAA, GDPR 또는 특정 내부 감사 규정을 따르고 있다면 이를 명시하세요. 인프라 비용에 민감하여 추가적인 관리형 캐시 클러스터(managed cache cluster)를 생성할 수 없다면 비용 상한선을 명확히 하세요. Claude Code는 존재 여부를 모르는 트레이드오프(trade-off)를 협상할 수 없습니다. 이러한 경계 조건을 일찍 주입할수록, 에이전트는 이를 나중에 패치해야 할 사후 고려 사항으로 취급하는 대신 솔루션의 기초 단계부터 반영할 것입니다.

메모리화하기

동일한 수정을 반복하는 것은 시간과 컨텍스트 창(context window)의 낭비입니다. 특정 라이브러리를 피하라거나, 특정 래퍼(wrapper)를 사용하라거나, 명명 규칙(naming convention)을 따르라는 말을 Claude에게 두 번 이상 하고 있다면 멈추세요. 그 수정을 프로젝트 메모리로 전환하세요.

저장소 루트에 CLAUDE.md 파일을 만드세요. 이것은 당신의 '하우스 매뉴얼'입니다. 중요한 규칙들로 채우세요: unittest 대신 pytest 사용하기, 모든 외부 HTTP 호출은 /lib/http에 있는 서킷 브레이커(circuit-breaker)를 거쳐야 함, 레거시 utils.py 파일에서 직접 임포트하지 말 것, 핸들러에 도달하기 전에 항상 스키마 계층(schema layer)으로 입력을 검증할 것 등입니다. Claude Code가 프로젝트를 로드할 때 이 파일을 자동으로 읽습니다. 시간이 지나면서 CLAUDE.md는 매 세션마다 규칙을 다시 입력할 필요 없이 표준을 확장해 주기 때문에 가장 활용도가 높은 자산 중 하나가 됩니다. 한때 일시적인 프롬프트였던 수정 사항들이 코드베이스의 영구적인 구성 요소가 됩니다.

훅(Hooks)으로 규칙 자동화하기

문서는 도움이 되지만, 놓칠 수도 있습니다. 규칙이 정말 중요하다면, 단순한 권고 사항에서 강제 사항으로 전환하십시오. 훅(hooks), pre-commit 체크, CI 게이트 또는 커스텀 검증 스크립트를 사용하여 엄격한 규칙을 어길 수 없도록 만드십시오.

모든 새 모듈에 상응하는 유닛 테스트가 있어야 한다면, 단순히 CLAUDE.md에 언급만 하지 마십시오. /src 내의 파일이 매칭되는 테스트 없이 추가될 경우 빌드를 실패하게 만드는 커버리지 게이트(coverage gate)를 설정하십시오. 보안 정책상 비밀 정보(secrets)를 커밋하는 것이 금지되어 있다면, 푸시를 차단하는 스캐너를 실행하십시오. 팀에서 특정 임포트 순서나 린트(lint) 규칙을 요구한다면, pre-commit 훅으로 수정을 자동화하십시오. 이러한 메커니즘은 여러분의 실수를 잡아내는 것과 동일한 방식으로 Claude의 출력을 잡아냅니다. 이는 인간의 실수나 모델 드리프트(model drift)의 가능성을 제거하고, "기억해 주세요"를 "진행할 수 없습니다"로 대체합니다. 강제되지 않는 규칙은 단순한 제안에 불과합니다.

독립적인 리뷰어 실행

셀프 리뷰는 신뢰하기 어렵습니다. Claude가 자신의 작업물을 검토할 때는, 애초에 자신이 생성한 가정을 스스로 확인하는 경우가 많기 때문입니다. 해결책은 새로운 시각을 도입하는 것입니다. 설령 그 시각이 다른 역할을 부여받은 동일한 모델에서 나온 것이라 할지라도 말입니다.

좁고 명확한 초점을 가진 별도의 리뷰어 에이전트를 구동하십시오. 하나는 보안을 엄격히 감사하도록 요청하십시오: 인젝션 위험, 노출된 내부 엔드포인트, 또는 안전하지 않은 역직렬화(deserialization)가 있습니까? 다른 하나는 테스트 커버리지와 엣지 케이스를 평가하도록 요청하십시오. 세 번째 에이전트는 변경 사항이 CLAUDE.md에 정의된 규칙을 준수하는지 확인할 수 있습니다. 이러한 리뷰어들에게 복잡한 커스텀 모델이 필요한 것은 아닙니다. 단지 원래의 생성 단계로부터 독립적이기만 하면 됩니다. 다른 누군가(또는 무언가)에게 코드를 봐달라고 요청하는 과정에서 발생하는 마찰은, 작성자에게는 당연해 보였던 가정을 잡아냅니다. 추가적인 토큰 비용은 버그가 프로덕션 환경에 도달했을 때 치러야 할 대가에 비하면 무시할 수 있는 수준입니다.

루프(The Loop)

얼라인먼트(Alignment)는 끝나는 프로젝트가 아닙니다. 유지해야 하는 루프입니다. Claude의 출력을 수정할 때마다, 그 수정 사항이 CLAUDE.md의 새로운 항목이 되거나 도구의 새로운 게이트가 될 수 있는지 자문해 보십시오. 같은 수정을 두 번 반복했다면, 시스템의 빈틈을 발견한 것입니다. 그 빈틈을 영구적으로 메우십시오.

몇 주에 걸쳐 이러한 관행은 복리로 쌓입니다. 에이전트는 추측을 멈추고 여러분이 닦아놓은 길을 따르기 시작합니다. 제약 조건이 명확하고, 예시가 깔끔하며, 규칙이 기계적으로 작동하기 때문에 코드베이스는 마치 스스로 코딩하는 것처럼 느껴지기 시작합니다. 여러분의 역할은 수정(correction)에서 큐레이션(curation)으로 전환됩니다.

Source: https://dev.to/az365ai/how-to-align-claude-code-with-your-codebase-6-techniques-2026-3k28

Optional learning community: https://t.me/GyaanSetuAi