Barbelic devdocs

Appearance

updates/ — 작업 기록 형식 ​

저장소 분리 (#1463): 작업 기록·인덱스·사이드바는 모두 dekerd/Barbelic-docs에서 함께 갱신한다. 기록용 앱 커밋이나 앱 release 큐 요청을 만들지 않는다. 아래 앱 검증 명령은 관련 제품 변경의 실제 증거를 기록하라는 뜻이며 문서 게시가 앱 검증을 실행하는 조건은 아니다.

이 폴더의 작업 기록은 모두 이 형식을 따른다 (오너 지시 2026-08-24). 트랙(캠페인·수리·기능)이 랜딩한 날, 그 트랙을 끝낸 세션이 쓴다. 독자는 몇 주 뒤의 오너와 다음 세션 — "왜 이렇게 됐는가"를 코드를 안 열고도 알 수 있어야 한다.

언제 쓰나 ​

  • 트랙의 마지막 PR이 머지된 직후(같은 턴). Phase가 여러 PR에 걸치면 마지막 Phase에서 한 문서로 묶고, 도중에 쓴 문서는 Phase 현황 표를 갱신한다.
  • 버그 수리만 있는 작은 건은 bug-report/가 정본이고, 작업 기록은 그 리포트를 링크하는 짧은 문서로 충분하다.

파일과 등록 ​

  • 경로·이름: docs/updates/YYYY-MM-DD-slug.md — 날짜 = 랜딩일(KST), slug = 영문 kebab-case(트랙 이름).
  • 등록 2곳(빠지면 사이트에서 안 보인다):
    1. docs/.vitepress/config.mts 사이드바 "작업 기록" 그룹 맨 끝 — { text: "제목 (YYYY-MM-DD)", link: "/updates/YYYY-MM-DD-slug" }
    2. docs/README.md "작업 기록" 표 맨 끝 — | [\파일`](updates/파일) | 한 줄 요약 |`
  • 링크: 레포 안은 상대 경로(../platform/..., ../../bug-report/...), PR은 전체 URL, 설계서는 artifact id.

본문 구조 (순서 고정) ​

# 제목 — 부제 (YYYY-MM-DD)

- 기간: 시작 ~ 끝 (세션 수, 오너 보고/지시 원문 한 줄)
- 랜딩: PR #n(Phase, `해시`) · … — 마이그레이션·엣지 번호, Vercel 배포 여부
- 설계서: artifact `id`("예상 효과·개선사항" 절 포함) — 또는 "없음(수리 건)"
- 정본: 이 트랙 뒤에 규칙이 사는 곳 — 계약 문서·코드 경로·상수 이름
- 도구: 계측·생성 스크립트(레포 안/밖, gitignored 여부)
- 게이트: 이 트랙이 남긴 검사. 마이그레이션을 만졌으면 로컬 `supabase db reset --local --no-seed` + `npm run schema:snapshot -- --check` 통과 기록(시각)과, 제품 동작을 확인했으면 QA2 부분 실행(`qa:ci --mode focused --risk …`) 결과를 여기에 적는다 (2026-09-15 QA1 퇴역 — pgTAP·e2e 기록은 더 이상 없다)
- 버그리포트: `bug-report/bug-NNN-YYYYMMDD.md` (있으면)
- 계약: 바뀐 계약 문서 절 (있으면)

## Phase 현황            ← Phase 트랙일 때만
| Phase | 내용 | 상태 |
|---|---|---|
| Phase 1 | … | ✅ PR #n (`해시`) |
| Phase 2 | … | 🔄 / ⬜ |

## 1. 배경
트랙 전의 상태. 왜 지금 이 일을 했는가(오너 보고·감사·사고).

## 2. 문제 제기
### 문제 하나마다 소제목 — "무엇이 어떻게 틀려 있었다"를 한 문장으로
증거(계측·코드 위치·수치).

## 3. 해결 방안
### 원칙 (오너 결정 D1~Dn, 날짜)
결정 문장 인용 + 채택/기각.
### 접근
대안 비교(표 또는 불릿)와 고른 이유. 기각한 대안도 남긴다.

## 4. 적용한 내용
### Phase N — 이름 (#PR, 마이그레이션 번호)      ← Phase마다
바뀐 파일·계약·테스트.
### 주요 결정과 그 근거
### 작업 중 드러난 것
함정·사고·우회 — 다음 세션이 같은 곳에서 넘어지지 않게.

## 5. 적용 결과
| 항목 | 결과 |  ← 전 → 후 수치, 실기기/Production 확인 여부, 미검증 항목 명시

## 6. 이번 개선으로 향상된 것
### 효과 하나마다 소제목 — 사용자/개발 체감으로
"구조적으로 남는 것"(계약·게이트·절차)을 포함.

## 남은 것
범위 밖·후속·오너 결정 대기 항목.

문장 규칙 ​

  • 제목 한 줄에 증상 → 결과가 들어가게(예: "아이폰 Pro Max 양옆 여백에서 뷰포트 계층 계약까지").
  • 수치는 전 → 후. 미검증·오너 확인 대기는 5절에 그대로 쓴다 — 완료처럼 보이게 쓰지 않는다.
  • Phase 이름은 Phase N / Phase N-M(전역 지침 §7). 옛 레이블은 괄호로 한 번만.
  • 오너 결정은 D1~Dn으로 번호 붙여 인용한다. 설계서의 "예상 효과·개선사항" 표(전역 지침 §8)는 5·6절에서 실측으로 닫는다.

예시: 2026-08-23-viewport-tiers.md(Phase 5개, 결과 표 10행), 2026-08-22-stats-centralization.md(오너 결정 D1~D6).