일하는 방법 — 기능이 태어나서 문서로 남기까지
새 기능·API 변경이 어떤 순서로 움직이는지의 팀 규약. 근거 결정은 ADR-0002(스펙 퍼스트)와 ADR-0003(문서 중앙화).
기능 개발 흐름 (풀 코스)
flowchart LR A["1 PRD"] --> B["2 스펙 PR"] --> C["3 병렬 구현"] --> D["4 기록"] --> E["5 연결"]
1. PRD — 기능 정의
- prd.md 복사 →
product/기능명-prd.md - 직무별 관점 표를 회의에서 채운다 — 기획·디자인·FE·BE 각자의 제약과 우려. 여기 안 적히면 증발한다.
- 시스템 흐름(Mermaid)으로 어떤 API들이 움직일지 스케치.
2. 스펙 PR — 구현 전에 계약 합의
tapple-be/openapi/openapi.yaml수정 PR. 코드보다 스펙이 먼저다.- FE·BE가 이 diff에서 요청/응답을 합의한다. 여기서 싸우는 게 구현 후에 싸우는 것보다 100배 싸다.
- 스키마·필드는 전부 여기에 — md 문서에 스키마 복사 금지.
3. 병렬 구현
- 계약이 합의됐으므로 FE는 BE를 기다리지 않는다 — 스펙 기준 mock으로 바로 시작.
- BE는 springdoc이 코드에서 뽑은 스펙과 손 스펙이 일치하는지 확인(향후 CI 자동화).
4. 기록 — 구현이 끝난 결과를 남긴다
- BE: 구현 상세가 계약과 달라졌거나 깊이가 생겼으면
be/에 as-built 갱신·작성. as-built는 설계서가 아니라 지은 대로의 기록 — 구현 전에 쓰지 않는다. - 공통 맥락: 엣지케이스·불변조건·gotcha가 생겼으면
api/리소스 문서에. 맥락 없으면 안 만든다 — 평범한 CRUD는 스펙 항목으로 끝. - FE: 배포·라우팅 계약이 바뀌었으면
fe/에.
5. 연결 — 그래프 완성
PR 규약 — 느린 PR이 빠른 개발
리뷰 병목은 리뷰를 빨리 해서가 아니라 리뷰하기 쉬운 PR을 미리 만들어서 푼다. 근거 결정은 ADR-0004.
작성자 규칙
- 1 이슈 = 1 PR. 이슈 없는 PR 금지. 이슈→브랜치→PR 흐름 유지.
- 200줄 이하 목표. 마이그레이션·생성 파일·lock 파일은 카운트 제외. 초과하면 쪼개거나, 못 쪼갠 이유를 리뷰 포인트에 쓴다.
- 본문은 의사결정 문서. 템플릿의 “왜 · 한계와 트레이드오프 · 리뷰 포인트(🔴🟡🟢)“를 작성자가 채운다. 리뷰어가 diff에서 추리게 만들지 않는다.
리뷰 무게 차등
| 변경 유형 | 사람 리뷰 |
|---|---|
| 리네임 · 포맷팅 · 테스트 추가 · 동작 동일 리팩토링 | 불필요 — AI 리뷰 통과로 머지 가능 |
| 비즈니스 로직 변경 · 새 패턴 도입 · 트레이드오프 있는 설계 | 필수 |
판정 기준은 템플릿의 “한계 & 트레이드오프” 섹션: 위 자명한 유형에 해당해서 비운 경우만 사람 리뷰 생략. 그 외 빈칸 금지.
AI 리뷰
- FE·BE 레포에 claude-review 워크플로가 PR마다 자동 리뷰를 단다. 코멘트 심각도:
[r]반드시 반영 /[c]권장 /[a]사소. [r]은 반영하거나, 거절 근거를 코멘트로 남긴다. 거절 근거가 설계 결정이면 ADR로 승격.- Copilot 리뷰는 보조로 계속 쓴다.
작은 변경 (숏컷)
계약이 안 바뀌는 버그 픽스·내부 리팩토링은 1·2번 생략. 단 하나만 지킨다: 코드 변경으로 허브 문서가 낡으면 같은 작업에서 그 문서를 고친다. 이게 중앙화(ADR-0003)의 유지 조건이다.
중복 금지 — 한 사실은 한 노드
기능 하나가 여러 문서(PRD·design·api·as-built)에 걸치는 건 정상이다. 문제는 같은 내용을 여러 문서가 각자 다시 쓰는 것. 규칙:
- 옆 레이어 내용은 재설명하지 않고 링크한다. 요약이 필요하면 한 줄까지만 + 링크.
- flowchart·상태 다이어그램은 design/에 정식 1개. PRD·as-built는 그걸 링크(자기 버전을 또 그리지 않는다).
- 개념 설명(“왜 세 층인가” 같은)은 그 개념의 주인 문서 1곳이 원본. 예: 세 층 구조 → public-card.md.
- 계약 표(엔드포인트·스키마)는 문서에 복사하지 않는다 → openapi.yaml.
각 문서가 자기 레이어의 것만 갖는지 자문: “이 문단, 옆 문서에 이미 있나?” 있으면 지우고 링크.
| 레이어 | 여기만 갖는 것 |
|---|---|
PRD (product/) | 왜·직무별 관점·목표·API 목록 |
설계 (design/) | 정식 흐름도·컴포넌트 소통 방식 |
API 맥락 (api/) | 계약의 왜·엣지케이스·불변조건 |
as-built (be/·fe/) | 구현 진실(캐시·검증 순서·제한) |
문서를 어디에 쓸까 — 판정 한 줄
상대 직군이 볼 일 있으면 허브, 그 레포 작업자만 보면 코드 옆.
| 쓰려는 것 | 위치 |
|---|---|
| 기능 정의·직무별 관점 | 허브 product/ (PRD) |
| API 요청/응답 스키마 | tapple-be/openapi/openapi.yaml |
| API의 왜·엣지케이스·불변조건 | 허브 api/ |
| 구현 상세 기록 (as-built) | 허브 be/ · fe/ |
| 시스템 결정 (둘 다 영향) | 허브 adr/ |
| 한 레포만의 기술 결정 | 그 레포 docs/adr/ |
| 구현 규칙·테스트 가이드·온보딩 | 그 레포 docs/ |
| 장애 대응 | 허브 runbook/ · 회고는 postmortem/ |
읽는 곳 (진입점)
- 웹: https://tapple-docs.pages.dev — 검색·그래프 뷰. 기능 이해는 PRD에서 시작해 그래프를 따라간다.
- 편집: 이 레포를 Obsidian 볼트로 열거나 아무 에디터. 링크는 표준 마크다운만 (CONVENTIONS).
- AI: 각 레포 CLAUDE.md가 진입점. AI에게 기능 작업을 시킬 땐 PRD 경로를 주면 필요한 문서를 알아서 따라간다.