기능 개발 전 작성하는 기술 명세서(Tech Spec) 템플릿. 목표, 설계, 위험 요소 포함.

기술 명세서: [기능/시스템 이름]

작성자: @username 작성일: 2026-05-05 검토자: @reviewer1, @reviewer2 상태: 초안 / 검토 중 / 승인됨 / 구현 완료

요약 (TL;DR)

3-5문장으로 이 명세서의 핵심을 요약하세요. 무엇을 만들고, 왜 만들며, 어떻게 접근할지를 간략히 설명합니다.

배경 및 목표

문제 정의

해결하려는 문제를 구체적으로 설명하세요.

현재 어떤 문제가 있는가?
이 문제가 사용자/비즈니스에 미치는 영향은?

목표

✅ [측정 가능한 목표 1]
✅ [측정 가능한 목표 2]

범위 밖 (Out of Scope)

❌ 이번 작업에서 다루지 않을 것들
❌ 향후 고려할 사항

제안 설계

시스템 개요

[다이어그램 또는 텍스트 아트로 시스템 구조를 표현]

클라이언트 → API 게이트웨이 → 서비스 A → DB
                            → 서비스 B → 캐시

API 설계

새로운 엔드포인트 또는 변경되는 엔드포인트를 기술합니다.

POST /api/v1/feature
Request:  { "field": "value" }
Response: { "id": 123, "status": "created" }

데이터 모델

CREATE TABLE features (
  id         BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id    BIGINT NOT NULL REFERENCES users(id),
  name       VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

핵심 로직

주요 알고리즘이나 비즈니스 로직을 설명합니다.

대안 검토

접근법	장점	단점	결론
현재 제안	…	…	채택
대안 A	…	…	기각
대안 B	…	…	기각

위험 요소 및 완화 방안

위험	가능성	영향	완화 방안
DB 성능 저하	중	높음	인덱스 추가, 쿼리 최적화
외부 API 장애	낮	중간	Circuit breaker 패턴 적용

구현 계획

마일스톤

Phase 1 (2주): 핵심 API 구현
Phase 2 (1주): 프론트엔드 연동
Phase 3 (1주): 테스트 및 배포

작업 목록

데이터베이스 마이그레이션 작성
API 엔드포인트 구현
단위 테스트 작성 (커버리지 80% 이상)
통합 테스트 작성
문서 업데이트

검토 질문

명세서 검토 시 피드백이 필요한 부분을 명시하세요.

DB 스키마 설계가 적절한가?
캐싱 전략이 충분한가?

기술 명세서 템플릿