AI 드리븐

지도 위치 : 1일차 · 준비 · 에이전트 하나를 팀으로 바꾸는 장치 | 이전: 1차시 에이전트형 개발과 환경 준비 | 다음: 3차시 요구사항을 완료 기준으로 키워드 : 기억, 재사용, 격리, 검증, 강제 규칙, 외부 연결, 선택 기준

이 차시를 다 읽으면

1. 맨몸 에이전트의 여섯 가지 한계 를 말하고, 여섯 기능(기억 · 재사용 · 격리 · 검증 · 강제 규칙 · 외부 연결)과 하나씩 짝지을 수 있다.
2. 지침 파일 · 스킬 · 하위 에이전트 · 권한 설정 · 훅 · MCP 를 유와 종차로 정의할 수 있다.
3. 대화와 지침 파일을 디스크 ↔ 메모리 축에 놓고, 기억을 왜 파일에 두는지 설명할 수 있다.
4. 같은 규칙을 지침 파일에 쓰는 것과 권한 · 훅으로 막는 것의 차이를 부탁 ↔ 강제 축으로 설명할 수 있다.
5. 상황별로 어떤 기능을 쓸지 고르고, 하위 에이전트 정의 파일의 tools: 한 줄로 고칠 수 있는 역할인지 알아볼 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "에이전트 하나를 어떻게 믿을 수 있는 팀으로 만드는가" 입니다. 앞에서 배운 에이전트 루프(1차시 2절)는 혼자서도 돌지만, 잊고(축 1 · 4), 섞이고(축 3), 어기고(축 2), 폴더 밖을 못 봅니다(축 5). 여섯 기능은 이 한계들에 하나씩 대응합니다.

---

1. 맨몸 에이전트의 여섯 한계와 여섯 기능

1.1 한계와 짝

⭐ 이 과정 전체는 이 여섯 기능을 상황에 맞게 골라 쓰는 연습 입니다. 3차시부터 나오는 모든 장치가 이 표의 어느 한 줄에 속합니다.

1.2 여섯 기능은 서로 다른 범주다

여섯 기능을 "에이전트의 옵션 여섯 개"로 뭉뚱그리면 헷갈립니다. 상위 범주 가 다릅니다.

다른 에이전트 도구도 이름만 다를 뿐 같은 범주의 장치를 갖고 있습니다. 파일 위치와 정확한 문법은 버전에 따라 바뀌니 공식 문서 를 확인하세요.

---

2. 기억과 재사용 — 디스크에 두는 것

2.1 정의

지침 파일 (프로젝트 지침, CLAUDE.md) — [에이전트가 읽는 문서]인데, [ 세션을 시작할 때마다 자동으로 읽혀 모든 작업에 적용된다 ]는 점에서 해당 작업 때만 불러 쓰는 스킬과 구별된다.

스킬 (Skill) — [에이전트가 읽는 문서]인데, [ 반복되는 절차 하나에 이름을 붙여 저장해 두고 그 작업을 할 때만 불러 쓴다 ]는 점에서 늘 읽히는 지침 파일과 구별된다.

2.2 지침 파일의 모양

# CLAUDE.md
## 프로젝트
클래스온: 공방 원데이 클래스 예약 · 결제 서비스

## 명령어
- 실행: npm run dev
- 테스트: npm test

## 규칙
- API는 docs/api.md 명세를 단일 기준으로 삼는다
- 새 패키지 추가 전 반드시 사람에게 물어본다
- 금액 계산은 서버에서만 한다

## 나와 소통하는 규칙
- 나는 코드를 직접 읽지 않는다. 설명은 기능과 사용자 관점으로 한다.
- "완료"라고 말하기 전에 실행한 명령과 출력 원문을 보여준다.
- 돈, 개인정보, 데이터 삭제, 인증 · 권한, 외부 연결, 새 패키지가 관련된 변경은 맨 앞에 [위험] 표시를 하고 따로 알린다.
- 테스트, 자동 검사 설정, .claude/ 설정을 바꿨으면 반드시 알리고 이유를 말한다.
- 확실하지 않으면 추측하지 말고 "확인 필요"라고 쓴다.

🔍 읽는 포인트 : ## 나와 소통하는 규칙 아래 다섯 줄만 보면 됩니다. 1차시에서 매번 쓰던 보고 형식(증거 요구)이 여기로 옮겨져 모든 세션에 자동 적용 됩니다.

⭐ 개발자용 지침 파일에는 보통 "나와 소통하는 규칙"이 없습니다. 하지만 코드를 읽지 않고 맡기는 사람에게는 가장 효과가 큰 몇 줄 입니다.

💡 지침 파일은 짧고 구체적일수록 잘 지켜집니다. 수백 줄짜리 지침에서는 정말 중요한 규칙이 묻힙니다.

2.3 반례 — 이건 기억이 아닙니다

앞으로 다시 만납니다 — 8차시에서 "왜 이렇게 결정했는가"를 결정 기록(ADR) 파일로 남깁니다. 같은 원리입니다. 에이전트는 대화를 잊으므로, 결정의 이유도 디스크(파일)에 둡니다.

---

3. 격리와 검증 — 역할을 나누고 다른 눈으로 보기

3.1 하위 에이전트

하위 에이전트 (Subagent) — [AI 에이전트]인데, [ 역할 하나만 맡고 별도의 맥락(대화 기록)과 제한된 도구로 일한다 ]는 점에서 모든 일을 하는 메인 에이전트와 구별된다.

메인 에이전트가 일을 넘기면, 하위 에이전트가 자기 맥락에서 처리하고 결과 요약만 돌려줍니다.

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 코드 변경을 검토한다. 구현이 끝난 뒤 사용.
tools: Read, Grep, Glob
---
너는 코드 리뷰어다. 코드를 고치지 말고, 문제를 찾아 파일:줄 번호와 함께 보고만 한다.
점검 항목: 명세 일치, 입력 검증, 에러 처리, 테스트 유무.

🔍 읽는 포인트 : tools: 한 줄만 보면 됩니다. Write나 Edit이 있으면 파일을 고칠 수 있는 역할 , 없으면 읽고 보고만 하는 역할 입니다. 이 파일은 Read, Grep, Glob(읽기 · 검색 · 파일 찾기)뿐이므로 보고만 합니다.

격리로 얻는 것은 두 가지입니다.

⚠️ 0절 축 3(하나 ↔ 여럿)의 어느 쪽도 "발전된 형태"가 아닙니다. 역할을 나눌수록 넘겨줄 맥락 이 늘어납니다. 에이전트 열 개가 한 개보다 늘 낫지 않습니다(5차시).

3.2 검증

검증 — [작업 단계]인데, [ 만든 쪽이 아닌 수단으로 결과가 기준에 맞는지 판정한다 ]는 점에서 만든 쪽이 스스로 "잘 됐다"고 말하는 자기 평가와 구별된다.

앞으로 다시 만납니다 — 7차시에서 검증이 의미를 갖는 세 조건 (다른 맥락 · 제한된 권한 · 명시적 기준)을 "만드는 자 ↔ 검증하는 자" 축으로 정리합니다.

---

4. ⭐ 강제 규칙과 외부 연결

4.1 권한 설정과 훅

권한 설정 (Permissions) — [강제 장치]인데, [ 도구 · 명령 · 파일 단위로 허용(allow) · 확인 요청(ask) · 거부(deny)를 미리 정해 둔다 ]는 점에서 특정 시점에 스크립트로 검사하는 훅과 구별된다.

훅 (Hook) — [강제 장치]인데, [ 정해진 시점(도구 실행 전 · 후, 작업 종료 등)에 스크립트를 자동 실행해 검사하거나 막는다 ]는 점에서 고정된 목록으로 거르는 권한 설정과 구별된다.

// .claude/settings.json (개념 예시 — 정확한 규칙 문법은 공식 문서 확인)
{
  "permissions": {
    "deny": ["Read(./.env)", "Bash(rm -rf:*)"]
  }
}

🔍 읽는 포인트 : deny 목록만 보면 됩니다. .env(비밀값을 담는 파일) 읽기와 rm -rf(폴더째 삭제)가 막혀 있다 는 뜻입니다.

⚠️ 권한 규칙은 도구 단위 로 걸립니다. 같은 파일을 다른 도구(예: 터미널 명령)로 읽는 길까지 막히는지는 도구와 버전에 따라 다릅니다. 그래서 막았다고 믿지 말고 직접 시험 합니다(5절 실습).

4.2 부탁 ↔ 강제 — 같은 규칙, 세 가지 자리

".env 파일을 읽지 마"라는 같은 규칙을 어디에 두느냐에 따라 성격이 완전히 달라집니다.

README 6장의 사다리로 놓으면 이렇습니다.

약함 ◀──────────────────────────────────────────────▶ 강함
 프롬프트로 부탁  →  지침 파일(기억)  →  권한 제한  →  훅 · 커밋 검사  →  자동 검사 관문

🔍 읽는 포인트 : 왼쪽 두 칸은 부탁, "권한 제한"부터 오른쪽이 강제입니다. 오른쪽으로 갈수록 AI가 어길 수 있는 여지가 줄어듭니다.

⭐ 판단 기준은 하나입니다. 한 번이라도 어기면 사고가 나는 규칙 (데이터 삭제, 비밀값, 결제, 배포)은 오른쪽에 둡니다.

⭐ 코드를 읽어서 실수를 잡는 사람에게 강제 장치는 "있으면 좋은 것"입니다. 코드를 읽지 않는 사람에게는 코드 읽기 능력의 대체재 입니다(README 9.1의 신뢰 근거 ①). 여섯 기능 중 검증과 강제 규칙 에 가장 많이 투자해야 하는 이유입니다.

앞으로 다시 만납니다 — 12차시(데이터 파괴 방지), 14차시(위반 차단), 18차시(커밋 검사), 19차시(자동 검사 관문)가 이 사다리의 각 칸입니다.

4.3 외부 연결 — MCP

MCP (Model Context Protocol) — [연결 규격]인데, [ 외부 시스템(DB, 브라우저, GitHub 등)을 에이전트가 쓸 수 있는 도구로 내놓는 표준 ]이라는 점에서 서비스 하나만을 위한 전용 연동과 구별된다.

⚠️ MCP 서버를 연결한다는 것은 에이전트에게 그 시스템의 권한을 주는 것 입니다. DB라면 처음엔 읽기 전용 계정 으로 연결합니다(되돌릴 수 있는가 축).

---

5. 선택 기준과 클래스온

5.1 언제 무엇을 쓰나

💡 처음부터 다 만들지 마세요. 기억(지침 파일) 하나로 시작해서, 같은 실수가 반복되면 그때 재사용이나 강제 규칙으로 올립니다.

5.2 클래스온에 적용하면

과정이 끝날 무렵 저장소는 대략 이런 모습이 됩니다.

classon/
├── CLAUDE.md                 # 기억
├── docs/                     # 기획 · 설계 산출물 (3~8차시)
├── .claude/
│   ├── agents/               # 격리: planner, designer, design-reviewer, backend, ...
│   ├── skills/               # 재사용
│   ├── hooks/                # 강제 규칙 스크립트
│   └── settings.json         # 권한, 훅 등록
├── .mcp.json                 # 외부 연결
└── .github/workflows/        # 검증 · 강제의 최종 관문 (19~20차시)

🔍 읽는 포인트 : 각 줄 오른쪽 주석이 1.1 표의 어느 기능인지만 보면 됩니다.

💡 비유는 마지막에 — 기억은 팀 위키, 재사용은 업무 매뉴얼, 격리는 담당자를 따로 두는 것, 검증은 QA, 강제 규칙은 출입 통제 게이트, 외부 연결은 사내 시스템 접근권입니다.

---

6. 실습 — 맡기고 검수하기

세 가지 기능(기억 · 격리 · 강제 규칙)을 하나씩 세우고, 각각이 정말 작동하는지 행동으로 확인합니다.

지시

classon/ 프로젝트에 아래 세 가지를 만들어줘.
1. CLAUDE.md: 프로젝트 한 줄 소개, 규칙 3개(API는 docs/api.md가 기준, 새 패키지는 먼저 물어봄,
   금액 계산은 서버에서만), "나와 소통하는 규칙" 5줄(이 노트 2.2절과 같은 내용)
2. .claude/agents/code-reviewer.md: 읽기 전용 리뷰어. tools에는 Read, Grep, Glob만.
3. .claude/settings.json: .env 읽기와 rm -rf를 deny에 넣기.
.claude/settings.json을 만들거나 바꾸기 전에는 바꿀 내용을 먼저 보여주고 내 승인을 받을 것.
보고: [만든 파일 | 핵심 내용 한 줄 | tools 또는 deny에 들어간 것] 표 + 각 파일 내용 원문.

받을 증거

• 세 파일의 내용 원문
• code-reviewer.md의 tools: 줄, settings.json의 deny 목록

내가 직접 확인할 것

⚠️ .env에는 진짜 비밀값을 절대 넣지 마세요. 시험용 가짜 값(TEST=hello)이면 충분합니다.

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 2차시 노트만 근거로 6문제를 내줘. 코드를 모르는 사람 기준으로.
"여섯 한계와 여섯 기능 짝짓기", "지침 파일 vs 스킬", "부탁 ↔ 강제의 세 자리", "tools 한 줄 읽기"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.