앞서 URL 설계와 DB 설계를 완료했습니다. 이제 이 설계를 바탕으로 AI가 이해할 수 있는 명세서를 작성해보겠습니다. 명세서의 품질이 AI가 생성하는 코드의 품질을 결정합니다.

명세서를 작성하는 방법은 여러분의 코드 이해도에 따라 달라집니다.

1. 이미 코드를 충분히 이해하고 있는 경우: 일반적인 요구사항 명세서 작성
2. 코드를 잘 모르는 경우: 단계별로 직접 구현할 수 있는 '설명서 구현'을 위한 명세서 작성
3. 가장 쉬운 방법: 앞서 작성한 URL 설계와 DB 설계를 AI에게 전달하고, "이 설계를 바탕으로 Django를 사용해서 개발해줘. 방식은 모놀리식이야. 나는 개발을 전혀 모르니, 상세한 설명을 함께 작성해줘."라고 요청

1. 일반적인 요구사항 명세서 작성

코드에 익숙한 분들을 위한 방법입니다. 앞서 설계한 내용을 구조화하여 AI에게 전달합니다.

1.1 명세서 구조

좋은 명세서는 다음 요소를 포함합니다.

1. 프로젝트 개요: 무엇을 만드는지 한 문장으로 설명
2. 기술 스택: 사용할 언어, 프레임워크, 데이터베이스
3. URL 설계: 앞서 작성한 URL 목록
4. DB 설계: 앞서 작성한 모델 정의
5. 기능 요구사항: 각 기능의 상세 설명
6. 제약 조건: 보안, 성능 등의 요구사항

1.2 블로그 명세서 예시

# 개인 블로그 서비스 명세서

## 1. 프로젝트 개요
카테고리와 댓글 기능을 갖춘 개인 블로그 웹 서비스

## 2. 기술 스택
- Backend: Django 5.x
- Database: SQLite (개발), PostgreSQL (운영)
- Frontend: Django Templates + Bootstrap 5

## 3. URL 설계
| URL | Method | 기능 |
|-----|--------|------|
| / | GET | 메인 페이지 (최신 게시글 목록) |
| /posts/ | GET | 게시글 목록 |
| /posts/create/ | GET, POST | 게시글 작성 |
| /posts/<id>/ | GET | 게시글 상세 |
| /posts/<id>/edit/ | GET, POST | 게시글 수정 |
| /posts/<id>/delete/ | POST | 게시글 삭제 |
| /categories/<slug>/ | GET | 카테고리별 게시글 |
| /posts/<id>/comments/ | POST | 댓글 작성 |
| /comments/<id>/delete/ | POST | 댓글 삭제 |

## 4. DB 설계
### Category
- name: CharField(100)
- slug: SlugField(unique)

### Post
- title: CharField(200)
- content: TextField
- author: ForeignKey(User)
- category: ForeignKey(Category, null=True)
- created_at: DateTimeField(auto_now_add)
- updated_at: DateTimeField(auto_now)

### Comment
- content: TextField
- author: ForeignKey(User)
- post: ForeignKey(Post)
- created_at: DateTimeField(auto_now_add)

## 5. 기능 요구사항

### 5.1 사용자 인증
- Django 기본 인증 시스템 사용
- 로그인, 로그아웃, 회원가입

### 5.2 게시글 관리
- 로그인한 사용자만 작성 가능
- 본인 글만 수정, 삭제 가능
- 카테고리 선택은 선택 사항
- 목록에서 페이지네이션 (10개씩)

### 5.3 댓글 기능
- 로그인한 사용자만 작성 가능
- 본인 댓글만 삭제 가능
- 게시글 삭제 시 댓글도 함께 삭제

## 6. 관리자 기능
- Django Admin에서 모든 데이터 관리
- 카테고리 CRUD
- 게시글, 댓글 관리

1.3 쇼핑몰 명세서 예시

# 간단한 쇼핑몰 서비스 명세서

## 1. 프로젝트 개요
상품 등록, 장바구니, 주문 기능을 갖춘 간단한 쇼핑몰

## 2. 기술 스택
- Backend: Django 5.x
- Database: SQLite
- Frontend: Django Templates + Bootstrap 5

## 3. URL 설계
| URL | Method | 기능 |
|-----|--------|------|
| / | GET | 메인 페이지 (추천 상품) |
| /products/ | GET | 상품 목록 |
| /products/<id>/ | GET | 상품 상세 |
| /categories/<slug>/ | GET | 카테고리별 상품 |
| /cart/ | GET | 장바구니 조회 |
| /cart/add/<product_id>/ | POST | 장바구니 담기 |
| /cart/remove/<item_id>/ | POST | 장바구니 빼기 |
| /orders/ | GET | 주문 내역 |
| /orders/create/ | POST | 주문 생성 |
| /orders/<id>/ | GET | 주문 상세 |

## 4. DB 설계
### Category
- name: CharField(100)
- slug: SlugField(unique)

### Product
- name: CharField(200)
- description: TextField
- price: IntegerField
- stock: IntegerField(default=0)
- category: ForeignKey(Category)
- image: ImageField(blank=True)
- created_at: DateTimeField(auto_now_add)

### CartItem
- user: ForeignKey(User)
- product: ForeignKey(Product)
- quantity: IntegerField(default=1)

### Order
- user: ForeignKey(User)
- total_price: IntegerField
- status: CharField (pending, paid, shipped, delivered)
- created_at: DateTimeField(auto_now_add)

### OrderItem
- order: ForeignKey(Order)
- product: ForeignKey(Product)
- quantity: IntegerField
- price: IntegerField (주문 당시 가격)

## 5. 기능 요구사항

### 5.1 상품 관리
- 관리자만 상품 등록, 수정, 삭제
- 카테고리별 필터링
- 재고가 0인 상품은 "품절" 표시

### 5.2 장바구니
- 로그인한 사용자만 이용 가능
- 같은 상품 추가 시 수량 증가
- 재고보다 많이 담을 수 없음

### 5.3 주문
- 장바구니 상품을 한 번에 주문
- 주문 시 재고 차감
- 주문 내역 조회 가능

2. 설명서 구현을 위한 명세서 작성

코드를 잘 모르는 분들을 위한 방법입니다. AI에게 단계별 실행 가이드를 만들어달라고 요청합니다. 이 가이드를 따라하면서 코드를 이해할 수 있습니다.

2.1 프롬프트 작성법

아래 설계를 바탕으로 Django 웹 애플리케이션을 구현하는 단계별 가이드를 `명령어.md` 파일로 작성해줘.

[앞서 진행한 URL 설계, DB 설계 내용을 여기에 복사 붙여넣기]

`명령어.md` 파일은 아래와 같은 형식으로 작성해줘:
- 각 단계를 명확하게 구분
- 터미널 명령어와 코드 수정을 구분
- 코드는 어떤 파일의 어느 부분을 수정하는지 명시
- 각 단계가 왜 필요한지 간단한 설명 추가

2.2 명령어 가이드 예시

AI가 생성할 명령어.md 파일의 예시입니다.

# Django 블로그 구현 가이드

##########################################

# Step 1: 터미널 - 프로젝트 초기 설정 (Windows)

# 가상환경 생성 및 활성화
python -m venv venv
.\venv\Scripts\activate

# Django 설치
pip install django

# 프로젝트 생성
django-admin startproject config .

##########################################

# Step 2: 코드 수정 - 기본 설정 변경

# 파일: config/settings.py
# 위치: ALLOWED_HOSTS 설정
# 이유: 모든 호스트에서 접속 허용 (개발용)

ALLOWED_HOSTS = ["*"]

##########################################

# Step 3: 터미널 - 데이터베이스 초기화 및 서버 실행

# 데이터베이스 마이그레이션
python manage.py migrate

# 개발 서버 실행 (http://127.0.0.1:8000 에서 확인)
python manage.py runserver

##########################################

# Step 4: 터미널 - 블로그 앱 생성

# Ctrl+C로 서버 중지 후 실행
python manage.py startapp blog

##########################################

# Step 5: 코드 수정 - 앱 등록

# 파일: config/settings.py
# 위치: INSTALLED_APPS 리스트
# 이유: 생성한 blog 앱을 프로젝트에 연결

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'blog',  # 추가
]

##########################################

# Step 6: 코드 작성 - 모델 정의

# 파일: blog/models.py
# 이유: 데이터베이스 테이블 구조 정의

from django.db import models
from django.contrib.auth.models import User

class Category(models.Model):
    name = models.CharField(max_length=100)
    slug = models.SlugField(unique=True)

    def __str__(self):
        return self.name

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    author = models.ForeignKey(User, on_delete=models.CASCADE)
    category = models.ForeignKey(
        Category,
        on_delete=models.SET_NULL,
        null=True,
        blank=True
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.title

class Comment(models.Model):
    content = models.TextField()
    author = models.ForeignKey(User, on_delete=models.CASCADE)
    post = models.ForeignKey(
        Post,
        on_delete=models.CASCADE,
        related_name='comments'
    )
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f'{self.author}의 댓글'

##########################################

# Step 7: 터미널 - 모델을 데이터베이스에 반영

python manage.py makemigrations
python manage.py migrate

##########################################

# Step 8: 코드 작성 - 관리자 페이지 등록

# 파일: blog/admin.py
# 이유: 관리자 페이지에서 데이터 관리 가능하게 설정

from django.contrib import admin
from .models import Category, Post, Comment

@admin.register(Category)
class CategoryAdmin(admin.ModelAdmin):
    list_display = ['name', 'slug']
    prepopulated_fields = {'slug': ('name',)}

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'author', 'category', 'created_at']
    list_filter = ['category', 'created_at']
    search_fields = ['title', 'content']

@admin.register(Comment)
class CommentAdmin(admin.ModelAdmin):
    list_display = ['author', 'post', 'created_at']
    list_filter = ['created_at']

##########################################

# Step 9: 터미널 - 관리자 계정 생성

python manage.py createsuperuser

# Username: admin
# Email: admin@example.com
# Password: (원하는 비밀번호)

##########################################

# Step 10: 확인 - 관리자 페이지 접속

# 서버 실행
python manage.py runserver

# 브라우저에서 http://127.0.0.1:8000/admin 접속
# Step 9에서 생성한 계정으로 로그인
# Category, Post, Comment 관리 가능 확인

##########################################

2.3 단계별 진행의 장점

이 방식의 장점은 다음과 같습니다.

1. 이해하면서 진행: 각 단계가 왜 필요한지 알 수 있습니다.
2. 오류 발견 용이: 문제가 생기면 어느 단계에서 발생했는지 알 수 있습니다.
3. 학습 효과: 반복하다 보면 Django의 구조를 자연스럽게 익힙니다.
4. 커스터마이징: 필요에 따라 특정 단계를 수정하기 쉽습니다.

3. 가장 쉬운 방안

코드를 전혀 모르는 분들을 위한 방법입니다. 앞서 작성한 URL 설계와 DB 설계만 있으면 됩니다. AI에게 모든 것을 맡기되, 상세한 설명을 요청합니다. 아래처럼 테이블로 넣지 않고 머메이드만 넣어도 됩니다.

3.1 프롬프트 작성법

나는 개발을 전혀 모르는 사람이야.
아래 설계를 바탕으로 Django 웹 애플리케이션을 만들어줘.

[URL 설계]
(앞서 작성한 URL 설계 내용 붙여넣기)

[DB 설계]
(앞서 작성한 DB 설계 내용 붙여넣기)

[요청사항]
- 방식은 모놀리식(Django Templates 사용)
- 각 파일이 무슨 역할인지 설명해줘
- 코드 작성 후 어떻게 실행하는지 알려줘
- 오류가 발생하면 어떻게 해결하는지도 알려줘

3.2 AI의 응답 활용하기

AI는 다음과 같은 내용을 제공합니다.

1. 프로젝트 구조 설명: 어떤 폴더와 파일이 필요한지
2. 코드 전체: 복사해서 붙여넣기만 하면 되는 완성된 코드
3. 실행 방법: 터미널에서 입력할 명령어
4. 파일별 역할 설명: 각 파일이 무슨 일을 하는지

AI가 제공한 코드를 그대로 사용하되, 실행 중 오류가 발생하면 오류 메시지를 복사해서 AI에게 다시 물어보세요.

아래 오류가 발생했어. 어떻게 해결해야 해?

[오류 메시지 붙여넣기]

3.3 이 방법의 장단점

장점

• 가장 빠르게 결과물을 얻을 수 있습니다
• 코드를 몰라도 시작할 수 있습니다
• AI가 상세한 설명을 제공합니다

단점

• 코드 이해 없이 진행하면 수정이 어렵습니다
• 오류 발생 시 AI에게 계속 물어봐야 합니다
• 세부적인 커스터마이징이 어렵습니다

처음에는 이 방법으로 시작하고, 점차 코드를 이해해 나가는 것을 추천합니다. 완성된 코드를 보면서 "이 부분은 이런 역할이구나"라고 파악하는 것도 좋은 학습 방법입니다.

4. 명세서 작성 팁

4.1 명확하게 작성하세요

모호한 표현을 피하고, 구체적으로 작성하세요.

# 나쁜 예
- 사용자 관리 기능

# 좋은 예
- 사용자 회원가입 (이메일, 비밀번호, 닉네임)
- 로그인/로그아웃 (세션 기반)
- 비밀번호 변경 (현재 비밀번호 확인 필요)

4.2 우선순위를 정하세요

모든 기능을 한 번에 구현하려 하지 마세요. MVP(최소 기능 제품)부터 시작하세요.

## 우선순위

### Phase 1 (MVP)
- 게시글 CRUD
- 카테고리 분류

### Phase 2
- 댓글 기능
- 페이지네이션

### Phase 3
- 태그 기능
- 검색 기능

4.3 예외 상황을 고려하세요

정상 동작뿐 아니라 예외 상황도 명시하세요.

### 게시글 삭제
- 본인 글만 삭제 가능
- 삭제 전 확인 모달 표시
- 삭제 시 관련 댓글도 함께 삭제
- 삭제 후 목록 페이지로 이동

5. AI에게 명세서 검토 요청하기

작성한 명세서를 AI에게 검토받을 수도 있습니다.

아래 명세서를 검토해줘.
- 빠진 기능이 없는지
- 모순되는 부분이 없는지
- 보안상 문제가 될 수 있는 부분이 없는지
- 개선할 점이 있는지

[명세서 내용]

6. Git ignore 설정하기

프로젝트를 GitHub에 올릴 때, 올리면 안 되는 파일들이 있습니다. 가상환경 폴더(venv)나 민감한 설정 파일들이 대표적입니다. .gitignore 파일을 만들어서 이런 파일들을 제외할 수 있습니다.

6.1 .gitignore 파일 생성

프로젝트 최상위 폴더에 .gitignore 파일을 만들고 다음 내용을 작성합니다.

# 가상환경
venv/

# Python 캐시
__pycache__/

# 환경 변수 (비밀키 등)
.env

# SQLite 데이터베이스
db.sqlite3

6.2 각 항목 설명