# Lesson 07 Debugging

> AI 에이전트 강의 패키지의 7강 — 비개발자가 에이전트가 왜 안 되는지 진단하는 체크리스트를 익히고, 본인이 최근 막힌 사례 1개를 직접 진단할 때 사용하는 30분 대화형 강의. 5가지 흔한 실패 패턴 / 10개 진단 질문 / 고립과 재현 흐름을 한 청크씩 익힌다. 기초 트랙 마지막 강의로, 종료 시 심화 트랙 진입 분기를 제공한다. 사용자가 "7강 시작", "디버깅", "에이전트가 이상해요", "왜 안 되지", "진단 도와줘", "에러", "막혔어요", "안 돌아가요" 같은 표현을 쓰거나, 6강 끝난 후 자연스럽게 이어지는 강의에 진입하려 할 때 반드시 이 스킬을 사용한다. 단순 디버깅 도움이 아니라, 한 청크씩 게임처럼 진행되는 30분짜리 가이드형 학습 흐름이라는 점이 핵심이다.

- Skill: `matthewoong/lesson-07-debugging` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add matthewoong/lesson-07-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matthewoong/lesson-07-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Matthewoong (https://skillmd.com/u/matthewoong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/matthewoong/lesson-07-debugging

---


# Lesson 07 — 에이전트 디버깅 (기초 트랙 마지막)

> 학습자가 끝나면 에이전트의 실패를 *진단하는 체크리스트*를 익히고, 본인이 최근 막힌 사례 1개를 직접 진단해본다.

이 스킬은 *대화형 강의*이자 **기초 트랙의 마지막 강의**입니다. 종료 시점에 학습자에게 *심화 트랙 진입 여부*를 묻는 분기가 추가됩니다.

---

## 0. 시작하기 전에

| 문서 | 언제 |
|---|---|
| `_shared/teaching-protocol.md` | 이론 청크 |
| `_shared/guided-practice-protocol.md` | 가이드 실습 |
| `_shared/learner-profile-schema.md` | 진도·draft·**트랙 분기** |
| `_shared/style-guide.md` | 톤·분기·예시 |
| `_shared/menu-template.md` | 메뉴·**트랙 전환 분기** |

---

## 1. 진입 시 행동

1. 학습자 프로필 확인.
2. `progress["07-debugging"].status` 분기.
3. 1~6강 미수강 시 한 번 안내.
4. 첫 인사 + **"기초 트랙 마지막 강의예요. 끝까지 가시면 ✅ 기초 트랙 완주!"** 격려.
5. 이론 진입. 헤더 `📘 [Lesson 7 · 청크 X/Y]`.
6. 이론 끝 → 가이드 실습 (옵션 2개 인라인).
7. 실습 종료 → **🎓 기초 트랙 완주 분기** (`_shared/menu-template.md`의 트랙 전환 분기 호출).

---

## 2. 진도 갱신 + draft 키 명세

| 시점 | 갱신 |
|---|---|
| 7강 첫 진입 | `status = "in_progress"`, `current_chunk = 1` |
| 청크 통과 | `current_chunk += 1` |
| 청크 3 답변 | `draft.recent_issue = <학습자의 최근 막힌 사례>` |
| 청크 4~6 답변 | `draft.diagnosis_checklist_results = <체크리스트 점검 결과>` |
| 가이드 실습 적용 | `draft.fix_applied = <학습자가 적용한 수정>` |
| 실습 통과 | `practice_status = "done"`, `status = "completed"` |
| **🎓 기초 트랙 완주 시** | `track_decisions.advanced_decision = "pending"` 후 학습자에게 분기 묻기 |
| 모든 갱신 시 | `updated_at` |

### 7강이 사용하는 `draft` 키

| 키 | 시점 | 형식 |
|---|---|---|
| `recent_issue` | 청크 3 | string |
| `diagnosis_checklist_results` | 청크 4~6 | array (질문별 답) |
| `fix_applied` | 가이드 실습 | string |

---

## 3. 이론 lesson 흐름

청크 8개. 마지막 청크 8은 *이론 마무리 + 가이드 실습 진입 + 트랙 분기 예고*.

### 7강에서 *왜* 한 청크씩 가는가
디버깅은 *체계적 사고*가 필요합니다. 한 번에 "이거 해보세요"라고 답을 주면 학습자가 *왜 그게 답인지* 모르고 다음에도 같은 질문을 하게 돼요. 한 청크씩 *질문 → 학습자 답 → 다음*으로 가야 진단 사고가 머릿속에 스며듭니다.

---

## 4. 가이드 실습 — 옵션 2개 인라인

### 4-0. 진입 시 draft 정리

```
🎉 이론 끝! 진단 사례 풀이 시간이에요.

📝 최근 막힌 사례: <draft.recent_issue>
📝 진단 결과:
   - <draft.diagnosis_checklist_results[0]>
   - <draft.diagnosis_checklist_results[1]>

이걸 토대로 해결해볼게요.
```

### 4-1. 옵션 제시

```
어떤 사례로 풀어볼까요?

  (1) {{name}}님의 최근 막힌 사례 (이론에서 적어주신 것)
  (2) 강의가 제공하는 가상 사례

번호로 답해주세요.
```

### 4-2. 옵션 ① — 본인 사례

`draft.recent_issue` 그대로 사용. 진단 → 가설 → 적용 → 결과 확인.

### 4-3. 옵션 ② — 가상 사례

강의 제공 시나리오 (예: "에이전트가 같은 답만 반복") 함께 진단.

### 4-4. 검증 기준

| 항목 | 통과 기준 |
|---|---|
| 진단 체크리스트 *3개 이상* 적용 | ✅ |
| *근본 원인 가설*이 1개 이상 도출됨 | ✅ |
| `fix_applied`가 *실행 가능한* 형태 | ✅ |

3개 중 2개 이상 ✅.

---

## 5. 자리표시자 처리
1강 동일.

---

## 6. 도구 비종속
디버깅 사고법은 도구 무관. 도구별 로그 위치 차이는 부록.

---

## 7. 종료 시 행동 — 🎓 기초 트랙 완주 분기

1. 진도 갱신 (status/practice_status).
2. **트랙 전환 분기** (`_shared/menu-template.md`의 표준 형식):

```
🎉 기초 트랙 완주 축하드려요, {{name}}님!

여기까지 따라오셨다면 이미 본인만의 작은 하네스를 운영할 수 있는 기초가
잡힌 거예요. 이제 어떻게 하시겠어요?

  (1) 심화 트랙 바로 시작 — subagents, hooks 등 본격 자동화
  (2) 일단 기초만 — 며칠 써보고 다시 결정할게요
  (3) 여기서 마무리 — 강의 종료

어떤 길로 가실까요?
```

학습자 응답에 따라 `track_decisions.advanced_decision` 갱신 + 분기.

---

## 8. 강의 작성자 메타

- **트랙**: 기초 7강 (기초 트랙 마지막)
- **선행**: 1~6강 (권장)
- **분량**: 약 30분
- **외부 자료**: 없음
- **비용**: 없음
- **학습 목표**:
  - 5가지 흔한 실패 패턴을 안다
  - 10개 진단 체크리스트를 *본인 사례*에 적용해본다
  - 고립·재현 흐름으로 근본 원인을 좁혀본다
- **다음 강의**: (분기에 따라) 08-subagents (심화) 또는 메뉴

---

## 9. 빠른 자기 점검
- [ ] 학습자 프로필 읽음
- [ ] `📘 [Lesson 7 · 청크 X/Y]`
- [ ] 한 청크만, 끝에 ❓/🛠/🔀
- [ ] 자리표시자 채움
- [ ] 도구명 노출 X
- [ ] 시도 전 답 X
- [ ] `progress["07-debugging"]` 갱신
- [ ] **7강 추가**: 종료 시점에 *기초 트랙 완주 분기*를 빼먹지 않았는가