Vibe Docs ⋅ 기록에서 발행까지
원자료를 읽고 근거를 구분해 한 편의 문서 페이지로 만드는 과정을 정리한다.
이 문서의 목차
먼저 답할 질문을 정한다
원자료를 곧바로 페이지에 옮기기 전에 독자와 질문을 정한다. 이 글의 독자는 새 문서를 추가할 사람이고, 답할 질문은 “기록이 어떻게 같은 규칙을 가진 문서 페이지가 되는가”이다.
사실과 해석을 나눈다
확인한 코드와 설정은 사실로, 그 사실에서 읽어 낸 의미는 해석으로, 아직 적용하지 않은 선택지는 제안으로 표시한다. 확인하지 못한 상태는 성공한 것처럼 쓰지 않는다.
AI의 해석문서 목록과 본문을 분리하면 목록에 필요한 정보만 먼저 읽고, 본문은 해당 주소에서만 렌더할 수 있다.제안새 글은 기존 섹션 컴포넌트를 조합하고, 반복되는 표현이 실제로 두 번 이상 나타날 때 공용 컴포넌트로 올린다.커스텀 도메인의 DNS 연결과 배포 상태는 외부 설정을 확인하기 전까지 완료로 기록하지 않는다.
한 섹션에 하나의 주장만 둔다
섹션은 제목 하나와 그 제목을 뒷받침하는 본문, 예시로 구성한다. 긴 문단을 여러 카드로 잘게 나누기보다 내용이 바뀌는 지점에서 섹션을 나눈다. 96px의 큰 간격은 그 전환을 화면에서도 보여준다.
콘텐츠와 화면의 책임을 나눈다
페이지는 주소를 해석하고, 메타데이터는 목록과 목차를 설명하며, 콘텐츠 파일은 글의 순서를 책임진다. 탭이나 타임라인처럼 클릭이 필요한 부분만 클라이언트 컴포넌트로 두고 나머지 글은 서버에서 렌더한다.
app라우트와 페이지 조합
- docs/[slug]/page.tsx주소의 slug로 문서와 메타데이터를 선택
content문서 본문
- component-gallery.tsx컴포넌트 규칙을 보여주는 예시 글
- writing-workflow.tsx기록에서 발행까지의 예시 글
components여러 문서가 함께 쓰는 표현
- ui.tsx본문, 섹션, 표와 근거 표시
- controls.tsx탭처럼 상태가 있는 표현
- code-block.tsx서버에서 강조한 코드
- lib/reports.ts문서 목록과 목차 메타데이터
- styles/tokens.stylex.ts색, 글꼴, 여백과 곡률 토큰
서버와 클라이언트 컴포넌트의 경계는 Next.js 공식 문서의 기준을 따른다.
공용 언어로 문서를 쓴다
새 글은 Section, Text,Callout처럼 이미 정한 표현을 조합한다. 문서 목록에는 제목, 요약, 날짜, 읽기 시간, 분류와 목차를 한 번만 등록한다.
export const reports = [ { slug: "component-gallery", title: "컴포넌트 갤러리 ⋅ 문서를 이루는 작은 규칙", summary: "문서를 이루는 시각 규칙과 상호작용을 확인한다.", date: "2026-10-04", readingMinutes: 8, category: "DESIGN SYSTEM", sections: [ { id: "palette", title: "색은 역할이 있을 때" }, { id: "typography", title: "글자의 크기로 읽는 순서 만들기" }, ], },];읽는 순서대로 검토한다
구현 파일을 하나씩 보는 데서 끝내지 않고 목록, 문서 첫 화면, 본문, 목차 이동, 작은 화면 순서로 읽는다. 독자가 마주치는 순서와 검토 순서를 같게 두면 코드 단위 검사에서 놓친 연결 문제를 찾기 쉽다.
| 확인 대상 | 통과 조건 | 관점 |
|---|---|---|
| 질문 | 제목과 도입만 읽어도 답할 질문이 드러나는가 | 독자 관점 |
| 근거 | 사실, 해석, 제안을 같은 문장에 섞지 않았는가 | 내용 관점 |
| 구조 | 각 섹션이 하나의 주장만 설명하는가 | 편집 관점 |
| 화면 | 작은 화면에서도 표와 코드가 잘리지 않는가 | 렌더 관점 |
| 경로 | 문서 주소와 목록의 slug가 일치하는가 | 라우팅 관점 |
발행은 검증 뒤에 온다
타입 검사와 빌드가 통과하고, 두 문서 주소를 직접 열어 목록·목차·본문이 이어지는지 확인한 뒤 배포한다. 배포 뒤에는 실제 주소의 응답과 커스텀 도메인 연결을 별도로 확인한다.