LLM 코딩 에이전트 행동 지침 (CLAUDE.md 원칙)

한 줄 정의

안드레이 카파시(Andrej Karpathy) 등의 엔지니어링 실무에서 도출된 가이드라인으로, LLM 코딩 에이전트의 속도보다 신중함과 검증 루프에 중점을 두어 과도한 오버엔지니어링과 불필요한 코드 수정을 억제하는 4대 행동 규범 체계이다.

원칙 1: 코딩 전 사고 (Think First): 혼란을 조용히 임의 추정하여 고르지 말고 가정을 명시하며, 여러 해석이나 불확실성이 존재할 때는 즉시 멈추고 질문한다.
원칙 2: 단순함 우선 (Simplicity First / YAGNI): 문제를 해결하는 최단·최소 코드만 작성하며, 200줄의 코드를 50줄로 줄일 수 있다면 재작성한다. 요청받지 않은 기능·추상화·에러 처리를 전면 배제한다.
원칙 3: 외과적 수정 (Surgical Edits): 요청받은 코드만 엄격히 수정하며, 인접 코드의 포맷팅·주석·리팩터링 등 “개선” 시도를 전면 금지하고 변경으로 생성된 고아(Orphan) 코드만 정리한다.
원칙 4: 목표 중심 실행 (Goal-Oriented Execution): “버그 수정”을 “재현 테스트 작성 후 테스트 통과”라는 검증 가능한 목표로 치환하여 에이전트 자율 검증 루프(Self-verification loop)를 돌린다.

LLM이 코딩 작업을 수행할 때 흔히 저지르는 대표적인 실수는 ‘과도한 추측(Over-assumption)’, ‘불필요한 추상화 도입(Over-engineering)’, ‘주변 코드 스타일 훼손(Diff Pollution)’, ‘확인되지 않은 엉성한 완료 선언’이다.

CLAUDE.md 행동 지침의 4대 섹션 상세 규격:

코딩하기 전에 먼저 생각하라:
- 조용히 독단적인 구현 방향을 고르지 말 것.
- 더 단순한 접근이 있다면 반대 의견 제시.
단순함을 우선하라:
- 한 번만 쓰일 코드에 추상화 패턴을 도입하지 말 것.
- 일어날 수 없는 시나리오용 예외 처리를 넣지 말 것.
- 판단 기준: “시니어 엔지니어가 보고 과하게 복잡하다고 할까?”
외과적으로 수정하라:
- 고장 나지 않은 것을 리팩터링하지 말 것.
- 본인 변경 때문에 발생한 고아 import/변수/함수만 치우고, 기존에 떠돌던 죽은 코드는 건드리지 말 것.
- 판단 기준: 변경된 모든 줄은 사용자의 요청과 1:1로 직접 연결되어야 함.
목표 중심으로 실행하라:
- 작업을 검증 가능한 목표와 확인 방법으로 세분화:
```
1. [단계] -> 검증: [확인 방법]
2. [단계] -> 검증: [확인 방법]
```

버그 수정 작업의 목표 전환: 단순 “에러 해결” 요청을 받아 코드를 무작정 고치는 대신, “1. 버그 재현 테스트 작성 -> 2. 테스트 실패 확인 -> 3. 최소 코드 수정 -> 4. 테스트 통과”라는 자율 루프로 실행.
200줄 -> 50줄 단순화: 헬퍼 클래스와 인터페이스를 장황하게 생성하려 할 때, 단일 함수 50줄 구조로 압축하여 과도한 추상화 방지.

신속한 구현 vs 외과적 수정/검증: 본 지침은 즉각적인 스피드보다 코드베이스의 무결성과 신중함에 무게를 둔다. 사소한 1줄 핫픽스 작업 시에는 상황에 맞게 융통성을 발휘할 수 있다.