03중급과정180분 (이론 45 + 실습 135)

스펙 기반 개발

“코드보다 먼저 합의를 쓴다”

02이 차시를 마치면

1.기존 PRD를 구현 관점의 기술 스펙으로 확장할 수 있다.
2.기술 스펙을 완료 조건이 명시된 태스크 단위로 분해할 수 있다.
3.Claude Code의 계획 모드로 태스크마다 승인 게이트를 만들 수 있다.
4.구현 중 바뀐 결정을 스펙에 반영해 스펙과 코드를 동기화할 수 있다.

03왜 필요한가

기본과정에서 만든 PRD만 들고 Claude Code에 '이거 만들어줘'라고 던졌다고 해보자. 화면은 그럴듯하게 나오는데, 에러가 났을 때 어떤 메시지를 보여줄지, 입력값이 비어 있으면 어떻게 처리할지, 데이터를 어떤 형태로 저장할지는 PRD 어디에도 안 적혀 있다. AI는 그때그때 그럴듯한 값으로 빈 곳을 채우고, 다음에 같은 걸 또 요청하면 다르게 채운다. 몇 차례 기능을 더 얹고 나면 화면마다 에러 처리 방식이 다르고, 아무도 왜 이렇게 됐는지 설명하지 못하는 코드가 쌓인다.

PRD에 없는 세부사항(에러 처리, 데이터 형식, 권한 범위)을 AI가 그때그때 다르게 채워 코드 전체의 일관성이 깨진다.
큰 기능을 통째로 맡기면 중간에 방향을 확인할 지점이 없어, 다 만든 뒤에야 원하던 게 아니었다는 걸 안다.
'완료했습니다'라는 말만 믿고 넘어가면, 애초에 무엇을 확인해야 완료인지가 정의된 적이 없다.
시간이 지나 스펙 문서와 실제 코드가 따로 놀면, 나중에 합류한 사람이나 미래의 나 자신이 어느 쪽을 믿어야 할지 모른다.

04개념 설명

PRD와 기술 스펙은 다른 층위의 문서다

PRD는 '왜 만들고 무엇을 만드는가'를 다룬다 — 대상, 문제, 성공 기준. 기술 스펙은 '어떻게 만드는가'를 다룬다 — 데이터 모델, API 형태, 에러 처리 전략, 기술적 제약. PRD가 기획의 언어라면 기술 스펙은 구현의 언어다.

기본과정 07차시(9절)에서 만든 PRD를 그대로 코드 작성 요청에 넘기면 이 번역 단계가 빠진 채로 진행된다. AI는 빈 자리를 즉흥적으로 채우고, 그 즉흥적 선택이 태스크마다 달라지는 것이 앞서 본 불편함의 근본 원인이다.

문서	다루는 것
PRD	무엇을 · 왜 (대상, 문제, 성공 기준)
기술 스펙	어떻게 (데이터 모델, API, 에러 처리)

PRD = 무엇 / 왜, 기술 스펙 = 어떻게
번역 단계가 빠지면 AI가 매번 다르게 결정한다
기존 PRD를 버리지 않고 그 위에 확장한다

태스크와 완료 조건 — '다 했다'의 기준을 미리 정한다

기술 스펙만으로는 여전히 크다. 태스크 단위로 쪼개되, 각 태스크에 '이게 되면 끝'이라는 완료 조건(Definition of Done)을 붙인다. 완료 조건이 없는 태스크는 코드가 동작하는지 애매한 상태에서 다음으로 넘어가게 만든다.

완료 조건은 느낌이 아니라 확인 가능한 문장이어야 한다. '잘 동작한다'가 아니라 '이 명령을 실행하면 이 값이 나온다'처럼 직접 실행해서 눈으로 볼 수 있는 형태로 쓴다.

완료 조건 없이

"잘 동작한다"

되는지 애매한 채로 다음으로 넘어간다

완료 조건 있게

"이 명령을 실행하면 이 값이 나온다"

직접 실행해서 눈으로 확인할 수 있다

태스크는 한 번에 검증 가능한 크기로 쪼갠다
완료 조건은 확인 가능한 문장으로 쓴다
완료 조건이 안 써지면 태스크가 아직 너무 크다는 신호다

계획 모드와 승인 게이트

Claude Code의 계획 모드(Plan Mode)는 코드를 바로 쓰지 않고 먼저 어떻게 구현할지 계획을 보여준 뒤, 승인을 받고서야 실제 작업을 시작한다. 9절에서 다룬 'PRD를 먼저 합의하고 나중에 만든다' 원칙을 코딩 단계로 그대로 옮긴 장치다.

승인 게이트를 매 태스크마다 두면, 잘못된 방향으로 30분을 더 진행하기 전에 멈출 수 있다. 계획을 보고 반려하는 비용은 다 만든 걸 되돌리는 비용보다 훨씬 싸다.

01계획 제시코드를 쓰기 전 미리보기

02승인 게이트태스크마다 확인

03실제 작업 시작

계획 모드는 실행 전 미리보기다
태스크 단위로 승인 게이트를 둔다
'다 좋아요'로 승인하지 않는다 — 9.4절의 실수를 코딩 단계에서 반복하지 않는다

스펙과 코드의 동기화

스펙은 한 번 쓰고 끝나는 문서가 아니다. 구현 중 결정이 바뀌면(예: 응답 데이터 형식 변경) 스펙도 같이 갱신해야, 다음 태스크를 진행할 때 AI가 낡은 정보를 참고하지 않는다.

스펙이 코드보다 뒤처지면 스펙은 아무도 믿지 않는 문서가 된다. 태스크가 하나 끝날 때마다 '스펙과 다르게 구현한 부분이 있는가'를 확인하는 습관이 이 격차를 막는다.

01구현 중 결정 변경

02스펙 즉시 갱신

03다음 태스크 시작 전 확인스펙과 다르게 구현한 부분이 있는지

구현 중 결정이 바뀌면 스펙도 즉시 갱신한다
스펙 갱신을 다음 태스크 시작 전 체크리스트에 넣는다

05실습 가이드

1. 기존 PRD를 기술 스펙 초안으로 확장하기
- 기본과정에서 만든(또는 07차시 방식으로 새로 작성한) PRD.md를 프로젝트 폴더에 준비한다.
- 구현하려는 기능 하나를 정한 뒤, P3-1 프롬프트로 Claude Code에 기술 스펙(SPEC.md) 작성을 요청한다.
- AI가 되묻는 질문(데이터 형식, 에러 처리, 범위 등)에 답하며 SPEC.md가 채워지는 것을 확인한다.
예상 결과 — SPEC.md 파일이 생성되고, 데이터 모델·API 형태·에러 처리·범위 밖 항목이 채워져 있다.
안 될 때 — AI가 질문을 거의 안 하고 바로 스펙을 채운다면 PRD 자체가 너무 추상적이라는 신호다. PRD의 해당 절을 먼저 구체화한 뒤 다시 요청한다.
2. 스펙이 구현 가능한 수준인지 검증하기
- 완성된 SPEC.md를 두고 '이 스펙만 보고 다른 개발자가 만들 수 있을까'를 스스로 자문한다.
- 애매하다고 느껴지는 부분을 AI에게 그대로 물어 '이 스펙에서 아직 모호한 지점이 있는지' 점검받는다.
예상 결과 — 모호한 지점 목록을 받거나, 없다는 확인을 받는다.
안 될 때 — 모호한 지점이 계속 나오면 그 부분만 따로 붙잡고 결정을 먼저 내린 뒤 스펙에 반영한다. 나머지 단계로 넘어가지 않는다.
3. 태스크 목록으로 분해하기 (완료 조건 포함)
- P3-2 프롬프트로 SPEC.md를 태스크 목록(TASKS.md)으로 쪼개달라고 요청한다.
- 각 태스크에 완료 조건과 선행 태스크(의존성)가 함께 적혀 있는지 확인한다.
예상 결과 — TASKS.md에 태스크별 이름, 완료 조건, 순서(의존성)가 정리되어 있다.
안 될 때 — 완료 조건을 한 문장으로 못 쓰는 태스크가 있다면 그 태스크가 아직 너무 크다는 뜻이다. 더 쪼개달라고 다시 요청한다.
4. 계획 모드로 첫 태스크 승인받기
- Claude Code에서 계획 모드로 전환한다.
- P3-3 프롬프트로 TASKS.md의 첫 번째 태스크 진행을 요청하고, 계획(건드릴 파일·스펙 근거·검증 방법)만 먼저 확인한다.
- 계획이 스펙과 어긋나지 않으면 승인해 실제 작업을 진행시킨다.
예상 결과 — 계획이 표시되고, 검토 후 승인하면 그 계획대로 코드 작성이 시작된다.
안 될 때 — 계획이 스펙과 다른 방향이면 승인하지 않고 어느 부분이 스펙과 다른지 짚어 다시 계획을 요청한다.
5. 완료 조건으로 태스크 검증하기
- 태스크 구현이 끝나면 TASKS.md에 적어둔 완료 조건을 그대로 실행하거나 확인한다.
- 조건을 충족하면 TASKS.md에서 해당 태스크를 완료로 표시한다.
예상 결과 — 완료 조건이 실제로 충족되는 것을 눈으로 확인하고, 태스크 보드에 완료 표시가 남는다.
안 될 때 — 조건이 충족되지 않으면 완료로 표시하지 않는다. 무엇이 부족한지 AI에게 구체적으로 알려 재작업을 요청한다.
6. 다음 태스크로 승인 게이트 반복하기
- TASKS.md의 다음 태스크에 대해 4~5단계(계획 확인 → 승인 → 완료 조건 검증)를 반복한다.
- 태스크 간 의존성이 있다면 순서를 지켜 진행한다.
예상 결과 — 여러 태스크에 걸쳐 계획-승인-검증 흐름이 반복되며 태스크 보드가 점점 채워진다.
안 될 때 — 앞 태스크의 완료 조건이 실은 충족되지 않았는데 다음 태스크가 그 위에서 막힌다면, 앞 태스크로 돌아가 먼저 바로잡는다.
7. 구현 중 바뀐 결정을 스펙에 반영하기
- 구현하다 보면 스펙에 없던 세부사항을 그 자리에서 결정하게 되는 경우가 생긴다.
- P3-4(복구) 프롬프트로 이 결정이 스펙의 다른 부분과 충돌하지 않는지 확인받고, 문제 없으면 SPEC.md에 반영한다.
예상 결과 — SPEC.md가 실제 구현 결정을 반영해 갱신되고, 영향받는 다른 태스크가 있으면 목록으로 안내받는다.
안 될 때 — 왜 그렇게 결정했는지 스스로도 설명이 안 되면 반영을 미루고, 먼저 그 결정의 이유부터 명확히 한다.
8. 스펙-코드 정합성 최종 점검하기
- 계획한 태스크를 모두 마친 뒤, P3-5 프롬프트로 SPEC.md와 실제 코드를 비교 점검받는다.
- 발견된 불일치를 보고 스펙을 고칠지 코드를 고칠지 각각 결정한다.
예상 결과 — 스펙-코드 간 불일치 표를 받고, 항목별로 처리 방향이 정리된다.
안 될 때 — 불일치가 너무 많이 나오면 이번 차시 범위를 벗어난 것이다. 우선순위가 높은 항목 2~3개만 먼저 정리하고 나머지는 다음 세션의 할 일로 남긴다.

06실전 프롬프트

P3-1PRD를 기술 스펙으로 확장하기

사용 시점 — 실습 1단계 — 기존 PRD를 구현 가능한 기술 스펙으로 넓힐 때

지금 PRD.md에 있는 [기능 이름]을 실제로 구현하려고 해.
이 PRD를 기술 스펙으로 확장해서 SPEC.md 파일로 만들어줘.

다음 내용을 반드시 포함해줘.
· 데이터 모델(어떤 값을 어떤 형태로 저장할지)
· API 또는 함수 형태(입력과 출력)
· 에러가 났을 때 어떻게 처리할지
· 이번 범위에 안 넣을 것(범위 밖)

확실하지 않은 부분은 짐작해서 채우지 말고,
나에게 먼저 물어봐줘. 질문은 객관식으로 줘.

기대 결과 — SPEC.md 파일이 생성되고, 구현 관점의 미확정 사항을 객관식 질문으로 되물어온다.

P3-2태스크 목록과 완료 조건 뽑기

사용 시점 — 실습 3단계 — 스펙을 실행 단위로 쪼갤 때

방금 만든 SPEC.md를 태스크 목록으로 쪼개줘.

각 태스크마다 이렇게 적어줘.
· 태스크 이름
· 무엇을 하면 끝인지(완료 조건) — 내가 직접 확인할 수 있는 문장으로
· 이 태스크가 끝나야 시작할 수 있는 다음 태스크(있다면)

한 태스크는 30분~1시간 안에 끝낼 수 있는 크기로 쪼개줘.
너무 크면 더 쪼개고, 완료 조건을 못 쓰겠으면 그것도 알려줘.

기대 결과 — TASKS.md에 태스크별 완료 조건과 진행 순서가 정리되어 나온다.

P3-3계획 모드로 태스크 진행 승인하기

사용 시점 — 실습 4단계 — 계획 모드로 진입해 승인 여부를 결정할 때

TASKS.md의 [태스크 번호]를 진행하고 싶어.
계획 모드로 먼저 어떻게 구현할지 계획만 보여줘. 코드는 아직 쓰지 마.

계획에는 다음이 들어가야 해.
· 건드릴 파일 목록
· SPEC.md의 어느 부분을 따르는지
· 완료 조건을 어떻게 확인할 건지

계획을 보고 내가 승인하면 그때 진행해줘.

기대 결과 — 실행 전 계획(파일 목록·스펙 근거·검증 방법)을 먼저 확인받고, 승인 여부를 판단할 수 있다.

P3-4스펙에 없던 결정을 내렸을 때 복구용

사용 시점 — 실습 7단계(복구) — 구현 중 스펙에 없던 세부사항을 임의로 정했을 때

구현하다가 SPEC.md에 안 적혀 있던 부분을
내 마음대로 [어떻게 처리했는지]로 결정했어.

1. 이 결정이 SPEC.md의 다른 부분과 충돌하는 게 있는지 확인해줘.
2. 문제 없으면 SPEC.md에 이 결정을 반영해서 갱신해줘.
3. 이미 만든 다른 태스크 중에 이 결정 때문에 다시 고쳐야 하는 게 있는지도 알려줘.

기대 결과 — 충돌 여부 확인 → 스펙 갱신 → 영향받는 다른 태스크 목록 순서로 안내받는다.

P3-5스펙-코드 정합성 점검하기

사용 시점 — 실습 8단계 — 태스크를 모두 마친 뒤 최종 점검할 때

SPEC.md와 지금까지 작성된 코드를 비교해줘.

1. 스펙에는 있는데 코드에 없는 것
2. 코드에는 있는데 스펙에 기록 안 된 것
3. 각 태스크의 완료 조건을 실제로 만족하는지 다시 확인

발견한 불일치를 표로 정리해줘.

기대 결과 — 스펙-코드 간 불일치를 표로 받고, 어느 쪽을 기준으로 맞출지 결정할 수 있다.

07이것만은 주의

스펙을 한 번 쓰고 다시 안 본다

무슨 일이 생기나 — 구현 중 결정이 바뀌어도 스펙을 갱신하지 않으면, 다음 태스크에서 AI가 낡은 스펙을 참고해 이미 바뀐 방식과 다르게 코드를 만든다.

대처 — 태스크 하나가 끝날 때마다 '스펙과 다르게 구현한 부분이 있는지'를 완료 조건 점검 항목에 포함시킨다.

계획을 안 읽고 승인만 누른다

무슨 일이 생기나 — 계획 모드가 보여주는 계획을 제목만 훑고 승인하면, 9.4절의 '다 좋아요' 실수를 코딩 단계에서 그대로 반복하게 되어 엉뚱한 파일을 건드리는 계획도 그냥 통과된다.

대처 — 최소한 '건드릴 파일 목록'과 '완료 조건 확인 방법' 두 줄은 승인 전에 반드시 읽는다.

완료 조건이 '잘 동작한다'처럼 뭉뚱그려진다

무슨 일이 생기나 — 완료 조건이 구체적이지 않으면 태스크가 끝났는지 아닌지 사람마다 다르게 판단하게 되고, 결국 아무도 확인하지 않은 채 다음으로 넘어간다.

대처 — 완료 조건은 '이 명령을 실행하면 이 결과가 나온다'처럼 직접 실행해서 눈으로 확인할 수 있는 문장으로 다시 쓴다.

태스크를 너무 크게 쪼갠다

무슨 일이 생기나 — 태스크 하나가 여러 화면·여러 기능을 포함하면 계획 모드의 승인 게이트가 사실상 무력화된다 — 승인은 했지만 그 안에서 무슨 일이 벌어지는지 다 확인할 수 없다.

대처 — 완료 조건을 한 문장으로 쓸 수 없다면 태스크가 너무 크다는 신호다. 더 쪼갠다.

기술 스펙에 없는 세부사항을 AI가 알아서 채운다

무슨 일이 생기나 — 스펙에 에러 처리 방식이나 데이터 형식이 안 적혀 있으면 AI는 그럴듯한 기본값으로 채우는데, 태스크마다 다른 기본값을 고를 수 있어 코드 전체가 일관성 없어진다.

대처 — 스펙 검증 단계(2단계)에서 '이 스펙만 보고 만들 수 있는가'를 반드시 자문하고, 모호한 부분은 태스크 분해 전에 먼저 채운다.

08자가 점검

0 / 6 완료0%

기존 PRD를 기술 스펙(SPEC.md)으로 확장했다
각 태스크에 확인 가능한 완료 조건을 적었다
계획 모드로 최소 한 태스크를 승인 후 진행했다
완료 조건을 직접 실행해 확인했다
구현 중 바뀐 결정을 스펙에 반영했다
스펙과 코드의 불일치를 점검했다

09과제

자신의 L1 프로젝트(또는 현재 진행 중인 프로젝트)의 PRD 중 아직 구현하지 않은 기능 하나를 골라, 기술 스펙으로 확장하고 완료 조건이 붙은 태스크 3개 이상으로 분해한다. 그중 최소 1개 태스크는 계획 모드의 승인 게이트를 거쳐 실제로 구현까지 완료한다.

제출 형식 — ① SPEC.md 파일 ② 완료 조건이 명시된 TASKS.md ③ 계획 모드 승인 화면 캡처 1장 ④ 구현 중 스펙을 갱신했다면 그 변경 내역을 하나의 문서로 정리해 제출한다.

10더 알아보기

Claude Code 계획 모드 공식 문서 — 계획 모드 진입/승인 단축키와 동작 방식 확인용
이 과정 PRD.md 9절 — PRD 작성 실습 — 이번 차시가 이어받는 PRD 작성 5단계 워크플로 복습용

기술 스펙(Technical Spec): — PRD가 정의한 '무엇을 왜'를 '어떻게 구현할지'로 옮긴 문서. 데이터 모델, API 형태, 에러 처리 방식 등을 담는다.
완료 조건(Definition of Done): — 하나의 태스크가 끝났다고 판단할 수 있는, 직접 확인 가능한 구체적 기준.
계획 모드(Plan Mode): — 코드를 바로 실행하지 않고 계획을 먼저 보여준 뒤 승인을 받고서야 진행하는 Claude Code의 동작 모드.

다음 차시 예고 — 다음 차시에서는 이렇게 승인받은 태스크를 실제로 실행해, 구글 시트와 데이터베이스를 자동으로 동기화하는 파이프라인을 만듭니다. 대량 데이터를 배치로 나누고, API 실패에 대비한 재시도 로직까지 다룹니다.