AI 에이전트 코딩 원칙
개요
AI 에이전트가 코드를 작성하고 유지보수할 때 따라야 할 핵심 원칙들을 정리한 개념 노트. 단순한 코딩 가이드라인을 넘어, 에이전트의 인지적 한계와 맥락 유지 능력을 고려한 실용적 규칙들을 제시한다.
핵심 원칙
1. 단일 책임 원칙의 강화 (SRP+)
- 기존 SRP: 하나의 함수/클래스는 하나의 책임만 가져야 한다.
- 에이전트 SRP: 하나의 파일은 하나의 ‘인지적 단위’만 가져야 한다. 에이전트는 한 번에 하나의 완결된 작업만 수행할 수 있도록 코드를 분할한다.
- 실천: 함수 길이 20줄 이하, 파일당 public export 3개 이하
2. 명시적 맥락 주입
- 원칙: 에이전트가 코드를 이해하는 데 필요한 모든 맥락을 주석이나 문서로 명시적으로 제공한다.
- 이유: 에이전트는 암묵적 지식(프로젝트 히스토리, 결정 이유)을 추론하지 못함
- 방법:
// WHY: 이 함수는 X를 위해 Y 방식으로 구현됨형태의 의도 주석
3. 결정적 인터페이스
- 원칙: 모든 함수와 API는 입력이 같으면 항상 같은 출력을 보장해야 함
- 이유: 에이전트의 디버깅 능력은 결정적 시스템에서 극대화됨
- 예외: 명시적으로 문서화된 비결정적 동작만 허용
4. 점진적 구체화
- 원칙: 추상화 계층을 명확히 분리하고, 각 계층을 독립적으로 테스트 가능하게 설계
- 실천: 인터페이스 → 구현 → 세부 구현 순서로 단계별 접근
5. 에러 복원력
- 원칙: 모든 함수는 실패 가능성을 명시적으로 처리하고, 에러 발생 시 복구 가능한 상태를 유지
- 방법: Result 타입 패턴, 명시적 에러 처리, fallback 전략 내장
통찰: 인지적 부하 관리
이 원칙들의 근본적 의도는 에이전트의 인지적 부하를 최소화하는 것이다. 인간 개발자와 달리, 에이전트는 작업 메모리에 제한이 있고 맥락 전환 비용이 높다. 따라서 코드의 구조가 에이전트의 인지 패턴에 맞춰져야 한다. 이는 역설적으로 인간 개발자에게도 더 나은 코드를 만든다.