d01/04. sdd-philosophy.md

1일차 2교시: SDD 철학과 단계 구분

이 교시는 실습을 시작하기 전에 무엇을 왜 이 순서로 하는가를 이해하는 시간입니다. 여기서 경계가 흐리면 이후 슬래시 명령 입력도 뒤섞입니다.

교시 목표

• Vibe Coding과 SDD의 차이를 설명할 수 있다.
• Specify -> Plan -> Tasks -> Implement의 차이를 설명할 수 있다.
• Clarify와 Analyze가 언제 끼어드는지 설명할 수 있다.
• Constitution, Specify, Plan에 각각 어떤 내용을 넣어야 하는지 구분할 수 있다.

왜 이 교시가 중요한가

설계서의 핵심 의도는 AI를 빠른 생성기가 아니라 검토 가능한 흐름 속 도구로 쓰게 만드는 데 있습니다. 그냥 Copilot에 바로 구현을 시키면 빠를 수는 있지만 다음 문제가 생기기 쉽습니다.

• 요구사항이 파일로 고정되지 않습니다.
• 사람마다 이해한 기능이 달라집니다.
• 테스트 기준이 늦게 정해집니다.
• 변경이 생기면 어디서부터 다시 시작할지 판단하기 어렵습니다.

SDD는 이 문제를 규칙 -> 요구사항 -> 설계 -> 작업 -> 구현의 순서로 통제합니다.

• 규칙 : constitution
• 요구사항 : specify
• 설계 : plan
• 작업 : task
• 구현 : implement

SDD 4단계 공식 흐름

1. Specify

무엇을 만들지와 왜 필요한지를 정리합니다.

2. Plan

어떤 기술과 구조로 만들지 정합니다.

3. Tasks

구현 가능한 작업 단위로 쪼갭니다.

4. Implement

작업 목록을 바탕으로 실제 코드를 만듭니다.

보조 단계의 역할

/speckit.clarify

spec 안의 모호한 표현을 질문과 답으로 구체화합니다.

/speckit.analyze

constitution, spec, plan 사이에 충돌이나 누락이 없는지 점검합니다.

가장 많이 헷갈리는 경계

구분들어가야 하는 것들어가면 안 되는 것

Constitution	테스트 원칙, 브랜치 정책, 문서-코드 정합성, 보안 기준	특정 기능 요구사항, 특정 화면 배치, 특정 DB 테이블
Specify	사용자 문제, 사용자 시나리오, 비즈니스 규칙, 수용 기준	React 사용, FastAPI 사용, 테이블 구조 세부 설계
Plan	기술 스택, 아키텍처, 데이터 모델, API 계약, 테스트 전략	"사용자는 태그를 추가할 수 있어야 한다" 같은 요구사항 원문

같은 기능을 서로 다른 명령에 넣어 보면

주제: Todo 앱에 태그 기능 추가

/speckit.constitution에 맞는 입력

이 프로젝트의 기본 원칙을 작성해줘.

- 모든 사용자 기능은 테스트가 있어야 완료로 본다.
- 문서와 코드가 다르면 문서를 먼저 수정한다.
- 직접 main 브랜치에 커밋하지 않는다.
- UI는 모바일과 데스크톱 모두에서 읽기 쉬워야 한다.
- 보안상 비밀값은 .env로 관리하고 저장소에 커밋하지 않는다.

이 입력은 팀이 계속 지킬 규칙을 말합니다.

/speckit.specify에 맞는 입력

사용자가 Todo 항목에 여러 개의 태그를 붙일 수 있게 해줘.
태그를 통해 항목을 분류하고 나중에 필터링하기 쉽게 하는 것이 목적이다.
사용자는 태그를 추가, 삭제, 조회할 수 있어야 한다.
같은 태그를 한 항목에 중복으로 넣을 수 없고, 태그 이름은 20자를 넘기지 않는다.
태그가 있는 Todo와 없는 Todo를 구분해서 볼 수 있어야 한다.

이 입력은 기능 요구와 사용자 가치를 말합니다.

/speckit.plan에 맞는 입력

이 기능은 기존 Todo 앱에 추가한다.
프론트엔드는 Vite와 Vanilla JavaScript를 유지하고, 백엔드는 FastAPI를 사용한다.
Todo와 Tag는 다대다 관계로 설계하고, SQLite를 사용한다.
태그 필터 API와 태그 추가/삭제 API를 정의해줘.
pytest 기반 테스트 전략과 입력 검증 방식을 포함해줘.

이 입력은 구현 방식과 설계 방향을 말합니다.

추가 비교 예시

예시 1: 사내 회의실 예약 도구

• Constitution: 승인 없는 직접 배포 금지, 감사 로그 필수, 민감 정보 마스킹
• Specify: 사용자는 회의실을 날짜와 시간으로 검색하고 예약해야 함
• Plan: Django + PostgreSQL, 예약 중복 방지 트랜잭션, 관리자 승인 API

예시 2: 교육용 과제 제출 서비스

• Constitution: 모든 제출 기록은 추적 가능해야 함, 삭제는 soft delete 사용
• Specify: 학생은 마감 전까지 과제를 제출하고 수정 이력을 확인할 수 있어야 함
• Plan: Next.js + FastAPI, 제출물 버전 테이블, 파일 업로드 저장 전략

초심자가 자주 하는 실수

실수 1. constitution에 기능 요구를 넣음

예: 사용자는 태그를 5개까지 추가할 수 있어야 한다

이 문장은 프로젝트 원칙이 아니라 기능 규칙이므로 spec 쪽에 가야 합니다.

실수 2. specify에 기술 스택을 넣음

예: React와 Supabase로 만들고 배포는 Vercel로 한다

이 문장은 구현 결정이므로 plan 쪽에 가야 합니다.

실수 3. plan에 사용자 가치를 빼먹음

plan은 구현 문서이지만, spec의 어떤 요구를 만족시키기 위한 설계인지 연결되어야 합니다.

실습

1. 현재 프로젝트에서 /speckit.constitution, /speckit.specify, /speckit.plan에 각각 무엇을 넣어야 하는지 한 문장씩 적어 봅니다.
2. 아래 세 문장을 보고 어느 명령에 들어가야 하는지 구분합니다.

• 한 사용자는 같은 알림을 두 번 읽음 처리할 수 없어야 한다
• 테스트가 없는 기능은 완료로 보지 않는다
• 알림 읽음 상태는 user_notification 테이블에서 관리한다

1. 구분 결과를 동료와 비교합니다.

스스로 점검

1. Constitution은 프로젝트 전체에 적용되는가, 이번 기능에만 적용되는가?
2. Specify는 사용자와 비즈니스 관점에서 읽히는가?
3. Plan은 구현자와 리뷰어가 구조를 검토할 수 있을 만큼 구체적인가?