David Brain

Claude Code 개발 명세서 템플릿

6 min read

Claude Code 개발 명세서 템플릿

이 템플릿의 목적

Claude Code가 최소한의 질문으로 개발을 완료할 수 있도록 “What”과 “How”를 모두 명확하게 정의하는 것이 목표다. 애매한 부분이 있으면 Claude Code가 임의로 판단하므로 모든 항목을 가능한 한 구체적으로 작성한다.

📋 명세서 기본 정보

항목내용
프로젝트프로젝트명
모듈모듈명
작성일YYYY-MM-DD
작성자작성자명
상태작성중 / 검토중 / 확정
우선순위높음 / 중간 / 낮음

🧭 개발 목적

한 문단으로 이 개발이 왜 필요한지 설명한다. Claude Code가 맥락을 이해하고 판단해야 할 때 이 목적을 기준으로 삼는다.

예시: 반복적인 JPA CRUD 코드를 줄이고, 일관된 에러 처리 및
      테넌트 격리를 자동화하여 개발 생산성을 높인다.

📁 프로젝트 구조

Claude Code가 파일을 어디에 생성할지 판단하기 위해 반드시 작성한다. 기존 구조와 새로 생성할 파일을 구분해서 표시한다.

project-root/
└── src/main/java/com/example/
    ├── existing/
    │   ├── ExistingClass.java        ← 기존 파일 (수정 대상)
    │   └── AnotherExisting.java      ← 기존 파일 (참고용)
    └── new/                          ← 새로 생성할 패키지
        ├── NewClass.java             ← 새로 생성
        └── AnotherNew.java           ← 새로 생성

⚙️ 기술 스택 및 제약 조건

Claude Code가 코드를 작성할 때 지켜야 할 기술적 제약을 명시한다.

  • 언어/버전: Java 21
  • 프레임워크: Spring Boot 3.x
  • 빌드 도구: Maven
  • 필수 라이브러리: Lombok, JPA, Hibernate
  • 금지 사항:
    • JPQL 문자열 직접 조합 금지
    • 실제 DB DELETE 금지 (Soft Delete 사용)
    • (추가 금지 사항 작성)

🔢 개발 순서

아이템 간 의존성이 있을 경우 반드시 순서를 명시한다. Claude Code는 이 순서를 엄격히 따른다.

아이템 1. 이름
      ↓  (이유: 아이템 2가 아이템 1에 의존)
아이템 2. 이름
      ↓  (이유: 아이템 3이 아이템 1, 2에 의존)
아이템 3. 이름

✅ 아이템 N. {아이템 이름}

아이템마다 아래 구조를 반복한다.

목적

이 아이템이 해결하는 문제를 한 문장으로 설명한다.

생성/수정할 파일 목록

생성:
  path/to/NewFile.java             ← 역할 설명

수정:
  path/to/ExistingFile.java        ← 어떤 부분을 수정하는지

상세 명세

각 파일별로 아래 항목을 작성한다. Claude Code가 임의로 판단하지 않도록 최대한 구체적으로 작성한다.

{FileName}.java

  • 역할: 한 줄 설명
  • 상속/구현: extends X implements Y
  • 어노테이션: @Component, @Service 등 명시
  • 필드 목록:
    • 타입 필드명 — 설명
  • 메서드 목록:
    • 반환타입 메서드명(파라미터) — 동작 설명
  • 예외 처리: 어떤 상황에서 어떤 예외를 throw하는지
  • 특이사항: 주의해야 할 구현 세부사항

동작 흐름

텍스트 다이어그램으로 주요 흐름을 표현한다.

입력값
  ↓
처리 단계 1
  ↓
처리 단계 2  ← 특이사항 설명
  ↓
결과값 / 예외

완료 기준 체크리스트

Claude Code가 개발 완료 여부를 스스로 판단할 수 있게 작성한다.

  • 정상 케이스 동작 확인
  • 예외 케이스 동작 확인
  • 기존 코드와의 호환성 확인
  • 단위 테스트 작성 완료

🚫 공통 금지 사항

프로젝트 전체에 적용되는 금지 사항을 한곳에 모아 명시한다. Claude Code가 개발 중 이 목록을 참고한다.

  • 금지 사항 1
  • 금지 사항 2
  • 기존 핵심클래스명 구조 변경 금지 (확장만 허용)

📎 참고 문서 및 파일

Claude Code가 참고해야 할 기존 코드나 문서를 명시한다.

  • 설계 문서: 경로/설계문서.md
  • 기존 코드 예시: 경로/ExampleClass.java
  • 관련 표준: 경로/표준문서.md

❓ 판단이 필요한 경우

Claude Code가 개발 중 판단이 필요한 상황이 생기면 아래 원칙을 따른다.

  1. 명세서에 명시된 내용이 있으면 → 명세서를 따른다
  2. 명세서에 없으면 → 개발을 멈추고 질문한다 (임의 판단 금지)
  3. 기존 코드 스타일과 충돌하면 → 기존 코드 스타일을 우선한다

Graph View