📚 FDE · 세션 · 에이전틱 개발 · L04

Agents

작성일자 2026-06-28 · 수정일자 2026-08-05 · 강의차수 L04 · 예상소요 15분

목표 이 강의가 끝나면 학습자가 에이전트가 "큰 일을 통째로 맡아 딴 방에서 대신 처리하는 별도 도우미(격리된 창)"임을 이해하고, 실제 프로젝트에서 agent.md 한 장으로 어떻게 만들고, 어떻게 불러 쓰는지 설명할 수 있다.

1. 에이전트란?

에이전트는 큰 일을 통째로 맡아, 자기만의 창에서 대신 처리하고 결과만 가져오는 별도 도우미입니다.

예를 들어 "이 일을 어떻게 진행할지 계획 세워줘"라고 맡기면, 에이전트는 자기 방에서 관련 자료를 다 살펴보고 "이렇게 5단계로 진행" 같은 계획만 가져옵니다. 지저분한 중간 과정이 이 대화에 쌓이지 않습니다.

Q. 에이전트가 살펴본 자료가 내 대화에도 쌓이나요?

A. 아니요. 그 과정은 에이전트의 창에만 남고, 이 대화에는 결론 한 줄만 돌아옵니다.

에이전트란, 별도 창에서 한 가지 일을 하고 결론만 돌려주는 도우미.

2. 에이전트 만들기

에이전트는 프로젝트의 .claude/agents/ 폴더에 모여 있습니다. 파일 하나가 에이전트 하나이고, 파일 이름이 곧 에이전트 이름입니다. 어떤 에이전트가 있는지는 이 폴더의 각 .md 맨 위 description 한 줄로 확인합니다.

새 에이전트가 필요하면 여기에 .md 하나를 추가합니다. 스킬과 달리 폴더 없이 파일 하나입니다.

.claude/agents/
├── plan.md         ← 목표를 단계별 계획으로
├── research.md     ← 자료 조사해서 요약
└── translate.md    ← 문장 번역

---
name: plan
description: 목표를 받아 실행 단계 계획을 세워 보고하는 읽기 전용 에이전트. 어떻게 진행할지 계획이 필요할 때 사용하세요.
tools: Read
---

# 실행 계획

목표를 잘게 나눠 단계별 계획으로 정리합니다.

## 작업 절차

1. 목표와 조건을 파악한다.
2. 해야 할 일을 순서대로 단계로 나눈다.
3. 각 단계에 필요한 것과 주의점을 적어 보고한다.

**반드시**:
- 계획만 세우고 실제로 실행하지 않는다.
- 불확실한 부분은 추측하지 말고 표시한다.

에이전트 파일도 스킬(SKILL.md)처럼 4개 영역으로 되어 있습니다. 다른 점은 frontmatter 에 tools 한 줄이 있다는 것뿐입니다.

frontmatter: name·description 은 필수, 나머지는 선택.
# 제목: 에이전트 이름과 한 줄 소개.
## 작업 절차: Claude 가 따라 할 단계.
**반드시**: 꼭 지켜야 할 규칙.

항목	필수	무엇
`name`	필수	에이전트 이름(파일명과 같게).
`description`	필수	언제 맡기는 에이전트인지. Claude 가 이 줄을 보고 고릅니다.
`tools`	선택	이 에이전트가 쓸 수 있는 도구. 좁힐수록 안전합니다.
`model`	선택	사용할 모델(가벼운 일은 가벼운 모델로).

이 예시에서는 tools 에 읽기(Read) 권한만 주고 쓰기·수정(Write·Edit) 권한은 뺐습니다. 그러면 이 에이전트는 계획만 세우고 파일은 못 건드리는 기획 전용이 됩니다. 하지 말라는 부탁이 아니라 도구 자체를 주지 않은 것이라, 계획을 짜다 실수로 파일을 바꾸는 사고가 구조적으로 불가능합니다.

3. 에이전트 사용 방법

직접 @.claude/agents/plan.md 를 입력하여 에이전트를 호출하거나, 자연어로 "진행 계획 세워줘"처럼 입력하면 Claude 가 각 에이전트의 description 을 보고 알맞은 에이전트를 골라 맡깁니다.

주로 이럴 때 맡깁니다.

자료가 많아 대화가 무거워질 때(긴 로그, 검색 결과).
권한을 좁혀야 안전할 때(읽기만 하는 조사·검토).
다른 일과 동시에 돌리고 싶을 때.

4. 팀·도구 공유

에이전트도 .claude/agents/ 아래에 있어, git 저장소에 올리면 팀원 모두가 같은 에이전트를 내려받고, 누가 고치면 수정된 에이전트를 팀 전체가 함께 씁니다. 조사·검토 방식을 한 번 잘 정해 두면, 팀이 같은 에이전트를 똑같이 쓰는 셈입니다. 다만 에이전트는 스킬과 달리 공개 표준이 아니라 Claude Code 전용 형식이라, Codex 같은 다른 AI 도구는 이 파일을 그대로 읽지 못할 수 있습니다.

5. 스킬과의 차이

스킬은 이 대화 "안에서" 정해진 절차를 따르고, 에이전트는 딴 방에서 대신 하고 결과만 가져옵니다.
스킬이 에이전트를 부르기도 합니다. 절차 도중 무거운 일이 나오면 그 부분만 에이전트에게 넘깁니다.

6. 에이전트 목록 (standarda-template, 2026-08-06)

에이전트	자연어	설명
`ui-tester`	"화면 동작 테스트해줘"	브라우저로 화면·폼 동작 확인
`api-tester`	"이 API 잘 되는지 봐줘"	Django API 엔드포인트 테스트
`debug-server-log`	"에러 원인 봐줘"	서버 로그에서 오류 원인 조사 (읽기 전용)
`spec-verifier`	"스펙대로 됐는지 확인해줘"	코드가 사전 스펙과 일치하는지 검증
`pdf-parser`	"이 PDF 어떻게 읽을지 정해줘"	PDF 파싱 전략 결정 (텍스트 vs Vision)

에이전트의 심화 내용은 엔지니어 세션 Agents에서 다룹니다.

마무리

핵심 정리: 에이전트는 별도 창에서 한 가지 일을 대신 처리하고 결론만 돌려줍니다. 실제로는 .claude/agents/<이름>.md 파일 하나이고, tools 로 쓸 도구를 좁혀 안전을 도구 수준에서 강제합니다. Claude 가 알아서 부르거나 내가 지정해 씁니다.
주의 사항: 에이전트에게 필요 이상으로 넓은 도구를 주지 않습니다. 검토용에 고치는 도구를 주면 "검토하다 고치는" 사고가 열립니다.
다음 시간: 훅. 스킬·에이전트가 "하기로 한 것"이라면, 훅은 "안 하면 자동으로 막는 것"입니다.

이 강의를 학습하셨나요?