심화 트랙 색인 (A01~A11)

코어 16차시를 마친 뒤 이어서 공부하는 심화 11차시다. 풀24 트랙은 A01~A08, 마스터27 트랙은 A01~A11 전체를 이수한다.

심화 차시 목록

트랙별 이수 범위

• 코어16: L01~L16만 이수. 심화 차시 없음.
• 풀24: 코어16 + A01~A08. 배포·운영·유지보수 영역을 깊이 다룬다.
• 마스터27: 코어16 + A01~A11 전체. 성숙·공통 축까지 완전 이수.

워크시트

각 심화 차시에 대응하는 워크시트는 worksheets/ 폴더에 있다. 차시를 마치면 대응하는 AW 파일을 열어 빈칸을 채운다.

A01. 프로덕션 6층 계약 — 기능 뒤에 숨은 여섯 개 약속

모듈: 빌드(심화) · 2시간

1. 오늘의 질문

"기능이 '완성'됐다고 할 때, 그 뒤에 아직 안 만든 약속이 몇 층이나 남아 있는가?"

이 질문에 6가지 항목으로 답할 수 있으면 오늘 수업을 제대로 들은 것이다.

2. 오늘 배울 용어

• production(프로덕션) — 실제 사용자가 쓰는 실서비스 환경. "내 PC에서 됨"과 다르다.
• state machine(상태 기계) — 어떤 것이 가질 수 있는 상태(예: 시작·진행·종료)와 그 사이 이동 규칙을 명시한 설계도.
• SPOF(단일 장애점, Single Point of Failure) — 이것 하나가 고장나면 전체가 멈추는 약한 고리.
• blast radius(폭발 반경) — 컴포넌트 하나가 죽었을 때 얼마나 많은 기능이 함께 죽는지 범위.
• confidence label(확신 라벨) — 내가 이 주장을 얼마나 확신하는지 표시. confirmed / likely / inferred 세 단계.

3. 쉬운 이야기

건물을 지을 때 '1층 벽'만 올렸다고 "집 완성"이라고 말하지 않는다. 지붕도 있어야 하고, 수도관도 있어야 하고, 비상구도 있어야 한다.

소프트웨어도 똑같다. 화면이 보이고 버튼이 눌리는 것은 1층일 뿐이다. 실서비스가 되려면:

• "이 데이터가 올바른지 어떻게 확인하나?" (1층: 데이터 검증)
• "주문이 어떻게 시작해서 어떻게 끝나나?" (2층: 상태 기계)
• "인터넷이 끊기면 어떻게 되나?" (3층: 실패 모드)
• "서버 하나가 죽으면 얼마나 넓게 피해가 퍼지나?" (4층: 운영 토폴로지)
• "기능을 끄거나 켜는 버튼이 있나?" (5층: 토글·버전)
• "이 구조를 처음 보는 사람이 추측 없이 파악할 수 있나?" (6층: 추출)

AI는 1층을 빠르게 만든다. 3~6층이 비어 있어서 실서비스에서 터지는 것이 바이브 코더의 가장 흔한 실패 패턴이다.

데이터 vs 코드 실: "화면 문구가 바뀔 수 있나? 바뀌면 코드를 건드려야 하나, 설정 파일만 바꾸면 되나?" — 이 차이가 1층 계약의 핵심이다.

4. 실제 파일에서 찾기

아래 파일들이 각 층의 살아 있는 예시다. contract-forge 레포에서 직접 열어 확인한다.

1층 예시 — 데이터/콘텐츠 검증:

• examples/hackathon-ai-tutor/output/validation-checklist.md
  • 열면 ## PRD 품질 게이트, error-count 항목이 보인다.
  • 이 파일이 "완성 판정 기계"다. error-count가 0이어야 1층 통과.
• examples/hackathon-ai-tutor/output/data-contracts.yaml
  • 열면 엔티티·필드·타입·검증 규칙이 한눈에 나열된다.

4층 예시 — 운영 토폴로지:

• examples/hackathon-ai-tutor/output/delivery-manifest.yaml
  • codeClassification 항목에서 각 모듈이 experimental / core / reusable / adapter 중 어느 역할인지 볼 수 있다.

5층 예시 — 토글·버전:

• examples/hackathon-ai-tutor/output/capability-matrix.yaml
  • 열면 각 capability가 real / local / stub / disabled 4모드 중 무엇으로 설정됐는지 보인다.
  • requiresSecrets: true 항목이 붙으면 real 모드는 빌드에서 물리적으로 제외된다.

6층 예시 — 추출/confidence:

• docs/production-contract-layers.md
  • 이 문서 자체가 6층 SOP를 담은 레퍼런스다. "8단계" 단락을 찾아 읽는다.

5. 따라 하기

이 차시는 실행 명령보다 계약 설계가 중심이다. 아래 단계는 기존 생성물을 읽고 6층 표를 채우는 흐름이다.

단계 1 — 생성물 확인

먼저 validation-checklist.md를 열어 1층이 이미 채워졌는지 본다.

파일 경로: examples/hackathon-ai-tutor/output/validation-checklist.md
확인할 것: "error-count == 0" 항목이 pass인지 fail인지

결과 예시:

## PRD 품질 게이트
- [x] error-count == 0   ← PASS 이면 1층 통과
- [ ] ...

흔한 오류: 파일이 없으면 node ./bin/contract-forge.mjs generate 를 먼저 실행해 생성물을 만든다.

단계 2 — capability-matrix 읽기

capability-matrix.yaml에서 각 capability의 모드를 확인한다.

파일 경로: examples/hackathon-ai-tutor/output/capability-matrix.yaml
확인할 것: mode 값이 real / local / stub / disabled 중 어느 것인지

결과 예시:

- id: CAP-01
  name: AI 튜터 세션
  mode: local          ← 지금은 local 모드(비밀키 없이 동작)
  requiresSecrets: false
  fallback: stub

흔한 오류: requiresSecrets: true인데 mode가 real이면 배포 시 비밀키 없이 터진다. local로 내리거나 stub fallback을 확인한다.

단계 3 — 6층 점검 표 손으로 채우기

아래 표를 워크시트(AW01)에 옮겨 직접 채운다. "있나" 칸에 O / X / 미확인 중 하나를 적는다.

흔한 오류: 모든 칸에 "O"를 적고 싶은 충동이 든다. 증거(파일·명령 출력)가 없으면 반드시 "미확인"으로 남긴다.

6. 혼자 하기

자기 프로젝트(또는 input.json을 수정한 버전)를 대상으로:

1. validation-checklist.md를 열어 1층 통과 여부를 확인하고, error가 있으면 이유를 한 줄로 쓴다.
2. capability-matrix.yaml에서 mode: real인 항목을 찾아 "이 항목이 stub으로 대체 가능한지" 판단한다.
3. 2층(상태 기계)이 지금 파일에 명시돼 있는지 찾아본다. 없으면 "2층 비어 있음 — 상태: 시작·진행·종료, 전이 조건 미정"이라고 적는다.

제출: 6층 표(단계 3) + 층별 근거 파일 경로 1개씩(없으면 "없음").

7. 실패 상황

실패 1 — 2층이 비어 있는 채 배포

세션이 "시작→종료" 외에 "중단됨" 상태를 갖지 않으면, 사용자가 브라우저를 닫고 다시 들어왔을 때 세션이 살아 있는지 죽은 것인지 코드가 모른다. 결과: 중복 과금 또는 데이터 유실.

왜 위험한가: 상태 전이를 공통 코드에 하드코딩하면, 나중에 "취소됨" 상태를 추가할 때 전체 코드를 뒤져야 한다.

실패 2 — 3층 없이 외부 API 사용

외부 AI API 타임아웃이 발생했을 때 감지 코드가 없으면, 사용자는 무한 로딩을 본다. 복구 계획도 없으면 수동 재시작이 유일한 방법이 된다.

왜 위험한가: 감지는 있는데 액션이 stub인 경우("telemetry만 있고 enforcement 없음")도 3층 미완이다. 로그만 남기고 아무 조치도 없으면 터진 후에도 계속 터진다.

실패 3 — 5층 없이 버그 배포

버그가 있는 기능을 끄는 버튼이 없으면 롤백이 유일한 방법이다. 롤백도 10분 걸리면 그 10분 동안 사용자 전체가 피해를 입는다.

8. 보완할 것과 대안

6층 중 하나라도 비었을 때 보강 방법:

• 1층 미완: data-contracts.yaml에 필드별 type / nullable / validation 추가. error-count가 0이 될 때까지 반복.
• 2층 미완: 상태 이름 3~5개와 전이 화살표를 텍스트로 적는 것만으로 시작. 그 다음 JSON Schema로 직렬화.
• 3층 미완: 실패 하나를 골라 {symptom, detection, recovery, terminality} 4칸을 채운다. 전부 한꺼번에 할 필요 없다.
• 4층 미완: delivery-manifest.yaml의 codeClassification에 stateful / stateless 한 칸만 추가해도 시작이다.
• 5층 미완: capability-matrix.yaml에 mode: stub을 추가하는 것이 가장 빠른 토글.
• 6층 미완: 레포 최상단에 "이 디렉터리 역할" 한 줄짜리 주석만 있어도 새 사람이 시작할 수 있다.

[실: 데이터 vs 코드 점검] — 지금 보완하려는 항목이 "실행 중에 바뀌는 값(데이터)"인가, "배포할 때 결정되는 코드"인가? 데이터라면 JSON/YAML 파일 수정으로 해결 가능하고 재배포 없이 바꿀 수 있다. 코드라면 배포 사이클이 필요하다. 이 구분이 5층(토글)의 핵심이다.

9. 실패 시 축소 전략

시간이 부족하거나 팀이 작을 때 6층 전부를 한꺼번에 만들 수 없다. 이때 핵심 약속을 살리며 줄이는 순서:

• 1층만 확보하고 나머지는 known gap 표로: 1층(데이터 검증)은 가장 싸게 만든다. 2~6층은 "비어 있음"을 문서로 명시하고, 각 층이 비어 있을 때 발생할 수 있는 위험을 한 줄씩 적는다. 모르면 모른다고 쓰는 것이 추측보다 낫다.

• 2층 축소: 전체 상태 기계 대신 "가장 중요한 실패 전이 하나"만 명시. 예: "결제 진행 중 → 실패" 전이 하나를 먼저 잡는다.

• 3층 축소: 모든 실패 모드 대신 "가장 자주 터지는 실패 1개"에만 감지+복구를 만든다. 나머지는 Unknown / 미구현 라벨로 남긴다.

• 4층 축소: 전체 토폴로지 지도 대신 "SPOF가 어디인지 한 줄"만 적는다. 예: "캐시 서버 1대가 단일 진실 원천이며 SPOF다."

• 5층 축소: 런타임 토글이 없으면 capability-matrix.yaml의 mode를 stub으로 내리는 것만으로 기능을 끄는 효과를 낸다.

• 6층 축소: 전체 SOP 대신 confidence: inferred로 라벨을 붙이고 검증이 필요한 항목 목록만 남긴다.

10. 오늘의 워크시트

대응 워크시트: ../worksheets/AW01-production-6-layers.md

이 워크시트에서 완성하는 것:

• 내 기능 1개에 대한 6층 점검 표(각 층: 있나/비었나/근거 파일)
• 비어 있는 층에 대한 known gap 1줄 설명 + 보강 계획 한 줄

11. 동료 리뷰 질문

짝과 서로 점검한다.

1. 6층 표에서 "O(있음)"으로 표시한 항목마다 근거 파일 경로가 실제로 적혀 있는가? 경로가 없으면 "미확인"으로 바꿔야 한다.
2. 3층(실패 모드) 칸에 "감지"만 있고 "복구 액션"이 비어 있지 않은가? telemetry만 있고 enforcement가 없으면 미완이다.
3. 실패 시 축소 전략에서 "핵심 약속 1개"가 명확히 적혀 있는가? "다 줄인다"가 아니라 "이것만은 살린다"가 있어야 한다.

12. 오늘의 단어장

[실: false certainty 점검] — 위 표에서 내가 채운 설명 중 "이건 확실히 맞다"고 느끼는 칸을 하나 골라라. 그 설명을 뒷받침하는 파일이나 명령 출력이 있는가? 없으면 likely 또는 inferred 라벨을 붙인다.

[실: 증거 없는 완료 금지 점검] — 오늘 채운 6층 표에서 "O"로 표시한 항목이 있다면, 각각에 대해 "어느 파일의 어느 줄이 이것을 증명하는가?"를 말할 수 있는가? 말할 수 없으면 "O" → "미확인"으로 되돌린다.

13. 다음 차시 예고

다음 차시 A02 — agent contract와 completeness-critic에서는, 오늘 찾은 "비어 있는 층"을 AI 구현 에이전트에게 "여기까지만 만들어라"라고 경계를 그어 주는 계약으로 바꾼다. 오늘의 6층 점검 표가 A02의 시작 재료가 된다.