AI 드리븐

지도 위치 : 2일차 · 구현과 검증 · 구현의 출발점 | 이전: 8차시 아키텍처 결정과 근거 기록 | 다음: 10차시 백엔드 역할: 서버 로직 키워드 : 계획 기반 진행 방식, 프로젝트 구조 생성, 로컬 실행·연결 확인

이 차시를 다 읽으면

1. 걸어 다니는 뼈대 를 유와 종차로 정의하고, 기능부터 만드는 방식과 무엇이 다른지 말할 수 있다.
2. 화면 · 서버 · DB를 나눈 대가(연결 비용) 가 무엇이고, 왜 그 비용을 첫날 먼저 치르는지 설명할 수 있다.
3. 계획 기반 진행 방식 의 다섯 단계를 대고, 내가 개입하는 두 자리(계획 검토 · 완료 확인)를 짚을 수 있다.
4. plan mode 가 무엇을 막고 무엇을 막지 못하는지 말할 수 있다.
5. 뼈대의 완료 조건을 "명령 + 기대 출력" 으로 적고, README의 명령만으로 서비스를 직접 띄워 확인할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "기능을 하나도 만들기 전에 무엇을 먼저 세워야 하는가" 입니다. 앞에서 배운 아키텍처 결정(8차시)에서 화면과 서버를 나누기로 했다면, 축 1의 오른쪽을 고른 것입니다. 나누는 순간 층 사이를 잇는 비용이 생기고, 이 차시는 그 비용을 축 2의 오른쪽(얇게 관통) 으로 첫날 치르는 방법을 다룹니다. 축 3은 그 일을 AI에게 맡기는 방식입니다.

---

1. 나누면 생기는 것 — 연결 비용

1.1 세 층과 그 사이의 이음매

앞에서 배운 ⑤ 하나 ↔ 여럿 축(5차시)을 다시 떠올리세요. 나누면 안전하고 확장하기 쉬워지지만, 대신 조율 비용이 생깁니다. 서비스를 화면 · 서버 · DB로 나누면 그 조율 비용은 층 사이의 이음매 로 나타납니다.

환경변수 — [프로그램 설정값]인데, [ 코드 밖(실행 환경)에서 주입되어 같은 코드가 환경마다 다른 값을 쓰게 한다 ]는 점에서 코드 안에 직접 적힌 값과 구별된다. DB 주소, 서버 포트, 결제 키가 대표적입니다. 로컬에서는 보통 .env라는 파일에 적어 둡니다.

1.2 연결 문제는 마지막에 몰아서 터진다

수평 (층별로 완성)                          수직 (얇게 관통)
 먼저: 서버 기능 전부 ──┐                  먼저: 화면─서버─DB 한 줄 연결 (확인 끝)
 다음: 화면 기능 전부 ──┤                  다음: 그 길 위에 "클래스 목록"
 끝:   연결 ───────────┘ ← 이음매 문제      그다음: 그 길 위에 "예약"
        다섯 가지가 한꺼번에                    (이음매는 이미 검증됨)

🔍 읽는 포인트 : 왼쪽은 이음매 문제를 마지막에 한꺼번에 만나고, 오른쪽은 첫날 하나씩 만납니다.

왼쪽 방식에서 연결이 안 되면, 원인이 1.1의 다섯 이음매 중 어디인지 가려내기 어렵습니다. 여러 원인이 겹쳐 있으면 AI도 하나를 고치고 다른 증상을 만나 "같은 에러를 다른 방법으로 세 번 고치는"(README 9.4) 상태에 빠지기 쉽습니다.

---

2. ⭐ 걸어 다니는 뼈대

2.1 정의

걸어 다니는 뼈대 (Walking Skeleton) — [초기 구현 결과물]인데, [ 기능은 거의 없지만 모든 층이 실제로 연결되어 요청이 끝에서 끝까지 오간다 ]는 점에서 한 층만 만든 초안이나 화면만 있는 디자인 시안과 구별된다.

브라우저 화면: "서버: 정상 · DB: 연결됨"
     │  GET /health
     ▼
서버: DB에 아주 작은 질의(SELECT 1)를 보내 보고 결과를 돌려줌
     │
     ▼
DB: 응답

🔍 읽는 포인트 : /health는 "살아 있는가"를 묻는 주소 입니다. 화면의 "DB: 연결됨"은 이 요청이 DB까지 실제로 다녀왔다 는 뜻이어야 합니다.

2.2 경계 — 비슷한 것들과 무엇이 다른가

2.3 반례 — 이건 뼈대가 아닙니다

두 번째 반례가 6절 실습의 행동 시험으로 이어집니다. DB를 껐을 때 화면 표시가 바뀌는지 가 진짜 뼈대인지 가르는 시험입니다.

2.4 비유 (기억 보조)

새 건물에 수도관을 깔면 벽지를 바르기 전에 물부터 한 번 끝까지 흘려 봅니다. 새는 곳이 있으면 벽을 뜯지 않고 바로 고칠 수 있습니다. 뼈대는 그 "물 한 번 흘려 보기"입니다.

---

3. 계획 기반 진행 방식

3.1 다섯 단계

① 지시   목표 · 참고 문서 · 제외할 것 · 완료 조건
② 계획   에이전트가 무엇을 어떤 순서로 할지 제안 (아직 파일 변경 없음)
③ 검토   ← 내가 개입: 고치거나 승인 ("이 패키지는 빼", "폴더 이름은 이렇게")
④ 실행   승인된 계획대로 진행
⑤ 확인   ← 내가 개입: 완료 조건을 명령 출력과 화면으로 확인

0절 축 3의 이유 그대로입니다. 에이전트에게 "프로젝트 만들어줘"를 바로 실행시키면 수십 개 파일이 한 번에 생깁니다. 마음에 안 들면 되돌리기 번거롭습니다. 계획 단계에서 고치는 것이 가장 쌉니다.

3.2 plan mode

plan mode — [에이전트의 실행 모드]인데, [ 파일 수정과 명령 실행 없이 읽고 계획만 제안하도록 시스템이 묶어 둔다 ]는 점에서 곧바로 변경하는 기본 모드와 구별된다.

Claude Code에는 이 모드가 있고(전환 방법은 버전에 따라 다를 수 있으니 공식 문서 확인), 다른 도구에도 비슷한 기능이 있습니다. 없다면 "아직 파일은 만들지 말고 계획만 보여줘"라고 지시합니다.

⚠️ plan mode는 "계획 단계에서 아무것도 바뀌지 않는다"만 보장합니다. 계획이 좋은지, 실행이 계획대로 됐는지는 여전히 ③과 ⑤에서 내가 봐야 합니다.

3.3 ⭐ 계획 검토 — 코드를 몰라도 판단할 수 있는 자리

계획 검토는 이 방식에서 가장 중요한 개입 지점 입니다. 코드가 만들어진 뒤에는 내가 판단할 수 있는 것이 줄어들지만, 계획 단계에서는 아키텍처 감각만으로 충분합니다.

계획이 파일 이름과 기술 용어로만 가득하다면 이렇게 다시 요청합니다.

이 계획을 코드를 모르는 사람이 검토할 수 있게 다시 정리해줘.
[단계 | 무엇이 생기나 | 끝나면 내가 무엇을 보고 확인하나 | ADR과 다른 선택인가] 표로.
범위 밖 기능이 섞여 있으면 따로 표시하고, 새로 설치하는 것은 목록과 이유를 붙여줘.

---

4. 프로젝트 구조와 실행 확인

4.1 구조

8차시에서 하나의 저장소에 화면과 서버를 함께 두기로(모노레포) 결정했다면 예를 들어 이런 모양입니다.

classon/
├── apps/
│   ├── web/              # 화면 (프론트엔드)
│   └── api/              # 서버 (백엔드)
├── packages/
│   └── shared/           # 화면과 서버가 함께 쓰는 요청·응답 모양 (11차시)
├── docs/
│   └── architecture.md   # 어떤 기능이 어느 폴더에 있는지 (구조 지도)
├── .claude/              # 에이전트 설정
├── .env.example          # 필요한 환경변수 이름 목록 (값은 비움)
├── .gitignore            # .env 등 저장소에 올리지 않을 것
├── CLAUDE.md             # 지침 파일
└── README.md             # 실행 방법

🔍 읽는 포인트 : .env.example(이름만)과 .gitignore(올리지 않을 목록)가 첫날부터 있는지만 보면 됩니다.

• .env.example과 .gitignore는 첫날 만듭니다. 나중에 만들면 이미 비밀값이 저장소에 올라간 뒤일 수 있습니다(14차시).
• docs/architecture.md(구조 지도) 도 첫날 만들고, 지침 파일에 "구조가 바뀌면 이 문서도 고친다"를 적어 둡니다. 코드는 늘어나는데 그 구조를 아는 사람이 없는 상태(이해 부채)를 막는 가장 싼 방법입니다. 장애가 났을 때(23차시) 나와 AI 모두의 출발점이 됩니다.

4.2 완료 조건은 명령으로

뼈대의 완료는 "만들었습니다"가 아니라 명령과 기대 출력 으로 적습니다.

# 1. DB 실행 (예: 컨테이너로 로컬 PostgreSQL)
docker compose up -d db

# 2. 서버 실행 후 상태 확인
curl http://localhost:4000/health
# 기대: {"status":"ok","db":"connected"}

# 3. 화면 실행 후 브라우저에서 "DB: 연결됨" 확인

🔍 읽는 포인트 : docker compose는 여러 프로그램(DB, 서버)을 설정 파일 하나로 함께 띄우는 도구 입니다. # 뒤의 "기대:" 줄이 완료 조건입니다.

4.3 명령은 파일에 적는다

이 명령들을 README.md와 CLAUDE.md의 "명령어" 절에 적어 둡니다. 앞에서 배운 ① 디스크 ↔ 메모리 축(2차시)의 적용입니다. 대화 속에서 한 번 성공한 실행 방법은 세션이 끝나면 사라지고, 파일에 적힌 방법만 다음 에이전트에게 남습니다. 적어 두지 않으면 에이전트마다 다른 방식으로 서버를 띄우고, 그 차이가 또 하나의 이음매 문제가 됩니다.

앞으로 다시 만납니다 — /health는 여기서 끝나지 않습니다. 15차시 배포 설정에서 "상태 확인 경로"로, 21차시에서 배포 직후 확인으로, 23차시에서 장애가 났을 때 가장 먼저 열어 보는 계기판 으로 다시 나옵니다.

---

5. 클래스온에 적용하면

docs/adr/의 결정에 맞게 클래스온 프로젝트 뼈대를 만들 계획을 세워줘. 아직 파일은 만들지 마.
- 포함: apps/web, apps/api, packages/shared, DB 실행용 docker compose, /health API,
        화면의 상태 표시, .env.example, .gitignore, docs/architecture.md
- 제외: 실제 기능(클래스, 예약, 결제), 인증
- 완료 조건: README에 적은 명령만으로 세 층이 모두 실행되고, 화면에 "DB: 연결됨"이 보일 것.
             DB를 끄면 화면 표시가 "DB: 연결 안 됨"으로 바뀔 것.

🔍 읽는 포인트 : "제외"와 마지막 완료 조건(DB를 끄면 바뀐다)이 이 지시의 핵심입니다. 앞은 범위를, 뒤는 2.3의 가짜 뼈대를 막습니다.

---

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

지시

(plan mode에서) 5절의 지시대로 뼈대 계획을 세워줘.
[단계 | 무엇이 생기나 | 끝나면 내가 확인할 것 | ADR과 다른 선택인가] 표로 보고하고,
새로 설치하는 패키지·도구는 [이름 | 이유 | 공식 페이지 주소] 표로 따로 붙여줘.

(계획 승인 후) 실행해줘. 끝나면 README의 명령을 처음부터 순서대로 실행하고,
각 명령과 그 출력 원문을 요약하지 말고 그대로 붙여줘.
마지막으로 DB 컨테이너를 멈춘 상태에서 /health를 한 번 더 호출한 출력도 붙여줘.

받을 증거

• 승인 전: 단계별 계획 표, 설치 목록 표
• 승인 후: README 명령 각각의 실행 출력 원문 , DB가 켜졌을 때와 꺼졌을 때의 /health 응답 두 개

내가 직접 확인할 것

💡 이후에도 무언가 이상하면 /health부터 열어 보세요. 서버가 죽었는지, DB가 끊겼는지가 한 번에 갈립니다.

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 9차시 노트만 근거로 5문제를 내줘. 비전공자 기준으로.
"나누면 생기는 이음매", "걸어 다니는 뼈대와 가짜 뼈대 구별", "plan mode와 지시의 차이(부탁↔강제)"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.