1. AI 친화적 요구사항 작성

AI와 함께하는 개발 환경에서는 전통적인 요구사항 명세서 작성법과는 다른 접근이 필요합니다. Claude Code는 자연어를 이해할 수 있지만, 그렇다고 해서 모호하거나 추상적인 표현을 선호하지는 않습니다. 오히려 명확하고 구조화된 지시사항을 제공할 때 더 정확하고 효율적인 코드를 생성할 수 있습니다. 따라서 AI 시대의 요구사항 명세는 기계가 이해하기 쉬우면서도 인간이 검토하고 수정하기 편한 형태로 작성되어야 합니다.

1.1 명확성과 구체성

AI는 애매모호한 표현을 해석하는 데 어려움을 겪습니다. 인간은 맥락을 통해 의미를 추론할 수 있지만, Claude Code는 명시적으로 작성된 내용을 바탕으로 판단하기 때문입니다. 따라서 요구사항은 가능한 한 명확하고 구체적으로 작성해야 합니다. 특히 UI/UX 관련 요구사항에서는 시각적 요소들을 수치로 표현하고, 동작 방식을 단계별로 명시하는 것이 중요합니다.

나쁜 예

사용자 친화적인 인터페이스를 만들어 주세요.

좋은 예

사용자 인터페이스 요구사항:
- 메인 네비게이션은 상단에 고정
- 버튼 크기: 최소 44px x 44px (터치 접근성)
- 색상 대비: WCAG AA 기준 준수
- 로딩 상태: 스켈레톤 UI 표시
- 에러 메시지: 사용자가 이해할 수 있는 자연어
- 반응형 디자인: 모바일(320px), 태블릿(768px), 데스크톱(1024px+)

1.2 컨텍스트 제공

Claude Code가 올바른 결정을 내릴 수 있도록 충분한 배경 정보를 제공하는 것이 필수입니다. 동일한 기능이라도 사용되는 서비스의 성격, 타겟 사용자, 비즈니스 모델에 따라 구현 방식이 완전히 달라질 수 있기 때문입니다. 예를 들어, 스타트업의 MVP와 대기업의 엔터프라이즈 시스템에서 요구되는 보안 수준과 확장성은 현저히 다릅니다.

프로젝트 컨텍스트 템플릿

프로젝트명: [서비스명]
도메인: [비즈니스 영역]
타겟 사용자: [구체적인 사용자 페르소나]
비즈니스 모델: [수익 모델]
기술 스택: [사용할 기술들]
제약사항: [시간, 예산, 기술적 한계]
성공 지표: [측정 가능한 KPI]

1.3 예시 기반 설명

Claude가 이해하기 쉽도록 구체적인 예시를 포함하는 것이 매우 효과적입니다. 추상적인 설명보다는 실제 데이터 구조, API 응답 형태, 화면 플로우 등을 예시로 제시하면 Claude가 요구사항의 의도를 정확히 파악할 수 있습니다. 또한 예시를 통해 개발자도 최종 결과물을 더 명확히 예상할 수 있어 의사소통 효율성이 크게 향상됩니다.

API 설계 예시

기능: 게시물 목록 조회
엔드포인트: GET /api/posts

쿼리 파라미터:
- page: 페이지 번호 (기본값: 1)
- limit: 페이지당 항목 수 (기본값: 20, 최대: 100)
- category: 카테고리 필터 (선택사항)
- search: 검색 키워드 (선택사항)

응답 예시:
{
  "posts": [
    {
      "id": "post-123",
      "title": "게시물 제목",
      "content": "게시물 내용 미리보기...",
      "author": {
        "id": "user-456",
        "name": "작성자명",
        "avatar": "https://example.com/avatar.jpg"
      },
      "createdAt": "2024-08-13T10:00:00Z",
      "category": "tech",
      "tags": ["javascript", "react"],
      "likeCount": 42,
      "commentCount": 7
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 10,
    "totalItems": 200,
    "hasNext": true,
    "hasPrev": false
  }
}

2. AI와의 협업을 위한 요구사항 구조화

복잡한 프로젝트를 Claude Code와 함께 개발할 때는 체계적인 구조화가 필요합니다. 전체 시스템을 한 번에 구현하려고 하면 Claude도 혼란을 겪을 수 있고, 개발자도 전체적인 일관성을 유지하기 어려워집니다. 따라서 에픽-스토리-태스크의 3단계 구조를 활용하여 큰 그림에서 세부 구현까지 단계적으로 접근하는 것이 효과적입니다.

2.1 에픽(Epic) - 스토리(Story) - 태스크(Task) 구조

2.1.1 에픽 레벨

에픽: 사용자 인증 시스템
목표: 안전하고 편리한 사용자 인증 환경 제공
기간: 2주
의존성: 데이터베이스 스키마 설계 완료 후

2.1.2 스토리 레벨

스토리: 이메일 회원가입
사용자: 신규 사용자
목표: 이메일과 비밀번호로 계정 생성
조건:
  - 이메일 중복 검증
  - 비밀번호 강도 검증
  - 이메일 인증 필요
완료 기준:
  - 회원가입 폼 작동
  - 인증 이메일 발송
  - 이메일 인증 완료 시 계정 활성화

2.1.3 태스크 레벨

태스크 1: 회원가입 API 엔드포인트 구현
- POST /api/auth/register
- 입력 검증 (이메일 형식, 비밀번호 강도)
- 중복 이메일 체크
- 비밀번호 해싱
- 사용자 레코드 생성 (비활성 상태)
- 인증 토큰 생성 및 이메일 발송

태스크 2: 이메일 인증 API 구현
- GET /api/auth/verify?token=xxx
- 토큰 유효성 검증
- 사용자 계정 활성화
- 성공 페이지로 리디렉션

태스크 3: 회원가입 폼 UI 구현
- 이메일, 비밀번호, 비밀번호 확인 입력 필드
- 실시간 유효성 검사
- 에러 메시지 표시
- 로딩 상태 처리

2.2 반복적 개선을 위한 요구사항 관리

바이브 코딩의 핵심 장점 중 하나는 빠른 반복과 개선입니다. Claude Code와의 대화 과정에서 새로운 아이디어가 나오거나 기존 요구사항의 한계가 발견되는 경우가 많기 때문에, 요구사항 명세서도 이러한 변화를 유연하게 수용할 수 있어야 합니다. 정적인 문서가 아닌 살아있는 문서로서 지속적으로 업데이트되고 개선되어야 합니다.

2.2.1 버전 관리

요구사항 문서도 코드처럼 버전을 관리하는 것이 중요합니다. 특히 Claude Code와 여러 차례 대화를 나누며 요구사항이 진화하는 과정에서, 어떤 시점에 어떤 결정이 내려졌는지 추적할 수 있어야 합니다.

v1.0: 초기 요구사항 정의
v1.1: 사용자 피드백 반영
v1.2: 기술적 제약사항 추가
v2.0: 스코프 확장

2.2.2 변경 이력 추적

모든 변경사항에 대해 명확한 이유와 영향 범위를 기록해야 합니다. 이는 나중에 문제가 발생했을 때 원인을 파악하거나, 비슷한 상황에서 참고할 수 있는 중요한 자료가 됩니다.

변경일: 2024-08-10
변경자: 기획자
변경 내용: 로그인 방식에 소셜 로그인 추가
영향 범위: 인증 시스템 전체
승인자: 개발팀 리드

2.2.3 AI 피드백 통합

Claude Code와의 대화 과정에서 나온 개선사항을 체계적으로 문서화하는 것이 중요합니다. AI는 종종 인간이 놓치기 쉬운 기술적 이슈나 최적화 방안을 제안하는데, 이러한 피드백을 요구사항에 반영하면 더 나은 시스템을 구축할 수 있습니다.

AI 제안사항:
- 현재 API 설계에서 N+1 쿼리 문제 발생 가능
- GraphQL 또는 데이터 로더 패턴 도입 검토 필요
- 캐싱 전략 추가로 성능 최적화 가능

검토 결과:
- GraphQL 도입: 3주 추가 개발 필요 → 다음 버전으로 연기
- 캐싱 전략: Redis 도입으로 현재 버전에 포함
- N+1 쿼리: Prisma의 include 최적화로 해결

2.2.4 도구와 템플릿 활용

효율적인 요구사항 관리를 위해서는 적절한 도구와 템플릿을 활용하는 것이 중요합니다. 일관된 형식으로 요구사항을 작성하면 Claude Code가 더 쉽게 이해할 수 있고, 팀원들 간의 소통도 원활해집니다. 아래 템플릿은 기본적으로 갖춰야 하는 명세를 담아봤습니다. 다만, 이러한 명세서는 개발자와 비개발자, 규모, 예산 등에 따라 달라질 것입니다. 프로젝트 특성에 맞게 수정하여 사용하시기 바랍니다.

2.2.5 요구사항 명세서 템플릿

# [프로젝트명] 요구사항 명세서

## 1. 프로젝트 개요
- **목적**:
- **범위**:
- **타겟 사용자**:
- **주요 기능**:

## 2. 시스템 아키텍처
- **프론트엔드**:
- **백엔드**:
- **데이터베이스**:
- **인프라**:

## 3. 기능적 요구사항
### 3.1 사용자 관리
- [ ] 회원가입
- [ ] 로그인/로그아웃
- [ ] 프로필 관리

### 3.2 핵심 기능
- [ ] 기능 1
- [ ] 기능 2
- [ ] 기능 3

## 4. 비기능적 요구사항
- **성능**:
- **보안**:
- **사용성**:
- **호환성**:

## 5. 제약사항
- **기술적 제약**:
- **비즈니스 제약**:
- **시간 제약**:

## 6. 성공 지표
- **KPI 1**:
- **KPI 2**:
- **KPI 3**:

이렇게 구조화된 요구사항 명세서를 통해 Claude Code와의 협업 효율성을 극대화하고, 바이브 코딩의 진정한 가치를 실현할 수 있습니다. 중요한 것은 문서 작성 자체가 목적이 아니라 AI와 함께 더 나은 소프트웨어를 만들어가는 과정에서 효과적인 소통 도구로 활용하는 것입니다. 처음에는 이러한 방식이 낯설 수 있지만 Claude Code와 몇 번 프로젝트를 진행하다 보면 자연스럽게 AI 친화적인 요구사항 작성법을 익히실 수 있습니다.

3. 비개발자와 개발자를 위한 요구사항 템플릿

로그인, 로그아웃, 게시판, 댓글이 있는 간단한 '감귤 주문 서비스 MVP'를 만든다고 했을 때, 비개발자와 개발자 템플릿을 보면서 설명을 해보도록 하겠습니다. 위에 있는 모든 내용을 다 써넣은 것은 아니고, 각자 상황에 맞게 간소화 해보았습니다.

아래 있는 md 양식을 그대로 Claude Code에게 명령을 내리는 것이 아니라 요구사항.md 파일로 만들어 아래처럼 프롬프트로 입력합니다.

요구사항.md 파일을 참고하여 해당 MVP 서비스를 만들어주세요.

3.1 비개발자를 위한 요구사항 템플릿

비개발자분들은 기술적인 세부사항보다는 사용자 관점에서 서비스가 어떻게 작동해야 하는지에 집중하여 요구사항을 작성하시면 됩니다. 다만 코드를 전혀 모르는 상태에서 개발이 이뤄질 경우 유지보수가 쉽지는 않고, 개발한 부분이 블랙박스로 남는다는 사실을 유념해야 합니다. 그렇기에 개발 학습을 병행하시길 권해드립니다.

# [제목] 서비스 MVP 요구사항 명세서

## 1. 서비스 개요
**목적**: [서비스 개발에 구체적인 개발 목적]
**타겟 사용자**: [나이, 성별 등 상세한 타겟팅, 구체적 사용자 페르소나]
**핵심 가치**: [핵심적으로 전달하려고 하는 가치]
**비즈니스 모델**: [수익 모델]
**목표**: [사용자가 이 서비스를 통해 얻는 구체적 경험, 성공지표 등 KPI]
**제약사항**: [시간, 예산, 기술적 한계]

## 2. 주요 기능
### 2.1 [로그인, 주문 등] 기능
- [기능의 상세 내용]

## 3. 화면 구성
### 3.1 [메인, 상품 목록 등] 페이지
- [페이지 상세 정보, 기능과 구성 모두 상세하게 제시]

## 4. 사용자 시나리오
1. [사용자가 메인 페이지에 들어옴 등의 구체적 시나리오 단계별 제시]

## 5. 디자인 요청사항
[6장에서 작성된 구체적 디자인 요구사항 design-system.md 또는
design-system.JSON 파일 경로]를 기반으로 개발

## 6. 기본 에셋
[이미지, 동영상 등이 있는 폴더]를 기반으로 개발하며
아래 파일별 사용되어야 하는 페이지를 참고하여 개발
- [파일 이름]: [파일이 쓰여야 하는 페이지]

## 7. 개발 우선순위
이번 작업을 통해 [1] 순위까지 개발
### 7.1 [1]순위
- [해당 순위는 한 번에 개발하기가 힘든 프로젝트일 경우 명시,
  만약 한 번에 개발이 되는 가벼운 프로젝트라면 우선순위를 정하지 않아도 됨]

## 8. 유사 서비스 분석
- [비슷한 서비스나 경쟁사 서비스를 분석하여 명시,
  유명한 서비스라면 AI가 레퍼런스를 가지고 있음]

## 9. 상황 설명과 기술 선택
- [해당 서비스 유지보수를 해야 하는 사람은 비개발자]
- [관리자 페이지와 유지보수, 해킹의 위험이 덜한 프레임워크 선택]
- [비개발자에 맞게 설명서를 상세히 작성 필요]
- [배포 방법도 상세히 명시]

3.2 개발자를 위한 요구사항 템플릿

개발자를 위한 요구사항 명세는 2개의 부분으로 나뉩니다.

첫번째는 처음 세팅을 하는 부분입니다. 언어, 라이브러리, 프레임워크, 폴더구조와 버전, 배포 인프라 등을 고려하여 세팅을 요구합니다. 이 부분은 상당 부분 비개발자 요구사항과 유사합니다.

그렇게 세팅이 되면 이제 세부단위 기능 요구사항을 작성하여 개발합니다. 세부 기능 요구사항에는 테스트 코드의 목표와 작성, 통과까지 요구하는 모듈 개발의 모든 절차가 명시되어야 합니다.

3.2.1 세팅 요구사항 템플릿

# [제목] 서비스 MVP 요구사항 명세서

## 1. 서비스 개요
**목적**: [서비스 개발에 구체적인 개발 목적]
**타겟 사용자**: [나이, 성별 등 상세한 타겟팅, 구체적 사용자 페르소나]
**핵심 가치**: [핵심적으로 전달하려고 하는 가치]
**비즈니스 모델**: [수익 모델]
**목표**: [사용자가 이 서비스를 통해 얻는 구체적 경험, 성공지표 등 KPI]
**제약사항**: [시간, 예산, 기술적 한계]

## 2. 주요 기능
### 2.1 [로그인, 주문 등] 기능
- [기능의 상세 내용]

## 3. 화면 구성
### 3.1 [메인, 상품 목록 등] 페이지
- [페이지 상세 정보, 기능과 구성 모두 상세하게 제시]

## 4. 사용자 시나리오
1. [사용자가 메인 페이지에 들어옴 등의 구체적 시나리오 단계별 제시]

## 5. 디자인 요청사항
[6장에서 작성된 구체적 디자인 요구사항 design-system.md 또는
design-system.JSON 파일 경로]를 기반으로 개발

## 6. 시스템 아키텍처
**Frontend**: [React, Tailwind CSS 등 기술과 버전 명시]
**Backend**: [Django, Spring 등 기술과 버전 명시]
**Database**: [개발과 프로덕션 기술 명시]
**Payment**: [결제 스택 명시]
**Deployment**: [배포 스택 명시]

## 7. ERD
[머메이드 형태의 ERD를 기입합니다.
만약 이 부분이 없을 경우 문서 작성을 요구합니다.]

## 8. URL 구조

### 8.1 게시글 API
[App, Method, URL, ViewClass, Note, Auth 등
테이블 형태로 제시합니다.
만약 이 부분이 없을 경우 문서 작성을 요구합니다.]

## 9. 폴더 구조
[폴더와 폴더 안 파일이 있어야 하는 내용 등을 명시합니다.
그렇지 않을 경우 원하지 않는 구조를 잡아 프로젝트를 시작할 수 있으니
꼼꼼하게 작성하길 권합니다.]

## 10. 개발 일정(WBS)과 우선순위
[머메이드 형태의 개발 일정과 일정별 우선순위 기입]

개발자는 작업을 한 번에 시키지 않습니다. 따라서 명령을 내릴 때에는 개발 일정에 따라 세부적인 과업을 지시합니다.

요구사항.md 파일을 읽고, 개발 일정에 따라 우선 환경 세팅을 진행해줘.
내가 이번 단계에서 원하는 환경세팅 목록은 아래와 같아.

- [구체적인 환경세팅 요구사항]

3.2.2 세부단위 기능 요구사항 템플릿

구조가 잡혔다면 이제 하나의 기능단위로 아래와 같은 문서를 작성하여 개발할 필요가 있습니다. MVP 수준이거나, 간단한 프로젝트라면 아래와 같은 문서 양식이 필요하지 않지만 프로젝트가 조금만 커져도 아래와 같은 문서 양식이 필요하게 됩니다.

예를 들어, 실제 규모가 있는 프로젝트의 경우 Table이 매우 많기 때문에 Claude Code가 이 Table을 모두 읽지 않습니다. 필요할 것 같은 테이블을 참조하고, 그러한 테이블이 없다면 탐색할텐데, 탐색하는 과정에서 없다고 판단이 되면 생성하는 경우도 자주 보았습니다. 이는 Table의 복잡도가 상당하기 때문이기도 하며, 세션이 다시 시작되면 Claude Code가 전체 코드를 다 읽지 않고 작업에 필요한 만큼만 읽기 때문이기도 합니다.

과하다고 생각이 된다면 회사에 맞게, 개인에 맞게 수정하여 사용하세요.

# [기능명] 세부 기능 요구사항

## 1. 기능 개요
**기능명**: [예: 사용자 인증 API]
**모듈 위치**: [예: /src/modules/auth]
**의존성**: [예: JWT, bcrypt, nodemailer]
**연관 기능**: [예: 회원가입, 프로필 관리]

## 2. 기능 상세 명세
[입력, 출력 데이터와 타입 예시, 비즈니스 로직 및 예외처리 변수 목록 제시]

## 3. API 명세
[엔드포인트, 요청 예시, 출력 예시(성공과 실패 모두 기입)]

## 4. 데이터베이스 스키마
[관련 테이블 명시(명시하지 않으면 테이블을 생성하거나
다른 테이블에 컬럼 생성할 가능성 있음,
특히 프로젝트가 커지면 커질수록 그러한 경향이 두드러짐)]

## 5. 테스트 요구사항
[단위 테스트, 통합테스트 코드와 성공 지표 제시]

## 6. 보안 요구사항
[보안 요구사항 제시]

## 7. 구현 체크리스트
[단계별 체크리스트 작성]

## 8. 참고사항
[참고할만한 사항 작성]