에이전틱 엔지니어링 핵심 개념 5가지
실밸개발자님 영상을 많이 참고했다.
"99%의 시간 동안 당신은 직접 코드를 작성하지 않는다. 에이전트를 오케스트레이션하고 감독하는 것이다. 거기에는 예술과 과학, 전문성이 있다."
— Andrej Karpathy
에이전트가 Context를 바탕으로 Plan을 세우고,
Tool/MCP를 사용해 실행하고,
훅과 스킬로 품질 제어,
Human이 감독한다.
에이전틱 엔지니어링으로 개발해라
AI가 코드를 구현하되, 인간이 아키텍처, 품질, 정확성을 책임지는 방식으로, 단순한 AI 코드 생성인 '바이브 코딩'의 한계를 넘어선다.
| Vibe Coding (BEFORE) | Agentic Engineering (AFTER) | |
|---|---|---|
| 방식 | AI한테 대충 말하면 코드가 뚝딱 | AI가 구현하되, 인간이 아키텍처와 품질과 정확성을 소유 |
| 특징 | 재밌지만 한계 명확 | 체계적 위임과 감독 |
| 문제 | 품질 보장 없음 | 5가지 핵심 개념 |
5가지 핵심 개념
| 01 Agent & Sub-Agent | 02 Context Engineering | 03 Tool & MCP | 04 Hook & Skill | 05 Planning & HITL |
|---|
1. 에이전트: 계층적 위임 구조
- 목표를 해석하고, 계획 세우고, 도구 사용해서 자율적으로 실행하는 주체
- 목표 해석 → 계획→ 실행 → 평가 (루프)
- 도구 사용: 파일 읽기/쓰기, 터미널, API 호출 등
- 자율성
- 스스로 오류 감지 하고 수정 시도(self healing)
복잡한 작업일때?
Lost-in-the-Middle 현상
[회상률]
~90% ●
\
\
●
\
\
● ~40% ← 중간 구간 (핵심 정보가 여기 있으면 모델이 놓침)
/
/
●
/
~85% ● ▲ 최종 구간- 하나의 Context안에서 여러 작업을 하면 성능 떨어짐(Lost in the middle)
- 회상률 다운
그래서 등장!
Multi Agent 오케스트레이션
[Orchestrator Agent]
총감독
|
┌──────────────────┼──────────────────┐──────────────────┐
↓ ↓ ↓ ↓
[Sub-Agent] [Sub-Agent] [Sub-Agent] [Sub-Agent]
프론트엔드 전문 백엔드 전문 DB 설계 전문 테스트 전문
UI/UX, 컴포넌트, API, 비즈니스 로직, 스키마, 쿼리 최적화, 유닛, 통합,
스타일링 인프라 마이그레이션 E2E 테스트영화감독과 같다. 전체 비전을 가지고, 전문가에게 위임하고, 결과물을 통합한다!
그래서 진짜, 어떻게 멀티 에이전트 오케스트레이션을 하는건데?
Fan-out → 병렬 실행 → Fan-in
작업을 분배하고, 동시에 실행하고, 결과를 통합하는 패턴
PHASE 1 PHASE 2 PHASE 3
┌→ [프론트엔드] ──┐
[작업 분배] ───┼→ [백엔드] ┼──→ [결과 통합]
Fan-out ├→ [DB 설계] ─┤ Fan-in
└→ [테스트] ──┘
병렬 실행에이전트 팀즈
Subagents 구조
[Main Agent]
|
┌─────────┼─────────┐
↓ ↓ ↓
[Subagent] [Subagent] [Subagent]
Work Work Work
↓ ↓ ↓
Result Result Result
↓
ReportAgent Teams 구조
[Main Agent (Team Lead)]
|
Spawn Team & Assign Tasks
|
[Shared Task List]
↙ ↓ ↘
Communicate Communicate Communicate
& Claim Tasks & Claim Tasks & Claim Tasks
↓ ↓ ↓
[Teammate] ↔ [Teammate] ↔ [Teammate]
Work Work Work서브에이전트
- 메인 컨텍스트와 분리된, 별도의 컨텍스트를 갖고있음 → 작업 끝난다음 결과 요약 후 메인 컨텍스트(에이전트)에 리턴 → 메인 컨텍스트 아끼면서 더 길고 복잡한 작업 이어갈 수 있음
- 하지만 서브 에이전트끼리 직접 대화 불가
- 여러개 돌리게 되면 병목, 한계
- 메인 에이전트가 매번 지시 필요 (a 서브에이전트야 뭐 해라 ~)
- 비용 저렴
서브에이전트 vs 에이전트 팀즈 차이
핵심 차이 = 스킬 상속 방식
| CLAUDE.md | MCP 도구 | 스킬 | 대화 기록 | |
|---|---|---|---|---|
| 팀원 | ✅ 자동 | ✅ 자동 | ✅ 전부 자동 | ❌ 프롬프트만 |
| 서브에이전트 | ✅ 자동 | ✅ 자동 | ⚠️ 선택 지정 | ❌ 프롬프트만 |
유일한 차이는 스킬입니다.
팀원은 프로젝트의 모든 스킬을 전부 자동으로 가져가고, 서브에이전트는 골라서 넣어줘야 합니다.
설계 기준:
스킬을 정밀하게 제어해야 한다면 → 서브에이전트
모든 팀원이 같은 스킬 셋이면 → 팀원이 편리
에이전트 팀즈
- 독립된 컨텍스트 유지
- 팀장이 전부 중계하지말고, 팀원끼리 직접 소통하고 스스로 작업을 나눠 가지게 하자
- 공유 태스크 리스트가 있음 → 스스로 다음 작업 가져감
- 테스크리스트
- 공유 작업 목록
- 리드가 작업 목록 생성 → 팀원들이 처리
- 테스크리스트
- 팀원수 X 토큰 비용
- 사용법
- 3명의 팀원을 만들어서 각각 보안, 성능, 스타일 리뷰해줘
- 언제사용?
- 서브에이전트는 결과 요약만 메인에 갖다준다. 서브 에이전트간 병렬로 했을 때, 서로 대화 못함. 메인이 많은 일을 제어 ⇒ 병목 생김
에이전트 팀즈 사용법
ex 3명의 팀원을 만들어서 각각 보안, 성능, 스타일 리뷰해줘
→ 팀이 생성되고 → 테스크 리스트 작성 → 팀원 스폰(생성) → shift+ 방향 아래키로 팀원들 확인 가능
→ 팀 리드한테 "지금 상황을 보고해"
컨텍스트 계승
팀원은 새 세션으로 생성 - claude.md, MCP, 스킬 전부 자동로드. 서브에이전트는 스킬만 선택 주입.
계획 먼저, 코딩 나중
팀원이 바로 코딩하면 방향이 틀어질 때 토큰 전부 낭비
- 팀 생성 → "각 팀원이 변경하기 전에 plan approval을 받도록 해줘", 추가 : 팀원이 plan mode로 시작함(읽기모드)
- 계획 분석 (Plan Mode)
- 계획 제출 → 리드에게 보고
- 승인/ 거절 → 리드가 판단
- 구현 시작 → 승인 후 실행
모델믹싱 = 핵심전략
- 리드 = Opus
- 팀원 = Sonnet
팀원은 모두 Sonnet을 사용해
4가지 비용 절감
- 소통 불필요한 작업은 서브에이전트 사용
- 3~5명이면 충분
- 끝난 팀원은 즉시 종료
- Claude.md에 비용 지침
- 브로드캐스트 금지
Hooks = 이벤트기반 자동화
- 팀원이 작업을 끝나면 → idle(유휴상태) : 그걸 훅이 감지 가능
TeammateIdle vs TaskCompleted
| TeammateIdle | TaskCompleted | |
|---|---|---|
| 발동 시점 | 팀원이 할 일을 끝내고 쉬고 있을 때 | 팀원이 태스크를 "완료" 처리할 때 |
| 동작 | exit 2 → 피드백을 전달해서 팀원이 계속 작업하도록 | exit 2 → 완료 자체를 차단하고 피드백 전달 |
| 설명 | "쉬고 있는 직원에게 추가 업무 주는 것" | "팀장이 결과를 검토 후 돌려보내는 것" |
| 활용 예시 | "작업 끝나면 요약 보고서를 작성해라" | npm test \|\| exit 2 (자동 테스트 게이트) |
Eric Tech님의 예시
아래와 같이 상세하게 propmt를 적는 방법도 있다.
# KAN-75 오픈뱅킹 리서치 — 에이전트 팀 프롬프트
Plaid(US)와 Flinks(Canada)를 통한 직접 은행 연결로 거래 내역을 우리 북키핑 앱(Next.js 14 + Supabase, 캐나다 우선, 타겟 1000 유저 → YC March 2026)에 자동 임포트하는 방안을 리서치한다.
💡 `kan-75-research` 팀을 만들어서 4개의 병렬 에이전트를 구성하고, 각자의 조사 결과를 `docs/research/KAN-75-open-banking-research.md` 파일로 취합한다.
JIRA 티켓 넘버는 여기에 있으니 티켓 컨텍스트가 필요하면 접근해서 확인할 것: **KAN-75**
---
## Agent 1 — Business & Product
**Name:** `business-product`
**Model:** Sonnet
**Sub-agent type:** `product-strategy-advisor`
💡 웹 검색을 활용해서 경쟁사와 시장 데이터를 수집한다. 산문이 아닌 구조화된 표로 출력한다.
- 경쟁사 비교 매트릭스: Wave, QuickBooks, FreshBooks, Bench, Hurdlr — 각각 어떤 오픈뱅킹 프로바이더를 쓰는지, 은행 연결을 포함하는 요금제 티어, 연결 제한
- Plaid vs Flinks의 캐나다 우선 전략에 대한 Product-Market Fit (Big 5 은행, 신용조합, 핀테크 커버리지)
- 사용자 경험 비교: 연결 플로우 스텝 수, 재인증 주기, 실패 모드, 첫 거래까지 걸리는 시간
- 영향 분석 표: 은행 연결 유무에 따른 retention, paid conversion, churn 예상 효과
- YC 내러티브 앵글: 은행 연결이 "AI 북키퍼" 포지셔닝을 "영수증 스캐너" 대비 어떻게 강화하는가
---
## Agent 2 — Financial & Cost
**Name:** `financial-cost`
**Model:** Sonnet
**Sub-agent type:** `general-purpose`
현재 Plaid와 Flinks 가격을 웹 검색으로 확인한다. 모든 추정치는 **build-for-longevity** 관점으로 프레임 — 런칭 시점이 아니라 스케일 상태의 비용을 모델링한다.
- Plaid 가격: 연결당 수수료, API 콜 비용, free tier / 스타트업 프로그램 한도, 엔터프라이즈 할인
- Flinks 가격: 연결당 수수료, 월 최저액, 스타트업 딜
- **100 / 1,000 / 10,000 / 1,000,000** 연결 유저 규모에서 각 프로바이더의 비용 추정 표
- Breakeven 분석: 은행 연결을 paid tier에만 게이팅할 수 있는가? 몇 명 유저부터 프로바이더 비용이 구독 매출을 초과하는가?
- 현재 AI 크레딧 비용(Gemini Flash) 대비 비교 — 오픈뱅킹이 더 큰 비용 라인인가, 작은 비용 라인인가?
- 듀얼 프로바이더 비용 모델: 캐나다는 Flinks + 미국은 Plaid vs 단일 프로바이더로 양 시장 커버
---
## Agent 3 — Technical Architecture
**Name:** `tech-architect`
**Model:** Opus
**Sub-agent type:** `system-architect`
비즈니스 로직을 다시 작성하지 않고도 Plaid/Flinks/미래 프로바이더를 교체할 수 있도록 provider-agnostic 추상화 레이어를 설계한다. 아키텍처 개요는 Mermaid 다이어그램으로 표현한다. 동기화 엔진의 async 플로우, 엣지 케이스, 상태 머신 설계에는 `/data-flow-analysis` 스킬을 트리거한다.
- 추상화 레이어 설계: `BankConnectionProvider` 인터페이스, Plaid SDK + Flinks Connect 위젯 + 미래 프로바이더를 위한 어댑터 패턴
- Mermaid 아키텍처 다이어그램: client → provider widget → callback → API route → token exchange → DB
---
## Agent 4 — Devil's Advocate
(원문 구조 유지 — 여기에 Devil's Advocate 역할의 리스크 분석/반론 지시사항 작성)
---
## Lead Synthesis (You — Opus)
4개 에이전트가 모두 리포트를 완료하면, 최종 리포트를 `docs/research/KAN-75-open-banking-research.md`에 다음 내용을 포함해서 작성한다:
1. **Go / No-Go 권고** — 근거 포함
2. **프로바이더 권고** — Plaid, Flinks, 둘 다, 또는 대안 (reasoning 포함)
3. **비용 요약 표** — 프로바이더별, 유저 티어별 (100 / 1K / 10K / 1M)
4. **아키텍처 권고** — Mermaid 다이어그램과 추상화 레이어 설계 포함
5. **리스크 레지스터** — Agent 4의 devil's advocate 분석 기반, 완화 방안 포함
6. **구현 페이즈** — 추천 롤아웃 계획과 공수 추정
위의 promt를 보고 내 프로젝트에서도 적용했다.
# BUR-01 BuryIt Mobile 개발 품질 감사 — 에이전트 팀 프롬프트
BuryIt-mobile(React Native + Expo)의 현재 코드베이스에 대한 포괄적인 개발 품질 감사를 수행한다. 보안, 성능, 테스트 커버리지, 아키텍처 건강도 4개 축으로 병렬 분석하고, 결과를 하나의 종합 리포트로 취합한다.
`buryit-dev-audit` 팀을 만들어서 4개의 병렬 에이전트를 구성하고, 각자의 조사 결과를 `docs/research/BUR-01-audit-report.md` 파일로 취합한다.
컨텍스트 참고 파일:
- `CLAUDE.md` — 프로젝트 전체 컨벤션 (절대규칙, 아키텍처, 도메인 용어)
- `docs/frontend-architecture.md` — 라우팅, 데이터 흐름, 상태 관리 설계
- `docs/api-spec.md` — GraphQL API 명세 (29개 오퍼레이션)
- `docs/fe-to-mobile-mapping.md` — 웹 포팅 상태 및 미포팅 목록
- `.claude/skills/mobile-architecture/SKILL.md` — 5-Layer 아키텍처, SRP/레이어 규칙, 훅 분해 패턴
- `TODO.md` — Phase 1~5 작업 목록 및 진행률
---
## Agent 1 — Security Auditor
**Name:** `security-auditor`
**Model:** Sonnet
**Sub-agent type:** `security-reviewer`
BuryIt-mobile의 인증/인가, 토큰 관리, 입력 검증, GraphQL 보안을 감사한다. React Native + Expo 환경 특유의 보안 위험(SecureStore 한계, 디컴파일 위험, 네트워크 인터셉션)까지 포함한다.
- **토큰 관리 감사**: `lib/auth.ts`의 이중 저장 레이어(메모리 캐시 + SecureStore) — 메모리 캐시 누출 시나리오, 토큰 만료 처리, refresh token rotation 안전성
- **urql authExchange 감사**: `lib/urql.ts`의 인증 교환 파이프라인 — UNAUTHENTICATED 에러 시 토큰 갱신 로직, 동시 요청 시 race condition, 갱신 실패 시 정리 동작
- **입력 검증 감사**: `features/burial/schemas/burial.schema.ts` (Zod) — 매장 폼 입력의 검증 범위, XSS/인젝션 가능 필드(title, story, hashtags), 이미지 URL 검증
- **환경변수 노출**: `.env`, `app.json`, `eas.json` — 하드코딩된 시크릿, `EXPO_PUBLIC_*` 접두사로 클라이언트에 노출되는 변수 식별
- **의존성 보안**: `npm audit --audit-level=high` 실행, 알려진 CVE가 있는 패키지 식별
- **게스트 모드 접근 제어**: `features/auth/hooks/useAuthGuard.ts`, `components/ui/AuthPromptModal.tsx` — 게스트가 인증 필요 기능에 접근하는 경로 누락 여부
- **GraphQL 보안**: 클라이언트 사이드 쿼리에서 과도한 데이터 요청(over-fetching), 민감 필드 노출 여부
출력: 취약점 매트릭스 (Critical / High / Medium / Low) + 각 항목별 수정 코드 예시
---
## Agent 2 — Performance Optimizer
**Name:** `perf-optimizer`
**Model:** Sonnet
**Sub-agent type:** `code-reviewer`
React Native + Expo 환경에서의 성능 병목을 식별한다. 리렌더 최적화, 리스트 가상화, 맵 성능, 번들 사이즈, 메모리 관리에 집중한다.
- **컴포넌트 리렌더 분석**: `features/` 전체 컴포넌트에서 불필요한 리렌더 유발 패턴 — 인라인 객체/배열 생성, useCallback/useMemo 누락, 컨텍스트 구독 범위 과다
- **Zustand selector 효율성**: `stores/` 4개 스토어(auth, explore, feed, map)의 selector 패턴 — 전체 스토어 구독 vs 세분화된 selector, `useMapStore`의 4개 네임스페이스별 구독 최적화
- **FlashList 설정 점검**: `features/feed/`, `features/place/`, `features/hall-of-fame/`의 리스트 컴포넌트 — `estimatedItemSize` 값의 적절성, `getItemType` 활용 여부, `keyExtractor` 안정성
- **맵 성능**: `features/map/` — `TombstoneMarkersByBounds` 쿼리의 마커 수 제한, 클러스터링 임계값, 뷰포트 변경 시 디바운싱 적용 여부
- **이미지 로딩**: `features/burial/components/ImagePickerButton.tsx`, 피드/상세 화면의 이미지 표시 — 이미지 캐싱 전략, 플레이스홀더, 프로그레시브 로딩
- **번들 사이즈 분석**: 주요 의존성 크기 확인, 트리 셰이킹 가능한 import 패턴 확인
- **메모리 관리**: 화면 전환 시 구독 해제, useEffect 클린업 누락, 큰 데이터셋의 메모리 유지 패턴
출력: 성능 병목 목록 (영향도 High / Medium / Low) + Before/After 코드 예시 + 측정 가능한 개선 지표 제안
---
## Agent 3 — Test & Coverage Auditor
**Name:** `test-auditor`
**Model:** Sonnet
**Sub-agent type:** `tdd-guide`
기존 테스트 스위트(82개 파일)의 품질과 커버리지 갭을 분석한다. 테스트 작성이 아닌 **감사 모드**로 동작하여, 미테스트 영역과 테스트 품질 문제를 식별한다.
- **커버리지 갭 매트릭스**: `npx jest --coverage` 실행 후 feature별 커버리지 수치 산출 — `features/` 9개 모듈 각각의 분기/함수/줄 커버리지
- **미테스트 훅 식별**: `features/*/hooks/` 디렉토리의 모든 커스텀 훅 vs `__tests__/features/*/hooks/` 매칭 — 테스트 파일이 없는 훅 목록
- **미테스트 스토어 액션**: `stores/` 4개 스토어의 액션 중 테스트에서 호출되지 않는 액션 식별
- **코어 라이브러리 커버리지**: `lib/auth.ts`, `lib/urql.ts`, `lib/hooks/`, `lib/utils/` — 핵심 유틸의 엣지 케이스 커버리지
- **mock 품질 감사**: `__tests__/` 전체의 mock 패턴 — 과도한 mock(구현 세부사항 테스트), 불완전한 mock(실제 동작과 괴리), mock 일관성(같은 모듈을 다른 방식으로 mock)
- **테스트 안티패턴**: 공유 상태 의존, 어설션 없는 테스트, 구현 세부사항 테스트, flaky 테스트 후보(타이머/네트워크 의존)
- **엣지 케이스 누락**: null/undefined 입력, 빈 배열, 네트워크 에러, 토큰 만료, 동시 요청 시나리오
출력: Feature별 커버리지 매트릭스 + 미테스트 항목 우선순위 목록 (Critical Path 기준) + mock 품질 점수
---
## Agent 4 — Architecture & Code Health
**Name:** `arch-health`
**Model:** Sonnet
**Sub-agent type:** `code-reviewer`
코드 패턴 일관성, 데드 코드, 의존성 건강도, 기술 부채를 식별한다. `refactor-cleaner`와 `architect` 에이전트의 관점을 결합하여 코드베이스 전반의 구조적 건강도를 평가한다.
- **5-Layer SRP 준수 검사**: `.claude/skills/mobile-architecture/SKILL.md`의 레이어 규칙(Route/Screen/Hook/Component/API)에 따라 각 레이어가 허용/금지 사항을 지키는지 검사 — Route에 로직이 있는지, Component에서 useQuery를 호출하는지, Hook에서 UI를 렌더링하는지, Screen이 비즈니스 로직을 직접 포함하는지
- **훅 크기 & 책임 분리**: 범용 훅(lib/hooks/) 50줄 이내, Feature 훅(features/*/hooks/) 30줄 이내 규칙 준수 여부 — 여러 책임을 혼합한 훅(데이터 페칭 + UI 상태 + 사이드이펙트), 범용 훅으로 추출 가능한 반복 패턴
- **의존성 방향 검사**: feature → lib 방향만 허용, feature 간 직접 import 금지, Component → Store 직접 접근 금지(props로 전달), API Layer에서 로직 포함 여부
- **Feature 모듈 일관성**: `features/` 9개 모듈이 레이어드 아키텍처(api/ → hooks/ → components/ → screens/)를 일관되게 따르는지 — 누락된 레이어, 잘못된 위치의 파일, index.ts(Public API) 누락
- **데드 코드 식별**: 미사용 export, 미사용 의존성, 도달 불가 코드 경로 식별
- **중복 코드 감지**: 유사한 GraphQL 오퍼레이션(burial vs feed의 DeleteTombstone/AscendTombstone 중복), 유사한 컴포넌트 패턴, 반복되는 유틸리티 로직
- **의존성 건강도**: `package.json` 분석 — 미사용 패키지, 메이저 버전 뒤처진 패키지, 대체 가능한 무거운 패키지
- **파일 크기 & 복잡도**: 800줄 초과 파일, 50줄 초과 함수, 4단계 초과 중첩 — CLAUDE.md 코딩 컨벤션 위반 식별
- **Import 그래프 분석**: 순환 의존성, 레이어 위반(components가 stores를 직접 import 등), 과도한 barrel export
- **네이밍 일관성**: 파일명, 컴포넌트명, 훅명, 스토어 액션명의 네이밍 컨벤션 일관성
- **app.json 정비 상태**: 현재 "BuryIt-mobile-temp" + anonymous bundle ID — 런칭 전 필수 메타데이터 정비 항목
출력: 기술 부채 목록 (즉시 수정 / 단기 / 중기) + Feature 모듈 일관성 매트릭스 + 의존성 건강도 점수
---
## Lead Synthesis (You — Opus)
4개 에이전트가 모두 리포트를 완료하면, 최종 리포트를 `docs/research/BUR-01-audit-report.md`에 다음 내용을 포함해서 작성한다:
1. **종합 건강도 점수** — 보안/성능/테스트/아키텍처 각 영역 A~F 등급 + 종합 점수
2. **교차 영역 이슈** — 복수 에이전트가 동시에 지적한 이슈 (예: 테스트 없는 보안 코드, 성능 병목인 아키텍처 패턴)
3. **즉시 조치 목록** — Critical/High 이슈 중 1일 이내 수정 가능한 항목, 코드 예시 포함
4. **단기 개선 계획** — 1~2주 내 해결할 Medium 이슈, 우선순위순 정렬
5. **중기 리팩토링 로드맵** — Phase 1 완료 후 착수할 구조적 개선, TODO.md와 연계
6. **Feature별 성숙도 매트릭스** — 9개 feature 모듈 각각의 보안/성능/테스트/아키텍처 점수 (Mermaid 히트맵 또는 표)
7. **권고 에이전트 실행 순서** — 감사 결과 기반으로, 어떤 에이전트를 어떤 순서로 실행하여 이슈를 수정할지 제안
2. Context Engineering: 에이전트의 두뇌 설계
| 기존 방식: 프롬프트 엔지니어링 | 새로운 패러다임: 컨텍스트 엔지니어링 |
|---|---|
| 어떻게 물어볼까에 집중 | 어떤 정보를 제공할까에 집중 |
| 질문을 잘 쓰면 답이 잘 나온다 | 무엇을, 언제, 어떤 형태로 넣을지 체계적 설계 |
| 단일 상호작용 최적화 | 전체 시스템 최적화 |
- 프롬프트 엔지니어링은 끝났다. "어떻게 물어볼까"에 집중했다.
- 컨텍스트 엔지니어링은, "어떤 정보를 제공할까"에 집중
- 무엇을, 언제, 어떤 형태로 넣을지 체계적으로 설계하는 분야
예시
- "맛이는거해줘" → 프롬프트 엔지니어링
- 재료, 인원, 알레르기, 예산 알려줌 → 컨텍스트 엔지니어링
컨텍스트의 3가지 레이어
┌───────────────────┐ ┌────────────────────────┐ ┌──────────────────────────┐
│ System Context │ │ Conversation Context │ │ Tool & Environment Context│
│ 에이전트가 항상 │ │ 대화 과정에서 누적되는 │ │ 도구 실행으로 얻는 실시간 │
│ 참조하는 기본 설정 │ │ 정보 │ │ 정보 │
│ │ │ │ │ │
│ - CLAUDE.md │ │ - 이전 대화 │ │ - 파일 내용 │
│ - 프로젝트 규칙 │ │ - 실행 결과 │ │ - API 응답 │
│ - 아키텍처 문서 │ │ - 사용자 피드백 │ │ - 테스트 결과 │
│ │ │ │ │ - MCP 데이터 │
└───────────────────┘ └────────────────────────┘ └──────────────────────────┘- System Context - 에이전트가 항상 참조하는 기본 설정 → Claude.md, 프로젝트 규칙, 아키텍처 문서
- Conversation Context - 대화 과정에서 누적되는 정보 → 이전 대화, 실행 결과, 사용자 피드백
- Tool & Environment Context - 도구 실행으로 얻는 실시간 정보 → API 응답, 테스트 결과 ,MCP 데이터, 파일 내용
이 세 레이어를 어떻게 설계하느냐에 따라 컨텍스트 엔지니어링 품질이 달라짐
그럼 그냥 컨텍스트에 모든 정보 다 넣으면 되잖아? 안됨 → 비용 지연 폭발
3중 압박 — 왜 컨텍스트 설계가 중요한가
| 내용 | |
|---|---|
| 💥 비용·지연 폭발 | 컨텍스트 커질수록 비용·응답 시간 급증. 읽는 양(입력)이 답변(출력)의 100배 → 넣는 만큼 토큰 소모 |
| ⚠️ 신호 약화 (Lost-in-the-Middle) | 관련 없는 정보가 넘치면 모델이 핵심을 놓침. 중간 정보 회상률 급락 |
| 🖥️ 캐시 효율성 저하 | 같은 정보를 반복 전달하면 두 번째부터는 10분의 1 비용. 바뀌지 않는 정보를 앞에 고정 → 캐시 극대화 |
핵심 원칙: 필요한 정보만, 적시에, 적절한 형태로 제공하라
컨텍스트 엔지니어링이 가장 직접적으로 나타나는 곳이 CLAUDE.md 임
- 프로젝트 구조, 코딩 스타일, 빌드 테스트 방법을 정의해두면 에이전트가 매 세션마다 자동으로 읽고, 프로젝트 맥락을 파악한 후에 작업함
- 매번 설명 반복 불필요
3. 툴, 플러그인, MCP: 에이전트의 손과 발
3단계 계층 구조
┌──────────────────────────────────────────┐
│ Level 3 — MCP │
│ 표준 프로토콜 │
│ 모든 Tool/Plugin을 표준화된 인터페이스로 연결 │
├──────────────────────────────────────────┤
│ Level 2 — Plugin │
│ Tool 묶음 │
│ GitHub 플러그인 (PR 조회 + 생성 + 리뷰) │
├──────────────────────────────────────────┤
│ Level 1 — Tool │
│ 개별 함수 │
│ 파일 읽기, 터미널 실행, 웹 검색 │
└──────────────────────────────────────────┘- 에이전트가 실제 세계와 상호 작용하는 수단
- Tool 설계 원칙
- 최소 권한 원칙 - 에이전트에게 필요한 툴만 노출하기 (혼란 줄이기)
- 툴은 검증 가능해야함
- 툴이 실패했을때, 에이전트가 대안 경로 선택 (ex GitHub API 무응답 ⇒ 로컬 캐시 사용)
- 경계 설정 (ex. 프로덕션 DB)
- 이러한 도구들을 통해 에이전트는 GitHub 이슈 관리, Notion 페이지 생성, Slack 알림, Google 캘린더 일정 관리 가능
에이전트가 이런 도구들을 자유롭게 쓸 수 있다면, 아래와 같이 일할수있다..
MCP: 프로토콜 → ex. Gtihub mcp, ….
MCP 연결 워크플로우
[이슈 확인] → [코드 수정] → [PR 생성] → [진행 기록] → [팀 알림]
GitHub Editor GitHub Notion Slack
← 한 번의 지시로 전체 워크플로우 자동화 →4. 훅과 스킬: 에이전트 행동 제어
훅
훅은 에이전트 워크플로우의 특정 지점에서 자동으로 실행되는 인터셉터
클로드 코드 훅 실전 예시
- 파일 변경 시 → 관련 테스트 자동 실행
package.json수정 시 → 의존성 충돌 검사- 보안 관련 파일 수정 시 → 보안 리뷰 에이전트 자동 호출
- 토큰 사용량 초과 시 → 컨텍스트 압축 트리거
- 그 외: 코드 저장 전 lint 자동실행, 커밋 후 자동 테스트 실행, 보안 취약점 스캔, 비용 임계치 초과 경고
에이전트가 알아서 작업하가다도, 위험 순간에 자동으로 안전장치 작동
스킬
스킬은 에이전트가 특정 작업을 수행할 때 참조하는 베스트 프랙티스 문서 (=skill.md)
ex PPT 만들어줘 → PPT 생성 스킬이 있다면, 에이전트가 자동으로 가이드라인대로 작업함
- 현재는 수동으로 작성한 정적 skill이지만, 점점 동적 → 공유 skill로 갈 것임
훅 + 스킬 시너지 !!
- 훅이 PPT 파일 생성 감지 → 스킬이 PPT 베스트 프랙티스 자동 로드
- 훅이 보안 관련 코드 변경 감지 → 스킬이 보안 리뷰 체크리스트 자동 적용
- 훅이 API 통합 코드 작성 감지 → 스킬이 해당 API 가이드라인 자동 주입
5. 플래닝과 휴먼 인 더 루프: 인간의 감독 역할
- 에이전트를 단순한 챗봇과 구분 짓는 핵심 특성 ⇒ 계획 → 실행 → 검증 루프 !
- 계속 수정하면서 반복
- 에이전틱 엔지니어링에서 인간의 역할은 코드를 쓰는 게 아닌, 감독관임
빠르게 검증 가능한 작업(보일러플레이트, 리팩터링, 테스트 작성)은 에이전트에게 위임하고, 아키텍처 결정, 보안 민감 코드, 성능 크리티컬 로직 등은 직접 하거나 협업하는 것을 추천
에이전트 자율성 ↔ 인간 개입 수준
← 에이전트 자율성 (높음) 인간 개입 (높음) →
LEVEL 1 LEVEL 2 LEVEL 3 LEVEL 4
완전 자율 감독 위임 협업 인간 주도
─────────── ─────────── ─────────── ───────────
인간: 인간: 인간: 인간:
결과만 확인 계획 승인 후 위임 핵심 결정 개입 직접 설계·지시
에이전트: 에이전트: 에이전트: 에이전트:
계획~실행 전부 계획 + 실행 실행과 보조 구현 보조
적합한 작업: 적합한 작업: 적합한 작업: 적합한 작업:
보일러플레이트, 새 기능, 아키텍처, 성능 크리티컬,
리팩터링 버그 수정 보안 코드 신규 패턴위임 직감 키우기
내가 결과를 빠르게 검증(즉시 확인)할 수 있는가?
→ YES → 위임하세요 (보일러플레이트, 리팩터링, 테스트 작성, 버그 재현)
→ NO → 직접 or 협업 (아키텍처 결정 ,보안 민감 코드, 성능 크리티컬)
바이브코딩과 에이전틱 엔지니어링의 큰 차이는 "테스트"이다. 견고한 테스트 스위트가 있으면 AI 에이전트가 테스트가 통과할 때까지 반복할 수 있다.
이 다섯 가지 핵심 개념을 이해하고 적용하면 바이블 코딩에서 에이전틱 엔지니어링으로 진정한 레벨업이 가능하다.
