4-2. 명세 작성과 문서화

01

AI가 이해하는 명세 작성법

명확하고 실행 가능한 명세의 조건

명세 품질 측정기

0%

모호함 보통 명확함

❌ 나쁜 명세 예시

사용자 관리 기능을 만들어주세요. 로그인, 회원가입이 있어야 하고 보안도 신경 써주세요. 빠르게 동작했으면 좋겠어요.

✅ 좋은 명세 예시

## 사용자 인증 모듈 ### 기능 요구사항 1. 이메일/비밀번호 기반 회원가입 - 이메일 형식 검증 (RFC 5322) - 비밀번호: 최소 8자, 대소문자+숫자+특수문자 2. JWT 기반 로그인 - Access Token: 15분 만료 - Refresh Token: 7일 만료 ### 비기능 요구사항 - 응답 시간: p99 < 200ms - BCrypt 해싱 (cost factor: 12)

📌 좋은 명세의 5가지 원칙 (SMART)

Specific (구체적) — 무엇을, 어떻게, 어떤 조건에서를 명확히 기술
Measurable (측정 가능) — 성공 기준을 수치로 정의
Actionable (실행 가능) — 바로 구현할 수 있는 수준의 상세함
Relevant (관련성) — 비즈니스 목표와 연결된 요구사항
Time-bound (제약 조건) — 성능, 보안 등 비기능 요구사항 포함

02

프롬프트 아키텍처

효과적인 AI 지시를 위한 구조화된 프롬프트 설계

🎯 Role Definition (역할 정의) ▼

AI에게 특정 전문가 역할을 부여하여 응답의 맥락과 품질을 높입니다.

                                "당신은 10년 경력의 시니어 백엔드 아키텍트입니다. Clean Architecture와 DDD에 깊은 이해를 가지고 있으며, 확장 가능한 시스템 설계에 전문성이 있습니다."
                            

📋 Context Setting (컨텍스트 설정) ▼

프로젝트 배경, 기술 스택, 제약 조건 등 필요한 맥락 정보를 제공합니다.

                                "현재 프로젝트: e-commerce 플랫폼

                                기술 스택: TypeScript, NestJS, PostgreSQL

                                제약: MSA 구조, 이벤트 소싱 패턴 적용"

📝 Task Description (작업 기술) ▼

수행할 작업을 단계별로 명확하게 기술합니다.

                                "다음 작업을 수행해 주세요:

                                1. 주문 도메인의 Aggregate Root 설계

                                2. 주문 상태 변경 이벤트 정의

                                3. 주문 리포지토리 인터페이스 작성"

📐 Output Format (출력 형식) ▼

원하는 결과물의 형식을 정확히 지정합니다.

                                "출력 형식:

                                - TypeScript 코드 블록으로 작성

                                - 각 클래스에 JSDoc 주석 포함

                                - 파일 경로 주석 (// src/domain/...)"

✅ Constraints & Examples (제약과 예시) ▼

지켜야 할 규칙과 참고할 예시를 제공합니다.

                                "제약 조건:

                                - 외부 라이브러리 최소화

                                - 불변 객체 패턴 사용

                                예시 참조: [기존 Product 도메인 코드]"

💡 프롬프트 아키텍처 팁

복잡한 작업일수록 단계별로 분리하세요. 한 번에 모든 것을 요청하기보다, 설계 → 구현 → 검토 순서로 나누어 진행하면 품질이 높아집니다. 각 단계의 결과물을 다음 단계의 컨텍스트로 활용하세요.

03

ADR (Architecture Decision Record)

아키텍처 결정을 문서화하는 표준 방법

📄

ADR-001: 이벤트 소싱 패턴 도입

Status: Accepted | Date: 2026-01-15

▸ Context (맥락)

주문 시스템에서 상태 변경 이력을 추적하고, 특정 시점의 상태를 복원해야 하는 요구사항이 있습니다. 현재 CRUD 기반 설계로는 변경 이력 관리가 어렵고, 감사 로그를 별도로 구현해야 합니다.

▸ Decision (결정)

주문 도메인에 이벤트 소싱 패턴을 도입합니다. 모든 상태 변경을 이벤트로 저장하고, 현재 상태는 이벤트 리플레이를 통해 재구성합니다.

▸ Consequences (결과)

장점: 완전한 감사 추적, 시점 복원 가능, 이벤트 기반 통합 용이
단점: 학습 곡선, 쿼리 복잡성 증가, 저장소 용량 증가
완화 방안: CQRS 패턴 병행, 스냅샷 전략 적용

📝

Context

결정이 필요한 배경과 상황을 설명합니다. 문제점과 제약 조건을 명시합니다.

⚖️

Decision

내린 결정과 그 이유를 기록합니다. 고려했던 대안들도 함께 기록합니다.

📊

Consequences

결정의 장단점과 영향을 분석합니다. 위험 완화 방안도 포함합니다.

04

API 스펙 작성

OpenAPI, GraphQL Schema 등 API 명세 작성

REST API

GraphQL

gRPC

GET /api/v1/orders/{orderId} 주문 상세 조회

POST /api/v1/orders 새 주문 생성

PUT /api/v1/orders/{orderId}/status 주문 상태 변경

DELETE /api/v1/orders/{orderId} 주문 취소

🔧 명세 빌더 (Interactive)

기능 이름

설명

입력 파라미터

출력 형식

interface Specification { name: "명세 이름을 입력하세요", description: "설명을 입력하세요", input: [], output: { format: "json" } }

05

명세 품질 체크리스트

AI에게 전달하기 전 확인해야 할 항목들

✓

명확한 목표 정의 무엇을 달성하려는지 한 문장으로 설명할 수 있는가?

✓

구체적인 입출력 명시 입력 데이터와 기대하는 출력 형식이 정의되어 있는가?

✓

제약 조건 나열 성능, 보안, 호환성 등 지켜야 할 조건이 있는가?

✓

예외 케이스 정의 에러 상황과 처리 방법이 명시되어 있는가?

✓

기술 스택 명시 사용할 언어, 프레임워크, 라이브러리가 지정되어 있는가?

✓

예시 코드 또는 참조 포함 따라야 할 코딩 스타일이나 패턴 예시가 있는가?

⚠️ 체크리스트를 완료하세요

위의 항목을 모두 클릭하여 체크하면, 상단의 품질 측정기가 올라갑니다. 모든 항목을 충족하는 명세가 AI로부터 최상의 결과를 얻을 수 있습니다.

SUMMARY

핵심 요약

AI가 이해하는 명세는 SMART 원칙을 따른다: Specific, Measurable, Actionable, Relevant, Time-bound
프롬프트 아키텍처: 역할 정의 → 컨텍스트 설정 → 작업 기술 → 출력 형식 → 제약과 예시
ADR로 아키텍처 결정을 문서화: Context, Decision, Consequences
API 스펙은 OpenAPI, GraphQL Schema 등 표준 형식으로 작성
명세 작성 전 품질 체크리스트를 활용하여 누락 항목 확인