이 워크북 쓰는 법

트랙 선택 (코어16 / 풀24 / 마스터27)

이 워크북은 세 가지 트랙으로 이수할 수 있다.

• S0: L00a~L00d, CLI 없이 브라우저만으로 첫 제품을 만들어 보는 무료 선행 4차시. AI를 처음 써 보는 완전 초급자는 코어16/풀24/마스터27 중 무엇을 고르든 이 4차시부터 시작한다.
• 코어16: L01~L16 총 16차시. 처음 공부하거나 시간이 부족하면 여기서 시작한다.
• 풀24: 코어16 + 심화 A01~A08. 배포·운영·유지보수를 실무 수준으로 깊이 배우고 싶을 때.
• 마스터27: 코어16 + 심화 A01~A11 전체. 성숙·공통 축까지 모두 이수한다.

심화 차시(A01~A11) 색인은 advanced/README.md에서 확인한다. 도구·모델의 실제 이름과 가격은 appendix/tool-map-2026-09.md에서만 다룬다. 이 워크북 본문에는 적지 않는다.

모르는 용어가 나오면 레포 docs/ 아래 관련 파일에서 먼저 찾는다.

누가 쓰는 워크북인가

이 워크북은 AI 도구로 무언가를 빠르게 만들어 본 성인을 위해 설계했다. 설명 난이도는 중학생도 이해할 수 있는 쉬운 말로 유지한다. 실습 난이도는 실무에서 실제로 쓸 수 있는 수준이다.

이 워크북은 아래 두 상황에서 모두 쓸 수 있다.

• 강사와 함께 (집합 교육): 강사가 앞에서 설명하고, 수강생은 워크북을 채우며 따라간다.
• 혼자서 (셀프러너): 순서대로 읽고, 실습하고, 워크시트를 채운다. 막히면 레포의 예제 파일을 열어 본다.

한 차시는 2시간이다

모든 차시는 2시간 기준으로 설계했다. 아래 8단계 타임박스 안에서 돈다.

운영(L13) 이후 차시는 명령을 직접 실행하기 어렵다. 그 대신 계약 설계와 maturity-checklist 인스턴스 작성이 실습을 대신한다.

셀프러너라면: 각 구간을 혼자 해도 된다. 동료 리뷰는 체크리스트를 스스로 읽으며 대신한다.

13블록 페이지 구조

모든 차시(L01~L16)는 아래 13개 블록을 순서대로 담는다. 블록 번호와 이름을 알아 두면 어느 차시를 펼쳐도 같은 자리에서 같은 것을 찾을 수 있다.

1. 오늘의 질문 — 차시 전체를 관통하는 질문 하나. 차시를 마치면 이 질문에 답할 수 있어야 한다.
2. 오늘 배울 용어 — 새 용어 2~4개. "영어용어(쉬운 우리말) — 한 줄 뜻" 형태로 적는다.
3. 쉬운 이야기 — 일상 비유로 오늘 개념을 3~6문장으로 풀어 설명한다.
4. 실제 파일에서 찾기 — 레포의 진짜 파일 경로를 지정한다. 파일을 열어 개념이 어디에 있는지 눈으로 확인한다.
5. 따라 하기 — 강사와 함께 하는 단계별 실습. 각 명령에는 설명·결과 예시·흔한 오류가 붙는다.
6. 혼자 하기 — 스스로 input.json을 수정하거나 계약을 1개 작성하는 과제.
7. 실패 상황 — 일부러 실패시켜 보는 실습. "왜 위험한가"를 한 줄로 적는다.
8. 보완할 것과 대안 — 산출물이 부족할 때 어떻게 보강하나. 데이터 vs 코드 점검 1줄 포함.
9. 실패 시 축소 전략 — 시간·자원이 부족할 때 무엇을 줄여 핵심 약속을 살리나.
10. 오늘의 워크시트 — 대응 워크시트 파일 링크. 워크시트로 무엇을 완성하는지 1~2줄.
11. 동료 리뷰 질문 — 짝과 서로 점검할 질문 3개.
12. 오늘의 단어장 — 오늘 용어를 직접 내 말로 설명하는 빈칸 표.
13. 다음 차시 예고 — 다음 차시 제목과 연결 한 줄.

양식 상세는 LESSON-TEMPLATE.md에서 확인한다.

가로지르는 4개 실

4개 실은 차시 주제와 상관없이 모든 차시에 반드시 등장한다. 블록 3·7·8·9·12에 자연스럽게 녹아 있다. 공부하면서 이 4개 질문이 떠오르면, 그게 바로 이 워크북이 가르치려는 것이다.

1. 데이터 vs 코드 지금 다루는 것은 실행 중에 바뀌는 값인가(데이터), 아니면 프로그램 안에 고정된 것인가(코드)? 데이터는 input.json이나 DB에 두고, 코드에 직접 박아 넣으면 안 된다.

2. false certainty 사냥 이 문장은 확정된 사실인가, 아직 가정인가? "아마 될 거예요"는 계약이 아니다. 누가, 언제, 무엇 기준으로 결정하는지를 적어야 계약이다.

3. 실패 시 축소(downscope) 막혔을 때, 무엇을 줄이면 핵심 약속만이라도 살릴 수 있나? 전부 포기하기 전에, 먼저 범위를 좁혀라.

4. 증거 없는 "완료" 금지 어떤 명령·파일·게이트가 "됐다"를 증명하는가? 증거 없이 완료라고 쓰는 것은 허용하지 않는다.

안전한 실습 폴더

실습할 때 생성되는 파일은 항상 ./tmp-learning-output 폴더 안에 만든다. 예제 파일을 망가뜨리지 않기 위해서다.

폴더 만들기

mkdir ./tmp-learning-output

• 무슨 명령인가: 실습용 임시 폴더를 만든다.
• 결과 예시: (아무 메시지 없이 폴더가 생긴다)
• 흔한 오류: File exists → 이미 있으므로 그냥 쓰면 된다.

실습이 끝나면 이 폴더를 지워도 된다. 원본 예제는 ./examples/ 아래에 그대로 남아 있다.

강사가 지켜야 할 금지 행동

강사가 있는 수업이라면 아래는 하지 않는다.

• "그냥 외우세요" 금지. 모든 개념은 레포 파일에서 근거를 찾아 확인한다.
• PRD를 문장력 평가로 만들지 않는다. 우리는 검증 가능한 계약을 쓴다.
• PASS 확인 없이 차시를 끝내지 않는다.
• artifact review 없이 "완료"라고 선언하지 않는다.
• 운영·유지보수 차시를 "이론이니까 대충"으로 넘기지 않는다. maturity-checklist 인스턴스를 실제로 작성해서 점검한다.

셀프러너도 같은 기준을 스스로에게 적용한다. 워크시트 자가 점검란의 체크 항목을 건너뛰지 않는다.

Contract Forge — 끝까지 가는 제품 만들기

빠르게 만든 아이디어를 대규모로 운영 가능한 제품 계약으로 바꾸는 전체 생애주기 워크북

핵심 철학 문장

이 과정은 여섯 문장으로 시작한다.

아이디어는 말로 시작한다.
제품은 계약으로 시작한다.
신뢰는 증거로 생긴다.
운영은 보이지 않는 것을 보이게 만드는 일이다.
유지보수는 못 읽는 코드를 안전하게 진화시키는 일이다.
실력은 실패했을 때 줄일 수 있을 때 완성된다.

외우는 것이 목표가 아니다. 16차시가 끝났을 때, 이 여섯 문장이 자기 프로젝트로 설명되면 된다.

한 장 멘탈 모델

코드는 AI가 만든다.
사람은 결정하고, 판단을 판단하고, 연속성을 잇는다.
바이브 코더가 막히는 곳은 코드가 아니라 메타층이다.

메타층이란 무엇인가? 다섯 가지다.

AI는 코드를 잘 쓴다. 그런데 "무엇이 옳은지"는 정해 주지 않는다. 그 판단이 메타층이고, 그 판단은 사람의 몫이다. 이 과정은 그 판단을 훈련한다.

대상

수강생은 성인이다. 이미 AI 도구로 무언가를 빠르게 만들어 본 사람이다. 시작 한 번은 해봤지만, 끝까지 가지 못하거나 혼자 운영하기 막막했던 경험이 있는 사람이다.

설명은 중학생도 이해할 수 있게 쓴다. 이것은 수준을 낮추는 일이 아니다. 복잡한 일을 흔들리지 않게 이해하도록 만드는 일이다. 어려운 영어 단어는 처음 나올 때 반드시 쉬운 우리말을 함께 쓴다.

실습 난이도는 실무에서 실제로 쓸 수 있는 수준으로 둔다. 장난감 예제가 아니라, 자기 프로젝트에 바로 적용할 수 있는 계약과 게이트를 직접 만든다.

S0(선행 4차시)는 이 대상을 AI 완전 초급자까지 넓힌다. 아직 AI로 아무것도 만들어 본 적 없는 사람은 코어16 전에 S0(L00a~L00d)부터 완주한다. 코어16 이후 트랙은 여전히 S0를 마쳤거나 무언가를 한 번은 만들어 본 사람을 전제로 설계되어 있다.

이 과정이 가르치지 않는 것

"PRD를 멋지게 쓰는 문장력"

이 과정에서 PRD(제품 요구사항 문서)는 글쓰기 과제가 아니다. PRD는 "이 요구사항은 어떻게 확인하는가"라는 질문에 답하는 계약이다. 멋진 문장보다 확인 가능한 문장이 중요하다. 숫자, 상태, 파일, 명령 중 하나로 확인할 수 없으면 requirement(요구사항)가 아니라 wish(바람)다.

"특정 클라우드 버튼 누르는 법"

배포와 운영을 특정 서비스 버튼 순서로 가르치지 않는다. 배포는 "롤백(되돌리기)을 먼저 확보하고, 헬스체크(정상 작동 확인)가 통과한 다음 내보낸다"는 계약이다. 어느 클라우드를 쓰든 이 원리는 바뀌지 않는다.

"artifact review를 부록으로"

artifact review(생성물 검토)는 마지막에 잠깐 보는 장식이 아니다. 이 과정에서 검증은 모든 "완료" 주장의 최종 관문이다. PASS 확인 없이 차시를 끝내지 않는다. 증거 없는 완료는 없다.

이 과정이 생긴 이유

기존 AI 코딩 교육은 "아이디어 → 코드 생성 → 배포"를 빠르게 보여 준다. 그런데 실제로 만들고 난 뒤 어려운 일은 따로 있다.

• 기능이 늘어날수록 결정이 쌓이고, 어느 순간 무엇을 바꿔도 다른 것이 망가진다.
• AI가 만든 코드는 아무도 못 읽는다. 6개월 뒤 고치려면 처음부터 다시 써야 한다.
• 배포 후 무슨 일이 나는지 모른다. 사용자가 먼저 알고 나서야 안다.

이 과정은 그 빈 곳을 채운다. 기획부터 유지보수까지 전체 생애주기를 한 줄기로 연결하고, 그 줄기 위에 계약과 증거와 게이트를 놓는다.

코어 트랙 16차시 커리큘럼 맵

전체 생애주기(기획→빌드→검증→배포→운영→유지보수→성숙)를 16차시 2시간으로 압축한 한 척추(lifecycle-spine). 각 차시 카드는 레슨 작성자(사람·AI)의 콘텐츠 브리프다. 양식은 LESSON-TEMPLATE.md를 따른다.

전체 흐름

아이디어
→ 계약 문장(PRD)
→ 7대 결정 + 불확실성 원장(pm-seed)
→ feature contract + product surface + capability matrix
→ 5개 게이트 + evidence + artifact review
→ delivery manifest + 배포 계약 + clearance
→ 운영 계약 + 유지보수 계약
→ maturity 자가점검
→ 최종 발표/포트폴리오

모듈 ↔ 차시

• S0: L00a~L00d
• 기획: L01~L04
• 빌드: L05~L07
• 검증: L08~L10
• 배포: L11~L12
• 운영: L13
• 유지보수: L14
• 성숙: L15~L16

반복 실행 4명령 (검증 차시부터 등장)

npm test
node ./bin/contract-forge.mjs generate --input ./examples/hackathon-ai-tutor/input.json --out ./tmp-learning-output
node ./bin/contract-forge.mjs review --input ./examples/hackathon-ai-tutor/input.json
node ./bin/contract-forge.mjs review --input ./examples/hackathon-ai-tutor/input.json --artifacts ./tmp-learning-output

S0 (선행 4차시)

AI 완전 초급자를 위한 무료 선행 트랙. CLI 없이 4차시로 첫 제품을 만들어 본다. 코어16 L01 앞에 온다.

• L00a. 도구 지도를 읽는 법 — 무엇을 쓸지보다 무엇을 맡길지 — 오늘의 질문: 나는 AI에게 무엇을 맡기고 무엇은 내가 판단해야 하는가?
• L00b. 첫 세션 안전하게 열기 — 계정·한도·비밀 — 오늘의 질문: 돈과 비밀이 새지 않게 첫 실행을 여는 순서는?
• L00c. 장난감 하나 만들어 세상에 내놓기 — 오늘의 질문: 한 화면짜리 제품이 "됐다"는 걸 무엇으로 아는가?
• L00d. 왜 여기서 멈추는가 — 코드가 아니라 메타층 — 오늘의 질문: 6개월 뒤 이 장난감을 고쳐야 한다면 무엇이 막히는가?

L01. 진짜 병목은 코드가 아니다 (기획·토대)

• 오늘의 질문: 나는 왜 빠르게 만들었는데 끝까지 못 갔는가?
• 용어: meta-layer(메타층), data-vs-code(데이터 vs 코드), decision-bottleneck(결정 격차), AI의 6가지 도움.
• 레포 닻: docs/vibe-coder-bottleneck-analysis.md, docs/ai-vibe-coding-support.md, docs/product-lifecycle-for-vibe-coders.md.
• 실습: 과거 멈춘 프로젝트 1개를 "코드 문제 / 메타층 문제"로 분류. contract-forge를 한 바퀴 구경(generate+review).
• AI 6가지: 결정 이끌어내기 / 믿을 수 있는 게이트 / 가드레일 / 번역 레이어 / 빠진 것 비평 / 폴백·에스컬레이션.
• 실패 시 축소: 큰 비전 1개 → 수직 슬라이스 1개로 좁히기.

L02. 아이디어는 아직 제품이 아니다 (기획)

• 오늘의 질문: 내가 만들고 싶은 것은 누구의 어떤 문제를 해결하는가?
• 용어: problem/target user/user goal, MVP boundary(MVP 경계), one-thing rule(핵심 1개 사수/버릴 1개).
• 레포 닻: input.json의 problem/targetUsers/goal/mvpScope/nonGoals, docs/scope-governor.md.
• 실습: 문제 카드·사용자 카드·한 문장 goal·MVP 경계 1줄 작성. input.json에서 해당 필드 찾기.
• 실패 시 축소: 사용자 3명→1명, 기능 여러 개→행동 하나.

L03. PRD는 설명서가 아니라 계약이다 (기획)

• 오늘의 질문: 이 문장은 실제로 확인할 수 있는가?
• 용어: PRD, requirement, contract, verification, success criteria(이진 판정).
• 레포 닻: 생성물 prd.md, validation-checklist.md, input.json의 successCriteria.
• 핵심 규칙: 확인 방법(숫자·시간·상태·파일·화면)이 없으면 requirement가 아니라 wish.
• 실습: 애매한 문장 5개를 검증 가능한 계약 문장으로 변환.
• 실패 시 축소: 측정 어려운 목표는 MVP 제외, 성공 기준을 행동 하나로.

L04. 7대 결정과 불확실성 원장 (기획)

• 오늘의 질문: 무엇을 확정했고, 무엇을 아직 모르는가? 모르는 것도 종류가 다르다.
• 용어: 7 core decisions, assumption/decide-later/deferred-to-dev/stakeholder decision, false certainty.
• 7대 결정: 데이터vs코드 / 완성 기준 / 흐름 소유 / 실패 복구 / 상태와 blast radius / 토글과 버전 / 폴백 완주.
• 레포 닻: 생성물 pm-seed.json(4개 필드), prd-gap-analysis.md(누락 경고), docs/decision-interview-contract.md.
• 실습: 7대 결정 답 적기(못 정한 것은 원장으로), 불확실성 분류표 + false certainty 목록.
• 핵심 규칙: "나중에"만 적으면 실패 — 누가·언제·무엇 기준으로 정할지까지.
• 실패 시 축소: 결정 많은 기능은 MVP 제외, 승인 필요 문구는 임시 문구로.

L05. feature contract (빌드)

• 오늘의 질문: 기능 하나는 사용자에게 무엇을 약속하는가?
• 용어: feature contract, requirement_id(FC-01…), user promise, done_when.
• 레포 닻: 생성물 feature-contracts.yaml, data-contracts.yaml, input.json의 mvpScope/featureContracts.
• 핵심 규칙: 이름만 있으면 부족 — 약속·데이터·실패 상태·검증 기준을 붙인다.
• 실습: feature contract 카드 3개 작성.
• 실패 시 축소: feature 5개→3개, 핵심 흐름 밖 기능은 non-goal로.

L06. product surface 4상태 (빌드)

• 오늘의 질문: 사용자는 이 기능을 실제로 어떻게 경험하는가?
• 용어: product surface(제품 표면), loading/empty/error/success.
• 레포 닻: 생성물 feature-contracts.yaml의 UI 상태, docs/completeness-critic.md(null로 때우는 안티패턴).
• 실습: 한 기능의 4상태 스케치 + fallback 문구.
• 실패 시 축소: 복잡 화면→카드 UI 하나, 자동 처리→수동 입력 fallback.

L07. capability matrix (빌드)

• 오늘의 질문: 외부 기능이 없어도 흐름을 검증할 수 있는가?
• 용어: capability, real/local/stub/disabled, fallback-first(real→local→stub).
• 레포 닻: 생성물 capability-matrix.yaml(4모드·UI fallback·no-production-secret-in-repo 체크), input.json의 capabilities.
• 코드 사실: 기본은 local ON, real OFF(real은 requiresSecrets).
• 실습: capability matrix 작성 + disabled fallback 문구.
• 실패 시 축소: real provider를 MVP 밖으로, stub으로 발표 흐름 유지.

L08. 신뢰 검증 루프와 5개 게이트 (검증)

• 오늘의 질문: "됐다"를 무엇으로 믿는가?
• 용어: machine gate(기계 게이트) 5종 — test/static/build/secret-scan/fallback, evidence-backed(증거 기반).
• 레포 닻: docs/trustable-verification-loop.md, npm test, tests/*.test.mjs.
• 철칙: 모든 "done"은 최소 1개 게이트 출력으로 뒷받침. "아마 될 거예요" 금지.
• 실습: npm test 실행 후 결과를 증거로 읽기.
• 실패 시 축소: 폴백 완주도 게이트에 포함, 자기승인 금지(저자/검증 분리).

L09. evidence manifest 추적 (검증)

• 오늘의 질문: 요구사항은 어떤 증거 파일과 연결되는가?
• 용어: evidence manifest, requirement_id, verification_check, artifact_ref, sha256, memory policy.
• 레포 닻: 생성물 evidence-manifest.json(entries: requirement_id/verification_check/status/evidence/artifact_ref).
• 핵심 규칙: requirement는 있는데 evidence entry 없으면 누락.
• 실습: FC-01을 골라 evidence-manifest에서 증거 파일까지 손으로 추적.
• 실패 시 축소: 증거 못 만드는 요구사항은 MVP 제외 또는 manual validation으로.

L10. artifact review gate (검증)

• 오늘의 질문: 생성된 산출물을 믿어도 되는가?
• 용어: artifact review, required artifacts(17), JSON validity, hash/ref consistency, high finding vs medium warning.
• 레포 닻: review --artifacts, src/artifact-reviewer.mjs, 생성물 run-ledger.json.
• 실습: review --artifacts로 PASS 확인. 안전한 실패: 임시 폴더에서 run-ledger.json 이름 바꿔 high finding 만들고 되돌리기.
• 핵심 규칙: PASS만 보지 말 것 — high finding 있으면 다음 단계 금지, medium은 known gap/follow-up으로.

L11. delivery manifest와 배포 계약 (배포)

• 오늘의 질문: 안전하게 세상에 내보내려면 무엇이 필요한가?
• 용어: delivery manifest, code classification(experimental/core/reusable/adapter/temporary/presentation), managed hosting, env 분리, preview deploy, canary, rollback, health check.
• 레포 닻: 생성물 delivery-manifest.yaml(run/test/included/excluded/unverifiedAreas), docs/product-lifecycle-for-vibe-coders.md §4.
• 핵심: "내 PC에선 됨"은 배포 아님. 되돌릴 수 없으면 배포 금지(롤백 1버튼 먼저).
• 실습: delivery manifest + 코드 분류표 + 배포 계약 1장(헬스체크 기준·롤백 절차·점진 비율).
• 실패 시 축소: 자동 배포 어려우면 수동 롤백 절차라도 먼저 문서화.

L12. clearance-class 발행 게이트 (배포·보안)

• 오늘의 질문: 이 산출물을 밖으로 내보내도 안전한가?
• 용어: clearance class(INTERNAL/PUBLIC/METHOD), release gate(발행 게이트), proper nouns(고유명사), transformation rule.
• 레포 닻: docs/clearance-class-contract.md, 생성물 agent-contract.md의 외부 경계.
• 발행 게이트: PUBLIC 내보내기 전 고유명사 0·비밀(키/토큰) 0·원본 코드 0. 하나라도 걸리면 중단.
• 핵심: 사설 repo도 외부 전송. 비밀 한 번 새면 끝.
• 실습: push 전 grep로 키/토큰 스캔. 산출물에 clearanceClass 부여 + INTERNAL→PUBLIC 변환.
• 실패 시 축소: 변환 비용 크면 PUBLIC 범위를 METHOD(방법론만)로 줄인다.

L13. 운영 계약 (운영)

• 오늘의 질문: 보이지 않는 prod에서 무슨 일이 나는지 어떻게 아는가?
• 용어: observability(관측성), health check, kill switch(킬스위치), feature flag, incident runbook, SPOF/blast radius, cost monitoring, idempotency(멱등성).
• 레포 닻: docs/product-lifecycle-for-vibe-coders.md §5, docs/lessons-from-a-mature-live-product.md(L2 생존감지·L3 SPOF·L6 enforcement).
• 실습(CLI 실행 불가→계약 설계): 관측성 계약(무엇을 보고/언제 누구에게 알림) + SPOF 지도 + 킬스위치 목록 + 런북 1건 + 비용 알림 임계값.
• 핵심: 장애가 사용자보다 먼저 알림으로 와야 한다. 감지만 하고 처리 없는 telemetry는 함정.
• 실패 시 축소: 킬스위치 없으면 최소한 "끄는 절차"를 런북에.

L14. 유지보수 계약 (유지보수)

• 오늘의 질문: AI가 만든 못 읽는 코드를 어떻게 안전하게 바꾸는가?
• 용어: regression test(회귀 테스트), docs-as-contract, decision log(결정 로그), dependency bot, data migration contract, dead code cleanup.
• 레포 닻: docs/product-lifecycle-for-vibe-coders.md §6, docs/lessons-from-a-mature-live-product.md(L10 안 하는 것도 명시), 이 레포 자체가 docs-as-contract 예.
• 핵심: 못 읽는 코드를 살리는 길은 셋 — 회귀 테스트·docs-as-contract·결정 로그.
• 실습(계약 설계): 회귀 테스트 항목 목록 + 결정 로그 3건(결정·이유·대안) + 마이그레이션 계약 1장 + 임시 코드 제거 조건표.
• 실패 시 축소: 자동 의존성 봇 없으면 수동 점검 주기를 결정 로그에.

L15. maturity-checklist 자가점검 (성숙)

• 오늘의 질문: 이 제품은 정말 끝까지 갈 준비가 됐는가?
• 용어: maturity checklist(6층+10교훈+6게이트), binary check, status(pass/fail/unknown/na), mature 판정.
• 레포 닻: docs/maturity-checklist.md, schemas/maturity-checklist.schema.json.
• 6단계 게이트: planning/build/verify/deploy/operations/maintenance 각 통과 조건.
• 실습: schema 인스턴스 작성(checks[] + summary) + 6단계 게이트 통과/미통과 표.
• 핵심 규칙: unknown을 추측으로 채우지 말 것 — unknown은 다음 조사 항목. 증거 없는 pass 거부.
• 실패 시 축소: unknown이 많으면 mature 선언 대신 "다음 조사 목록"으로 정직하게.

L16. 최종 발표와 포트폴리오 (성숙)

• 오늘의 질문: 나는 빠르게 만든 결과를 끝까지 갈 수 있게 남겼는가?
• 용어: replayable evidence, run ledger replay, known gap/follow-up, contract pack, portfolio.
• 레포 닻: 생성물 run-ledger.json(input_ref/generated_files/sha256), contract-pack.md.
• 최종 제출물: input.json / pm-seed 7대결정·불확실성 / feature contract+surface+capability / evidence 추적 1건 / artifact review report(high 0) / 배포·clearance / 운영·유지보수 계약 / run ledger replay / maturity 점수 / downscope 전략.
• 발표 구조(7분): 문제·사용자 / 계약과 7대 결정 / 검증과 증거 / 배포·운영·유지보수 / maturity와 축소 전략.
• 완료 기준: npm test PASS · 17 artifact · brief review PASS · artifact review PASS · high 0 · medium은 known gap/follow-up.

L01. 진짜 병목은 코드가 아니다

모듈: 기획 · 2시간

1. 오늘의 질문

나는 왜 빠르게 만들었는데 끝까지 못 갔는가?

이 질문에 스스로 답할 수 있으면 오늘 수업은 성공이다.

2. 오늘 배울 용어

• meta-layer(메타층) — 코드 바깥에 있어야 하는 것들. 결정·검증·범위. 집으로 치면 설계도와 허가서.
• data-vs-code(데이터 vs 코드) — 실행 중 바뀔 수 있는 값(데이터)과 고정된 지시문(코드)을 구분하는 시각.
• decision-bottleneck(결정 격차) — 만들기는 빠른데 "무엇을 만들지"를 늦게 정해 막히는 현상.
• AI의 6가지 도움 — 바이브 코더가 AI에게서 실제로 받아야 하는 여섯 종류의 지원.

3. 쉬운 이야기

친구가 이케아 책장을 산다. 조립은 빠르게 끝냈다. 그런데 다음 날 보니 벽에 맞지 않는다. 치수를 미리 안 잰 것이다. 나사를 더 잘 조이는 기술이 문제가 아니었다. 재기 전에 조립을 시작한 것이 문제였다.

바이브 코딩도 똑같다. AI는 나사를 빠르게 조여 준다. 하지만 "어디에 놓을 책장인지", "몇 칸이 필요한지", "옮길 때 어떻게 하는지"는 AI가 대신 정해 줄 수 없다. 그것이 메타층이다.

케이스 스터디에서 반복된 패턴이 있다. 결정을 뒤늦게 내리고, 검증을 믿지 못하고, 범위가 조용히 커진다. 이 세 가지는 코드 문제가 아니라 메타층 문제다.

여기서 "데이터 vs 코드" 실을 한 번 건드리자. 어떤 것이 고정돼야 하고(코드처럼), 어떤 것이 바뀔 수 있어야 하는지(데이터처럼) — 이 구분을 설계 단계에서 하지 않으면 나중에 모든 것을 다시 짠다.

4. 실제 파일에서 찾기

아래 파일들을 열어 직접 눈으로 확인한다.

① 병목 분석 원문

파일: docs/vibe-coder-bottleneck-analysis.md

찾을 것: "핵심 인사이트 7" 섹션. 7개 중 1번을 읽는다.

예시로 보이는 것:

1. **병목은 결정.** 결정을 앞으로 당기고(interview), 안 정한 건 보이게(uncertainty ledger).

② AI 6가지 도움 표

파일: docs/ai-vibe-coding-support.md

찾을 것: "Part 1 — 필요한 6가지 도움" 표.

예시로 보이는 것:

| ① 결정 이끌어내기 | 7가지 결정을 모른 채 지나침 | interview — 빌드 전 결정을 질문으로 끌어내 계약으로 고정 |

③ 생애주기 전체 그림

파일: docs/product-lifecycle-for-vibe-coders.md

찾을 것: "0. 전제 — 바이브 코더의 불변 제약" 3가지 항목.

예시로 보이는 것:

1. 코드/시스템 세부를 **못 읽는다** → 평가 불가

5. 따라 하기

강사와 함께 contract-forge를 한 바퀴 구경한다. 실습은 안전한 임시 폴더를 쓴다.

5-1. contract-forge가 무엇을 만드는지 살펴보기

아래 명령은 예제 입력을 읽어 계약 산출물을 만드는 명령이다.

node ./bin/contract-forge.mjs generate \
  --input ./examples/hackathon-ai-tutor/input.json \
  --out ./tmp-learning-output

실행 후 보이는 것 (예시):

✓ Generated: tmp-learning-output/prd.md
✓ Generated: tmp-learning-output/feature-contracts.yaml
✓ Generated: tmp-learning-output/capability-matrix.yaml
✓ Generated: tmp-learning-output/pm-seed.json
...

흔한 오류: tmp-learning-output 폴더가 없다고 나오면 mkdir tmp-learning-output을 먼저 실행한다.

5-2. 리뷰 게이트 구경하기

아래 명령은 "됐다"를 기계가 판정하는 리뷰 명령이다.

node ./bin/contract-forge.mjs review \
  --input ./examples/hackathon-ai-tutor/input.json

실행 후 보이는 것 (예시):

PASS  prd.md — required sections found
WARN  pm-seed.json — 2 decide-later items without owner
...

흔한 오류: input.json이 없다고 나오면 경로를 ./examples/hackathon-ai-tutor/input.json으로 정확히 입력했는지 확인한다.

5-3. 내 프로젝트를 "코드 문제 / 메타층 문제"로 분류하기

강사가 칠판에 두 칸 표를 그린다. 수강생은 과거 멈춘 프로젝트 하나를 골라 아래 질문에 답한다.

• 멈춘 이유가 "기능을 못 만들었다"인가? → 코드 문제 칸
• 멈춘 이유가 "무엇을 만들지 헷갈렸다", "팀원과 기준이 달랐다", "언제 끝인지 몰랐다"인가? → 메타층 문제 칸

6. 혼자 하기

과제: 내 멈춘 프로젝트 분석표 작성

아래 빈칸을 채운다.

프로젝트 이름: _______________________

멈춘 시점: _______________________

멈춘 이유 (솔직하게 한 문장): _______________________

분류 (하나에 O 표시):
  [ ] 코드 문제 — 기능을 기술적으로 못 만들었다
  [ ] 메타층 문제 — 결정·검증·범위에서 막혔다
  [ ] 둘 다

메타층 문제였다면, 구체적으로 어디서 막혔나:
  [ ] 무엇을 만들지 정하지 못했다 (결정 격차)
  [ ] 됐는지 아닌지 모르겠다 (검증 불신)
  [ ] 만들 것이 계속 늘어났다 (범위 폭주)

7. 실패 상황

실패 1 — "코드는 됐는데 끝이 없다"

아래 상황을 읽고, 왜 위험한지 한 문장으로 말해 보라.

3주 동안 AI와 함께 기능을 40개 만들었다. 그런데 아직도 뭔가 부족한 느낌이다. 언제 끝인지 모르겠다.

왜 위험한가: 성공 기준(done의 정의)을 처음부터 정하지 않으면, 영원히 "조금만 더"가 반복된다.

실패 2 — false certainty(거짓 확신) 체험

아래 문장이 확정인가, 가정인가?

"사용자는 하루에 10번쯤 이 기능을 쓸 것이다."

이것은 가정이다. 누가, 언제, 어떤 데이터로 확인할지가 없으면 "10번"은 숫자처럼 보이는 희망사항이다. 이런 문장을 그냥 넘기면 나중에 메타층 전체가 틀린 전제 위에 서게 된다.

8. 보완할 것과 대안

분석표를 작성했는데 "코드 문제"가 하나도 없다면?

• 정직하게 다시 돌아본다. 코드 문제가 0개인 경우는 드물다.
• 반대로 코드 문제만 가득하다면, 메타층이 너무 잘 됐거나 아직 그 단계를 안 만난 것이다.

[실: 데이터 vs 코드] 지금 작성한 분석표는 데이터다. 고정된 코드가 아니라 언제든 다시 쓸 수 있는 값이다. 프로젝트가 바뀌면 이 표도 바뀐다. 그래서 파일로 저장해 두는 것이 의미 있다.

9. 실패 시 축소 전략

시간이 부족하거나 막혔을 때 핵심 약속을 살리는 방법(downscope).

• 큰 비전 → 수직 슬라이스 하나: "10개 기능 앱" 대신 "사용자 1명이 처음부터 끝까지 쓸 수 있는 기능 1개". 슬라이스 하나가 완주되면 나머지는 반복이다.
• 정교한 분류표 → 멈춘 이유 한 줄: 분석이 어려우면 "왜 멈췄나?" 한 줄만. 그것만 있어도 다음 프로젝트가 달라진다.
• contract-forge 전체 구경 → generate만: 시간이 없으면 generate 명령 하나만 실행해 산출물 목록을 눈으로 보는 것으로 대체한다.

10. 오늘의 워크시트

대응 워크시트: ../worksheets/W01-why-meta-layer.md

워크시트에서는 멈춘 프로젝트 분류표와 AI 6가지 도움 매핑표를 직접 완성한다. 수업 중 혼자 하기 과제와 연결된다.

11. 동료 리뷰 질문

짝과 서로 아래 질문으로 점검한다. "예/아니오"로 빠르게 확인한다.

1. 분류표에서 "메타층 문제"와 "코드 문제"를 구분할 수 있는가? 구분 기준을 한 줄로 설명할 수 있는가?
2. false certainty 예시(실패 상황 2)에서 "확정"과 "가정"의 차이를 자기 말로 설명할 수 있는가?
3. AI 6가지 도움 중 내 멈춘 프로젝트에 가장 필요했던 것이 무엇인지 하나 이상 말할 수 있는가?

12. 오늘의 단어장

증거 점검 질문: "결정 격차 때문에 멈췄다"고 말하려면 어떤 증거가 있어야 하는가? 내 분류표에 그 증거가 있는가?

13. 다음 차시 예고

다음은 L02. 아이디어는 아직 제품이 아니다.

오늘 "메타층이 빠져 있다"는 것을 알았다면, 다음 시간에는 그 메타층의 첫 번째 블록인 문제 정의·사용자·목표·MVP 경계를 직접 만든다. 오늘의 "결정 격차"가 다음엔 "결정을 어떻게 채울 것인가"로 이어진다.