에이전트-대비 코드베이스: 부정 규칙, 정확한 이름, 디렉터리 README

r/ClaudeAI의 한 개발자가 Claude Code가 새로운 기능을 UserManager 클래스(인증, 세션, 프로필, 분석)에 계속 집어넣은 후 Android 코드베이스를 어떻게 개선했는지 자세히 설명했습니다. 핵심 통찰: 에이전트는 매번 처음부터 시작하며, 건축 결정에 대한 기억이 없는 신입 사원과 같습니다. 해결책은 리포지토리 루트의 CLAUDE.md에 명시적인 규칙을 두는 것이었습니다.

가장 큰 차이를 만든 세 가지 패턴

1. 부정 규칙이 긍정 규칙보다 효과적입니다

개발자는 "좋은 설계를 따르세요" 대신 다음과 같은 지시를 작성합니다:

BaseActivity를 건드리지 마십시오 – 12개의 기능에서 공유되며 조용히 깨집니다.

에이전트는 기본적으로 낙관적이며 가장 쉬운 경로를 선택합니다. 위험한 경로를 명시적으로 차단하면 모호한 지침보다 잘못된 결정을 더 효과적으로 막을 수 있습니다.

2. 이름은 생각보다 중요합니다

UserSessionExpiryHandler라는 클래스는 계약입니다. 단순히 Handler라고 이름을 지으면 잡음이 됩니다. 에이전트는 이름을 강하게 패턴 매칭하므로, 좋은 이름은 파일 읽기 작업량을 줄여줍니다. 개발자는 일반적인 접미사를 피하고 이름에 목적을 명확히 할 것을 권장합니다.

3. 각 디렉토리에 무엇이 속하지 않는지 나열한 README를 둡니다

"이 폴더는 UI용입니다" 대신 README에 이렇게 씁니다:

presentation/에 비즈니스 로직 없음

이 부정적 프레이밍은 에이전트에 "더 강하게 와닿는" 것 같아 긍정 지침보다 잘못된 배치를 더 잘 막습니다.

CLAUDE.md를 위한 실용적인 규칙

• 파일을 작게 유지하십시오. 하나의 클래스, 하나의 역할.
• 기존 파일을 확장하기보다 새 파일을 만드십시오.
• 모놀리스를 만들지 말고, 일찍 관심사를 분리하십시오.

개발자는 이러한 규칙을 적용한 후 에이전트가 한 세션에서 600줄 파일을 세 번 다시 읽는 패턴이 거의 사라졌다고 보고했습니다. 토큰 비용이 크게 줄었을 것으로 추정되지만, 아직 제대로 측정하지는 못했습니다.

대상 독자

AI 코딩 에이전트(Claude Code, Copilot 등)를 사용하며 토큰 낭비를 줄이고 에이전트가 잘못된 아키텍처 결정을 내리는 것을 방지하려는 개발자.