home / skills / supercent-io / skills-template / agentic-principles

agentic-principles skill

This skill helps you implement agentic development principles to structure, manage context, automate workflows, and validate AI collaboration patterns.

npx playbooks add skill supercent-io/skills-template --skill agentic-principles

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

7.6 KB

---
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/)

Overview

This skill codifies core principles for collaborating with AI agents during software development. It presents practical rules—divide and conquer, context management, abstraction level selection, automation escalation, planning vs execution, and verification—to make agent-assisted work predictable and safe. Use it to standardize workflows and reduce context drift when multiple agents or sessions are involved.

How this skill works

The skill inspects development tasks and maps them to agent-friendly patterns: break large tasks into independent steps, keep conversation context fresh and purpose-specific, and choose the right abstraction mode (high-level vs deep-dive). It recommends when to automate repetitive steps, how to orchestrate multiple agents with clear roles, and concrete verification checkpoints like tests and draft PRs.

When to use it

At the start of any AI agent session to set collaboration rules
Before tackling complex or cross-file changes to define plan vs execution
When establishing context management strategy for long or multi-topic work
During onboarding to teach team members agent collaboration patterns
When repetitive manual steps appear and automation should be considered

Best practices

Always split large tasks into small, verifiable stages with independent checks
Keep each conversation single-purpose; create HANDOFF documents when sessions grow long
Select abstraction level deliberately: use high-level for design, deep-dive for debugging
Automate tasks repeated three or more times and evolve automation incrementally
Prefer planning mode for risky or large changes; use execution mode in safe, contained environments

Example use cases

Build a new feature by staging: schema → core logic → API → tests → integration
Run multi-agent workflow: planning agent defines tasks, analysis agent researches, executor runs builds
Onboard a teammate by demonstrating single-purpose tabs and HANDOFF.md state transfers
Convert repeated manual code transformations into a scripted workflow or skill
Perform production changes by planning thoroughly, generating draft PRs, and running self-verification

FAQ

How do I keep agent context from degrading over long sessions?

Use single-purpose conversations, minimize active tools/plugins, and create a HANDOFF document summarizing completed work, current state, next tasks, and caveats; then start a fresh session when needed.

When should I switch from planning to execution mode?

Default to planning for most work (recommended ~90%). Switch to execution for small, low-risk, or time-consuming repetitive tasks in safe environments like containers.