AI 드리븐

지도 위치 : 1일차 · 출발점 · 과정 전체의 작업 방식 | 다음: 2차시 AI 개발팀을 세우는 핵심 기능 키워드 : 대화형 vs 에이전트형 AI, 개발 환경, 설치·인증, 지시(프롬프트)의 기본형

이 차시를 다 읽으면

1. 에이전트형 AI를 유와 종차로 정의하고, 대화형 AI와 "누가 실행하는가" 로 가를 수 있다.
2. 에이전트 루프의 네 단계를 말하고, 결과 품질을 정하는 단계가 왜 "확인" 인지 설명할 수 있다.
3. 개발 환경의 구성 요소 여섯 가지가 각각 무슨 일을 하는지 말할 수 있다.
4. 승인 창에 뜬 명령을 읽기만 하는 것 과 바꾸거나 내보내는 것 으로 가를 수 있다.
5. 지시의 다섯 요소로 일을 맡기고, "완료했습니다"라는 주장 대신 증거 를 받는 보고 형식을 쓸 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 하나입니다. AI가 직접 실행하게 되면, 나는 무엇을 근거로 그 결과를 믿는가? 축 1이 "AI가 실행한다"는 새 상황을 만들고, 축 2가 그 상황에서의 답(증거를 받는다)을 주며, 축 3이 실행 전에 내가 지킬 첫 관문(승인 창)을 줍니다. 과정의 출발점이라 앞 차시는 없습니다. 이 세 축은 24차시 내내 다시 나옵니다.

---

1. 대화형 AI와 에이전트형 AI

1.1 정의

대화형 AI — [AI 도구]인데, [ 질문을 받아 글로 답하고 멈추며, 실행은 사람이 한다 ]는 점에서 에이전트형 AI와 구별된다.

에이전트형 AI (코딩 에이전트) — [AI 도구]인데, [ 목표를 받아 스스로 도구를 써서 파일을 읽고 고치고 명령을 실행한 뒤, 결과를 확인하며 반복한다 ]는 점에서 답을 글로 내놓고 멈추는 대화형 AI와 구별된다.

도구 (Tool) — [에이전트가 할 수 있는 동작 단위]인데, [ AI 바깥의 세계를 실제로 읽거나 바꾼다 ]는 점에서 글을 만드는 것으로 끝나는 답변과 구별된다. 파일 읽기(Read), 파일 쓰기(Write), 파일 고치기(Edit), 명령 실행(Bash), 내용 검색(Grep) 같은 것이 도구입니다.

앞으로 다시 만납니다 — 2차시와 5차시에서 하위 에이전트 정의 파일의 tools: 한 줄을 봅니다. 그 줄에 적힌 이름이 바로 이 "도구"입니다. 도구를 빼면 그 동작을 아예 못 합니다.

1.2 경계 — 무엇으로 갈리는가

⚠️ 마지막 줄이 이 과정 전체의 출발점입니다. 에이전트는 스스로 "끝났다"고 판단 합니다. 그 판단이 맞는지는 별개의 문제입니다(2절).

1.3 반례 — 이건 에이전트형이 아닙니다

💡 비유는 마지막에 — 대화형 AI는 전화로 고치는 법을 설명해 주는 수리 기사, 에이전트형 AI는 집에 와서 직접 고치고 물을 틀어 확인하는 수리 기사입니다.

---

2. ⭐ 에이전트 루프 — 확인이 품질을 정한다

2.1 정의와 모양

에이전트 루프 — [작업 방식]인데, [ 관찰 → 계획 → 행동 → 확인을 목표가 달성될 때까지 반복한다 ]는 점에서 한 번 답하고 끝나는 질의응답과 구별된다.

  ┌──────────────────────────────────────────────────────┐
  ▼                                                      │
 관찰(파일 · 에러 읽기) → 계획 → 행동(편집 · 명령 실행) → 확인(테스트 · 출력 보기)
                                                         │
                                         목표 달성? ── 예 → 보고하고 종료

🔍 읽는 포인트 : 오른쪽 끝 "목표 달성?"을 누가, 무엇을 보고 판정하는지만 보면 됩니다.

2.2 확인 단계가 결과 품질을 정한다

에이전트가 루프를 끝내는 근거는 둘 중 하나입니다.

⭐ 그래서 확인할 수단을 미리 주는 것 이 일을 맡기는 사람의 첫 번째 몫입니다. 이 과정이 완료 기준(3차시), 검증 분리(7차시), 동작 검증(13차시), 자동 테스트(17차시)에 많은 시간을 쓰는 이유가 여기 있습니다.

2.3 증거와 주장

에이전트가 루프를 끝내고 보고할 때, 그 보고는 두 종류로 갈립니다.

증거 — [보고 내용]인데, [ 실행한 명령과 출력 원문처럼 다른 사람이 다시 확인할 수 있다 ]는 점에서 "완료했습니다" 같은 주장과 구별된다.

주장 — [보고 내용]인데, [ 결과에 대한 말뿐이라 다시 확인할 길이 없다 ]는 점에서 증거와 구별된다.

⚠️ 에이전트의 말이 틀리는 것은 거짓말을 해서라기보다 확인하지 않은 것을 확인한 것처럼 말하기 때문입니다. 그래서 이 과정의 원칙은 단순합니다. AI의 말은 신뢰의 근거가 아니고, 증거가 붙어 있을 때만 받아들입니다. 이 밖의 위험 신호는 README 9.4에 모아 두었습니다.

앞으로 다시 만납니다 — 5차시에서 모든 역할 정의의 "완료 조건"에 증거 제출을 넣고, 23차시에서 장애 원인을 찾을 때 사실(증거)과 추측(주장)을 나누는 방식으로 다시 씁니다.

---

3. 개발 환경 준비

3.1 구성 요소 여섯 가지

⚠️ Git은 시작 전에 켭니다. 에이전트는 빠르게 많은 파일을 바꿉니다. 바꾸기 전 상태가 저장돼 있지 않으면 잘못 고쳤을 때 되돌릴 방법이 없습니다.

3.2 설치와 첫 실행

설치와 인증 방법은 도구마다 자주 바뀌니 공식 문서 를 따르세요. Claude Code라면 대략 이런 순서입니다.

# 설치 (공식 문서의 최신 방법 확인)
curl -fsSL https://claude.ai/install.sh | bash

# 프로젝트 폴더에서 실행 → 처음이면 로그인 안내가 나옴
cd my-project
claude

🔍 읽는 포인트 : 마지막 줄 claude를 어느 폴더에서 실행하느냐가 중요합니다. 에이전트는 실행한 폴더를 프로젝트로 보고 그 안을 탐색합니다.

3.3 ⚠️ 비밀값 — API 키

API 키 — [비밀값]인데, [ 그 자체만 있으면 유료 서비스를 내 이름과 내 돈으로 쓸 수 있는 열쇠 ]라는 점에서 아무에게 보여도 되는 일반 설정값과 구별된다.

비밀값 입력은 내가 직접 하는 일 입니다(README 9.2). AI에게 키를 알려 주지 않습니다.

앞으로 다시 만납니다 — 14차시에서 비밀값이 코드에 섞여 들어가는 것을 자동으로 차단 하고, 21차시에서 배포 환경에 비밀값을 안전하게 넣는 법을 봅니다.

3.4 승인 창 — 나의 첫 번째 관문 ⭐

에이전트 도구는 보통 파일을 고치거나 명령을 실행하기 전에 허락을 구합니다. 이 승인 창이 코드를 읽지 않는 사람에게 가장 먼저 주어지는 관문입니다.

• 모르는 명령이 뜨면 승인하기 전에 "이 명령이 무엇을 하는지 한 줄로 설명해줘" 라고 물으면 됩니다.
• 처음에는 하나하나 승인하면서 무엇을 하는지 지켜봅니다. 처음부터 모든 것을 자동 허용하지 않습니다.

앞으로 다시 만납니다 — 승인 창은 사람이 매번 판단하는 부탁에 가까운 관문 입니다. 2차시에서 무엇을 자동 허용하고 무엇을 아예 막을지 권한 설정 으로 고정하고, 14차시에서 위험한 행동을 훅 으로 차단합니다.

---

4. 지시(프롬프트)의 기본형

프롬프트 (지시) — [AI에게 주는 입력]인데, [ AI가 할 일과 그 일의 조건을 담는다 ]는 점에서 AI가 내놓는 출력과 구별된다.

4.1 다섯 요소

⭐ 완료 기준 은 2절 루프의 "확인" 단계에 들어갈 재료이고, 보고 형식 은 증거를 받는 통로입니다. 둘 중 하나라도 빠지면 0절 축 2의 오른쪽(주장)만 돌아옵니다.

4.2 나쁜 지시와 좋은 지시

클래스 목록 기능 만들어줘

docs/api.md의 GET /classes 명세대로 클래스 목록 API를 구현해줘.
- 기존 src/routes/ 구조와 같은 방식으로 만들 것
- 새 패키지 설치는 하지 말 것
- 끝나면 테스트를 돌리고, 실제로 요청을 보내 받은 응답을 보여줄 것
- 보고: ① 사용자 입장에서 달라진 점 ② 실행한 확인 명령과 출력 원문 ③ 내가 직접 확인할 방법

🔍 읽는 포인트 : 두 번째 지시에서 "끝나면 ~ 보여줄 것"과 "보고:" 두 줄만 보면 됩니다. 이 두 줄이 증거를 받는 장치 입니다.

나쁜 지시에도 AI는 그럴듯한 결과를 냅니다. 문제는 그게 맞는지 확인할 방법이 없다는 것 입니다.

4.3 완료 기준은 "내가 눈으로 확인할 수 있는 것"으로

코드를 읽지 않는 사람에게는 오른쪽이 훨씬 쓸모 있습니다. 왼쪽은 AI가 테스트로 옮기고, 오른쪽은 내가 행동 시험에 씁니다(README 9.1).

4.4 반례 — 이건 좋은 지시가 아닙니다

💡 보고 형식 세 줄(①②③)은 매번 쓰기 번거롭습니다. 2차시에서 이 문장을 지침 파일 에 넣어 두면 모든 세션에 자동으로 적용됩니다.

4.5 클래스온에 적용하면

• 빈 폴더 classon/을 만들고 Git을 켠다(git init)
• 에이전트를 실행해 "이 폴더에 무엇이 있는지 설명해줘" 같은 읽기만 하는 지시 로 동작을 확인한다
• 다섯 요소를 갖춘 지시로 README.md에 서비스 한 줄 소개를 쓰게 한다

---

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

이 차시의 목표는 에이전트가 실행하는 모습과 승인 창을 직접 겪어 보는 것 입니다. 결과물(README 한 줄)은 작고, 관찰이 중요합니다.

지시

이 폴더(classon/)를 클래스온 프로젝트의 시작점으로 만들어줘.
- 목표: README.md에 "클래스온: 동네 공방의 원데이 클래스를 검색 · 예약 · 결제하는 서비스" 한 줄 소개를 쓴다
- 제약: 새 패키지 설치 금지. README.md 외의 파일은 만들지 말 것
- 순서: 먼저 git status로 Git이 켜져 있는지 확인하고, 안 켜져 있으면 git init 전에 나에게 물어볼 것
- 완료 기준: README.md에 위 문장이 있고, git status에 README.md가 새 파일로 보인다
- 보고 형식: [한 일 | 실행한 명령 | 출력 원문] 표 + 내가 직접 확인할 방법 한 줄
요약하지 말고 실행 출력 원문을 붙여줘.

받을 증거

• git status 실행 출력 원문 (README.md가 새 파일로 표시된 줄)
• README.md의 내용 원문
• 실행한 명령 목록 (승인 창에 떴던 것과 같은지 대조용)

내가 직접 확인할 것

💡 위 지시의 "git init 전에 나에게 물어볼 것"처럼 실행 전에 승인을 받는 줄 을 넣어 두면, 되돌리기 어려운 작업에서 내가 끼어들 자리가 생깁니다. 이 습관이 15 · 21차시의 "되돌릴 수 있는가" 축으로 이어집니다.

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 1차시 노트만 근거로 5문제를 내줘. 코드를 모르는 사람 기준으로.
"대화형과 에이전트형을 가르는 축", "에이전트 루프에서 확인 단계의 역할", "증거와 주장", "승인 창에서 명령 분류"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.