AI 에이전트 협업 핵심 원칙 (Agentic Development Principles)

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

When to use this skill

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

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

핵심 개념

적용 방법

실전 패턴: 단계적 구현

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

검증 포인트

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

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

핵심 개념

• 오래되고 관련 없는 정보는 AI 성능을 저하시킴
• 컨텍스트 드리프트: 여러 주제 혼합 시 성능 39% 저하

컨텍스트 관리 전략

전략 1: 단일 목적 대화

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

전략 2: HANDOFF.md 기법

# HANDOFF.md

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

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

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

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

전략 3: 컨텍스트 상태 확인

• Claude:

  /context

  ,

  /clear

• Gemini: 새 세션 시작
• ChatGPT: 새 채팅 시작

최적화 지표

• 활성 도구/플러그인: 최소화 유지
• 대화 길이: 너무 길어지면 HANDOFF.md 생성 후 새 세션

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

핵심 개념

실전 적용

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

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

핵심 개념

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

자동화 레벨 진화

자동화 대상 식별

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

원칙 5: 계획 모드 vs 실행 모드

계획 모드 (Plan First)

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

실행 모드 (Just Do It)

• 간단하고 명확한 작업
• 실험적인 프로토타입
• 반복적이고 시간이 많이 걸리는 작업
• 반드시 안전한 환경(컨테이너 등)에서 사용

권장 비율

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

원칙 6: 검증과 회고

출력 검증 방법

1. 테스트 코드 작성

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

2. 시각적 검토
   • 변경된 파일들을 diff로 확인
   • 원하지 않는 변경 사항 되돌리기
3. Draft PR 생성

   "draft PR을 만들어줘"

4. 자기 검증 요청

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

검증 체크리스트

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

Multi-Agent 워크플로우 적용

에이전트별 역할 분담

오케스트레이션 패턴

[계획 에이전트] 계획 수립 → [분석 에이전트] 분석/리서치 → [실행 에이전트] 코드 작성 → [검증] 테스트 → [종합] 결과 정리

Quick Reference

6대 원칙 요약

1. 분해정복    → 작고 명확한 단계로 분할
2. 컨텍스트   → 신선하게, 단일 목적 대화
3. 추상화     → Vibe ↔ Deep Dive 상황별
4. 자동화     → 3회 반복 시 자동화
5. 계획/실행  → 계획 90%, 실행 10%
6. 검증/회고  → 테스트, PR, 자기 검증

핵심 질문

- 이 작업을 더 작게 나눌 수 있는가?
- 컨텍스트가 오염되지 않았는가?
- 올바른 추상화 수준인가?
- 3번 이상 반복했는가?
- 계획을 먼저 세웠는가?
- 결과를 검증했는가?

References

• Claude Code Best Practices
• ykdojo claude-code-tips
• Ado's Advent of Claude