---
name: agentic-principles
description: AI 에이전트 협업 개발의 핵심 원칙. 분해정복, 컨텍스트 관리, 추상화 수준 선택, 자동화 철학, 검증 회고를 정의. 모든 AI 에이전트 사용 시 최적의 협업 패턴 적용.
allowed-tools: [Read, Write, Bash, Grep, Glob]
tags: [agentic-development, principles, context-management, automation, multi-agent]
platforms: [Claude, Gemini, ChatGPT, Codex]
version: 2.0.0
source: Claude Code 완전 가이드 70가지 팁 (ykdojo + Ado Kukic)
---

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

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

## When to use this skill

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

---

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

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

### 적용 방법

| 잘못된 예 | 올바른 예 |
|----------|----------|
| "로그인 페이지 만들어줘" | 1. "로그인 폼 UI 컴포넌트 생성" |
| | 2. "로그인 API 엔드포인트 작성" |
| | 3. "인증 로직 연결" |
| | 4. "테스트 코드 작성" |

### 실전 패턴: 단계적 구현

```
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 기법
대화가 길어지면 상태를 문서화:
```markdown
# HANDOFF.md

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

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

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

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

#### 전략 3: 컨텍스트 상태 확인
- Claude: `/context`, `/clear`
- Gemini: 새 세션 시작
- ChatGPT: 새 채팅 시작

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

---

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

### 핵심 개념
상황에 따라 적절한 추상화 수준을 선택합니다.

| 모드 | 설명 | 사용 시점 |
|------|------|----------|
| **Vibe Coding** | 전체 구조만 보는 높은 수준 | 빠른 프로토타이핑, 아이디어 검증, 일회성 프로젝트 |
| **Deep Dive** | 코드 한 줄씩 파고드는 낮은 수준 | 버그 수정, 보안 검토, 성능 최적화, 프로덕션 코드 |

### 실전 적용

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

---

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

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

### 자동화 레벨 진화

| Level | 방식 | 예시 |
|-------|------|------|
| 1 | 수동 복사/붙여넣기 | ChatGPT → 터미널 |
| 2 | 터미널 통합 | Claude Code, Gemini CLI 직접 사용 |
| 3 | 음성 입력 | 음성 전사 시스템 |
| 4 | 반복 지시 자동화 | 프로젝트 설명 파일 활용 |
| 5 | 워크플로우 자동화 | 커스텀 명령어/스킬 |
| 6 | 판단 자동화 | AI Skills 활용 |
| 7 | 규칙 강제 자동화 | Hooks/Guard Rails |

### 자동화 대상 식별
- [ ] 같은 명령어를 3번 이상 실행하는가?
- [ ] 같은 설명을 반복하는가?
- [ ] 같은 패턴의 코드를 자주 작성하는가?

---

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

### 계획 모드 (Plan First)
분석만 하고 수정하지 않음

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

### 실행 모드 (Just Do It)
**사용 시점:**
- 간단하고 명확한 작업
- 실험적인 프로토타입
- 반복적이고 시간이 많이 걸리는 작업
- **반드시** 안전한 환경(컨테이너 등)에서 사용

### 권장 비율
- 계획 모드: **90%** (기본값으로 사용)
- 실행 모드: **10%** (안전한 환경에서만)

---

## 원칙 6: 검증과 회고

### 출력 검증 방법

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

2. **시각적 검토**
   - 변경된 파일들을 diff로 확인
   - 원하지 않는 변경 사항 되돌리기

3. **Draft PR 생성**
   ```
   "draft PR을 만들어줘"
   ```

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

### 검증 체크리스트
- [ ] 코드가 의도한 대로 동작하는가?
- [ ] 엣지 케이스가 처리되었는가?
- [ ] 보안 취약점은 없는가?
- [ ] 테스트가 충분한가?

---

## Multi-Agent 워크플로우 적용

### 에이전트별 역할 분담

| Agent | Role | Best For |
|-------|------|----------|
| **Claude** | Orchestrator | 계획 수립, 코드 생성, 스킬 해석 |
| **Gemini** | Analyst | 대용량 분석 (1M+ 토큰), 리서치 |
| **Codex** | Executor | 명령 실행, 빌드, 배포 |

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

---

## Quick Reference

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

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

---

## References

- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
- [ykdojo claude-code-tips](https://github.com/ykdojo/claude-code-tips)
- [Ado's Advent of Claude](https://adocomplete.com/advent-of-claude-2025/)