SESSION 03 / 06
문서를 깎고,
만들고, 연결합시다
정본 · Spec · 피라미드 · 100줄
지준영
비전공(경영학과) → 기자 · 해외영업 → 개발자 전향
iOS · Android · Frontend 약 5년 반 (6년차)
대기업 협업툴 iOS/macOS 앱 개발
2026~ 바이브코딩으로 웹 · 서버 1인 개발 · 사업화
PART 1 — 복기
버셀, 수파베이스
올려보셨어요?
안 해봤어도 상관 없습니다.
RECAP · 1화·2화
Claude가 보는 문서 · 다시 짚고 갑니다
2화 식당 비유 — 다시 한 번
Claude는 매번 새 알바생. 어제 한 일 기억 못 함.
주방 벽에 조리 규칙표를 붙여놔야 매번 같은 맛이 납니다.
그 조리 규칙표 =
CLAUDE.md — Claude가 무조건 읽도록 약속된 마스터 파일.
대문자로 정확히 명명한 이 파일은 시스템적으로 자동 인식.
큰 프로젝트 — 부서별 규칙표가 따로:
오늘 — 이 규칙표들을 어떻게 깎고, 만들고, 연결하느냐.
ORG CHART · 비유
회사 조직도 = Claude 문서 위계
머릿속의 회사 큰 그림 = 기획서 · PRD
기획서·PRD를 회사 전체가 따라가도록 적은 마스터 규칙
위에서 받은 규칙이 바뀌면 우리 부서는 어떻게 행동할지
부서별 규칙 — 홀 규칙 / 주방 규칙
현장에서 실제로 일하는 사람들
세부 명세 문서들
CANON — SINGLE SOURCE OF TRUTH
정본 — 개발에서의 의미
정본 = Single Source of Truth
줄여서 SSOT
어떤 정보든,
진짜 원본은 딱 한 곳에만 있어야 합니다.
영어권 용어 — Canonical
Canonical = 'Canon(기준·법·정경)'에서 파생된 형용사. "표준의, 정식의".
CS에서는 — 여러 표현 중 '정본으로 지정된 하나의 형식'.
예 — Canonical URL (중복 URL 중 대표) · Canonical form (2/4, 4/8 → 1/2로 정규화)
정본 · SSOT · Canonical — 세 개가 같은 얘기.
예시
직원 연락처가 인사팀·총무팀·팀장 엑셀 세 곳에 있음.
한 명이 번호를 바꿨는데 인사팀 엑셀만 바뀜.
→ 나머지 두 곳은 옛날 번호.
→ 어느 게 진짜인지 아무도 모름.
소프트웨어에서도 동일합니다. 같은 설정 값이 세 곳에 분산되어 있으면,
하나를 고쳤을 때 나머지가 안 바뀌면서 버그가 나옵니다.
CANON · REFERENCE · SPEC
정본 · 참조 · Spec — 실제로 어떻게 작동하는가
예 ① · 원료가공실의 정본
"우리 회사는 플라스틱을 280도로 녹여서 제품을 만듭니다."
→ 이 정보는 원료가공실 문서 한 곳에만 있어야 함.
→ 제작실·기계실은 이 한 곳을 참조해야 함.
→ 누가 290도로 바꾸고 다른 실에 안 알리면 → 사고.
예 ② · 기계실의 정본 + owner
"우리 회사 기계는 ABC-150 모델. 녹이는 온도는 원료가공실이 기준. 생산량 조절·기계 켜고 멈추기·업그레이드 후 시운전은 기계실 직원에게 먼저 물어보세요. 기계실이 그 다음에 원료가공실·제작실에 변경사항 공유."
→ 정본 + 변경 owner(진입점)까지 못 박아둔 상태.
→ 자기 담당 영역과 남의 영역을 정확히 분리해서 인지.
→ 안 정해두면 — 다른 실끼리 헛짓을 시작합니다.
정본의 두 조건 (AND):
① 한 곳에만 있다 + ② 다른 모든 곳은 그 한 곳을 참조한다
하나라도 깨지면 — 같은 정보가 두 곳에 다르게 적혀, 사람도 AI도 어느 게 진짜인지 모름. = 사고.
왜 Claude에게
정본이 중요한가
Claude는 판단 못 합니다.
작업이 증발합니다.
"이 문서가 원본이다."
이 한 줄이 프로젝트를 살리고 죽입니다.
DOC TYPES — 5 CATEGORIES
문서를 5가지 차원으로
제품 컨셉 · 누구를 위해 · 왜
기술 선택 · 시스템 구조 · 데이터 모델
UI · 디자인 · 화면 · 색 · 폰트
서버 · 호스팅 · 인프라 · 환경 변수
⑤ 정본·참조 트리거 —
웹 · 서버 · 안드로이드 · iOS 중 두 개체 이상이 공유해야 하고,
Claude가 헷갈릴 여지가 조금이라도 있으면
→ 그 영역은 뭐든 정본이 될 수 있다.
Spec / Design 문서가
왜 필요한가
Spec이 없으면 AI는 추측합니다.
추측이 100개, 200개 쌓이면
어디서부터 틀어진 건지 추적이 안 됩니다.
뭐가 틀렸는지 바로 보입니다.
비교할 기준 자체가 없습니다.
도면 없이 집 짓는 사람은 없습니다.
도면이 Spec이고, 집이 코드입니다.
한 줄 예시
한 줄 예시로 굳히기
정확한 수치 — 정본.
한 줄이 정본, 모든 공장이 이 한 줄을 참조.
290°C로 바꿨는데 통보 안 하면 → 사고.
911 · 파나메라 · 카이엔 · 타이칸 —
모두 한눈에 포르쉐임을 알 수 있는 룩.
플라이라인 · 헤드램프 시그니처 · 비례.
디자인 정본은 한 곳, 공장은 분산
모든 모델 디자인 한 곳에서 결정.
911 · 파나메라 · 카이엔 — 공장 다 흩어짐.
정본이 없다면 → 각 공장 디자이너가 알아서 추측.
911엔 어울리는 곡률, 카이엔엔 어울리는 곡률 — 따로 따로.
→ 한눈에 포르쉐인지 알 수 없게 됩니다.
둘 다 정본이 될 수 있다.
업무규칙 상 — 어느 부서가 그 문서를 관리하고,
다른 부서는 읽고 업무 진행에 참고만 해야 하는가?
→ 이 한 가지를 고민하면 됩니다.
PART 2
문서의
위계
오늘 수업의 핵심.
HIERARCHY
수정은 위에서 아래로만
↓
↓
↓
↓
코드부터 바꾸면
문서와 코드가 어긋나기 시작합니다.
문서 간 연결
"이 문서는 저 문서를 참조한다"를
AI에게 명시하세요.
안 그러면 AI가 전혀 다른 문서를 보고
엉뚱한 방향으로 작업합니다.
SINGLE RESPONSIBILITY · ATTENTION
한 파일에 — 다 때려넣지 마라
감 잡는 척도 ≈ 100줄 내외 (절대 임계값 X)
백엔드 개발자들이 평생 이 어휘로 코드를 쪼갭니다 — 왜?
사람 머리도 한 파일에서 길을 잃기 때문. AI도 똑같습니다.
너무 짧으면 맥락 부족.
너무 길거나 내부 질서가 없으면 AI가 안에서 길을 잃습니다.
한 파일에 이런 게 다 섞이면 AI가 정신 나감:
학계 용어도 있어요 — Context Rot (맥락 부패).
긴 문서에서 어텐션이 무너지는 현상.
줄 수가 다는 아닙니다 — 두 축으로 봐야
① 줄 수 (LOC) + ② 순환 복잡도 (Cyclomatic Complexity)
비유 — 같은 50m 도로 두 개
같은 거리, 결정 0번 vs 5번. 처음 가는 길에서 한 번 잘못 꺾으면 다른 동네.
코드도 똑같음. 같은 50줄, 분기 0개 vs 12개 → AI가 한 갈래 잘못 들면 엉뚱한 동네로.
업계 표준 CC ≤ 10 · SonarQube·ESLint가 자동 측정 (1976, McCabe).
즉 — 이 원칙은 CLAUDE.md 문서에만 적용되는 게 아닙니다. 여러분의 웹·백엔드 코드도 똑같이.
해결 — 파일을 쪼갠다.
줄 수 길거나 분기 빽빽하면 Claude한테 *"이 파일 쪼갤 수 있을까?"*
개발 업계 50년 원칙: 관심사 분리(Separation of Concerns)
외울 필요 없음. "이런 단어가 있다"만.
이 회사 구조 —
누가 만들었어요?
사람이 만들었습니다.
조직도 그리고, 부서 분담하고, 정본 정하고, owner 박아둔 거.
이렇게 만들어놨기 때문에 회사가 굴러갑니다.
하물며 AI는요?
AI는 이런 구조를 스스로 못 만듭니다.
사람도 만들어줘야 굴러가는데, AI는 더더욱.
사람이 줘야 합니다. 그 구조가 — 문서입니다.
PART 3
10원칙 복기
+ 오늘 다룰 4원칙
2회차 REVIEW
오늘 여기에 3가지를 더 추가합니다.
TODAY · 3 NEW PRINCIPLES
오늘 추가할 원칙 3개
이 셋, 하나씩 풀어 갑니다.
단, 본사에 목줄 찬 똑똑함입니다.
본사가 규정을 바꾸면,
여러분은 이유도 모른 채로
"오늘 클로드 좀 이상한데?"를 느끼게 됩니다.
EVIDENCE
클로드 퍼포먼스 변동
— 실제 보고
2026년 4월 — GitHub, Reddit, X
Anthropic이 서버비 절감을 위해
기본 노력 수준을 'medium'으로 낮춤.
사용자에게 알리지 않음.
Claude Code 리더가 직접 해명에 나설 정도.
특정 벤치마크에서 Opus 4.7이 일부 점수 하락 사례도 보고.
AI 회사도 기업입니다. 기업 사정에 따라 제품 품질이 변합니다.
이게 과장 광고를 경계해야 하는 근본적인 이유입니다.
1·2화 콜백
딸깍코딩·딸깍사업은 없다
1·2화에서 박은 메시지 — "이거 얘기했죠?"
그런데 오늘 — 이 긴 시간 동안 문서를 깎고 연결하는 얘기를 다뤘죠.
정본 → 위계 → 100줄 → 시연 …
이상하지 않으세요?
유튜브·인스타에선 — "딸깍이면 다 된다"고 하죠?
"AI한테 시키면 끝, 코딩 몰라도 OK"
그게 얼마나 허황된 건지 —
실제 개발자 톡방에서 나오는 얘기로 보여드립니다.
COMMUNITY EVIDENCE
매일 상태 다르다 — 저만의 경험이 아닙니다
개발자 커뮤니티 카톡방 · 최근 며칠 (닉네임·프로필 익명 처리)
AI는 '품질을 보장하는 공공재'가 아닙니다.
'매일 상태가 달라지는 서비스'입니다.
방어 3종 — ① 감 점검 루틴 ② 도구 다변화(클로드·제미나이·코덱스) ③ 커뮤니티 참여
자기 답을 옹호하는 게 본능입니다.
Claude → Gemini, Codex
또는 그 반대로 던져봐도 됩니다.
현업에서는 코드 작성과 코드 리뷰를 서로 다른 AI로 분리 운영합니다.
교차검증을 적극 활용하십시오.
:
비율이 뒤집히면 대부분 2주 안에 포기합니다.
처음부터 확인하기 쉬운 크기로 쪼개서 던지세요.
10 PRINCIPLES — 8/10
■ 오늘(3화)에서 다룬 원칙 · ■ 2화에서 다룬 원칙 · ■ 이후 회차
10원칙 중 8개를 다뤘습니다 — 오늘 새로 박은 게 3개(#1·#5·#9).
나머지 2개(#7·#8)는 이후 회차에서.
10분 휴식
PART 4
Claude에게
물어보기
Claude한테 이것들을
물어보세요.
CLAUDE.md를 어떻게 구조화해야 해?
PLANNING.md는 뭘 적어야 해?
PRD가 뭐야? Spec이 뭐야? 차이가 뭐야?
내 프로젝트에 필요한 문서 구조를 제안해줘
HOMEWORK PROMPTS · 5
집에 가서 — 이렇게 다시 물어보세요.
Q1 · 정본 점검
"내 프로젝트에 정본 개념이 필요해 보이는 문서가 있어?"
Q2 · 웹·백 공유 문서 + owner
"웹과 백이 둘 다 공유해야 하는 문서가 있는데, 그런 것들은 뭐지? 이런 경우엔 정본을 누가 들고 있어야 하지?"
Q3 · 부서별 문서 구체화
"Design·아키텍처뿐만 아니라, 웹과 백은 각각 어떤 문서를 들고 있어야 하지?"
Q4 · 백 인프라 문서
"백은 인프라스트럭처 관련 문서를 어떻게 구성해놔야 하지?"
Q5 · 시각적 다이어그램
"문서 간 참조 관계, 정본과 복사본 관계, 문서 간 위계 피라미드 관계 — 이걸 다이어그램 같은 시각적인 HTML로 만들어줘. 내가 눈으로 좀 확인해보려는 게 목적이야."
TODAY'S KEY TAKEAWAY
BONUS — AI 취조 3축
PART 5
오늘의
숙제
집에서 해보세요.
• PRD.md = 제품 요구사항 문서 (무엇을·누구를 위해·왜)
• CLAUDE.md = Claude가 무조건 읽는 규칙 문서
없으면 Claude한테 만들어달라고 시키세요.
• 참조 작업 시작되면 → "md 안에 어떤 내용이 추가되고, 어떤 이유로 클로드가 그걸 읽어?"
정본·참조가 글자가 아니라 AI가 따라가는 메커니즘임을 체감.
그대로 적용할 필요 없음. 구조 제안서가 있다는 것 자체가 시작.
업계 용어: Domain Knowledge. 바이브코딩 시대 — WHAT·WHY가 사람 몫. 정리·설명력이 그 어느 때보다 중요.
SESSION 03 / 06
오늘도
수고하셨습니다.
다음 시간 — 4회차.
F12 누르면 다 보인다 — 바이브코딩 보안의 현실.
OPEN CHAT
질문이 생기면
카카오톡 오픈채팅을 이용해주세요.