문제#
조사가 확장되면서 일부 페이지가 시장, 경쟁, 안전, 수익과 실험 계획을 한 번에 설명하기 시작했다. 같은 수치와 판단이 여러 페이지에 복제돼 수정할 곳과 기준 문서를 알기 어려웠다.
결정#
- 한 페이지는 하나의 질문에 답한다.
- 허브는 한 문장 결론과 최대 4개의 핵심 하위 문서를 연결한다.
- 수치, 정의, 비교표, 정책 원칙과 실험 절차는 기준 문서 한 곳에서만 관리한다.
- 종합 문서는 세부 근거를 반복하지 않고 기준 문서에서 도출한 판단과 우선순위만 적는다.
- 상세 문서가 길어지면 제목 수보다 질문 수를 기준으로 나눈다.
- 하위 문서는 상위 허브와 관련 기준 문서를 다시 연결한다.
페이지 역할#
| 역할 | 기본 책임 |
|---|---|
| 허브 | 현재 결론, 세부 문서 지도, 다음 행동 |
| 주제 | 하나의 질문에 대한 근거, 해석과 한계 |
| 종합 | 여러 주제에서 도출한 결론과 우선순위 |
| 계획 | 대상, 순서, 완료·중단 조건 |
| 결정 | 선택, 이유, 대안과 재검토 조건 |
| 출처 | 원본 범위와 어떤 주장에 사용됐는지 기록 |
분리 기준#
다음 중 둘 이상이면 문서를 나눈다.
- 서로 다른 질문이 두 개 이상이다.
- 큰 절이 7개를 넘는다.
- 독립적인 표가 3개 이상이다.
- 근거 설명과 실행 계획이 같은 수준으로 길다.
- 다른 기준 문서와 동일한 수치·표·정의가 반복된다.
허브와 종합은 공백 기준 단어 묶음 약 900개, 일반 주제는 약 1,400개를 자동 검사 경고선으로 사용한다. 분량보다 질문의 응집도가 우선이지만, 한도를 넘기려면 문서 역할을 다시 확인해야 한다.
기준 문서 표시#
중요 개념의 기준 페이지는 선택적으로 canonical_for를 선언한다. 같은 값은 두 페이지에서
사용하지 않는다. 다른 페이지는 해당 내용을 다시 정의하지 않고 한 문장 요약과 내부 링크를
사용한다.
적용 결과#
수익모델, 결제와 사용자 불만 문서는 짧은 허브와 단일 질문 문서로 나눈다. 퇴근길 만남 조사 결과와 프로젝트 개요는 상세 표를 제거하고 기준 문서를 연결하는 종합과 허브로 축소한다.
자동 검사는 페이지 역할별 분량, 제목 수, 허브의 내부 링크와 canonical_for 중복을
확인한다.
상세 절차: docs/playbooks/wiki-page-authoring.md
관련 문서: ADR-0001: LLM Wiki 지식 시스템, ADR-0004: Wiki 정보 구조와 시각 자료, ADR-0005: Wiki 디자인 시스템