AI 드리븐

지도 위치 : 1일차 · 팀 구성 · 모든 역할에 쓰는 공통 틀 | 이전: 4차시 범위 결정과 서비스 설계 | 다음: 6차시 디자인 ① 화면 설계 역할 키워드 : 'AI가 만든 티'의 원인과 처방, 역할을 정의하는 네 가지 축, 팀 편성

이 차시를 다 읽으면

1. 'AI가 만든 티' 의 증상 여섯 가지를 말하고, 코드를 읽지 않고도 알아챌 수 있는 신호를 댈 수 있다.
2. 증상의 원인 네 가지를 역할 정의의 네 축(책임 · 맥락 · 권한 · 완료 조건) 과 짝지을 수 있다.
3. 네 축을 하위 에이전트 정의 파일에 옮기고, 완료 조건에 증거 제출 을 넣을 수 있다.
4. 정의 파일의 "이 폴더만 수정한다"(부탁)와 tools: 줄(강제)의 차이를 말할 수 있다.
5. 역할을 언제 나누고 언제 나누지 않을지 하나 ↔ 여럿 축으로 판단할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "모든 역할에 공통으로 쓰는 정의 틀은 무엇인가" 입니다. 앞에서 기획 역할(3차시 5.1)을 정의했고, 6차시부터 디자이너 · 검증자 · 백엔드 · 프론트엔드가 나옵니다. 역할마다 즉흥적으로 지시를 쓰면 품질이 들쭉날쭉합니다. 앞에서 배운 하위 에이전트(2차시 3.1)가 그릇이라면, 이 차시는 그릇에 무엇을 채우는가 입니다.

---

1. 'AI가 만든 티' — 증상

1.1 정의

'AI가 만든 티' — [결과물의 품질 문제]인데, [ 이 프로젝트가 아니라 세상의 평균값에 맞춰진 흔적 ]이라는 점에서 특정 줄이 틀린 단순 버그와 구별된다.

1.2 코드를 읽지 않아도 보이는 신호 ⭐

'AI가 만든 티'는 코드를 몰라도 보입니다.

이런 신호를 보면 2절 표에서 원인 축 을 찾습니다. 결과를 대화로 고치는 대신 원인 축을 고칩니다.

---

2. 원인과 처방

⭐ 네 원인이 곧 네 축입니다. 증상을 보고 → 원인 축을 찾고 → 그 축을 정의 파일에서 고칩니다.

---

3. ⭐ 역할을 정의하는 네 가지 축

3.1 정의

역할 정의 — [에이전트 지시]인데, [ 책임 · 맥락 · 권한 · 완료 조건 네 축을 파일로 고정해 다음 세션에도 똑같이 적용된다 ]는 점에서 대화 중에 그때그때 쓰는 즉흥 지시와 구별된다.

(수업에서 쓰는 명칭은 다를 수 있습니다. 개념이 같으면 됩니다.)

3.2 네 축을 정의 파일로

# .claude/agents/backend.md
---
name: backend
description: docs/api.md 명세에 따라 서버 API를 구현한다. 명세가 확정된 기능을 구현할 때 사용.
tools: Read, Write, Edit, Bash, Glob, Grep
---
## 책임
- docs/api.md 명세대로 서버 코드를 구현한다
- 하지 않는 일: 화면 코드 수정, 명세 변경, DB 구조 변경(데이터 역할 담당)

## 맥락
- 기준: docs/api.md, docs/requirements.md의 인수 기준, docs/adr/
- 기존 코드 스타일을 먼저 읽고 따른다

## 권한
- apps/api/ 아래만 수정한다

## 완료 조건
- 해당 API의 테스트를 작성하고 통과시킨다
- 실제로 요청을 보내 응답을 확인한다
- 증거: 실행한 확인 명령과 출력 원문을 첨부한다. "통과했다"는 요약만으로는 완료가 아니다.
- 사용자(나)가 직접 확인할 수 있는 방법을 한 가지 이상 적는다.
- 위험 영역(돈 · 개인정보 · 삭제 · 권한 · 새 패키지)을 건드렸으면 [위험]으로 표시한다.
- 보고: 바꾼 파일 목록, 명세와 다르게 판단한 부분

🔍 읽는 포인트 : 세 곳만 보면 됩니다. tools: 줄(무엇을 할 수 있나), ## 책임의 "하지 않는 일", ## 완료 조건의 "증거" 줄.

⭐ 네 축 중 "완료 조건"을 가장 두껍게 씁니다. 코드를 읽는 사람은 결과물을 직접 읽어 완료를 판단하지만, 코드를 읽지 않으면 AI가 낸 증거로만 판단할 수 있습니다(0절 축 4). 그래서 모든 역할의 완료 조건에 증거 제출과 "내가 직접 확인할 방법"을 넣습니다.

3.3 description은 누가 읽나

description은 사람보다 메인 에이전트 가 읽습니다. 메인 에이전트는 이 설명을 보고 언제 이 역할에게 일을 넘길지 판단합니다. "서버 코드 담당"보다 "명세가 확정된 기능을 구현할 때 사용"처럼 언제 부를지 를 쓰면 엉뚱한 때 불리지 않습니다.

3.4 ⚠️ 권한 축의 두 자리 — 부탁과 강제

같은 "권한" 축이 정의 파일 안에 두 번 나옵니다. 성격이 다릅니다(앞에서 배운 부탁 ↔ 강제, 2차시 4.2).

그래서 "절대 고치면 안 되는 역할"(검증자, 7차시)은 글로 부탁하지 않고 tools:에서 수정 도구를 뺍니다. 폴더 단위로 강제로 막는 것은 권한 설정 · 훅의 몫입니다(12, 14차시).

3.5 반례 — 이건 역할 정의가 아닙니다

---

4. 팀 편성 — 하나 ↔ 여럿

                 사람(팀장): 목표, 승인, 최종 판단
                          │
              메인 에이전트(조율): 일을 나누고 넘기고 모음
     ┌──────┬──────┬──────┼──────┬──────┬──────┐
   기획   디자인  디자인검증 백엔드 프론트  데이터  리뷰/QA ...

🔍 읽는 포인트 : 맨 위 줄입니다. 사람은 코드를 쓰는 자리가 아니라 목표 · 승인 · 최종 판단 의 자리입니다(README 7장).

⚠️ 0절 축 1의 어느 쪽도 "발전된 형태"가 아닙니다. 기준은 산출물이 다른가, 독립된 판단이 필요한가 입니다. 둘 다 아니면 나누지 않습니다.

💡 비유는 마지막에 — 역할 정의는 회사의 직무 기술서 입니다. "유능한 사람"이라고 쓰지 않고, 담당 업무 · 참고 자료 · 결재 권한 · 성과물을 씁니다.

앞으로 다시 만납니다 — 6차시(디자이너), 7차시(디자인 검증자), 8차시(아키텍트)가 이 네 축으로 정의됩니다. 9차시에서 2일차 역할들이 한꺼번에 추가됩니다.

---

5. 역할 정의가 작동하는지 확인하기와 클래스온

5.1 같은 작업을 두 번 시켜 보기

정의 파일을 읽고 판단하기보다 같은 작업을 두 번 시켜 보세요.

이 시험은 코드를 몰라도 할 수 있습니다. 바뀐 파일 목록, 보고 모양, 화면만 비교하면 됩니다.

5.2 클래스온에 적용하면

1일차가 끝날 때 .claude/agents/에 최소한 이 정도가 있으면 좋습니다.

2일차에 backend.md, frontend.md, data.md, code-reviewer.md, security-reviewer.md가 추가됩니다.

---

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

지시

.claude/agents/에 있는 역할 정의 파일(planner.md 등)을 모두 읽고 네 축으로 점검해줘.
[파일 | 책임(하지 않는 일 포함) | 맥락(참고 문서) | 권한(tools 목록) | 완료 조건(증거 요구 여부) | 빠진 축] 표로.
빠진 축이 있으면 이 노트 3.2절의 완료 조건 형식(증거 · 내가 확인할 방법 · [위험] 표시)으로 보완안을 보여줘.
파일을 고치기 전에 바꿀 내용을 먼저 보여주고 내 승인을 받을 것.

받을 증거

• 점검표와 각 파일의 tools: 줄 원문
• 보완안(바꾸기 전 · 후)

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 5차시 노트만 근거로 6문제를 내줘. 코드를 모르는 사람 기준으로.
"AI가 만든 티의 원인 네 가지", "역할 정의 네 축", "완료 조건에 증거 넣기", "권한 축의 부탁과 강제"는 반드시 포함해줘.
증상 하나를 주고 어느 축을 고쳐야 하는지 내가 맞히는 문제도 1개 넣어줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.