2026-04-23

ADR 0016 — apps/docs 구조 재편 · audience 분리

결정문

apps/docs 를 2 sidebar + 2 navbar 탭 구조 로 분리해 외부 공개(변호사·사무장·Chair·투자자) 와 내부 엔지니어링(개발자·ADR·ideations) 관객 경계를 명시화한다. stale 3문서를 content/ 에서 완전 삭제하고, landing 을 mdx + <RoleCard> × 4 로 재설계한다. broken link 241개를 일괄 수정하고 onBrokenLinks: "throw" 로 승격해 CI/pre-push 차단을 활성화한다.

CLAUDE.md 는 내부 agent·개발자 SSoT, apps/docs 는 외부 공개 SSoT 로 역할을 분리하고, 중복된 주제는 한 쪽만 원본·다른 쪽은 1줄 상호 참조로 유지한다.

배경

Chair 피드백 (2026-04-23): "문서 페이지 정리 안 됨. 어디부터 봐야 할지 모르겠음. 모바일 탭 이용도 안 됨. 전체 정리가 필요."

직전 PR #539 가 landing 에 역할별 테이블을 추가했으나 근본 구조는 그대로. R1 5인 독립 수집 결과:

• P5 실측 broken link 241개 (72 source pages) — onBrokenLinks: "warn" 으로 빌드 green 유지 중
• P3 stale 3문서 (plan-system · promotion-code · ops-console-plan) 외부 surface 여전 노출
• P1 overview.md 420줄 변호사·투자자·보안 모두 혼재 → 파일럿 후보 3분 이탈 위험
• P4 navbar 항목 유형 4종 혼재 (docSidebar × 2 + to + href) — 모바일 햄버거 UX 근본 문제
• P2 사무장 전용 진입 경로 부재 — features 6건 중 1건만 사무장 관점

상세: ideations/015.

대안 검토

A — 한 사이드바 유지 + 카테고리 prefix 로 구분 (P1 R1 원안)

product / architecture / development / operations 를 "👥 공개 / 🔧 엔지니어링" prefix 로 구분. 기각: 모바일 햄버거 평탄 나열 문제 미해소. 독자가 자기 섹션만 보는 경로 차단 부족.

B — /internal/ 서브도메인 분리 (P4 R1 원안)

docs-pro.neohollo.com / internal.docs-pro.neohollo.com 2 도메인. 기각: DNS·빌드·auth 복잡도 과도. 단일 파일럿 규모에 오버엔지니어링.

C — Notion 이관 (P3 R1 원안)

ADR·ideations 를 Notion 으로 외부 이관. 기각: SSoT 3중화 (CLAUDE.md + apps/docs + Notion) → drift 확대. 운영 비용 ↑.

D — content/ 전체 삭제 후 재작성 (검토 없음)

기존 자산 손실. 기각.

E — 2 sidebar + 2 navbar 탭 · 단일 도메인 (R2 수렴안)

Docusaurus 기본 sidebars.ts 에 publicDocs · engineeringDocs 2개 선언 + navbar 탭 2개로 분리. 같은 도메인 유지로 링크 그래프·배포·검색 인덱스 일관. 채택.

결정 + 근거

3대 원칙

1. Audience 분리: public (변호사·사무장·Chair·투자자) ↔ engineering (개발자·ADR·ideations) 경계 명시. 모바일 햄버거에서 자기 섹션만 보이게.
2. stale 완전 제거: ADR 0002 이전 tier·가격 문서는 content/ 에서 삭제. 배너·레거시 라벨은 심리적 모면책 (P3). git history 로 충분.
3. SSoT 역할 분리: CLAUDE.md = 내부 코드·제약 SSoT. apps/docs = 외부 공개 정책·사용법 SSoT. 중복 제거 + 상호 참조 1줄.

신규 구조

navbar (상단)

[사용자 가이드] [엔지니어링] [업데이트 로그]          [GitHub]

publicDocs sidebar (사용자 가이드 탭)

🏠 홈
📦 Pack 1 대여금 회수 (최상단 강조)
  ├─ 기능 정의서
  └─ 화면 설계서
📋 제품
  ├─ 개요
  ├─ 로드맵
  ├─ 사무실 기억
  └─ 의뢰인 포털
🎯 운영·Chair
  ├─ 환경변수
  └─ 파일럿 runbook
📖 용어집

engineeringDocs sidebar (엔지니어링 탭)

🏗️ 아키텍처
  ├─ 개요
  ├─ 데이터 모델
  ├─ AI 파이프라인
  ├─ tenant 격리
  └─ (전체 architecture/*)
🛠️ 개발
  ├─ 온보딩
  ├─ 테스트
  ├─ 배포·릴리스
  ├─ Git·PR 컨벤션
  └─ 보안 체크리스트
📐 ADR (Decisions)
  └─ 0001~0016
💡 아이디어 회의 (ideations)
  └─ 001~015
🔬 감사·audit
  ├─ 사건 상세 audit
  └─ 서류 생성 audit

기본 상태: landing 진입 시 publicDocs 가 활성. engineeringDocs 는 탭 클릭해야 노출.

즉시 실행 (8항목 · PR 분할)

PR	항목	목표
A	ADR 0016 + ideations 015 발행	결정 근거 기록 (본 PR)
B	구조 재편	sidebars.ts 2분리 · navbar 재편 · stale 3문서 삭제 · audit 2문서 이관 · H/M/L 치환
C	landing 재설계	index.mdx + <RoleCard> × 4 · pitch.md (변호사 30초) 신규
D	링크 정비 (별도 큰 PR)	broken link 241 → 0 · onBrokenLinks: "throw" · pre-push hook 에 docs 빌드 추가

양보 불가 선

역할	선	근거
P5	broken link 241 → 0 + throw + CI 차단	drift 누적 방지
P3	stale 3문서 외부 surface 완전 제거	독자 오판 실제 리스크
P1	변호사 진입 경로에 엔지니어링 문서 교차 금지	3분 이탈 방지
P4	navbar item 유형 4종 혼재 제거	모바일 UX 근본

Minority Report

P3 PM (초기 강한 입장, 양보)

"내부 문서 완전 분리 (Notion 이관 또는 password gate). 외부 공개 surface 에 내부 로그 섞이는 것 부적절." 처리: P5 반박 ("Notion 이관은 SSoT 3중화로 drift 확대") 수용. Docusaurus 2 sidebar 로 축소하되, engineering sidebar 는 기본 collapsed + landing 미노출로 절충.

P4 디자이너 (초기 강한 입장, 기각)

"/internal/ 서브도메인 분리. 도메인 자체가 경계를 준다." 처리: DNS·빌드·auth·검색 인덱스 복잡도 과도. 2 sidebar 가 동등 효과 · 1/10 복잡도.

P1 변호사 (초기 보수적, 양보)

"stale 문서는 배너 + 레거시 라벨 로 파일 보존. 삭제는 과도." 처리: P3 "심리적 모면책" 반박 수용. git history 로 충분, content/ 삭제 수용.

P5 개발자 (초기 기술적 제안, 대체)

"CLAUDE.md 를 remark plugin 으로 apps/docs 에 build-time include." 처리: Docusaurus 파서·캐시 충돌 우려. 역할 분리 + 상호 참조로 대체 (구현 복잡도 ↓).

성공 지표

• Docusaurus 빌드 broken link 241 → 0 (PR D 완료 시점)
• onBrokenLinks: "throw" 활성 후 3주 내 broken link 재발 0건
• 파일럿 변호사 first-visit 체류 시간 (Chair 관찰 지표, 정량 측정 어려움)
• stale 문서 외부 surface 0건
• 모바일 햄버거 탭 사용 가능 (사용자 피드백 해소)

후속 과제

• PR B: 구조 재편 (이번 세션)
• PR C: landing mdx + pitch.md (이번 세션)
• PR D: broken link 일괄 수정 + throw 전환 (별도 세션, 큰 작업)
• paralegal quickstart (/quickstart/paralegal 신규 5분 튜토리얼) — 파일럿 유치 전 (3주 내)
• ADR 번호 결번 (0008 · 0009 · 0013) 정리
• changelog author 미정의 40+ 수정
• CLAUDE.md 상단에 "apps/docs 와의 역할 분리" 명시 업데이트