코딩 에이전트가 추측으로 코드를 부풀리는 것을 막는 행동 지침
AI가 요구하지 않은 기능을 추가하거나, 이해하지 못한 코드를 건드려서 생긴 혼란을 겪어본 적 있나요? 이 저장소는 안드레이 카파시의 관찰을 바탕으로, AI 코딩 도구가 지켜야 할 네 가지 원칙을 담은 단일 파일입니다. 이 파일을 프로젝트에 적용하면 AI가 추측 대신 질문하고, 최소한의 코드만 작성하도록 유도할 수 있습니다.
AI 코딩 도구의 문제점
카파시는 LLM이 사용자의 의도를 잘못 추측하고 확인 없이 진행하는 문제를 지적합니다. 또한 코드를 지나치게 복잡하게 만들거나, 사용하지 않는 추상화를 남용하는 경향이 있다고 말합니다. 심지어 작업과 무관한 주석이나 코드를 임의로 수정하거나 삭제하는 경우도 발생합니다. 이러한 행동은 코드베이스를 혼란스럽게 만들고 유지보수를 어렵게 만듭니다.
네 가지 행동 원칙
이 저장소는 이러한 문제를 해결하기 위해 네 가지 원칙을 제시합니다.
- 코딩 전 사고 가정을 숨기지 않고 명시하며, 모호한 부분이 있으면 추측 대신 질문합니다.
- 단순성 우선 요청한 기능 외의 추가 기능이나 추상화를 배제하고, 시니어 엔지니어가 과도하다고 판단할 수준을 피합니다.
- 정밀한 수정 인근 코드나 주석을 임의로 개선하지 않고, 자신의 변경으로 인해 불필요해진 코드만 정리합니다.
- 목표 기반 실행 명령형 지시 대신 검증 가능한 성공 기준을 설정하고, 테스트를 통과할 때까지 반복합니다.
설치 및 적용 방법
Claude Code 플러그인으로 설치하면 모든 프로젝트에서 이 지침을 적용할 수 있습니다. plugin marketplace add 명령으로 마켓플레이스를 추가한 뒤 plugin install 명령으로 설치합니다. 개별 프로젝트에 적용하려면 CLAUDE.md 파일을 다운로드하거나 기존 파일에 추가하면 됩니다. Cursor를 사용하는 경우에도 해당 규칙 파일을 통해 동일한 지침을 적용할 수 있습니다.
적용 시 고려할 점
이 지침은 신중함을 우선시하므로, 단순한 오타 수정이나 한 줄짜리 변경에는 과도한 절차가 될 수 있습니다. 중요한 작업에서 비용 높은 실수를 줄이는 것이 목적이지, 모든 작업을 느리게 만드는 것이 아닙니다. 프로젝트 특유의 규칙이 있다면 기존 CLAUDE.md에 이 지침을 병합하여 사용해야 합니다. MIT 라이선스로 공개되어 있어 자유롭게 수정하고 사용할 수 있습니다.
