spec 문서 만들기

1. 무엇을 하나

코드를 짜기 전에 무엇을 만들지를 검증 가능한 명제로 고정한다. 그 산출물이 스펙(spec) 문서다.

• onboarder: 참고 자료를 업로드하면 AI 가 빈 곳을 질문(Q&A)으로 채우고, 개요·입력·처리·출력·예외·규칙이 정리된 스펙 문서를 생성하는 사내 웹 도구.
• 흐름: onboarder 로 스펙 생성 → 내보내기 zip 을 프로젝트 src/docs/spec/ 에 배치 → /develop 의 요구사항 근거로 사용
• 스펙이 명제 단위로 또렷하면 /develop 의 5.5단계(스펙 작성)와 spec-verifier 검증이 정확해진다. (참고: CHAP.03 개발 - L02 기능 개발)

2. onboarder 접속

브라우저에서 프로젝트 대시보드로 접속한다. 로그인은 필요 없다.

https://onboarder-dev.popupstudio.ai/projects/dashboard/

3. 프로젝트 만들기

1. 새 프로젝트 로 이름·설명을 입력한다.
2. 예: 이름 법인세 보고서 자동화, 설명 세무조정계산서 분석 → 법인세 분석 보고서 생성
3. 생성 을 누르면 상세 페이지로 넘어간다.

4. 자료 올리고 분석

구현 대상과 관련된 참고 자료를 올리면 AI 가 이를 파싱해 Q&A 질문을 준비한다.

실습용 자료는 예제 프로젝트 법인세 보고서 자동화 8 의 내보내기 zip 안 data/ 폴더에 있다. 아래 주소로 zip 을 받아 압축을 풀면 data/ 가 나온다.

https://onboarder-dev.popupstudio.ai/api/projects/ho91hax3lguqnc15/export/

1. 상세 페이지에 data/ 안의 파일을 드래그해 업로드한다.
2. 파일 분석 시작 을 누르고 분석이 끝날 때까지 기다린다. (자료 양에 따라 1~5분)

5. Q&A 인터뷰

AI 가 생성한 질문에 답하며 스펙의 결정되지 않은 항목을 채운다.

1. Q&A 인터뷰 를 누른다.

2. 위쪽 충분도 바가 100% 에 가까워지도록 답한다.

3. 답변은 스펙 품질에 직결된다. 애매하게 답하면 스펙도 애매해지고 이후 검증도 헐거워진다.

   • 단위·정밀도 명시: "억원 단위, 소수점 둘째 자리" 처럼.
   • 실제 값/예시 포함: 입력 예와 기대 출력을 함께.
   • 아직 결정 안 된 항목은 미정 으로 두고 넘어가도 된다.

6. 스펙 문서 생성

1. 스펙 문서 생성 을 누른다.
2. 개요·입력·처리·출력·예외·규칙이 정리된 스펙 문서가 나온다.
3. 내용이 부족하면 재생성 으로 다시 뽑는다. Q&A 답변이 근거이므로, 부실하면 5단계로 돌아가 보강하는 편이 빠르다.

7. 스펙을 프로젝트에 넣기

스펙 화면의 개발 프로젝트로 내보내기(.zip) 로 zip 을 받는다. zip 안 레이아웃은 다음과 같다.

export.zip
├── docs/spec/
│   ├── development_spec.md      ← 사람이 읽는 스펙 본문 (개요·입력·처리·출력·예외·규칙)
│   ├── development_spec.json    ← 같은 스펙의 구조화 버전
│   ├── qa_full_log.md           ← Q&A 인터뷰 전체 로그 (결정 근거)
│   ├── file_analysis.md         ← 업로드 자료 분석 요약
│   └── CLAUDE_SNIPPET.md        ← CLAUDE.md 에 덧붙일 프로젝트 맥락 스니펫
└── data/<원본파일>              ← 업로드한 참고 자료 원본

1. zip 을 압축 해제한다. (zip 인 채로 두면 안 된다.)
2. 풀린 docs/spec/ 폴더를 통째로 본인 프로젝트의 src/docs/ 아래에 복사한다.
3. 경로가 src/docs/spec/development_spec.md 가 되면 배치 완료다.
4. CLAUDE_SNIPPET.md 의 내용은 필요하면 프로젝트 src/CLAUDE.md 의 맥락 섹션에 반영한다.

data/ 는 이후 파싱·테스트 시 샘플 입력으로 재사용한다.

8. 스펙대로 개발

프로젝트 src 에서 Claude Code 를 켠다.

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/my_project/src
gildong@ip-172-31-39-132:~/my_project/src$ claude

docs/spec/development_spec.md 를 요구사항으로 삼아 개발해줘

• /develop 은 이 문서를 상위 요구사항 근거로 읽고, 5.5단계에서 이번 사이클의 SoT(docs/specs/{app}.md)를 그 기반으로 작성한다. 즉 onboarder 스펙이 develop 스펙의 씨앗이 된다. (참고: CHAP.03 개발 - L02 기능 개발)
• "무엇을 만들지" 가 명제로 고정돼 있으므로, 맨땅 프롬프트보다 스펙·검증이 훨씬 정확해진다.

마무리

• 핵심 정리: onboarder 로 스펙을 생성(업로드·분석 → Q&A → 스펙)하고, 내보내기 zip(§7 의 docs/spec/ 파일들 + data/)을 프로젝트 src/docs/spec/ 에 배치해 /develop 의 요구사항 근거로 연결했다.
• 주의 사항: Q&A 를 뭉뚱그리면 스펙도 뭉뚱그려지고 spec-verifier 검증도 헐거워진다. 단위·예시를 명제 단위로 답하는 것이 핵심이다.
• 다음 시간: 이 스펙으로 프로젝트를 처음부터 생성해 한 바퀴 돈다.