일하는 방법 — 기능이 태어나서 문서로 남기까지
새 기능·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. 연결 — 그래프 완성
작은 변경 (숏컷)
계약이 안 바뀌는 버그 픽스·내부 리팩토링은 1·2번 생략. 단 하나만 지킨다: 코드 변경으로 허브 문서가 낡으면 같은 작업에서 그 문서를 고친다. 이게 중앙화(ADR-0003)의 유지 조건이다.
문서를 어디에 쓸까 — 판정 한 줄
상대 직군이 볼 일 있으면 허브, 그 레포 작업자만 보면 코드 옆.
| 쓰려는 것 | 위치 |
|---|---|
| 기능 정의·직무별 관점 | 허브 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 경로를 주면 필요한 문서를 알아서 따라간다.