developer-onboarding-doc-pattern

신규 개발자가 git clone 부터 첫 실행까지 도달하는 onboarding 문서 묶음의 표준 패턴. README / QUICKSTART / INDEX / docs 4-tier 구조 + 5분 검증 + FAQ + 트러블슈팅 표.

1. 사용 시점

• 신규 입사자가 첫 주에 0 → 실행까지 가는 가이드 작성
• 새 환경에서의 setup 가이드 (로컬 / staging / production)
• git clone 부터 first hello world 까지의 step-by-step
• 외부 contributor 첫 PR 가이드 (open source onboarding)
• 인수인계 문서 (전임자 → 후임자)

2. 4-tier 구조

핵심 원칙: 각 tier 는 단일 책임을 가진다. README 가 5분 quickstart 까지 다 담으면 길어진다. QUICKSTART 가 운영 상세까지 가면 5분 안에 안 끝난다. 분리.

3. README.md 표준 구조 (한 화면)

1. 한 줄 요약 (badge / live URL)
2. 시스템 아키텍처 (mermaid / ASCII 1개)
3. 5분 Quickstart (3-5 명령)
4. 검증된 메트릭 (성능 표 / 테스트 카운트)
5. 산출물 / 카탈로그 (책 / 매뉴얼 / skill 수)
6. 운영 도구 (CLI / 대시보드 표)
7. CI/CD 상태 (배지 / 최근 run)
8. 관련 문서 (QUICKSTART / INDEX / docs/ 링크)

전체 1 page (스크롤 1-2 번). 더 길면 잘라서 docs/ 로 보낸다.

4. QUICKSTART.md (5분 안에 끝나야 함)

git clone → install → run → 검증, 5 단계 이내. 각 단계는 4-tuple 로 (playbook-authoring-pattern 참고).

Step N (X min) — <목적 요약>
  [목적]      이 단계에서 무엇을 달성하는가
  [명령]      복붙 가능한 명령
  [기대출력]  실행 직후 보여야 할 것
  [실패시]    가장 흔한 실패 + 1줄 해결

5단계가 넘어가면 분리하거나 docs 로 옮긴다.

5. 검증 단계 (사용자가 성공했는지 한 줄로 확인)

quickstart 마지막에 반드시 확인 명령 한 줄:

curl http://localhost:8080/healthz
# 기대: HTTP 200, "ok"

검증 없이 끝나면 "되긴 한 건가?" 가 첫 슬랙 질문이 된다.

6. 한 줄 요약 (헤더) 작성법

• 무엇을 / 누구에게 / 왜 가치 (1-2 줄, 마케팅/기술 균형)
• 추상 X, 구체 수치 O
• 좋은 예: "GEM-LLM is a Qwen Coder dual-model coding assistant on 8×B200, OpenAI-compatible Gateway with 50-user concurrent verified production-ready system."
• 나쁜 예: "An AI system that helps developers." (무엇이? 누구에게?)

7. 시스템 아키텍처 다이어그램

mermaid 또는 ASCII art. 한 화면에 들어가게.

[User] → [Gateway:8000] → [vLLM-A:8001]
                       → [vLLM-B:8002]

3-7 개 박스 / 5-10 개 화살표. 더 복잡하면 docs/architecture.md 로. 참고: mermaid-diagram-authoring.

8. 검증된 메트릭 표 (믿음 단서)

추상 X. 구체 수치만.

테스트 카운트, uptime, 운영 일수, 사용자 수도 동일.

9. 산출물 / 카탈로그

• 책 / 매뉴얼 / 논문 PDF 페이지 수
• skills 카운트 + 링크
• 테스트 카운트 (passing / total)
• INDEX.md 로 전체 자산 일람

INDEX.md 가 단일 진실의 출처(SoT).

10. FAQ (5-10 Q&A, 입사 첫 주에 묻는 것)

• Q1: 비용 얼마나 드나? (라이선스 / 클라우드 / GPU)
• Q2: 의존성? OS는? Python 버전?
• Q3: 운영 중 가장 흔한 트러블 5 가지
• Q4: 다음에 읽어야 할 문서 (학습 경로)
• Q5: 누구한테 물어보면 되나? (담당자 / 슬랙 채널)

답은 짧게 (3-5 줄). 길면 docs 링크.

11. 흔한 함정

12. 관련 skill

• bilingual-book-authoring — 한/영 동시 책 저작 (deep tier 문서)
• playbook-authoring-pattern — 4-tuple 절차서 작성 (QUICKSTART 단계 디테일)
• mermaid-diagram-authoring — 아키텍처 다이어그램
• claude-code-skill-authoring — skill 자체 onboarding

템플릿

• templates/README.md.template — Tier 1 한 화면 README
• templates/QUICKSTART.md.template — Tier 2 5분 quickstart

cp ~/.claude/skills/developer-onboarding-doc-pattern/templates/README.md.template README.md
cp ~/.claude/skills/developer-onboarding-doc-pattern/templates/QUICKSTART.md.template QUICKSTART.md

<PROJECT>, <repo>, <install command> 같은 placeholder 를 프로젝트에 맞게 치환.