본문으로 건너뛰기

015 — apps/docs 전체 문서 정리 · audience 분리

Tier: B (R1 + R2 + R3 완주) · 상태: 수렴 완료 → ADR 0016 발행

안건 배경​

Chair 피드백: "문서 페이지가 정리가 안 되어 있어서 어디부터 어떻게 봐야 하는지 모르겠다. 모바일에서는 탭 이용도 안 되고 이게 뭔가. 정리가 필요하다."

개별 문서 수정이 아닌 전체 구조·진입 경로·일관성 재정비 가 요구된 안건. 직전 PR #539 가 landing 에 역할별 테이블을 추가했으나 불충분.

Anti-Goal 체크​

  • ✅ 민사 외 소송 관리 도구: 영향 없음 (문서 메타 작업)
  • ✅ 법률 조언 AI: 영향 없음
  • ✅ 의뢰인 B2C: 영향 없음
  • ✅ 변호사 매칭·광고: 영향 없음

R1 (2026-04-23) — 5인 독립 발산​

각 subagent 가 타 역할 관점 모른 채 독립 수집.

P1 변호사 — 파일럿 후보 3분 이탈 위험​

  • overview.md 420줄에 변경이력·투자라운드·DPIA·AX 혼재
  • sidebar 2번째가 architecture 라 변호사 시야 가림
  • decisions/ 폴더 _category_.json 부재 · ADR 번호 결번 (0008·0009·0013)
  • landing 의 "운영·Chair → ADR 0015" 경로가 178줄 원문으로 직행

P2 사무장 — 진입 경로 소실​

  • landing 역할 테이블이 "변호사·사무장" 한 칸으로 묶여 변호사 경로로 흘려보냄
  • pack-1/features/ 중 debt-settlement-user-guide 1건만 사무장 관점, 나머지 5건 변호사 관점
  • ADR 0004 "사무원 챔피언 전략" 선언 vs 실제 IA 불일치
  • case-detail-audit.md / docs-generate-audit.md 의 "P1/P2/P3" 우선순위 표기가 회의 역할 P1~P5 와 네임스페이스 충돌

P3 PM — stale 과 현재 상태 혼재​

  • plan-system.md 에 ADR 0002 로 삭제된 SIGNUP_TRIAL_DAYS 상수 그대로
  • ideations/ 14개 내부 회의록이 상단 탭 아이디어 회의 로 외부 공개
  • ADR 1~15 내부 설계 로그인데 landing 에서 투자자 경로로 제시
  • Pack 1 단일 제품 현실 vs product/architecture/development/operations 4 추상 카테고리

P4 디자이너 — 구조 문제, CSS 아님​

  • landing 테이블 4행 × 4열 강제 대칭으로 단조성
  • 사이드바 4 카테고리가 외부·내부 관객 평탄 혼재
  • navbar 항목 유형 4종 혼재 (docSidebar × 2 + to + href) — 모바일 햄버거에서 구분 부재
  • CSS 는 증상 패치, navbar item 재편이 정답

P5 개발자 — 링크 그래프 붕괴​

  • broken link 241개 (72 source pages) 측정. onBrokenLinks: "warn" 으로 빌드 green 유지 중
  • decisions/ ADR 파일명 숫자 prefix 불일치 (index · roadmap · pack-1 에서 링크 섞임)
  • CLAUDE.md (643줄) vs apps/docs 이중 SSoT drift 실현 중
  • changelog 62 posts 중 40+ author 미정의 warning
  • CI 에 docs 빌드 없음 → 회귀 방지선 부재

합의 (R1 수렴 5건)​

  1. ✅ Audience 분리 필요 (전원)
  2. ✅ stale 3문서 (plan-system · promotion-code · ops-console-plan) 사이드바 노출 종료
  3. ✅ ADR 외부 노출 부적절
  4. ✅ broken link 241개 일괄 수정 필요
  5. ✅ Pack 1 을 IA 최상단 반영

충돌 (R2 해소 대상 5건)​

  • C1 분리 방식
  • C2 stale 문서 처리
  • C3 이중 SSoT 해결
  • C4 Landing 형태
  • C5 audit 문서 네임스페이스 (추가 발견)

R2 (2026-04-23) — 크로스 토크​

C1 Audience 분리 방식​

  • P5 반박: Notion 이관은 SSoT 3중화로 drift 확대. 동일 도메인 유지가 운영 비용 최소.
  • P4 보완: /internal/ 서브도메인은 오버엔지니어링. Docusaurus 2 sidebar + 2 navbar 탭으로 audience 분리 가능.
  • P1 찬성: 한 사이트 내 분리 OK. 단 landing 은 public sidebar 만 기본 노출.
  • P3 양보: "Notion 완전 분리" 철회. 조건부 수용 — 엔지니어링 sidebar 는 기본 collapsed + landing 미노출.
  • P5 추가: ideations/ 도 엔지니어링 sidebar 로 흡수.

해소: Docusaurus 2 sidebar (publicDocs + engineeringDocs) · navbar 탭 2개 · 단일 도메인.

C2 stale 문서 처리​

  • P3 재반박: 배너·레거시 라벨은 심리적 모면책. 외부 surface 에서는 삭제.
  • P1 양보: git history 로 충분. content/ 삭제 수용.
  • P2 발언: audit 2문서도 engineering 이관 대상.
  • P5 확인: 참조 검사 필수 (grep -rn dangling link 0 확인 후).

해소: stale 3문서 완전 삭제 + audit 2문서 engineering 이관.

C3 CLAUDE.md ↔ apps/docs 이중 SSoT​

  • P5 2안 제시: (1) build-time include (복잡) (2) 역할 분리 + 상호 참조 (단순).
  • P3 찬성: CLAUDE.md = 내부 agent·개발자 SSoT, apps/docs = 외부 공개 SSoT. 목적 다르면 역할 분리 자연스럽다.
  • P4 보완: 각 문서 상단에 "이 문서는 누구를 위한가" 한 줄 명시.

해소: 옵션 2 (역할 분리 + 상호 참조). build-time include 배제.

C4 Landing 형태​

  • P4 구체화: index.md → index.mdx. <RoleCard> 컴포넌트 4장.
  • P1 찬성: 변호사 카드 1단계 = /pitch (신규 30초 페이지) 필수.
  • P2 찬성: 사무장 카드 1단계 = /quickstart/paralegal (신규 5분 튜토리얼).
  • P3 우선순위: pitch.md 가 1순위 (투자자·도입 검토 공통). paralegal quickstart 는 파일럿 유치 전 단계.
  • P5 비용: RoleCard 컴포넌트 + mdx 전환 30분 · pitch.md 신규 1시간 · paralegal quickstart 별도 PR.

해소: index.mdx + RoleCard × 4 · pitch.md 이번 세션 · paralegal quickstart 후속 PR.

C5 네임스페이스 충돌​

  • P2 제안: audit 2 문서의 "P1/P2/P3" → "H/M/L" 교체.
  • 전원 양보 가능.

해소: H/M/L 치환.

R2 양보 불가 선​

역할선
P5broken link 241 → 0 + onBrokenLinks: "throw" + CI 차단
P3stale 3문서 외부 surface 완전 제거 (배너 X)
P1변호사 진입 경로에 엔지니어링 문서 교차 금지
P4navbar item 유형 4종 혼재 제거

R3 (2026-04-23) — 최종 결정​

결정​

apps/docs 를 2 sidebar + 2 navbar 탭 구조로 audience 분리, stale 3문서 삭제, landing 을 mdx + RoleCard × 4 로 재설계. broken link 241개 일괄 수정 + onBrokenLinks: "throw" 승격.

ADR 0016 발행.

즉시 실행 8항목 (순서대로)​

  1. broken link 241개 일괄 수정 (선행 필수 · P5 양보 불가 선)
  2. sidebars.ts 2 sidebar 분리 (publicDocs · engineeringDocs)
  3. docusaurus.config.ts navbar 재편 (2 탭 + changelog)
  4. stale 3문서 삭제 (plan-system · promotion-code · ops-console-plan)
  5. audit 2문서 engineering 이관 + H/M/L 치환
  6. index.md → index.mdx + <RoleCard> × 4
  7. pitch.md 신규 (변호사 30초 진입)
  8. onBrokenLinks: "throw" 승격 + pre-push hook 에 docs 빌드 추가

후속 PR (별도)​

  • paralegal quickstart (/quickstart/paralegal)
  • ADR 번호 결번 (0008·0009·0013) 정리
  • changelog author 미정의 40+ 수정

Minority Report​

  • P3 초기: "내부 문서 완전 분리 (Notion 이관 또는 password gate)". 처리: R2 에서 P5 drift 반박 수용. Docusaurus 2 sidebar 로 축소하되 engineering sidebar 는 collapsed + landing 미노출로 절충.
  • P4 초기: "/internal/ 서브도메인 분리". 처리: 오버엔지니어링 판정. 2 sidebar 구조로 대체.
  • P1 초기: "stale 문서는 배너 보존". 처리: P3 "심리적 모면책" 반박 수용. git history 로 충분, content/ 삭제.
  • P5 초기: "CLAUDE.md build-time include". 처리: 복잡도·빌드 충돌 우려로 역할 분리 + 상호 참조로 대체.

성공 지표​

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

후속 과제​

  • ADR 0016 발행: decisions/0016-docs-structure-and-audience-separation.md
  • PR 분해 (3~4개):
    • PR A: ADR 0016 + 015 ideations
    • PR B: 구조 재편 (sidebars + navbar + stale 삭제 + audit 이관 + H/M/L)
    • PR C: landing mdx + RoleCard + pitch.md
    • PR D: broken link 일괄 수정 + onBrokenLinks throw (큰 작업, 별도)

품질 체크리스트​

  • Anti-Goal 4개 위반 없음
  • Minority Report 4건 ADR 명시
  • 성공 지표 측정 가능 (broken link count · 모바일 탭 · stale 0 등)
  • 기존 코드·데이터 모델과 모순 없음 (문서 레이어 한정)
  • P1 변호사 + P5 개발자 양측 납득 (양보 불가 선 준수)