[TIL] 에이전틱 엔지니어링

• 해당 글은 2026년 3월 12일 기준으로 작성되었으며, AI 발전 속도로 봤을 때 deprecated될 수 있는 내용이 포함되어 있습니다.

무엇을 위한 글인가

Karpathy가 "코드 직접 타이핑하는 시대는 끝났다"고 선언했다. 하지만 끝난 건 타이핑이지, 엔지니어링이 아니다. 오히려 에이전트가 잘 작동하는 조건을 설계하는 능력이 더 중요해졌다. 많은 분들이 이미 적용하고 계시거나 더 고도화 하는 부분이 많겠지만, 최근에 여러 툴들을 사용해보면서 개념적으로 하나 남겨두면 좋을 것 같아 가볍게 정리해두려고 한다.

이 글은 두 가지를 살펴본다.

1. 도구와 개념 - 뭐가 있고, 어떻게 셋업하는가
2. 에이전틱 엔지니어링 - 이 도구들을 어떻게 써야 효과적인가

Part 1. 먼저, 에이전트가 뭔데?

AI Chatbot vs AI Agent

챗봇은 대화한다. 에이전트는 일한다.

Claude Code, Cursor, Cline 같은 도구들은 LLM을 에이전트로 동작시킨다. 파일을 읽고, 코드를 수정하고, 터미널에서 명령을 실행하고, 결과를 보고 다시 판단한다. 이 "컨텍스트 수집 → 행동 → 결과 검증"의 루프가 에이전트의 핵심이다.

에이전트의 구성 요소

┌───────────────────────────────────┐
│            AI Agent               │
├───────────┬───────────┬───────────┤
│  Context  │   Tools   │  Memory   │
│   (입력)   │   (행동)   │   (기억)   │
│           │           │           │
│ CLAUDE.md │ MCP Server│ Auto Mem  │
│ codebase  │ Skills    │ MEMORY.md │
│ history   │ Hooks     │ Compact   │
│ Rules     │ Bash/Edit │           │
└───────────┴───────────┴───────────┘
        ↕          ↕          ↕
    뭘 아는가   뭘 할 수 있는가  뭘 기억하는가

이 세 축을 얼마나 잘 설계하느냐가 에이전트의 성능을 결정한다.

Part 2. 도구 셋업 - 컨텍스트 편

CLAUDE.md - AI에게 주는 인수인계서

CLAUDE.md는 매번 새로 만나는 AI에게 주는 브리핑 문서라고 할 수 있다. 세션 시작 시 자동으로 로드되고, 명령어 실행, 코드 수정, 도구 사용 등 모든 작업에서 이 가이드라인들을 실시간으로 참조한다. 프로젝트 맥락과 선호를 전달해서 에이전트의 행동을 유도하는 역할이다.

어디에 두나

~/.claude/CLAUDE.md          ← 모든 프로젝트 공통 (개인 취향)
프로젝트루트/CLAUDE.md          ← 이 프로젝트 전용
프로젝트루트/src/CLAUDE.md      ← 하위 디렉토리 전용 (더 높은 우선순위)
.claude/rules/               ← 카테고리별 규칙 파일

우선순위: 하위 디렉토리 > 프로젝트 > 개인 구체적인 게 이긴다.

뭘 써야 하나

# CLAUDE.md
 
## 빌드 & 실행
- pnpm dev로 개발 서버 실행
- pnpm test -- --watch로 테스트
 
## 코드 컨벤션
- 컴포넌트는 named export
- 스타일은 Tailwind만 사용, CSS 파일 금지
- 커밋 메시지는 conventional commits
 
## 아키텍처 결정
- 상태관리: Zustand (Redux 아님)
- 날짜: dayjs (date-fns 아님)
- 폼: react-hook-form + zod

이처럼, 개발 워크플로 (특정 명령어 순서, 테스트 실행 규칙) / 코딩 스타일 (네이밍 컨벤션, 파일 구조, import 방식) / 보안 정책 (접근 금지 파일, 민감 정보 처리 방법) / 도구 사용법 (특정 라이브러리나 프레임워크 사용 규칙) / 프로젝트별 특수 규칙 (배포 절차, 리뷰 프로세스 등) 등의 내용들을 담을 수 있다. 다만, Claude의 근본적인 안전 정책은 오버라이드 할 수 없고, 물리적으로 불가능한 작업은 지시해도 소용이 없다. 또한 너무 복잡하거나 모호한 규칙은 제대로 따르지 못할 수 있다.

핵심 원칙

• 200줄 이하로 유지 - 길어질수록 규칙 준수율이 떨어진다
• 결정 사항을 쓰자 - package.json 보면 알 수 있는 건 안 써도 됨
• "왜" 를 쓰자 - "Zustand 사용" 보다 "Zustand 사용 (번들 크기, Redux 대비 보일러플레이트 감소)"
• /init으로 초기 파일 자동 생성 가능

Auto Memory

Claude가 스스로 학습한 내용을 기록하는 기능. ~/.claude/projects/ 아래에 자동 저장된다.

• 빌드 커맨드, 디버깅 패턴, 코드 스타일 등을 세션에서 배우면 자동으로 메모
• /memory 명령으로 확인 및 편집
• 매번 같은 말 반복할 필요 없어짐

Context Compression - 토큰 다이어트

AI 에이전트 비용의 대부분은 컨텍스트 토큰이다. 대화가 길어질수록 매 턴마다 전체 히스토리를 다시 읽기 때문이다.

/compact    ← 현재 대화를 구조화된 요약으로 압축

• 분석 내용, 수정한 파일, 남은 작업을 구조화된 형태로 요약
• 컨텍스트가 꽉 차면 자동으로도 작동
• 체감상 비용 50% 이상 감소 가능

Part 3. 도구 셋업 - 도구 편

MCP (Model Context Protocol) - AI의 USB-C

Anthropic이 2024년 11월에 공개한 오픈 프로토콜 이다. AI가 외부 도구/데이터에 접근하는 방식을 표준화한다. 2025년 3월에 OpenAI도 공식 채택했고, 사실상 업계 표준이 되었었다. (최근엔 MCP는 끝났다.. 뭐 이런 얘기도 있지만)

AI Agent ←── MCP Protocol ──→ MCP Server ──→ DB / API / File / etc.

셋업 예시

// .claude/settings.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

주요 MCP 서버들

75개 이상 존재하고, 직접 만들 수도 있다.

Skills & Plugins - AI의 기술 트리

Skills

특정 작업을 위한 프롬프트 패키지, 반복되는 지시를 재사용 가능한 형태로 만든 것

~/.claude/skills/           ← global 적용 
.claude/skills/             ← 프로젝트 스킬

스킬 예시:

<!-- .claude/skills/review/SKILL.md -->
---
name: review
allowed-tools: [Read, Grep, Glob]
---
 
# 코드 리뷰 스킬
 
## 체크리스트
1. 타입 안정성 확인
2. 에러 핸들링 누락 체크
3. 성능 이슈 (N+1, 불필요한 리렌더링)
4. 보안 취약점 (XSS, injection)
 
## 출력 형식
- 심각도: Critical / Warning / Suggestion
- 파일:라인 형태로 위치 표시

/review를 입력하면 이 지침이 로드되어 코드 리뷰를 수행한다.

Plugins & Marketplace

Plugin = Skills + Hooks + Agents + MCP 서버 + Commands를 하나로 묶은 패키지다. npm 패키지처럼 설치/관리/배포할 수 있다. (필요한 것 골라서 넣으면 됨)

/plugin                              # 플러그인 매니저 (인터랙티브 UI)
/plugin install plugin-name@market   # 설치
/plugin uninstall plugin-name@market # 제거

Marketplace는 플러그인들의 카탈로그다. Anthropic 공식 마켓플레이스가 기본 제공되고, 직접 마켓플레이스를 만들어서 팀/커뮤니티에 배포할 수도 있다.

# 마켓플레이스 추가
/plugin marketplace add anthropics/claude-code       # GitHub 레포
/plugin marketplace add https://gitlab.com/team/mp   # GitLab
/plugin marketplace add ./local/path                 # 로컬
 
# 마켓플레이스 목록 확인
/plugin marketplace list

플러그인은 문맥에 따라 자동으로 호출되고, 혹은 명시적으로 플러그인을 호출할 수도 있다.

플러그인 안에 뭐가 들어가나?

나만의 플러그인 만들기 - 디렉토리 하나가 곧 플러그인이다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 매니페스트 (이름, 버전, 설명)
├── skills/
│   └── review/
│       └── SKILL.md         # /my-plugin:review 로 호출
├── agents/
│   └── reviewer.md          # 서브에이전트 정의
├── hooks/
│   └── hooks.json           # 이벤트 자동화
├── .mcp.json                # MCP 서버 설정
└── README.md

매니페스트 예시

// .claude-plugin/plugin.json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "우리 팀 개발 워크플로우 자동화",
  "skills": "./skills/",
  "agents": "./agents/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}

로컬에서 테스트

claude --plugin-dir ./my-plugin    # 이 플러그인 로드해서 세션 시작
/reload-plugins                    # 수정 후 재로드 (재시작 불필요)

나만의 마켓플레이스 만들기

팀/커뮤니티에 플러그인을 배포하고 싶으면 마켓플레이스 레포를 만들면 된다.

// .claude-plugin/marketplace.json
{
  "name": "my-team-marketplace",
  "owner": { "name": "My Team" },
  "plugins": [
    {
      "name": "fe-toolkit",
      "source": "./plugins/fe-toolkit",
      "description": "프론트엔드 개발 도구 모음",
      "version": "1.0.0"
    },
    {
      "name": "api-review",
      "source": {
        "source": "github",
        "repo": "my-org/api-review-plugin",
        "ref": "v2.0.0"
      },
      "description": "API 코드 리뷰 자동화"
    }
  ]
}

이걸 GitHub에 올리면 팀원들은 한 줄로 설치한다. (아래는 예시)

/plugin marketplace add my-org/my-team-marketplace
/plugin install fe-toolkit@my-team-marketplace

소스 종류: 로컬 경로, GitHub, GitLab, Git URL, npm 패키지, pip 패키지 모두 지원한다.

설치 범위 (Scope)

핵심은, 플러그인은 흩어져 있는 설정 파일을 하나로 모아준다는 것이다. 팀 컨벤션, 리뷰 규칙, MCP 연결 등을 플러그인 하나로 묶어서 적용할 수 있다.

마켓플레이스 → 플러그인, 실제 동작 흐름

전체 흐름을 세 단계로 나누면 이렇다.

1. marketplace add     →  marketplace.json만 가져옴 (카탈로그 등록)
2. plugin install      →  source 찾고 → 실제 코드 fetch → 캐시에 저장
3. 세션 시작             →  캐시에서 plugin.json 읽고 → 컴포넌트 로드

1단계 - 마켓플레이스 추가

/plugin marketplace add owner/repo를 실행하면, 레포 전체를 클론하는 게 아니다. .claude-plugin/marketplace.json 파일만 가져와서 카탈로그로 등록한다. 앱스토어를 추가한 것과 같고, 아직 아무것도 설치되지 않은 상태다.

2단계 - 플러그인 설치

/plugin install plugin-name@marketplace를 실행하면 이런 순서로 진행된다.

1. marketplace.json에서 해당 플러그인의 source 필드를 읽는다
2. source 타입에 따라 실제 코드를 가져온다
   • GitHub repo → 클론
   • npm 패키지 → 레지스트리에서 다운로드
   • 로컬 경로 → 복사
3. ~/.claude/plugins/cache/에 캐싱한다 (원본이 아닌 캐시에서 실행)
4. settings.json의 enabledPlugins에 등록한다

3단계 - 런타임 로드

세션이 시작되면 settings에서 활성화된 플러그인 목록을 확인하고, 캐시에서 plugin.json을 읽어 컴포넌트를 자동으로 발견한다.

• Skills → /plugin-name:skill-name으로 호출 가능
• Hooks → 이벤트 발생 시 자동 실행
• MCP/LSP 서버 → 자동 시작
• Agents → 필요할 때 서브에이전트로 호출

마켓플레이스의 marketplace.json은 각 플러그인의 source 필드로 실제 코드 위치를 가리킨다. 외부 레포를 가리킬 수도 있고, 마켓플레이스 레포 안에 플러그인 코드를 같이 넣어둘 수도 있다.

marketplace.json
├── plugin-A → source: github.com/org/plugin-a     (외부 GitHub 레포)
├── plugin-B → source: npm @org/plugin-b            (npm 패키지)
└── plugin-C → source: ./plugins/plugin-c           (이 레포 안에 포함)

참고로, 1단계에서 카탈로그로 등록한다는 건 Claude Code 내부에 이 마켓플레이스의 위치를 저장해두는 것이다. 그래서 /plugin UI의 Discover 탭에서 해당 마켓플레이스의 플러그인 목록이 보이게 된다.

자동 업데이트

세션 시작 시 plugin.json의 version 필드를 비교한다. 버전이 바뀌었으면 자동 업데이트 후 /reload-plugins 알림이 뜬다. 코드만 바꾸고 버전을 안 올리면 업데이트가 감지되지 않으니 주의하자.

Hooks - 이벤트 기반 자동화

Claude Code 라이프사이클에 끼어드는 자동화.

이 외에도 Notification, Stop 등 20개 이상의 훅 이벤트가 존재한다. 전체 목록은 공식 문서에서 확인할 수 있다.

실용적인 예시 - 파일 수정 시 자동 포맷:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write \"$CC_EDIT_FILE_PATH\""
      }
    ]
  }
}

Subagents - 병렬로 처리하자!

복잡한 작업을 별도 컨텍스트에서 병렬 처리하는 서브 에이전트

메인 대화에서 파일 100개를 읽으면 컨텍스트가 터진다. Subagent에게 위임하면,

• 메인 컨텍스트를 깨끗하게 유지
• 여러 조사를 병렬 수행
• 결과만 요약해서 돌려받음

종류

• Explore - 코드베이스 탐색
• Plan - 구현 전략 설계
• General-purpose - 복잡한 멀티스텝 작업

대표적 도구들 - Serena (시맨틱 코드 이해)

Serena는 코드를 텍스트가 아닌 심볼 단위로 이해하는 MCP 서버다.

grep "handleSubmit" → 텍스트 매칭 (주석, 문자열도 걸림)
Serena           → 심볼 레벨 탐색 (함수 정의, 참조, 타입 추적)

• 30개+ 언어 지원 (LSP 기반)
• 대규모 리팩토링에 강력
• Claude Code, Cursor, Cline 등과 MCP로 연결
• 무료 오픈소스

대표적 도구들 - OpenCode (오픈소스 대안)

OpenCode는 Claude Code의 오픈소스 대안.

2026년 1월부터 GitHub Copilot 인증도 지원한다.

Part 4. 에이전틱 엔지니어링 - 잘 쓰는 법

도구를 설치하는 것과 잘 쓰는 것은 완전히 다른 문제다.

1. 분해 능력 - 에이전트가 삼킬 수 있는 크기로 쪼개라

에이전트에게 "이 앱 만들어줘"라고 하면 쉽지 않다. 파일 3개에서 5개, 15분에서 30분 내 완료 가능한 단위로 쪼개야 한다.

Bad: "회원가입 기능 만들어줘"

Good:

1. POST /api/auth/signup 엔드포인트 만들어줘 (이메일, 비밀번호, zod 검증)
2. 회원가입 폼 컴포넌트 만들어줘 (react-hook-form, 에러 표시)
3. 회원가입 성공 시 로그인 페이지로 리다이렉트 + 토스트 메시지

쪼갤수록 에이전트의 성공률이 올라간다. 이건 팀원에게 일을 시키는 것과 같은데, 명확한 명세와 검증 기준이 있어야 좋은 결과가 나온다.

2. 컨텍스트 설계 - 코드 구조가 곧 프롬프트다

에이전트는 코드를 읽고 패턴을 파악한다. 코드 구조가 정돈되어 있으면 에이전트도 정돈된 코드를 쓴다.

# 에이전트가 헤매는 구조
src/
  components/
    stuff.tsx         ← 뭐가 뭔지 모름
    utils.ts          ← 온갖 게 섞여있음
    page-thing.tsx
 
# 에이전트가 바로 파악하는 구조
src/
  components/
    auth/
      login-form.tsx
      signup-form.tsx
    ui/
      button.tsx
      input.tsx

디렉토리 조직화, 네이밍 통일, 관심사 분리가 잘 되어 있으면 에이전트에게 별도 설명이 필요 없다. 코드 구조 자체가 컨텍스트가 된다.

3. 완료 정의 (DoD) - "됐다"의 기준을 명확히

에이전트의 고질적 문제: 스텁만 남기고 "완료" 보고, 테스트를 자기 편하게 수정.

작업을 줄 때 반드시 완료 기준을 포함하자.

## 요구사항
- POST /api/users 엔드포인트
 
## 완료 기준 (DoD)
- [ ] zod 스키마로 입력 검증
- [ ] 중복 이메일 409 응답
- [ ] 성공 시 201 + 유저 객체 반환
- [ ] 기존 테스트 깨지지 않음
- [ ] TODO/FIXME 없음

4. 실패 복구 - 같은 프롬프트 재시도는 효과 없다

에이전트가 실패하면 원인을 분류하자.

핵심: 실패의 원인에 맞는 처방을 내려야 한다. "다시 해봐"는 답이 아니다.

5. 관찰 가능성 - 예광탄 전략

큰 작업을 바로 전체에 적용하지 말자. 작은 범위에서 먼저 시험하고, 검증된 패턴을 확산한다.

1단계: 한 컴포넌트에 다크모드 적용 → 검증
2단계: 검증된 패턴을 블루프린트로 기록
3단계: 나머지 컴포넌트에 블루프린트 적용

단계별 커밋으로 롤백 포인트를 확보하는 것도 중요하다. 에이전트가 3단계에서 망쳐도 2단계로 돌아갈 수 있다.

6. 메모리 설계 - 세션이 끊겨도 맥락은 이어져야

<!-- MEMORY.md -->
## 2026-03-12
- [결정] 인증은 JWT + httpOnly cookie 방식으로
- [작업] signup API 완성, login API 진행 중
- [이슈] refresh token 로테이션 미구현

이런 기록이 있으면 다음 세션에서 맥락 복원에 5초면 충분하다. 없으면 매번 처음부터 설명해야 한다. Hooks로 세션 종료 시 자동으로 메모리를 추출하는 것도 가능하다.

7. 병렬 관리 - 에이전트 여러 개 동시에

여러 에이전트를 동시에 돌리는 건 팀 매니징과 같다.

핵심은 컨텍스트 분리

• 에이전트 A: 프론트엔드 컴포넌트
• 에이전트 B: API 엔드포인트
• 에이전트 C: 테스트 작성

8. 추상화 - 반복을 자산으로

매번 반복되는 지시가 있다면, 그건 스킬/템플릿으로 만들어야 할 신호다.

Level 0: 직접 코딩
Level 1: 에이전트에게 지시
Level 2: 스킬/템플릿으로 자동화
Level 3: 에이전트가 스킬을 선택하는 메타 설계

이전 세션의 결과물이 다음 세션에 복리로 쌓인다. 이것이 컴파운딩 엔지니어링이다.

9. 감각 (Taste)

"AI는 평균적인 80%는 잘한다. 나머지 20%의 차별화는 인간의 영역이다."

에이전트가 만든 코드는 "동작한다". 하지만 "동작한다"와 "훌륭하다"는 다르다.

• 이 버튼이 여기 있는 게 맞나?
• 이 에러 메시지가 사용자에게 친절한가?
• 이 추상화가 과한 건 아닌가?

이런 판단은 도메인 지식과 경험에서 나온다. 이 맥락을 잘 전달할 수 있도록 하면 좋을 것 같다.

Part 5. IDE별 AI 설정 파일

AI 코딩 도구마다 프로젝트 규칙 파일이 있다. 역할은 전부 같다. "이 프로젝트에서 AI는 이렇게 행동해라." 라고 명시해두는 파일이다.

팀에서 여러 도구를 쓴다면, 핵심 규칙을 하나 작성하고 각 파일로 복사/심링크하는 전략이 실용적일지도!

Part 6. 실전 체크리스트

지금 당장

• CLAUDE.md 작성 - 빌드 명령, 컨벤션, 아키텍처 결정
• 200줄 이하로 유지, 결정 사항 중심
• 자주 쓰는 서비스 MCP 서버 연결

습관으로

• 작업 전 requirements + DoD 정의
• 대화 길어지면 /compact
• 큰 조사는 서브에이전트에 위임
• Hooks로 포맷터/린터 자동화
• 단계별 커밋으로 롤백 포인트 확보
• 30분 안에 진전 없으면 방향 전환

더 나아가서

• 반복 작업은 Custom Skill로
• Serena 연결해서 시맨틱 코드 탐색
• 병렬 에이전트 운용 (2개부터 시작)
• MEMORY.md로 세션 간 맥락 이어가기
• 팀 워크플로우를 플러그인으로 묶어서 배포
• claude --plugin-dir로 로컬 플러그인 테스트

마무리

최근에는 AI 코딩은 에이전트가 잘 작동하는 환경을 설계하는 것이라는 생각이 든다.

CLAUDE.md로 컨텍스트를 주고, MCP로 도구를 연결하고, Skills로 반복을 자동화하고, Hooks로 품질을 보장한다. 그리고 작업을 적절히 쪼개고, 완료 기준을 명확히 하고, 실패하면 원인별로 처방한다.

에이전트를 부리는 감각을 좀 더 고도화 해보자. 그 감각은 결국 경험에서 오는 것 같아서, 많이 시키고, 많이 실패하고, 패턴을 익혀봐야 겠다.