Agents (수정중)
목표 이 강의가 끝나면 학습자가
agent.md 의 frontmatter(tools·model)를 읽고, tools 화이트리스트가 왜 안전장치인지 설명하며, education 에이전트 12종의 역할과 read-only 게이트를 파악할 수 있다.FDE 세션 'Agents' 편이 개념(별도 창의 도우미)이라면, 여기선 agent.md 구조·권한·카탈로그를 코드 수준에서 본다.
1. 에이전트 = 파일 하나(agent.md)
에이전트 하나는 .claude/agents/{name}.md 파일 하나다.
frontmatter 는 스킬과 비슷하되 tools·model 이 핵심으로 더 붙는다.
---
name: spec-verifier
description: 사전 스펙과 구현이 일치하는지 검증하는 read-only 에이전트. /develop 7단계에서 호출, 미준수 시 머지 차단(BLOCKED).
tools: Read, Grep, Glob, Bash
---
| frontmatter 키 | 뜻 |
|---|---|
name |
에이전트 이름(Agent 도구로 위임할 때 지정) |
description |
언제 위임하는지(자동 위임 라우팅 키) |
tools |
쓸 수 있는 도구 화이트리스트(안전의 핵심, §2) |
model |
돌릴 모델(옵션). 예: ui-tester 는 model: sonnet |
2. tools 화이트리스트 = 권한 제한
tools 는 단순 선언이 아니라 권한 제한이다.
목록에 없는 도구는 그 에이전트가 아예 못 쓴다.
education 의 read-only 에이전트는 tools 에 Write·Edit 가 없다:
spec-verifier: 스펙↔구현 검증만. 코드를 못 고친다.lesson-finder: 교훈 색인 조회만.debug-server-log: 로그 읽어 원인 보고만.output-verifier·llm-usage-doc: 기록 결과 대조 / 코드 스캔 보고만.
이게 왜 중요한가: "read-only" 를 프롬프트 부탁이 아니라 도구 수준에서 강제한다.
검증 게이트(spec-verifier)가 코드를 못 고쳐야 게이트로서 믿을 수 있다.
3. MCP 도구까지 쥐어 준다
tools 엔 기본 도구(Read/Bash…)뿐 아니라 MCP 도구도 넣는다.
ui-tester 는 Playwright MCP 를 갖는다:
tools:
- Bash
- mcp__playwright__browser_navigate
- mcp__playwright__browser_click
- mcp__playwright__browser_take_screenshot
덕분에 실제 브라우저를 띄워 페이지를 누르고 스크린샷을 찍어 폼 동작을 e2e 로 확인한다. 에이전트 = 격리된 컨텍스트 + 딱 필요한 도구(기본 + MCP)만 쥐어 준 전문 작업자.
4. education 에이전트 카탈로그 (12종)
| 묶음 | 에이전트 | 한 줄 | read-only |
|---|---|---|---|
| 개발 게이트 | spec-verifier |
스펙↔구현 검증, 미준수 시 머지 차단 | ✅ |
merge-master |
worktree 점검 후 master 머지+정리 | ||
| 테스트 | ui-tester |
Playwright 로 UI/폼 e2e | |
api-tester |
Django test client 로 API 테스트 | ||
| 파싱 전략 | pdf-parser · excel-parser |
샘플로 text/vision 전략 결정 | |
| 조회·진단 | lesson-finder |
교훈 색인에서 관련만 선별 | ✅ |
debug-server-log |
로그부터 읽어 traceback 보고 | ✅ | |
output-verifier |
기록 결과를 소스와 3-layer 대조 | ✅ | |
| 문서·관리 | backlog-manager |
docs/backlog/ entry-per-file 관리 |
|
llm-usage-doc |
LLM 호출 스캔해 인벤토리 생성 | ✅ | |
project-intro |
코드 분석해 소개 .docx 생성 |
읽는 법은 스킬과 같다. 이름 끝 역할(-verifier/-tester/-parser/-finder/-manager)이 직무다.
이 에이전트들이 /develop 흐름의 3·7·끝 단계에 어떻게 박히는지는 ES03L01 §10 을 참고.
5. 왜 굳이 에이전트로 빼나
- 컨텍스트 격리: 지저분한 중간 과정을 메인에 안 쌓는다(
lesson-finder는 색인만 읽고 요약만 반환). - read-only 강제 게이트: 고치면 안 되는 일은
tools에서Write/Edit를 빼 구조적으로 막는다. - 병렬화: 독립적인 일을 동시에 여러 에이전트로 띄운다.
- 모델 선택: 무거운 추론이 필요 없는 일꾼은
model: sonnet으로 비용·속도를 맞춘다.
규칙: 메인을 더럽히거나, 권한을 좁혀야 안전하거나, 동시에 돌리고 싶은 일이면 에이전트로 뺀다.
마무리
- 핵심 정리: 에이전트 =
agent.md하나.tools화이트리스트가 권한을 좁혀 read-only 게이트를 도구 수준에서 강제한다. MCP 까지 넣어 브라우저도 운전한다. - 주의 사항: 필요 이상 넓은
tools를 주지 않는다. 검증용에Write를 주면 게이트가 무너진다. - 다음 시간: Prompting.