콘텐츠로 이동

ADR-001: 저장소 레이아웃 재편

  • 상태: Accepted
  • 날짜: 2026-03-15
  • 결정자: nodove
  • 검증 상태: 아래 체크리스트의 실행 증거가 이 문서에는 첨부되지 않음

맥락

저장소는 MkDocs 기반 문서 허브로 시작했으나, 시간이 지나며 출판용 문서, 렌더 파생 산출물, 실행 가능한 인프라 설정, 개발 코드, 자동화 스크립트가 루트에 혼재하게 됐습니다.

확인된 문제:

  1. docs/ 안에 MkDocs 콘텐츠와 JS/CSS 자산이 함께 존재 — 테마 코드와 콘텐츠가 구분되지 않음
  2. docker/, configs/, ansible/이 문서 옆에 배치 — 배포 자산과 문서 자산의 경계 없음
  3. code/, scripts/, tools/가 루트에 분산 — 실행 코드의 소유권 불명확
  4. project-docs/, legacy/, prompt/, memo/, research/가 독립적으로 분산 — 문서의 편집 권한 규칙 없음
  5. site/가 루트에 빌드 산출물로 존재 — gitignore는 했지만 명시적 dist 경계 없음

결정

루트를 **5개 최상위 도메인**으로 재편합니다:

apps/     — 실행 가능한 애플리케이션 (MkDocs 사이트 빌더)
content/  — 편집·출판·보존 정책으로 분류한 문서 소스
infra/    — 배포 및 운영 설정
src/      — 실행 가능한 코드와 스크립트
dist/     — 빌드 산출물 (gitignore 대상)

세부 매핑

content/ 내부는 편집 권한으로 추가 분류합니다:

하위 경로 편집 권한 설명
content/docs/ 자유 편집 MkDocs 출판 소스
content/rendered/ 원본만 수정 파생 산출물
content/archive/legacy/ 보존 편집 기능 확장 대신 사실 오류, 안전 경고, 출처·마이그레이션 메타데이터만 보정
content/prompts/ 자유 편집 AI 프롬프트
content/notes/ 자유 편집 개인 메모
content/research/ 자유 편집 리서치 문서

고려된 대안

A. 기존 구조 유지 + README 보강

  • 장점: 이동 비용 없음
  • 단점: 근본적인 탐색 비용과 소유권 불명확 문제 해결 안됨
  • 기각

B. 전면 일괄 이동 (모든 파일 즉시 이동)

  • 장점: 구 경로 즉시 제거
  • 단점: CI, 내부 링크, 스크립트가 한꺼번에 파손될 위험
  • 기각 — 단계적 전환 채택

C. 채택안: 복사 후 구 경로 단계적 제거

  • 1단계: 새 위치로 복사 + 설정 파일 경로 업데이트
  • 2단계: 새 경로를 정본으로 전환하고 쓰기 주체를 하나로 제한
  • 3단계: 빌드·내부 링크·자동화 경로 검증
  • 4단계: 구 경로 참조가 0임을 확인한 뒤 제거

결과

긍정적

  • 소유권 명확화: 파일 위치만으로 아티팩트 성격 파악 가능
  • CI 경로 의미 강화: apps/docs-site/, src/tools/, content/docs/가 목적을 드러냄
  • 빌드 격리: dist/site/가 빌드 산출물 경계를 명시
  • 컨트리뷰션 가이드 단순화: "새 문서 → content/docs/", "새 스크립트 → src/automation/"

부정적

  • 초기 이동 비용: 수백 개 파일 복사, CI/mkdocs.yml/스크립트 경로 수정
  • 외부 링크 파손 위험: GitHub Raw URL, 직접 파일 링크 등이 영향 받을 수 있음
  • 학습 곡선: 기존 기여자가 새 구조에 적응 필요

검증 기준

각 항목은 명령의 종료 코드와 실행 revision을 기록해야 완료로 표시합니다. 파일이 새 위치에 존재한다는 사실만으로 정본 전환이나 구 경로 제거가 끝났다고 판정하지 않습니다.

  • cd apps/docs-site && mkdocs build --clean 성공
  • CI deploy-pages.yml 로컬 경로 검증 통과
  • src/automation/site/sync-extra-assets.sh 정상 실행
  • cargo test --manifest-path src/tools/docs-validator-rs/Cargo.toml 통과
  • 저장소 설정·스크립트·문서에서 제거 대상 구 경로 참조가 없음
  • 외부 링크 리디렉션 또는 호환 경로의 유지·종료 정책 기록