---
name: crmin/working-docs
source: https://app.decimal.ai/s/crmin-working-docs@1/SKILL.md
source_sha256: 91ad8bd284d6
---

# 작업 문서 기록 및 유지관리 (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에 변경 내용과 이유를 날짜와 함께 추가합니다.