작업 문서 기록 및 유지관리 (docs/)
개발 작업의 전 과정(계획-진행-배포-운영)에서 문서를 docs/ 아래 표준 구조로 남기고, 결정/학습/이슈/문제의 추적 가능성과 명세 최신성을 보장합니다.
언제 사용하나요?
- 새 작업을 시작하며 작업 계획/TODO를 작성할 때 (plan)
- 조사/분석/비교/원인분석 등 지식 생성이 발생할 때 (works 문서)
- 동일 주제를 2회 이상 재조회(재확인/재검토)할 때 (works 문서 강제 기록)
- 요구사항/행동/인터페이스/정책 등 명세가 바뀔 때 (spec/README 반영)
- 코드 변경과 함께 문서를 수정해 커밋해야 할 때 (문서 단독 커밋 금지)
- 작업 완료 이후에도 운영 중 새 학습/문제/이슈가 생겼을 때 (works 문서 지속 업데이트)
디렉토리 규칙
작업 관련 문서는 반드시 docs/ 아래에서 관리합니다.
docs/plans/ (작업 계획 및 TODO)
- 작업 시작 전, 계획 문서를 아래 경로에 작성합니다.
docs/plans/{작업명}.md
docs/drafts/ (초안 및 임시 문서)
- 확정 전 스케치/임시 텍스트/표/설계 초안은 여기에 둡니다.
- 확정되면 반드시 적절한 문서로 반영하거나 이동합니다(README/spec/works 등).
docs/works/ (작업별 메모)
- 리서치/분석 결과, 학습 내용, 의사결정, 이슈, 문제점은 아래에 기록합니다.
docs/works/{작업명}/
{작업명}은 주제를 간결하게 표현하며 검색이 쉽도록 작성합니다.- 좋은 예:
auth-refresh-token,pv-shading-detect,k8s-ingress-routing - 나쁜 예:
task1,fix,misc,temp
- 좋은 예:
works 문서 고정 구조
docs/works/{작업명}/는 아래 4개 파일로만 구성합니다(파일명 고정).
learnings.md: 새로 알게 된 사실/근거/실험/정리decisions.md: 의사결정의 현재 상태 + 변경 이력(필수 규약)issues.md: 진행 중 장애/막힘/해결 현황problems.md: 문제 정의/원인/해결/회귀 방지
필수 규칙
- 작업 시작 전
docs/plans/{작업명}.md를 작성합니다. - 리서치/분석 결과는
docs/works/{작업명}/에 기록합니다. - 동일 주제를 2회 이상 조회하면 반드시 works 문서에 기록합니다.
- 작업 문서 수정은 독립 기능이 될 수 없으며, 관련 코드 변경과 함께 같은 커밋으로 포함합니다.
- 명세가 변경되면
spec*.md,README.md에 반영하여 항상 최신 상태를 유지합니다. - 작업 완료 후에도 새 학습/이슈/문제가 생기면 works 문서를 지속적으로 업데이트합니다.
금지 규칙 (하지 않습니다)
- 문서만 단독으로 커밋하지 않습니다.
docs/밖에 작업 문서를 흩뿌리지 않습니다.- "결정사항"을 채팅/PR 코멘트에만 남기고 works 문서에 누락하지 않습니다.
- 명세 변경이 있었는데
spec*.md/README.md를 업데이트하지 않은 채로 머지하지 않습니다. - works 문서에 날짜/근거/이유 없이 결론만 던지고 끝내지 않습니다.
작업명 및 파일명 규칙
{작업명}은 소문자 + 하이픈(-) 형식을 권장합니다.- 너무 포괄적인 이름을 피합니다.
- 좋은 예:
db-migration-online,oauth-login-flow - 나쁜 예:
backend,refactor,update
- 좋은 예:
decisions.md 규약 (필수)
docs/works/{작업명}/decisions.md는 반드시 아래 구조를 따릅니다.
- 문서 최상단에는 현재 유효한 결정사항 요약(Current/Active) 이 항상 최신으로 존재해야 합니다.
- 그 아래에는 날짜 포함 Change Log 로 결정 변경의 진화를 기록합니다.
- 변경 기록에는 반드시 아래가 포함되어야 합니다.
- Changed: 무엇이 바뀌었는지
- Reason: 왜 바뀌었는지(근거/관찰/요구/리스크)
decisions.md 템플릿
# Decisions
## Current (Active)
- [결정 1] 한 줄 요약 - 한 줄 근거
- [결정 2] 한 줄 요약 - 한 줄 근거
## Change Log
### YYYY-MM-DD
- Changed: (무엇이 변경되었는지)
- Reason: (변경 이유/근거/맥락)
### YYYY-MM-DD
- Changed:
- Reason:
기록 기준 (어디에 무엇을 쓰나)
plans/{작업명}.md에 씁니다
- 목표/범위(Out of scope 포함)
- TODO 체크리스트
- 리스크/가정
- 완료 기준(Definition of Done)
works 문서/learnings.md에 씁니다
- 조사/분석 결과 TL;DR
- 근거(로그/메트릭/실험 조건/재현 절차)
- 결론(무엇이 사실인지)
- 재사용 키워드(다음에 검색할 단어)
works 문서/issues.md에 씁니다
- 진행 중 막힘/장애 목록
- 영향 범위(어디가 막혔는지)
- 임시 대응/우회책
- 해결 상태(진행 중/해결/보류)
works 문서/problems.md에 씁니다
- 문제 정의(재현 절차 포함)
- 원인 후보 -> 최종 원인
- 해결 내용(수정 요약)
- 회귀 방지(테스트/가드레일/모니터링)
"동일 주제 2회 이상 재조회" 판정 기준
아래 중 1개 이상에 해당하면 동일 주제로 간주하고 works 문서 기록을 강제합니다.
- 같은 컴포넌트/모듈/기능 영역
- 같은 증상/현상/원인
- 같은 비교 대상(라이브러리/제품/아키텍처)
- 같은 결정 포인트(선택지 A/B와 trade-off)
커밋 구성 규칙
- 코드 변경과 문서 변경을 같은 커밋에 포함합니다.
- 명세 변경이 있으면 spec*.md/README.md 업데이트를 같은 커밋에 포함합니다.
- PR 단위에서도 문서가 따라가도록 합니다(리뷰 시 문서 누락을 결함으로 취급).
좋은 예 / 나쁜 예
좋은 예: 작업 시작
- docs/plans/oauth-login-flow.md 작성
- 리서치/검증 결과를 docs/works/oauth-login-flow/에 기록
- 구현 코드 + 문서 변경을 함께 커밋
나쁜 예: 문서 단독 처리
- README만 수정해서 단독 커밋
- 결정사항을 PR 코멘트에만 남기고 decisions.md는 비움
- 명세가 바뀌었는데 spec*.md/README 반영 없이 머지
완료 후 지속 업데이트 규칙
작업이 "완료" 상태여도 다음 이벤트가 발생하면 works 문서를 업데이트합니다.
- 운영/모니터링 중 새로 확인한 학습
- 회귀/장애/예외 케이스 발견
- 의사결정 변경(새 제약/요구/리스크 발생)
업데이트 시에는 decisions.md의 Current 요약을 최신으로 유지하고, Change Log에 변경 내용과 이유를 날짜와 함께 추가합니다.