공시한입 Docs

Appearance

Spec — 기획자 관점 + 도메인 로직 ​

목적 ​

Vibe coding 으로 코드는 빠르게 짜지지만 "내 핵심 비즈니스" 가 눈에 안 보이는 문제 를 풀기 위해.

화면 중심 (기획자 관점) + 비즈니스 도메인 룰 한 곳에 모음.

3 종류 prefix ​

prefix무엇관점
screen-단일 화면의 UI 동작 / 상태 / 분기기획자 / 디자이너
flow-여러 화면 걸친 사용자 시나리오기획자 / PM
domain-비즈니스 룰 (정량 / 정책 / 알고리즘)개발자 / PM

flat 구조 — prefix 로 grouping. grep 우선.

policies/ 와 차이 ​

위치무엇
../policies/"왜" 결정했나 (이력, 토론, 트리거)
spec/ (여기)"지금" 어떻게 동작하나 (현재 진실)

같은 주제 양쪽에 존재 가능 (예: policies/monetization.md 정책 진화 vs spec/domain-quota.md 현재 quota 동작 명세).

api/ 와 차이 ​

위치무엇
../api/endpoint 단위 명세 + 실 I/O 예제
spec/ (여기)화면 / 사용자 flow / 도메인 룰

API 와 spec 은 보완 관계. API 는 시스템 contract, spec 은 사용자 경험 / 비즈니스 룰.

작성 시점 (강제 X) ​

  • 새 화면 / 화면 큰 변경: 같은 PR 에 screen-X.md 같이
  • 사용자 시나리오 정해짐: flow-X.md 추가
  • 정책 / 정량 룰 결정 / 변경: domain-X.md update
  • 머릿속 정리 안 될 때: 코드 짜기 전 spec 먼저

템플릿 ​

screen-X.md ​

markdown
# 화면: <이름>

## 진입 경로
- 어디서 진입 (대시보드 / 알림 / 푸시 등)

## 상태별 노출
- 로딩 / 정상 / 에러 / 권한 없음 / 빈 상태
- 각 상태의 UI 요소

## 인터랙션
- 버튼 / 제스처별 동작
- 상태 전이 (state diagram 가능)

## 의존성
- 호출하는 API endpoint
- 다른 화면으로의 navigate

flow-X.md ​

markdown
# Flow: <이름>

## 시나리오
"사용자가 X 하면 Y 하고 Z 가 일어남"

## Step
1. ...
2. ...
3. ...

## 분기 / Edge case
- 권한 거부
- 네트워크 단절
- 동시성 충돌

domain-X.md ​

markdown
# 도메인: <영역명>

## 룰
정량적 룰 / 임계값 / 정책 (예: 월 quota 5, signup bonus 5, hard cap 200)

## 알고리즘
계산 흐름 (필요 시 pseudo-code)

## Edge case
- 월 경계 / 시간대
- 동시성
- reset 조건

## 관련 테이블 / API
- DB 테이블
- endpoint

인덱스 ​

아키텍처 / 구조 (코드 전반) ​

도메인 (비즈니스 룰) ​