에이전트 코딩 4원칙
한 줄 정의
에이전트 코딩 4원칙은 LLM이 코딩할 때 흔한 실패를 줄이기 위해 생각, 단순성, 변경 범위, 검증 목표를 먼저 고정하는 행동 지침이다.
핵심 요지
- 첫 원칙은 “구현 전에 가정과 불확실성을 드러내라”는 것이다. 에이전트가 조용히 추정하며 전진하는 습관을 막는다.
- 둘째 원칙은 최소한의 코드만 쓰는 것이다. 추측성 추상화, 요청받지 않은 유연성, 과잉 에러 처리를 억제한다.
- 셋째 원칙은 변경 범위를 외과적으로 제한하는 것이다. 사용자가 요청하지 않은 리팩터링과 주변 정리를 금지한다.
- 넷째 원칙은 작업을 검증 가능한 목표로 바꾸는 것이다. “되게 만들기”보다 테스트와 확인 루프를 완료 조건으로 둔다.
상세
이 지침은 거대한 프레임워크가 아니라, agent가 코딩 중 자주 빠지는 네 가지 실패 패턴을 반대로 뒤집은 체크리스트에 가깝다. 첫째, Think Before Coding은 해석이 여러 갈래일 때 침묵하지 말고 가정과 트레이드오프를 먼저 말하게 만든다. 이는 Thinking과 Understanding 분리와 연결된다. 에이전트가 thinking을 대신할 수는 있어도, 잘못된 가정 위에서 빠르게 코드를 쓰는 것은 오히려 위험하기 때문이다.
둘째, Simplicity First는 추상화와 옵션을 미래의 가능성 때문에 미리 넣지 말라고 요구한다. “한 번만 쓰일 코드에 추상화를 도입하지 마라”, “일어날 수 없는 시나리오를 위한 에러 처리를 넣지 마라”는 규칙은 Vibe Coding과 Agentic Engineering에서 말하는 과잉 생산의 함정을 막는 기준이 된다.
셋째, Surgical Changes는 변경분이 사용자의 요청과 직접 연결되어야 한다는 원칙이다. 기존 스타일을 존중하고, 관련 없는 포맷팅·주석·리팩터링을 하지 않으며, 오직 이번 변경 때문에 생긴 죽은 코드만 치운다. 이는 Claude Code 권한 설계와도 이어진다. 에이전트의 자유도를 줄여야 검토 가능한 diff가 나온다.
넷째, Goal-Driven Execution은 작업을 검증 가능하고 실패 가능한 목표로 다시 쓴다. “버그 수정” 대신 “버그를 재현하는 테스트를 먼저 만들고 그 테스트가 통과하게 하라”로 바꾸는 식이다. 이 원칙은 그대로 AI 코딩 에이전트 검증 전략의 최소 단위가 된다.
네 원칙을 합치면 좋은 CLAUDE.md나 AGENTS.md의 기본 골격이 된다. 그래서 이 지침은 단순한 프롬프트 팁이 아니라 Harness Engineering의 가장 작은 실행 단위로 볼 수 있다.
후속 설명이 덧붙인 중요한 포인트는 이 원칙이 추상 미학이 아니라 review cost를 줄이는 운영 규칙이라는 점이다. 조용한 가정, 과잉 엔지니어링, 부수적 피해를 줄이면 diff가 짧아지고, validation agent나 사람 리뷰어가 실제 변경 이유를 더 쉽게 심문할 수 있다.
예시
- 모호한 요청: “인증 개선”만 받았다면 바로 구현하지 않고, 세션 연장인지 권한 검증인지 해석 후보를 먼저 적는다.
- 단순성 점검: 50줄 함수 수정이면 충분한데 새 설정 옵션과 strategy class를 추가하려 한다면 과잉 설계 신호로 본다.
- 외과적 수정: 버그를 고치며 눈에 띈 기존 dead code는 언급만 하고, 이번 수정으로 새로 미사용이 된 import만 제거한다.
- 목표 기반 실행: “입력 검증 추가”를 “잘못된 payload에 대한 테스트를 작성하고 통과시킨다”로 다시 정의한다.
충돌
현재 확인된 충돌 없음.