5.6 KiB

Raw Blame History

문서 카테고리 분류 기준

목적

changes/ 남용을 줄이고, 문서의 주된 목적에 따라 카테고리를 일관되게 선택하기 위한 기준이다.

프로젝트 성격에 따라 아래 카테고리 목록에서 해당 없는 것은 삭제하고, 필요한 카테고리는 추가한다. 예: 웹 UI 가 있는 프로젝트는 uiux-qa-report/ 를 추가할 수 있다.

핵심 원칙

카테고리는 "무엇이 바뀌었는가" 보다 "이 문서를 나중에 왜 다시 찾는가" 를 기준으로 선택한다.
한 문서에는 하나의 주 목적만 둔다.
문서가 두 목적을 동시에 가지면, 오래 참조할 기준 문서를 우선 만들고 필요할 때만 보조 문서를 추가한다.

카테고리 선택 기준

카테고리	이럴 때 사용	이럴 때는 사용하지 않음
`adr/`	기술 선택/아키텍처 원칙에 대한 불변 결정 레코드. ORM/프레임워크/배포 방식/레이어 경계 등 되돌리기 어려운 결정	단건 구현 변경, 일회성 분석
`analysis/`	코드/데이터 흐름/성능/리스크를 이해하거나 원인을 추적하는 문서	수정 결과 changelog, 장기 운영 기준, 계약 스펙
`architecture/`	시스템 경계, 레이어 규칙, 저장 구조, 데이터 흐름, 스케줄러 설계처럼 오래 유지될 구조 설명	단건 변경 이력, 일회성 조사, ADR 에 가까운 결정(→ `adr/`)
`backlog/`	미채택 자동화/기능 아이디어, 재검토 트리거 조건 기록. 구현되지 않았지만 흔적 남길 가치 있는 것	확정된 로드맵, 완료된 작업 기록
`changes/`	이미 반영된 구현 변경의 이력(changelog). 런타임 동작·스케줄러 룰·DB 스키마·외부 클라이언트 계약이 실제로 바뀐 경우	분석만 한 경우, 문서만 동기화한 경우, 재사용 가이드/절차, 장애 조사만 있고 수정이 없는 경우
`contracts/`	외부/내부 계약 기준 문서. HTTP 엔드포인트 계약, CLI/커맨드 스펙, 내부 모듈 간 인터페이스	특정 날짜의 변경 이력, 조사 메모
`development/`	반복해서 재사용할 개발 규칙, 절차, 워크플로우, 툴 운영 기준. 이 문서 자체도 여기 속함	특정 구현 변경 이력, 단건 장애 보고서
`domain/`	프로젝트가 다루는 도메인 지식 (업계 규칙, 용어 정의, 비즈니스 룰 등)	구현 변경 이력, 내부 구조
`issues/`	운영 이슈, 장애, 재현 조건, 영향 범위, 원인, 대응 내역	일반 기능 변경 기록, 장기 가이드
`maintenance/`	운영자가 따라야 하는 점검, 수동 조치, 배치, 데이터 정리, 유지보수 절차	개발 규칙, 분석 보고서
`security/`	인증/인가, 입력 검증, 비밀 값 관리, 보안 정책/패턴을 설명하는 기준 문서	특정 기능 수정 이력 자체
`usage/`	이식자·사용자 관점 운영 가이드, FAQ, 체크리스트	내부 구조 설명(→ `architecture/`), 개발 규칙(→ `development/`)
`work-log/`	작업 중간 기록, 세션 간 handoff 메모, 시점성 있는 진행 로그	최종 기준 문서, 장기 참조용 설명
`graph/`	자동 생성 (graphify). 사람이 손으로 편집하지 않음. `index.md` 만 메타로 커밋	사람이 작성하는 아키텍처 설명(→ `architecture/`)

`changes/` 를 써도 되는 경우

코드가 실제로 수정되었다.
또는 코드가 소비하는 설정/정적 데이터가 바뀌어 실제 동작이 달라졌다.
문서의 중심이 "현재 구조 설명" 이 아니라 "이번 작업에서 무엇이 왜 바뀌었는지" 다.
읽는 사람이 "언제 어떤 구현 변화가 들어갔는지" 를 확인하려고 이 문서를 찾는다.

`changes/` 로 보내면 안 되는 경우

구현은 그대로고 설명만 보강했다.
README / CLAUDE.md 와 docs/ 를 동기화했다.
재사용 가능한 작업 절차나 작성 규칙을 정리했다(→ development/).
버그 원인/구조를 분석했지만 수정은 아직 없다(→ analysis/).
운영 장애를 복기하고 재현/영향 범위를 남기는 것이 핵심이다(→ issues/).

빠른 결정 순서

기술 선택/아키텍처 원칙에 대한 되돌리기 어려운 결정인가? → adr/.
운영 장애나 이슈 대응 기록인가? → issues/.
프로젝트의 업무 도메인 지식인가? → domain/.
외부/내부 계약 스펙인가? → contracts/.
현재 기준의 구조/가이드를 설명하는 문서인가? → architecture/, development/, security/ 중 하나.
조사, 비교, 원인 추적, 리스크 파악이 핵심인가? → analysis/.
수동 운영 절차나 유지보수 실행 가이드인가? → maintenance/.
진행 중인 작업 메모인가? → work-log/.
미채택 아이디어/흔적인가? → backlog/.
위가 아니고 실제 구현 변경 이력을 남기는 문서인가? 그때만 → changes/.

함께 작성하는 규칙

구현 변경과 장기 기준 문서가 동시에 필요하면, 기준 문서는 해당 도메인 카테고리(contracts/, architecture/, domain/ 등) 에 두고 changes/ 에는 변경 요약만 남긴다.
문서 동기화만 했다면 원칙적으로 changes/ 를 만들지 말고, 대상 기준 문서를 직접 갱신한다.
장애 수정이 있었더라도 핵심 가치가 장애 원인과 대응 이력 보존이라면 issues/ 를 우선하고, 필요할 때만 관련 changes/ 를 추가한다.
ADR 에 해당하는 결정이면 changes/ 대신 adr/ 에 불변 레코드로 남긴다.