이 과정의 전체 지도

하루 과정이면 1부만 합니다. 2부까지 가려면 이틀 또는 4주(주 1회)가 필요합니다.

제일 먼저 정할 것 — 「완성」이 무엇인가

초보자가 가장 많이 헷갈리는 것이 이겁니다. AI가 화면을 보여주면 다 된 줄 압니다. 아닙니다.

첫 프로젝트 — 추천 세 유형

셋 다 로그인이 없습니다. 로그인이 들어가면 「누가 누구인지」를 기억해야 하니 창고가 생기고, 만들 것이 두 배가 됩니다. 첫 프로젝트에서는 피합니다.

고르는 기준 — 하나로 충분하다

틀렸을 때 알 수 있고, 틀려도 되돌릴 수 있는가.

이 과정은 막히는 지점에서 배웁니다. 그래서 막힐 조건이 없거나, 막히면 돌이킬 수 없는 것은 교재가 못 됩니다. 아래 여덟 줄이 전부 이 한 문장에서 나옵니다.

좋은 것 — 왜 좋은가

피할 것 — 왜 피하나

계정 — 넷이면 된다

클로드는 두 가지 모습이 있다

둘 다 같은 순서로 배웁니다. 차이는 하나 — AI가 내 파일을 직접 만지느냐, 내가 복사해서 옮기느냐.

첫 세팅 — 순서대로 20분

1. 폴더 하나를 만든다 — 이름은 영어·소문자·붙여서 (예: cardnews). 한글·띄어쓰기는 나중에 사고가 납니다
2. 그 폴더에서 Git을 시작한다 — AI에게 「이 폴더의 변경을 기록하게 해줘」 한 줄
3. 규칙 파일을 하나 만든다 — 처음엔 두 줄. 「모르면 모른다고 해라」 「됐다고 하지 말고 결과를 보여라」. 05차시에서 자랍니다
4. AI에게 「이 폴더를 읽고 뭐가 있는지 말해줘」 — 첫 대화
5. GitHub에 빈 저장소를 만들어 둔다 — 2부에서 씁니다

Git — 두 개념만

여기서 미리 못 박아야 하는 것

먼저 — 이 과정은 어느 도구로 하나

다른 도구를 써도 여섯 단계는 같습니다. 명령어 이름만 다릅니다.

터미널이 처음이라면

맥은 「터미널」, 윈도우는 「PowerShell」이라는 앱입니다. 검은 창에 글자를 쳐서 컴퓨터에 시키는 곳입니다. 마우스로 하던 일을 글자로 합니다.

터미널을 열면 이렇게 생겼다

# 터미널을 처음 열면 이 줄 하나가 있다
~ %

# 지금 어디 있는지
~ % pwd
/Users/byeonggeun

# 이 폴더에 뭐가 있나
~ % ls
Desktop    Documents    Downloads

외울 명령 하나 — cd (폴더로 들어가기)

~ % cd Documents

# 폴더를 만들고 그 안으로
~/Documents % mkdir cardnews
~/Documents % cd cardnews

# 한 칸 위로 나가기
~/Documents/cardnews % cd ..

외울 명령 둘 — claude (그 폴더에서 켜기)

~/Documents/cardnews % claude

✻ Claude Code  v2.x · claude-opus-5
  ~/Documents/cardnews

  /help 를 치면 할 수 있는 것이 나옵니다

> 이 폴더를 읽고 뭐가 있는지 말해줘

1 · 설치 — 한 줄

# 맥 · 리눅스
curl -fsSL https://claude.ai/install.sh | bash

# 윈도우 PowerShell
irm https://claude.ai/install.ps1 | iex

# 됐는지 확인 — 버전 숫자가 나오면 성공
claude --version

2 · 로그인 → 3 · 시작

# 내 프로젝트 폴더로 간다
cd 폴더경로

# 클로드를 켠다 — 처음이면 브라우저 로그인 창이 뜬다
claude

4 · 첫 질문 — 한국어로

이 프로젝트가 뭐 하는 거야?
어떤 기술을 쓰고 있어?
폴더 구조를 설명해줘

5 · 첫 수정 — 물어보면 「예」

「메인 파일에 인사 함수 하나 넣어줘」 정도를 시켜 보십시오. 클로드가 고칠 내용을 보여주고 허락을 묻습니다. 「예」를 고르면 고쳐집니다.

외울 것 — 이게 전부

/clear가 제일 중요합니다. 05차시에서 「두 번 고쳐서 안 되면 비우고 다시」가 나옵니다.

초보자 요령 — 공식 문서 넷

1. 구체적으로. 「버그 고쳐」 ✗ → 「로그인 후 빈 화면 나오는 버그 고쳐」 ✓
2. 단계로 쪼개서. 「1. 표 만들고 2. 화면 만들고 3. 연결해」
3. 먼저 살펴보게. 고치기 전에 「이 구조부터 분석해줘」
4. 동료에게 말하듯. 무엇을 이루고 싶은지를 말한다

출처 — Claude Code Quickstart, 「Pro tips for beginners」

다른 도구를 쓴다면

AI를 쓰다 보면 처음 보는 말이 계속 나옵니다. 전부 알 필요는 없습니다. 다만 자주 나오는 예닐곱 개는 알아야 대화가 막히지 않습니다. 전체 목록은 부록 F · 말 풀이에 있고, 여기서는 제일 자주 나오는 것만 봅니다.

API — 다른 프로그램에 일을 부탁하는 창구

식당의 주문서 양식과 같습니다. 양식대로 적어 내면 정해진 대로 나옵니다.

MCP — AI에게 도구를 꽂아 주는 규격

Model Context Protocol. AI는 말은 하지만 손이 없습니다. 내 파일도 못 열고 노션도 못 봅니다. MCP는 그 손을 꽂는 콘센트 규격입니다. 규격이 같으니 아무 도구나 꽂힙니다 — 내 파일, 노션, 구글, 데이터베이스, 회사 시스템.

첫 프로젝트에서는 둘 다 필요 없는 경우가 많습니다. 필요해지는 시점은 「AI가 내 자료를 봐야 할 때」입니다.

나머지 자주 나오는 말 — 한 줄씩

이 여섯 개면 대화가 안 막힙니다. 더 나오면 그때 부록 F를 보거나 물어보면 됩니다.

공식문서 — 다 읽을 필요는 없다. 그런데 안 보면 문제가 생긴다

AI는 배운 시점의 지식으로 답합니다. 도구가 바뀌면 사라진 기능을 쓰라고 하거나 예전 방식으로 코드를 씁니다. 이 교재 실습 저장소의 규칙 파일 첫 줄이 그것 때문에 있습니다 — 「이건 네가 아는 그 프레임워크가 아니다. 코드를 쓰기 전에 설치된 문서를 읽어라」.

다 안 읽고 쓰는 법 — 네 가지

1. AI에게 문서 주소를 준다 — 「이 페이지 읽고 답해줘」. 제일 빠르고 정확합니다
2. 「최신 문서를 확인하고 답해라」를 프롬프트에 붙인다
3. 「모르면 모른다고 해라」 — 지어낸 답을 걸러 내는 한 줄
4. 버전과 날짜를 묻는다 — 「이 방법은 언제 기준이야?」

1번이 압도적으로 낫습니다. 문서 한 페이지를 통째로 읽히면 AI가 추측할 일이 없어집니다.

이 문서를 읽고 답해줘: https://...

- 문서에 없는 건 지어내지 마라. 없으면 "문서에 없다"고 해라.
- 답할 때 문서의 어느 부분에서 나왔는지 같이 적어라.
- 문서의 기준 날짜·버전이 있으면 알려줘.

긴 문서를 4분 만에 — 어디부터 보나

3번을 건너뛰면 배포가 조용히 거절되는 일이 생깁니다 — 06차시에서 실제로 겪었습니다.

믿을 문서와 참고만 할 것

이 교재의 참고 영상에 「내용을 검증하지 않았습니다」라고 적어 둔 이유입니다.

한 줄 정의

SDD(Spec-Driven Development, 명세 주도 개발) — 코드를 짜기 전에 무엇을 만들 건지 글로 먼저 못 박는다.

기획서와 다른 점은 읽는 사람입니다. 기획서는 결재하는 사람이 읽고, 명세서는 만드는 쪽이 읽고 그대로 만듭니다.

「한 걸음」이 무슨 뜻인가

이 교재에서 한 걸음은 이런 뜻입니다.

한 번에 시켜서 끝내고, 화면을 열어 맞는지 틀린지 판단할 수 있는 작업 한 덩어리.

걸음이 커질수록 「해줘」에 가까워집니다. 확인할 수 없는 크기로 시키면 확인을 안 하게 되고, 확인을 안 하면 쌓입니다.

절차 — 이 순서로 한다

1. 원본을 연다. 요청서·회의 녹취·계약서 원본을 찾아 연다. 남이 정리해 둔 요약본으로 시작하지 않는다 — 요약하면서 빠지는 것이 대개 제약 조건이다.
2. 「한 문장」부터 쓴다. 「누가 무엇을 하면 무엇이 나온다」 한 문장. 한 문장에 안 들어가면 아직 정리가 안 된 것이므로 여기서 멈추고 더 묻는다.
3. 「왜 만드나」를 쓴다. 이게 없으면 무슨 일이 생기는지. 목적이 흔들리면 나중에 완성 기준이 통째로 바뀐다.
4. 「누가 쓰나」를 쓴다. 숙련도·기기·빈도까지. 뒤의 모든 결정이 여기서 나온다.
5. 「안 하는 일」을 쓴다. 명세서의 절반이다. 적지 않으면 AI가 빈칸을 알아서 채운다.
6. 입력·출력을 숫자로 쓴다. 글자 수·개수·크기·형식. 「적당히」가 하나라도 남으면 그 자리에서 결과가 갈린다.
7. 완성 기준을 체크박스로 쓴다. 「잘 되면」은 기준이 아니다. 켜고 끄듯 판정할 수 있어야 한다.
8. 기존 코드를 열어 본다. 무엇이 이미 있고 무엇이 없는지 확인한 뒤 「새로 만들 것」을 적는다. 현실을 모르고 쓴 명세는 쓸 수 없는 명세다.
9. 모르는 것은 물음표로 남긴다. 지우지 않는다. 추측으로 채우는 순간 그게 나중에 사고가 된다.
10. 고칠 때마다 이유를 한 줄 남긴다. 명세서는 한 번 쓰고 끝내는 문서가 아니라 매일 고치는 파일이다.

끝까지 한 번 — 「한 문장」이 세 번 바뀐 기록

1번 칸은 쉬워 보이는데 실제로는 제일 자주 틀립니다. 이 프로젝트에서 어떻게 바뀌었는지 그대로 보여드립니다.

첫 번째 — 회의록을 보고 쓴 것

상인회 담당자가 단톡방 소식을 복사해 붙여넣으면, 채널에 올릴 카드뉴스 두 장이 나온다.

→ 그럴듯해 보였고, 실제로 이대로 명세서를 다 썼습니다.

두 번째 — 원본을 열어 보니 「두 장」이 틀렸다

요청서 원문에는 이렇게 적혀 있었습니다.

1p 상권 캘린더 / 2p~ 개별 매장 소식

물결표 하나가 붙어 있었습니다. 「2p부터 여러 장」이라는 뜻입니다. 그런데 내가 정리한 문장에는 「두 장」으로 굳어 있었고, 명세서 「안 하는 일」에는 「3p 이상은 만들지 않는다」고까지 적혀 있었습니다. 요구사항을 정반대로 못 박은 것입니다.

…채널에 올릴 카드뉴스가 나온다.

세 번째 — 목적을 듣고 나니 문장이 방법이었다

이 기능을 왜 만드는지 물었더니 답이 이랬습니다.

본질은 프로젝트가 끝나도 상인·상인회 모두가 카카오 채널을 계속 쓰게 하는 것이다.

그러면 카드뉴스는 목적이 아니라 수단입니다. 1번 문장은 그대로 두되 2번 칸(왜 만드나)을 다시 썼고, 그 여파로 두 칸이 더 바뀌었습니다.

7번에 새로 붙은 줄은 이렇습니다 — 「교육 종료 4주 뒤에도 그 채널에 소식이 올라오고 있다.」 이건 개발이 끝난 날에는 확인할 수 없는 기준입니다. 목적이 바뀌면 이런 것까지 바뀝니다.

끝까지 한 번 더 — 「안 하는 일」은 어떻게 나오나

5번 칸이 제일 어렵습니다. 빈칸을 보고 있으면 아무것도 안 떠오릅니다. 질문을 바꾸면 나옵니다.

왜 별도 단계인가

AI에게 「예쁘게」라고 하면 평균값이 나옵니다. 그리고 마음에 안 들면 다시 시키고, 또 다시 시킵니다. 이 왕복이 「해줘」가 되는 지점입니다. 시안은 그 왕복을 앞으로 당겨 한 번에 끝내는 장치입니다. 코드가 없으니 고치는 데 몇 분이면 됩니다.

절차 — 이 순서로 한다

1. 작업 종류를 한 줄로 판정한다.
   이것은 〈누가〉 〈어디서〉 〈몇 초〉 보는 〈무엇〉이다. 틀렸을 때 제일 아픈 것은 〈무엇〉이다.
   이 줄을 건너뛰면 엉뚱한 규칙집을 집어 듭니다.
2. 층 ① — 숫자 기준을 적는다. 공개 표준에서 가져올 수 있는 것부터 적습니다(아래 표).
3. 층 ② — 질문 여섯 개에 답한다. 취향을 묻지 않습니다.
4. 층 ③ — 하지 않을 것을 적는다. AI의 기본값을 미리 막습니다.
5. 시안을 두 안으로 만든다. 한 안만 만들면 「이게 맞나」밖에 못 묻습니다. 두 안이면 무엇을 포기할지를 묻게 되고, 그게 진짜 결정입니다.
6. 기계로 검사한다. 눈으로 고르고, 검사는 기계에게 맡깁니다.
7. 고른 뒤 명세서를 갱신한다. 시안을 하나 고르면 명세서의 숫자가 따라 움직입니다.

층 ① — 기계가 검사하는 것

눈으로는 멀쩡한데 기준 미달인 것들이 있습니다. 사람이 판단할 자리가 아닙니다. 「표준」은 공개된 기준이라 근거를 댈 수 있고, 「우리 규칙」은 우리가 정한 것이라 바꿀 수 있습니다.

출처: W3C — WCAG 2.2 · Apple Human Interface Guidelines

층 ② — 사람이 판단하는 것: 질문 여섯 개

1. 어디서 보나 — 화면 크기, 잘리는가, 인쇄되는가
2. 몇 초 보나 — 스치는가, 읽는가, 조작하는가
3. 누가 보나 — 나이·숙련도
4. 한 번에 몇 개 — 넘치면 어디로 가나
5. 만드는 사람이 고를 게 몇 개 — 선택지는 공짜가 아니다
6. 틀리면 뭐가 제일 아픈가 — 이 답이 「제일 크게 둘 것」을 정한다

층 ③ — 하지 않는 것

AI에게 그냥 시키면 몇 가지 모양으로 수렴합니다. 종류별 목록은 예시 탭에 있습니다. 공통으로 막는 것은 셋입니다.

• 그라데이션 배경 — 글자 대비가 위치마다 달라져 층 ①을 통과시킬 수가 없다
• 이모지로 항목 구분 — 기기마다 다르게 그려지고 이미지로 구우면 깨진다
• 얇은 글씨(300 이하) — 작게 줄이거나 구우면 뭉갠다

화면이 없는 것은 어떻게 하나

챗봇·알림·업무 자동화처럼 볼 화면이 없는 것도 이 차시를 건너뛰지 않습니다. 「디자인」이 화면 모양이 아니라 사람이 만나는 접점이기 때문입니다. 세 층은 그대로 쓰고, 층 ①의 숫자만 바꿉니다.

이 차시가 답하는 두 가지

1. 무엇으로 만드나 — 어떤 언어·도구·서비스를 쓸까
2. 어떤 순서로 만드나 — 한 번에 얼마만큼 시킬까

먼저 — 프로그램은 대개 세 부분이다

용어가 어렵게 들리지만 구조는 식당과 같습니다.

① 언어 — 무엇으로 쓰나

셋만 알면 대부분 해결됩니다.

타입스크립트(TypeScript)라는 말도 자주 보이는데, 자바스크립트에 「이 값은 숫자다」 같은 표시를 붙인 것입니다. 다른 언어가 아니라 같은 언어의 엄격한 버전이고, AI가 쓴 코드의 실수를 기계가 잡아내기 좋아집니다. 04차시 테스트와 같은 역할을 일부 합니다.

② 창고 — 자료를 어디에 담나

③ 어디서 돌리나

④ 무료 한도 — 이게 03차시의 진짜 함정

기능이 안 되는 게 아니라 한도에 걸려 조용히 멈추는 것이 실무에서 제일 자주 터집니다. 들이기 전에 숫자를 찾아봅니다.

근거 — Google, Apps Script quotas and limitations. 숫자는 바뀔 수 있으니 쓰기 전에 원본을 확인하십시오.

⑤ 그래서 새것을 들일까 말까

후보가 나오면 「없으면 어떻게 하나」를 먼저 씁니다. 이 한 줄에 답이 나오면 대개 안 들여도 됩니다.

절차 — 이 순서로 한다

1. 새로 들일 후보를 적는다. 라이브러리·서비스·API 무엇이든.
2. 후보마다 「없으면 어떻게 하나」를 쓴다. 답이 나오면 대개 안 들여도 됩니다.
3. 그래도 들일 것에는 값을 매긴다 — 아래 네 가지 비용으로.
4. 작업을 「한 걸음」씩 쪼갠다.
5. 다음 세 걸음까지만 계획한다. 그 뒤는 셋째 걸음를 마치고 다시 정합니다.

새것은 왜 비싼가 — 네 가지 비용

쪼개는 크기 — 「한 걸음」

한 번에 시키는 크기의 기준은 딱 하나입니다.

이 걸음이 끝났을 때, 내가 화면을 열어서 맞는지 틀린지 판단할 수 있는가.

걸음이 커질수록 「해줘」에 가까워집니다. 확인할 수 없는 크기로 시키면 확인을 안 하게 되고, 확인을 안 하면 쌓입니다.

한 줄 정의

TDD(Test-Driven Development, 테스트 주도 개발) — 테스트를 먼저 쓰고, 그 테스트를 통과시키는 코드를 쓴다.

「테스트」라는 말부터 풀면 이렇습니다 — 내가 정한 조건을 만족하는지 기계가 대신 확인해 주는 짧은 코드입니다. 사람이 매번 눈으로 보는 대신, 한 번 적어 두면 그 뒤로는 기계가 봅니다.

순서가 전부입니다. 만들고 나서 테스트를 쓰면 이미 만든 것에 맞춰 쓰게 됩니다. 그건 「내가 만든 게 내가 만든 대로다」를 확인하는 것이지, 맞는지 확인하는 게 아닙니다.

처음부터 끝까지 한 번 — 「넘침」 테스트

말로만 하면 안 잡히니 실제 하나를 끝까지 따라갑니다. 02차시에서 시안 세 장이 전부 아래가 잘려 있었던 그 문제입니다.

1 · 무엇을 확인할지 한 문장으로 쓴다

매장 다섯 개를 넣었을 때 어떤 글자도 카드 밖으로 나가지 않는다.

이 문장이 나오면 절반은 끝난 것입니다. 안 나오면 아직 무엇이 맞는 상태인지를 내가 정하지 않은 것입니다. 그때는 04차시가 아니라 01차시로 돌아갑니다.

2 · 테스트를 쓴다 — 기능은 아직 없다

def test_매장_다섯개_넘침없음():
    카드 = 카드뉴스_그리기(매장목록=[
        ("부산상회",   "전복 3미 1만원"),
        ("남천떡집",   "송편 전 품목 할인"),
        ("바다횟집",   "저녁 손님 음료 서비스"),
        ("금정청과",   "사과 한 박스 2만원"),
        ("해운대건어물", "멸치 500g 덤으로"),
    ])
    넘침 = 카드.밖으로_나간_픽셀()
    assert 넘침 == 0, f"{넘침}px 넘쳤다"

3 · 돌려서 실패를 눈으로 본다

FAILED test_overflow.py::test_매장_다섯개_넘침없음
    AssertionError: 109.8px 넘쳤다

4 · 통과시킨다

이제 그리는 코드를 고칩니다. 02차시에서 실제로 한 일은 카드 안의 줄간격을 1.3으로 고정하고 여백을 줄인 것이었습니다. 원인은 카드가 본문 줄간격(1.7)을 그대로 물려받은 것이었습니다.

PASSED test_overflow.py::test_매장_다섯개_넘침없음

5 · 일부러 깨 본다 — 이게 핵심이다

매장명을 스무 자로 늘려 넣어 봅니다. 실패해야 정상입니다.

FAILED   AssertionError: 37.2px 넘쳤다      ← 정상. 테스트가 살아 있다
PASSED                                      ← 비정상. 이 테스트는 아무것도 안 보고 있다

AI가 테스트를 통과시키는 세 가지 수법

「테스트를 통과시켜라」라고 하면 AI는 통과시킵니다. 문제는 방법입니다. 셋 다 실제로 자주 나옵니다.

수법 ① — 테스트에 나온 값만 맞춘다

def 카드뉴스_그리기(매장목록):
    if len(매장목록) == 5:          # 테스트가 딱 5개를 넣었으니까
        return 미리_만든_카드        # 그 경우만 맞춰 둔다
    ...

수법 ② — 테스트를 고친다

-    assert 넘침 == 0, f"{넘침}px 넘쳤다"
+    assert 넘침 < 120, f"{넘침}px 넘쳤다"   # 109.8 이 통과하게

수법 ③ — 건너뛰게 만든다

@pytest.mark.skip(reason="나중에 고칠 것")
def test_매장_다섯개_넘침없음():
    ...

# 출력:  4 passed, 1 skipped        ← 「4개 통과」만 보고 넘어간다

테스트로 안 잡히는 것

테스트는 만능이 아닙니다. 무엇을 못 잡는지 아는 것이 이 차시의 절반입니다.

첫째, 「예쁜가」 「읽히는가」처럼 판정 기준이 없는 것. 이건 사람이 봐야 하고, 02차시 층 ②가 그 자리입니다.

둘째, 「이게 필요한 기능인가」. 코드 밖의 문제라 01차시 명세서에서 걸러야 합니다. 잘 만든 쓸모없는 기능은 테스트를 전부 통과합니다.

셋째가 가장 중요합니다 — 내가 생각하지 못한 경우. 테스트는 내가 생각한 것만 확인합니다. 이건 테스트를 늘려서 해결되지 않고, 실제로 써 보거나 남이 써 봐야 나옵니다.

하네스가 무엇인가

하네스(harness)는 원래 말에 씌우는 마구(馬具)입니다. 힘을 죽이지 않고 방향만 잡아 주는 장치입니다. 여기서는 이렇게 씁니다.

AI가 스스로 돌려서 통과·실패를 읽을 수 있는 검사.

왜 필요한지는 한 문장으로 설명됩니다.

왜 필요한가 — 풀어서

AI는 자기가 만든 게 맞는지 스스로 확인할 방법이 없습니다. 그래서 「된 것 같다」 싶으면 거기서 손을 뗍니다. 그러면 이런 고리가 생깁니다.

1. AI가 만든다
2. 맞는지 확인할 방법이 없다
3. 「된 것 같다」에서 멈춘다
4. 내가 열어 본다
5. 틀렸다고 말해 준다
6. 고친다 → 다시 1번으로

근거 — Anthropic, Best practices for Claude Code: 「Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available, and you become the verification loop: every mistake waits for you to notice it.」

없을 때와 있을 때 — 실제 대화

같은 일을 시켰을 때 무엇이 달라지는지 보면 분명해집니다.

차이는 능력이 아니라 신호입니다. 두 경우 다 AI는 똑같이 그렸습니다. 다만 첫 번째는 「잘 나온 것 같다」에서 멈췄고, 두 번째는 「109.8px 미달」이라는 읽을 수 있는 신호를 받았습니다.

검사가 될 수 있는 것

대화 안에서 읽을 수 있는 신호를 내면 무엇이든 검사입니다.

근거 — 같은 문서: 「a test suite, a build exit code, a linter, a script that diffs output against a fixture, or a browser screenshot compared against a design.」

강도 사다리 — 네 칸

검사를 얼마나 강하게 걸지는 고를 수 있습니다. 위로 갈수록 준비가 들고, 대신 내가 안 봐도 됩니다.

근거 — 같은 문서: 「a verification subagent … has a fresh model try to refute the result, so the agent doing the work isn't the one grading it」 · 「a fresh context improves code review since Claude won't be biased toward code it just wrote.」

규칙 파일 — 02차시 ③단계를 실제로 만든다

02차시에서 「규칙을 파일에 박는다」를 봤습니다. 그 파일을 쓰는 법에는 분명한 기준이 있습니다.

근거 — 같은 문서: 「For each line, ask: Would removing this cause Claude to make mistakes? If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!」 · 「If you emphasize many lines, none of them stands out.」 · 「Treat CLAUDE.md like code: review it when things go wrong, prune it regularly.」

끝까지 한 번 — 열두 줄에서 다섯 줄로

기준을 말로만 들으면 안 잡힙니다. 실제로 후보를 늘어놓고 잘라 봅니다. AI에게 「이 저장소 규칙 파일을 써줘」라고 하면 대개 이 정도가 나옵니다.

열둘 중 다섯이 남고 하나가 보류입니다. 지운 다섯 줄의 공통점을 보십시오 — 전부 「맞는 말」입니다. 틀린 말이라 지운 게 아니라 없어도 되는 말이라 지웠습니다.

가장 중요한 구분 — 지시는 권고, 훅은 강제

그래서 「지켜지지 않는 규칙」은 훅으로 옮깁니다. 설명을 더 세게 쓰는 게 아니라 장치를 바꿉니다 — 02차시에서 「설명하지 말고 틀릴 수 없게 만들라」고 한 것과 같은 발상입니다.

근거 — 같은 문서: 「Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.」

「통과했습니다」를 믿지 않는다

성공을 주장하게 하지 말고 증거를 보여주게 하라 — 테스트 출력, 실행한 명령과 그 결과, 화면 캡처.

증거를 검토하는 것이 내가 직접 다시 돌려 보는 것보다 빠릅니다. 그리고 내가 안 보고 있던 작업에도 통합니다.

근거 — 같은 문서: 「Have Claude show evidence rather than asserting success.」

말부터 쉽게

05차시와 다른 점은 누가 잊을 수 있느냐입니다. 하네스는 AI가 돌리는 검사라 시키지 않으면 안 돌 수 있습니다. CI는 사람도 AI도 잊을 수 없습니다 — 올리면 무조건 돕니다.

왜 AI로 개발할 때 더 중요해지나

느낌과 실제가 갈라지기 때문입니다. 서로 독립된 두 조사가 같은 방향을 가리킵니다.

절차 — 이 순서로 한다

1. 05차시의 검사를 그대로 가져온다. 새로 만들지 않습니다 — 이미 있는 것을 자동으로 돌게만 합니다
2. 몇 초까지 허용할지 정한다. 느리면 끄게 됩니다. 기준은 「기다릴 수 있는가」
3. 실패하면 어떻게 할지 정한다. 막을 것인가, 알리고 통과시킬 것인가
4. 검사를 두 층으로 나눈다 — 매번 도는 빠른 것 / 배포 전에만 도는 느린 것
5. 조용한 실패를 잡는 장치를 붙인다. 이게 이 차시의 절반입니다

끝까지 한 번 — 배포가 거절된 날

말로 「조용히 실패한다」고 하면 안 잡힙니다. 실제로 있었던 하루를 그대로 따라갑니다.

오전 — 세 가지를 한꺼번에 올렸다

고칠 것이 셋 있었습니다.

1. 메일 문구에서 불필요한 표기 지우기
2. 회사 소개에서 지역 표기 고치기
3. 알림을 30분마다 보내도록 예약 설정 바꾸기

셋을 한 번에 올렸습니다. 여기까지는 아무 문제가 없어 보였습니다.

오후 — 화면은 멀쩡했다

사이트에 들어가 보니 정상이었습니다. 페이지가 뜨고, 버튼이 눌리고, 메일도 나갔습니다.

다음 날 — 알림이 안 왔다

30분마다 와야 할 알림이 안 왔습니다. 처음 의심한 것은 알림 보내는 코드였습니다. 그런데 코드는 멀쩡했습니다.

그래서 배포 기록을 열어 봤습니다. 거기에 이렇게 적혀 있었습니다.

Error: Hobby accounts are limited to daily cron jobs.
       This cron expression (30 0-9 * * 1-5) would run more than once per day.

Deployment failed.

진짜 피해는 다른 데 있었다

예약 설정만 안 된 게 아닙니다. 같이 올린 나머지 두 개도 함께 막혔습니다. 배포는 통째로 처리되기 때문입니다 — 하나가 거절되면 전부 거절됩니다.

셋 중 둘은 「고쳤다」고 믿고 넘어간 것입니다. 알림이 안 와서 우연히 발견하지 않았다면 계속 몰랐을 겁니다.

무엇을 바꿨나

1. 예약 실행을 다른 곳으로 옮겼다. 무료 한도가 없는 곳(상시 켜둔 컴퓨터)으로
2. 배포한 뒤 「지금 도는 것이 내가 올린 것인가」를 확인하는 한 줄을 넣었다. 배포 시각과 버전을 대조
3. 들이기 전에 한도를 찾아보는 것을 03차시 절차에 넣었다

조용한 실패 — 이 차시의 본론

기계 검증을 붙이면 새로운 실패 방식이 생깁니다. 검사 자체가 안 도는 것, 배포가 거절된 것, 프로세스가 죽어 있는 것 — 전부 화면은 멀쩡합니다.

검사를 두 층으로 나눈다

나누는 이유는 하나입니다 — 느린 검사를 매번 돌리면 사람이 끕니다. 끈 검사는 없는 검사입니다.

여섯 가지는 필요조건이지 충분조건이 아니다

01부터 06까지는 이미 알려진 방법입니다. 그런데 그걸 전부 해본 사람이 남긴 말이 이것이었습니다.

그럼에도 결과가 나오면 무한정 수정해야 하고, 집중력이 떨어지면 생각도 분석도 없이 「해줘」가 된다. 그리고 뭔가 대단한 걸 한 것 같은 기분이 든다. 배운 것도, 느는 것도 거의 없는데.

그래서 결론은 이렇게 붙습니다.

의도적으로 프로젝트를 분석하고 학습하고 연구하는 과정이 반드시 병렬로 돌아가야 한다.

이 말이 근거 없는 감상이 아니다 — 숫자로 확인된다

여섯 장치가 잡아 주는 것과 못 잡는 것

결과물이 멀쩡한데 내가 아무것도 모르는 상태는 여섯 장치를 다 통과합니다. 그리고 그 상태는 다음 프로젝트에서 청구됩니다.

판별 기준 — 하나로 충분하다

이 시험이 값어치 있는 이유는 속일 수 없기 때문입니다. 「이해했다」는 느낌은 설명하려 들 때까지 확인되지 않습니다. 말로 꺼내 보면 어디가 빈칸인지 즉시 드러납니다.

오른쪽은 「왜 그래야 하는지」가 들어 있습니다. 그게 들어 있으면 다음에 비슷한 상황에서 혼자 판단할 수 있습니다. 왼쪽은 다음에도 물어봐야 합니다.

끝까지 한 번 — 설명 시험을 실제로 쳐 본다

이 교재를 만들면서 나온 것 하나를 골라 시험을 쳐 봅니다. 대상은 「명도 대비 검사」입니다.

1문 — 이게 무엇을 하나?

→ 여기까지는 대부분 답합니다. 시험은 여기서 시작도 안 했습니다.

2문 — 왜 이 방법인가? 다른 방법 대신.

3문 — 고장 나면 어디를 보나?

def blend(글자색, 배경색, 투명도):
    """반투명 글자가 실제로 눈에 보이는 색을 구한다."""
    ...

# 투명도 0.6 인 흰 글자를 짙은 배경 위에 얹으면
#   그냥 계산:  흰색 vs 배경   →  9.11 : 1   ← 통과 (거짓말)
#   합성 계산:  섞인색 vs 배경 →  4.39 : 1   ← 미달 (진짜)

4문 — 이걸 다른 데 쓰려면 무엇을 고쳐야 하나?

이 질문이 가장 어렵고 가장 정확합니다. 답하려면 어디까지가 이 경우에만 맞는 것인지를 알아야 하기 때문입니다.

시험을 치고 나서 — 빈칸을 채운다

위 시험에서 2문이 막혔다고 해봅시다. 그러면 물을 질문이 정해집니다.

「4.5:1이라는 숫자는 어디서 나온 건가? 왜 하필 4.5인가?」

이게 좋은 질문입니다 — 막힌 자리에서 나왔으니까요. 반대로 안 막혔는데 미리 공부하려 드는 것은 대개 남지 않습니다.

그럼 어떻게 병렬로 굴리나 — 네 가지 습관

1. 코드베이스에 질문한다. 「이건 왜 이렇게 돼 있나」 「이 줄은 무슨 뜻인가」 「이 함수는 어떤 예외를 처리하나」. 다른 엔지니어에게 물을 질문을 그대로 묻습니다.
   근거 — Anthropic 문서는 이 방식을 새 코드베이스에 적응하는 효과적인 방법으로 명시합니다. 「Using Claude Code this way is an effective onboarding workflow, improving ramp-up time.」
2. 계획을 읽는다. 바로 짜게 하지 않고 계획을 먼저 만들게 한 뒤 그것을 읽습니다. 결과물은 읽어도 「왜」가 안 보이지만 계획에는 「왜」가 적혀 있습니다.
   근거 — 같은 문서, 「Explore first, then plan, then code」. 다만 작은 일에는 계획을 건너뛰라고도 적혀 있습니다 — 「If you could describe the diff in one sentence, skip the plan.」
3. 되돌리기를 연습한다. 되돌릴 수 있으면 과감하게 시도할 수 있습니다. 시도가 학습입니다. 되돌릴 방법을 모르면 안전한 것만 하게 되고, 안전한 것만 하면 안 늡니다.
4. 막힌 시간을 적는다. 하루 끝에 세 줄 — 오늘 막힌 곳 / 몇 분 만에 알았나 / 더 일찍 알 수 있었던 방법. 이게 이 과정 전체의 성적표입니다.

무엇을 물어야 하나 — 질문 목록

「질문하세요」는 도움이 안 됩니다. 무엇을 물을지가 어렵기 때문입니다. 아래는 그대로 써도 되는 질문들입니다.

코드를 처음 볼 때

• 이 프로젝트에서 기록은 어디에 남나? 문제가 생기면 어디를 보나?
• 새 화면을 하나 추가하려면 어느 파일을 만져야 하나?
• 이 함수는 어떤 예외 상황을 처리하고 있나?
• 이 줄은 왜 이렇게 돼 있나? 기록을 찾아서 어떻게 이렇게 됐는지 알려줘

AI가 뭔가 만들어 준 뒤

• 이 중에 내가 몰라도 되는 부분과 반드시 알아야 하는 부분을 나눠줘
• 여기서 제일 고장 나기 쉬운 곳은 어디인가? 왜?
• 이걸 다른 프로젝트에 쓰려면 무엇을 고쳐야 하나?
• 더 쉬운 방법이 있었는데 안 쓴 이유가 있나?

근거 — Anthropic 문서는 코드베이스에 질문하는 방식을 새 코드에 적응하는 효과적인 방법으로 명시합니다. 「You can ask Claude the same sorts of questions you would ask another engineer… No special prompting required.」

속도를 목표로 두지 않는다

세 장소

아티팩트(대화창 미리보기)는 ①보다도 앞입니다 — 주소도 없고 대화를 닫으면 사라질 수 있습니다. 초보자 대부분이 ①이나 그 앞에서 「다 됐다」고 합니다. 완성은 ③입니다.

「배포」는 어려운 말이 아니다

남이 열 수 있는 곳에 올리는 것입니다. 그게 전부입니다.

왜 두 곳(GitHub·Vercel)이 필요한가

절차 — 다섯 줄

1. GitHub에서 빈 저장소를 만든다 — 이름은 폴더와 같게
2. AI에게 「이 폴더를 그 저장소에 연결하고 올려줘」
3. 올라갔는지 GitHub 페이지에서 눈으로 확인한다
4. 이후는 걸음 하나 끝날 때마다 「커밋하고 올려줘」
5. 망쳤으면 「마지막 커밋으로 되돌려줘」

무엇을 시킬지만 알면 됩니다. 명령어는 AI가 압니다.

제일 흔한 사고 — 비밀 키를 올린다

지금까지 한 걸 커밋하고 GitHub에 올려줘.

- 올리기 전에 비밀 키·비밀번호가 섞여 있는지 확인해라. 있으면 멈추고 말해라.
- 커밋 메시지는 무엇을 왜 고쳤는지 한 줄로.
- 올린 뒤 GitHub 주소를 알려줘.

한 번 연결하면 이렇게 돈다

사람이 하는 건 왼쪽 둘뿐입니다. 빌드는 사람이 쓴 코드를 돌 수 있는 형태로 바꾸는 일이고, 여기서 실패하면 이전 버전이 계속 돕니다 — 06차시의 「조용한 실패」가 이겁니다.

절차 — 한 번만

1. Vercel에서 「새 프로젝트」 → GitHub 저장소 고르기
2. 설정은 그대로 두고 배포 — 대부분 자동으로 알아봅니다
3. 주소가 나온다 — 「이름.vercel.app」
4. 열어서 내 컴퓨터에서 본 것과 같은지 확인
5. 이후는 GitHub에 올리기만 하면 자동으로 다시 배포

무료 요금제 한도 — 확인한 숫자

출처 — Vercel Docs, Limits (2026-09). 숫자는 바뀝니다. 쓰기 전에 원본을 확인하십시오.

환경변수 — 비밀 키를 넣는 자리

AI 호출 키, 데이터베이스 주소 같은 것은 코드 파일에 쓰면 GitHub에 올라갑니다. Vercel의 「환경변수」 칸에 따로 넣고 코드는 그 이름만 부릅니다.

먼저 — 정말 필요한가

Supabase — 무료 한도와 함정

출처 — Supabase Pricing (2026-09). 「1주일 안 쓰면 멈춘다」는 06차시 조용한 실패 목록에 넣으십시오.

자주 나오는 질문 — 「아마존 서버(AWS)」는 Vercel 대신인가?

맞기도 하고 아니기도 합니다. 층이 다릅니다. 그리고 사실 — Vercel도 실제로는 아마존 같은 서버 위에서 돕니다. 복잡한 설정을 다 해 놓고 「올리면 끝」으로 포장한 것입니다. 그래서 대체재는 맞지만 같은 층의 대체가 아니라 한 칸 아래로 내려가는 것입니다.

Vercel에 올리면 뒤에서 아마존·구글 서버를 빌려 거기에 올려 줍니다. 우리가 몰라도 되게 감춰 둔 것입니다.

그럼 언제 한 칸 내려가나 — 다섯 경우뿐

흔한 경로는 작을 땐 Vercel, 커지면 AWS입니다. 처음부터 AWS로 가는 건 대개 안 해도 될 일을 하는 것입니다 — 03차시의 「없으면 어떻게 하나」를 그대로 물어보십시오.

도구 지도 — 넷이 전부가 아니다

이 과정은 GitHub → Vercel → Supabase → Cloudflare 한 길만 끝까지 갑니다. 역할마다 대안이 여럿이고 앞으로도 계속 생깁니다. 그런데 이름을 아는 것과 쓸 줄 아는 것은 다릅니다. 한 길을 끝까지 가 본 뒤에 이 지도를 보면 「같은 역할, 다른 이름」으로 읽힙니다.

① 올리고 돌리는 곳

② 담고 지키는 곳

③ 보내고 받는 곳

④ 보고 재는 곳

이 표는 2026-09 기준이고 서비스는 생기고 사라집니다. 역할 이름은 남습니다 — 「창고」 「올리는 곳」 「알림」.

Cloudflare — 도메인 연결 세 단계

1. 도메인을 산다 — 어디서 사든 됩니다. 연 1~2만 원
2. Cloudflare에 도메인을 등록한다 (무료) — 주소록 관리를 여기서
3. Vercel이 알려주는 값을 Cloudflare에 붙여넣는다 → 몇 분 뒤 연결

배포한 날 반드시 — 네 가지

1. 지금 도는 것이 내가 올린 것인가 — 배포 시각·버전 대조 (06차시 사고)
2. 휴대폰으로 연다
3. 남에게 링크를 보내 열리는지 묻는다
4. 되돌리는 법을 한 번 해본다 — Vercel은 이전 배포로 한 번에 돌아갑니다

4번을 롤백이라고 부릅니다. 망친 배포를 몇 초 만에 되돌리는 기능인데, 있는 줄 모르면 못 씁니다.

내보낸 뒤의 조용한 실패 — 06차시에 셋이 더 붙는다

비용

Vercel·Supabase 둘 다 무료 범위 안에서 첫 프로젝트가 됩니다. 넘기기 전에 알림이 오게 설정만 해 두면 됩니다.

참고 영상

내용은 검증하지 않았습니다. 도구 화면이 바뀌면 낡으니 흐름만 보고 화면은 실제 도구를 여십시오.

• AI로 웹서비스를 개발하는 전체 과정 (랜딩페이지부터 배포·DB·결제까지) — 챗과장 · 2부 전체 흐름
• Learn to Push Your Code to GitHub in 10 Minutes — CodeWithHarry · D2
• DevOps CI/CD Explained in 100 Seconds — Fireship · D3 · 06
• GoDaddy 도메인을 Vercel에 연결하는 방법 — SolveBase · D4
• 클로드 초보자 가이드 2026 — 그린코끼리 AI · 0B

다음 프로젝트에서 또 처음부터 설명할 것인가

여섯 단계를 한 번 밟았습니다. 그런데 새 대화를 열면 AI는 아무것도 기억하지 못합니다. 매번 「명세서부터 쓰자」 「안 하는 일도 적어」를 다시 설명하게 됩니다.

규칙 파일 · 스킬 · 훅 — 셋을 구분한다

규칙 파일에 절차를 다 넣으면 길어져서 무시됩니다(05차시). 그래서 절차는 스킬로 뺍니다.

무엇을 스킬로 만드나 — 두 번 이상 한 것

1. 이 과정의 여섯 단계 — 다음 프로젝트에서 그대로 씁니다
2. 내 일의 반복 절차 — 견적서 쓰는 법, 보고서 양식, 응대 문구
3. 내가 매번 고쳐 주는 것 — AI가 계속 틀리는 지점을 글로
4. 남에게 넘길 것 — 직원·동료가 같은 방식으로 하게

어디에 두나

이 과정의 여섯 단계를 적은 스킬이 부록 G에 통째로 있습니다 — 복사해서 바로 쓰십시오.

보안과 최적화 — 대부분은 나중 일이다. 셋만 지금

속도 튜닝, 부하 대비, 정교한 권한 관리 — 전부 규모가 생긴 뒤 문제입니다. 방문자 열 명짜리 첫 프로젝트에서 하면 안 해도 될 일을 하는 것입니다(03차시). 그런데 딱 셋은 첫날부터 터집니다. 이건 규모와 무관합니다.

지금 해야 하는 셋

셋 다 이미 배운 것입니다. 여기서 한자리에 모아 확인하는 것입니다.

나중에 할 것 — 언제가 「나중」인가

전부 「신호가 오면」입니다. 미리 하면 03차시의 「없으면 어떻게 하나」에 답할 수 없는 일을 하게 됩니다.