작업 문서 기록 및 유지관리 (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 : 문제 정의/원인/해결/회귀 방지

필수 규칙

1. 작업 시작 전 docs/plans/{작업명}.md를 작성합니다.
2. 리서치/분석 결과는 docs/works/{작업명}/에 기록합니다.
3. 동일 주제를 2회 이상 조회하면 반드시 works 문서에 기록합니다.
4. 작업 문서 수정은 독립 기능이 될 수 없으며, 관련 코드 변경과 함께 같은 커밋으로 포함합니다.
5. 명세가 변경되면 spec*.md, README.md에 반영하여 항상 최신 상태를 유지합니다.
6. 작업 완료 후에도 새 학습/이슈/문제가 생기면 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 템플릿

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에 변경 내용과 이유를 날짜와 함께 추가합니다.