1. 스펙

시작 상태

준비의 완료 확인이 끝났다는 전제입니다. 다시 확인합니다.

claude --version && ls ~/.claude/settings.json

Claude Code 세션을 열어 /plugin에 superpowers가, /mcp에 playwright가 보이는지도 확인합니다. 버전이나 파일이 없으면 준비: 기본 설정으로, superpowers가 없으면 준비: 공식 플러그인과 스킬로, playwright가 없으면 준비: 브라우저 도구로 돌아갑니다.

이 단계에서 하는 것

새 저장소를 만들고, Prompt의 1번 틀로 인터뷰를 받은 뒤 스펙 파일을 쓰게 합니다. 스펙을 대화가 아니라 파일에 두는 이유는 Feature 개발이 다룹니다.

스펙과 계획을 만드는 방법은 세 가지입니다. 이 튜토리얼의 기본 경로는 첫 번째입니다. 어느 쪽을 골라도 1·2단계의 완료 확인은 같습니다.

방법	계획이 남는 곳	구현으로 넘어가는 방식
인터뷰·계획 프롬프트	저장소 파일	`/clear` 뒤 새 세션이 파일을 읽음
plan mode	세션 안	승인이 곧 모드 전환. 같은 세션에서 계속
superpowers	저장소 파일	`executing-plans` 또는 새 세션이 파일을 읽음

인터뷰·계획 프롬프트는 Prompt의 1번·3번 틀을 붙여 넣어 씁니다. 설정이 필요 없습니다. plan mode는 Shift+Tab으로 순환하거나, 프롬프트 앞에 /plan을 붙이거나, claude --permission-mode plan으로 시작합니다. 세 진입 방법은 같은 모드입니다. 상태줄에 ⏸ plan mode on이 보이는 동안 세션이 읽기 전용이고, 계획이 준비되면 “auto mode로 승인”, “편집마다 승인”, “계속 계획”의 세 가지를 묻습니다. 승인하면 같은 세션이 실행 모드로 바뀌어 구현이 이어집니다. superpowers 플러그인이 설치되어 있으면 “기능을 만들자”는 프롬프트에 brainstorming 스킬이 개입하고, 이어서 writing-plans 스킬이 docs/superpowers/plans/에 계획을 씁니다. 경로는 프롬프트로 바꿀 수 있습니다.

이 튜토리얼은 파일로 남기고 새 세션에서 구현하는 쪽을 택합니다. 근거는 Feature 개발에 있습니다. plan mode로 시작했다면 2단계의 “이 단계에서 하는 것”에 파일로 옮기는 절차가 있습니다.

따라하기

저장소를 만듭니다. npm create vite@latest는 대상 디렉터리가 이미 있고 비어 있지 않으면 무엇을 할지 대화형으로 묻습니다. 아직 없는 새 디렉터리에 스캐폴딩하면 이 물음이 나오지 않습니다.

npm create vite@latest charcount -- --template vanilla-ts
cd charcount && git init
git add -A && git commit -m "chore: Vite 스캐폴딩"
mkdir -p docs/specs docs/plans
claude

이 스캐폴딩에는 기능 코드가 없습니다. npm install은 아직 하지 않습니다. 의존성 설치와 게이트 준비는 3단계에서 합니다. 기능 코드보다 스펙을 먼저 씁니다.

새 charcount 세션의 /mcp에 playwright가 보이는지 확인합니다. 없다면 준비의 등록 범위를 고친 뒤 진행합니다. 기록표를 만듭니다. 기본 설정의 기록표 내용을 docs/tutorial-log.md로 저장합니다.
인터뷰 프롬프트(1번 틀의 각괄호를 채운 것):

글자 수를 세는 웹 페이지를 만들려고 합니다. textarea 하나에 글을 입력하면 그 아래에
글자 수가 실시간으로 표시되는 것이 전부입니다. 저장, 서버, 로그인은 없습니다.
스택은 Vite + TypeScript(프레임워크 없음)입니다.

바로 시작하지 마세요. 먼저 저를 인터뷰해 주세요.
기술 구현, 엣지 케이스, 트레이드오프, 제가 놓쳤을 만한 것을 물으세요.
뻔한 질문은 빼고, 답에 따라 설계가 실제로 달라지는 것만 물으세요.
한 번에 하나씩 물어보세요.

다 물어본 뒤에 docs/specs/<날짜>-charcount.md 에 사양을 쓰세요.

준비에서 superpowers를 설치했으므로 이 프롬프트에 brainstorming 스킬이 개입할 수 있습니다. 개입하면 그대로 따릅니다. 질문 방식은 같습니다. 스펙을 쓰기 전에 접근 두세 개를 먼저 제안하는 점이 다릅니다. 저장 경로를 docs/superpowers/specs/로 잡으면 프롬프트에 적은 docs/specs/ 경로로 쓰게 다시 말합니다. 완료 확인이 그 경로를 봅니다.

인터뷰에서 설계가 실제로 갈리는 질문이 나오는지 봅니다. 나오지 않으면 다음 답을 직접 정해서 말합니다.
- “글자”의 정의: 코드 유닛(.length), 코드 포인트(Array.from), 그래핌(Intl.Segmenter) 중 무엇인가. 이모지 하나, 조합 한글 한 글자가 각각 몇으로 세어져야 하는가.
- 공백과 줄바꿈을 세는가.
- 빈 입력은 0인가.
이 튜토리얼의 기본 완주 경로는 두 가지를 정해 둡니다. 글자는 “사람이 보는 글자 수”, 즉 그래핌이나 최소 코드 포인트로 세고, 이모지 U+1F600은 1로 셉니다. 공백과 줄바꿈도 기본으로 셉니다. “공백 제외” 옵션은 7단계에서 따로 만듭니다. 다르게 골라도 됩니다. 코드 유닛을 골랐다면 10단계 전에, 공백 제외를 기본으로 골랐다면 7단계 전에 스펙과 테스트를 기본 경로에 맞추는 절차를 밟습니다.
사양이 써지면 두 절을 더 추가하게 합니다.

사양에 두 절을 더해 주세요.
- "범위 밖": 저장, 여러 문서, 서식, 모바일 최적화
- "테스트 훅": 글자 수를 표시하는 요소에 data-testid="count" 를 둔다

끝 비용과 컨텍스트 사용률을 읽어 docs/tutorial-log.md의 “1. 스펙” 행에 적습니다. 세션 수 열에는 1을 적습니다. 2단계가 이 세션을 그대로 이어받습니다.
스펙과 기록표를 함께 커밋합니다. 기록표를 커밋에 넣어야 다음 단계의 “시작 상태”가 요구하는 깨끗한 작업 트리로 넘어갑니다.

git add docs && git commit -m "docs: 스펙과 기록표"

완료 확인

grep -n "범위 밖\|data-testid" docs/specs/*-charcount.md

두 줄이 잡히면 됩니다. 스펙 안에 “글자”의 정의가 한 문장으로 있어야 합니다.

계측 기록

값은 6번에서 이미 적었습니다. 시작 상태를 확인한 직후 시작 비용을, 커밋 직전에 끝 비용과 컨텍스트 사용률을 각각 적고 차액으로 읽습니다. 세션 수는 이 단계에서 연 세션 개수입니다. 이 세션은 아직 /clear하지 않습니다. 2단계가 이어받으므로 이번 단계의 끝 비용을 2단계의 시작 비용으로 그대로 씁니다. 1·2단계를 한 세션으로 지나가면 두 행의 세션 수는 각각 1입니다. 중간에 세션을 다시 열었다면 그 개수를 그대로 적습니다.

어긋났을 때

인터뷰 없이 바로 코드를 쓰기 시작한다면 프롬프트의 “바로 시작하지 마세요”가 빠졌는지 Prompt에서 확인합니다. 질문이 일반적이라면 “답에 따라 설계가 달라지는 것만”을 다시 강조합니다.