---
name: agentic-development-principles
description: AI 에이전트와 협업하는 에이전틱 개발의 범용 원칙. 분해정복, 컨텍스트 관리, 추상화 수준 선택, 자동화 철학을 정의. 모든 AI 코딩 도구에 적용 가능.
allowed-tools: [Read, Write, Bash, Grep, Glob]
tags: [agentic-development, principles, context-management, automation, ai-collaboration, universal]
platforms: [Claude, ChatGPT, Gemini]
version: 1.0.0
source: Claude Code 완전 가이드 70가지 팁 (ykdojo + Ado Kukic) - 범용화
---

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

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

## When to use this skill

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

---

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

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

### 적용 방법

| 잘못된 예 | 올바른 예 |
|----------|----------|
| "로그인 페이지 만들어줘" | 1. "로그인 폼 UI 컴포넌트 생성" |
| | 2. "로그인 API 엔드포인트 작성" |
| | 3. "인증 로직 연결" |
| | 4. "테스트 코드 작성" |
| "앱 최적화해줘" | 1. "성능 병목 지점 분석" |
| | 2. "데이터베이스 쿼리 최적화" |
| | 3. "프론트엔드 번들 크기 줄이기" |

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

```
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 토큰 발급 로직 작성

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

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

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

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

#### 전략 3: 컨텍스트 상태 모니터링
- 대화가 길어지면 AI에게 현재 상태 요약 요청
- 필요시 대화 초기화 후 HANDOFF.md로 재시작

#### 전략 4: 최적화 지표
| 지표 | 권장 값 | 조치 |
|------|---------|------|
| 대화 길이 | 적정 수준 유지 | 길어지면 HANDOFF.md 생성 |
| 주제 수 | 1개 (단일 목적) | 새 주제는 새 세션 |
| 활성 파일 | 필요한 것만 | 불필요한 컨텍스트 제거 |

---

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

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

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

### 실전 적용

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

### 추상화 수준 선택 가이드
- **프로토타입/PoC**: Vibe Coding 80%, Deep Dive 20%
- **프로덕션 코드**: Vibe Coding 30%, Deep Dive 70%
- **버그 수정**: Deep Dive 100%

---

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

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

### 자동화 레벨 진화

| Level | 방식 | 예시 |
|-------|------|------|
| 1 | 수동 복사/붙여넣기 | AI 출력 → 터미널에 복사 |
| 2 | 터미널 통합 | AI 도구 직접 사용 |
| 3 | 음성 입력 | 음성 전사 시스템 |
| 4 | 반복 지시 자동화 | 프로젝트 설정 파일 활용 |
| 5 | 워크플로우 자동화 | 커스텀 명령어/스크립트 |
| 6 | 판단 자동화 | Skills 활용 |
| 7 | 규칙 강제 자동화 | Hooks/가드레일 활용 |

### 자동화 대상 식별 체크리스트
- [ ] 같은 명령어를 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대 원칙 요약

| 원칙 | 핵심 | 실천 |
|------|------|------|
| 1. 분해정복 | 작고 명확한 단위 | 독립 검증 가능한 단계로 분할 |
| 2. 컨텍스트 관리 | 신선하게 유지 | 단일 목적 대화, HANDOFF.md |
| 3. 추상화 선택 | 상황별 깊이 | Vibe ↔ Deep Dive 조절 |
| 4. 자동화² | 반복 제거 | 3회 반복 시 자동화 |
| 5. 계획/실행 균형 | 신중함 우선 | 계획 70-90%, 실행 10-30% |
| 6. 검증 회고 | 출력 확인 | 테스트, 리뷰, 자기 검증 |

### 마스터리 규칙
> "AI 도구를 진정으로 마스터하려면 충분히 많이 사용해봐야 한다"

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

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

---

## Best Practices

### DO (권장)
- 하나의 대화에서는 하나의 명확한 목표에 집중
- 컨텍스트를 주기적으로 정리
- 복잡한 작업 전 계획 수립
- 출력 결과 항상 검증
- 반복 작업은 자동화

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

---

## References

- [Anthropic Claude 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/)
- [OpenAI Best Practices](https://platform.openai.com/docs/guides/prompt-engineering)