에이전틱 개발 원칙 (Agentic Development Principles)

“AI는 부조종사, 주인공은 당신입니다” AI 에이전트는 개발자의 생각을 증폭시키고 반복 작업을 대신하지만, 최종 결정권과 책임은 항상 개발자에게 있습니다.

When to use this skill

• AI 에이전트와 협업 세션 시작 시
• 복잡한 작업 시작 전 접근 방식 결정
• 컨텍스트 관리 전략 수립
• 생산성 향상을 위한 워크플로우 점검
• 팀원에게 AI 협업 사용법 온보딩
• 새로운 AI 도구 도입 시 기본 원칙 적용

원칙 1: 분해하고 정복하라 (Divide and Conquer)

핵심 개념

AI는 크고 모호한 작업보다 작고 명확한 지시에 훨씬 더 좋은 성능을 발휘합니다.

적용 방법

실전 패턴: 단계적 구현

1단계: 모델/스키마 설계 및 검증
2단계: 핵심 로직 구현 (최소 기능)
3단계: API/인터페이스 연결
4단계: 테스트 작성 및 실행
5단계: 통합 및 리팩토링

검증 포인트

• 각 단계가 독립적으로 검증 가능한가?
• 실패 시 해당 단계만 수정하면 되는가?
• AI가 명확히 이해할 수 있는 범위인가?

원칙 2: 컨텍스트는 우유와 같다 (Context is like Milk)

핵심 개념

컨텍스트(AI의 작업 기억)는 항상 신선하고 압축된 상태로 유지해야 합니다.

• 오래되고 관련 없는 정보는 AI 성능을 저하시킴
• 컨텍스트 드리프트: 여러 주제 혼합 시 성능 최대 39% 저하 (연구 ê²°ê³¼)

컨텍스트 관리 전략

전략 1: 단일 목적 대화

세션 1: 인증 시스템 작업
세션 2: UI 컴포넌트 작업  
세션 3: 테스트 코드 작성
세션 4: DevOps/배포 작업

• 한 대화에서 여러 주제를 섞지 않기
• 새로운 주제는 새 세션에서 시작

전략 2: HANDOFF.md 기법

대화가 길어질 때 핵심만 요약하여 새 세션에 전달:

# HANDOFF.md

## 완료된 작업
- ✅ 사용자 인증 API 구현 완료
- ✅ JWT 토큰 발급 로직 작성

## 현재 상태
- 토큰 갱신 로직 작업 중

## 다음 작업
- 리프레시 토큰 구현
- 로그아웃 엔드포인트 추가

## 시도했지만 실패한 것
- Redis 세션 저장소 연동 실패 (네트워크 이슈)

## 주의사항
- 기존 세션 관리 코드와 충돌 주의

전략 3: 컨텍스트 상태 모니터링

• 대화가 길어지면 AI에게 현재 상태 요약 요청
• 필요시 대화 초기화 후 HANDOFF.md로 재시작

전략 4: 최적화 지표

원칙 3: 올바른 추상화 수준 선택

핵심 개념

상황에 따라 적절한 추상화 수준을 선택합니다.

실전 적용

새 기능 추가 시:
1. 높은 추상화: "사용자 프로필 페이지를 만들어줘" → 전체 구조 파악
2. 중간 추상화: "프로필 편집 폼의 유효성 검사 로직을 보여줘" → 특정 기능 검토
3. 낮은 추상화: "이 정규식이 왜 이메일 유효성 검사에 실패하는지 설명해줘" → 세부 디버깅

추상화 수준 선택 가이드

• 프로토타입/PoC: Vibe Coding 80%, Deep Dive 20%
• 프로덕션 코드: Vibe Coding 30%, Deep Dive 70%
• 버그 수정: Deep Dive 100%

원칙 4: 자동화의 자동화 (Automation of Automation)

핵심 개념

같은 작업을 3번 이상 반복했다면 → 자동화 방법을 찾아라
그 자동화 과정 자체도 → 자동화하라

자동화 레벨 진화

자동화 대상 식별 체크리스트

• 같은 명령어를 3번 이상 실행하는가?
• 같은 설명을 반복하는가?
• 같은 패턴의 코드를 자주 작성하는가?
• 같은 검증 절차를 반복하는가?

자동화 우선순위

1. 높음: 매일 반복하는 작업
2. 중간: 주 1회 이상 반복하는 작업
3. 낮음: 월 1회 정도의 작업

원칙 5: 신중함과 속도의 균형 (Plan vs Execute)

계획 모드 (Plan Mode)

분석만 하고 실행하지 않음 – 검토 후 승인

사용 시점:

• 처음 해보는 복잡한 작업
• 여러 파일에 걸친 대규모 리팩토링
• 아키텍처 변경
• 데이터베이스 마이그레이션
• 되돌리기 어려운 작업

실행 모드 (Execute Mode)

AI가 직접 코드 수정 및 명령 실행

사용 시점:

• 간단하고 명확한 작업
• 충분히 검증된 패턴의 작업
• 샌드박스/컨테이너 환경
• 되돌리기 쉬운 작업

권장 비율

• 계획 모드: 70-90% (기본값으로 사용)
• 실행 모드: 10-30% (안전한 환경에서만)

안전 원칙

• ⚠️ 위험한 명령어 자동 실행은 격리된 환경에서만
• 중요 데이터 변경 전 반드시 백업
• 되돌릴 수 없는 작업은 항상 계획 모드

원칙 6: 검증과 회고 (Verify and Reflect)

출력 검증 방법

1. 테스트 코드 작성

   "이 함수에 대한 테스트를 작성해줘. 엣지 케이스도 포함해야 해."
   

2. 시각적 검토

   • 변경된 파일들을 diff로 확인
   • 원하지 않는 변경 사항 되돌리기

3. Draft PR / 코드 리뷰

   "이 변경사항으로 draft PR을 만들어줘"
   

4. 자기 검증 요청

   "방금 생성한 코드를 다시 검토해줘.
   모든 주장을 검증하고, 끝에 검증 결과를 표로 정리해줘."
   

검증 체크리스트

• 코드가 의도한 대로 동작하는가?
• 엣지 케이스가 처리되었는가?
• 보안 취약점은 없는가?
• 테스트가 충분한가?
• 성능에 문제가 없는가?

회고 질문

• 이 세션에서 무엇을 배웠는가?
• 다음에 더 잘할 수 있는 것은?
• 자동화할 수 있는 반복 작업이 있었는가?

Quick Reference

6대 원칙 요약

마스터리 규칙

“AI 도구를 진정으로 마스터하려면 충분히 많이 사용해봐야 한다”

사용을 통한 학습이 핵심 – 이론만으로는 부족하고, 실제 프로젝트에서 다양한 상황을 경험해야 합니다.

황금률

AI에게 지시할 때:
1. 명확하게 (Specific)
2. 단계별로 (Step-by-step)
3. 검증 가능하게 (Verifiable)

Best Practices

DO (권장)

• 하나의 대화에서는 하나의 명확한 목표에 집중
• 컨텍스트를 주기적으로 정리
• 복잡한 작업 전 계획 수립
• 출력 ê²°ê³¼ 항상 검증
• 반복 작업은 자동화

DON’T (금지)

• 여러 관련 없는 작업을 한 대화에서 처리
• 컨텍스트가 가득 ì°¬ 상태로 계속 작업
• 위험한 명령어 무분별하게 자동 실행
• AI 출력을 검증 없이 그대로 사용
• 같은 작업을 반복하면서 자동화하지 않기

References

• Anthropic Claude Best Practices
• ykdojo claude-code-tips
• Ado’s Advent of Claude
• OpenAI Best Practices