핵심 정리

repo/
├─ README.md
├─ CHANGELOG.md
├─ docs/
│  ├─ index.md
│  ├─ setup.md
│  └─ images/
│     └─ architecture.png
└─ src/

구조 기준

README는 모든 내용을 담는 문서가 아니라 길 안내 문서다

저장소의 README.md는 독자가 처음 보는 진입점입니다. 프로젝트가 무엇인지, 어떻게 시작하는지, 어디서 자세한 문서를 볼 수 있는지를 짧게 안내하는 역할이 큽니다. 설치, 운영, API, 아키텍처 설명이 길어지면 docs/로 분리하고 README에는 링크를 둡니다.

시작하기:

빠른 실행은 [설치 가이드](./docs/setup.md)를 참고하세요.
전체 문서는 [문서 인덱스](./docs/index.md)에서 볼 수 있습니다.

README에 모든 내용을 쌓으면 처음 읽는 속도는 느려지고, 문서 변경 시 링크와 목차를 유지하기 어려워집니다.

index 문서는 섹션 안의 목차 역할을 맡긴다

문서가 여러 파일로 늘어나면 각 섹션에 index.md를 두어 탐색 기준을 제공합니다. 정적 사이트 빌더는 index.md를 섹션 랜딩 페이지로 다루는 경우가 많고, GitHub에서도 디렉터리 안의 대표 문서로 쓰기 좋습니다.

docs/
├─ index.md
├─ guide/
│  ├─ index.md
│  ├─ install.md
│  └─ deploy.md
└─ api/
   ├─ index.md
   └─ auth.md

index.md는 세부 내용을 반복하기보다 어떤 문서를 먼저 읽을지, 어떤 순서로 이어지는지 보여 주는 데 집중합니다.

이미지 위치는 링크 수명과 함께 결정한다

이미지를 문서 옆에 둘지 공용 assets/에 둘지는 재사용 범위로 결정합니다. 특정 문서에서만 쓰는 이미지는 해당 문서 근처에 두면 이동 맥락이 명확합니다. 여러 문서가 공유하는 로고, 아키텍처 다이어그램, 공통 스크린샷은 공용 assets 경로가 낫습니다.

docs/setup.md
docs/images/setup-screen.png

docs/assets/logo.png
docs/assets/system-architecture.png

파일 이동이 잦은 프로젝트라면 문서와 이미지를 함께 이동할 수 있는 구조가 링크 유지에 유리합니다.

선택 기준

주의할 점

대소문자와 공백이 섞인 파일명은 플랫폼별 차이를 만듭니다. 공개 문서에서는 setup-guide.md, api-auth.md처럼 소문자와 hyphen 중심의 파일명을 쓰는 편이 안정적입니다.