실습 과제와 포트폴리오 기초집LESSON 08

README 작성: 설치·실행·기능·제한 사항을 한 문서에 담기

난이도초급

예상 시간45분

선수지식프로젝트 구조 설명

8강. README 작성: 설치·실행·기능·제한 사항을 한 문서에 담기

1. 이번 강의에서 해결할 문제

README가 없거나 기술 배지만 가득하면 무엇을 설치하고 어떻게 실행해야 하는지 알 수 없습니다. 소개부터 제한 사항과 출처까지 한 경로로 안내합니다.

2. 학습 목표

3. 핵심 개념

README는 저장소의 첫 화면입니다. 프로젝트 소개, 결과 화면, 핵심 기능, 환경, 실행, 테스트, 구조, 제한과 출처 순으로 쓰면 독자가 “무엇인가?”와 “실행 가능한가?”를 빠르게 판단할 수 있습니다.

GitHub가 안내하는 README의 위치와 표시 방식은 공식 README 문서에서 공개 전에 다시 확인합니다.

4. 단계별 실습

문서 작업 · 산출물: <PROJECT_ROOT>/README.md

README.md
# 프로젝트 이름

> 대상 사용자의 문제를 핵심 기능으로 해결하는 결과물 한 줄 소개

## 주요 화면
![핵심 흐름 설명](./media/01-main-flow.png)

## 핵심 기능
- 사용자 행동 → 시스템 반응 → 확인 결과
- 오류 상황 → 안내 → 회복 방법

## 개발 환경
- 운영체제: Windows 11에서 검증
- 런타임·엔진: 프로젝트에서 실제 확인한 버전

## 실행 방법
1. 저장소를 내려받아 프로젝트 루트로 이동합니다.
2. 아래의 프로젝트별 실행 문서를 따릅니다: [실행 가이드](./docs/run-guide.md)

## 테스트
- [테스트 체크리스트와 결과](./docs/test-checklist.md)

## 구조
- [핵심 구조와 데이터 흐름](./docs/architecture.md)

## 알려진 문제
- [현재 제한과 우회 방법](./docs/known-issues.md)

## 기여와 출처
- 팀 프로젝트라면 [기여 범위](./docs/contribution.md)를 확인하세요.
- 외부 에셋·코드·폰트는 [출처와 라이선스](./docs/third-party-assets.md)에 기록합니다.

프로젝트에 없는 섹션을 가짜 내용으로 채우지 말고 해당 없음과 이유를 씁니다. 공개 URL 예시는 실제 공개가 끝난 뒤 검증된 링크만 추가합니다.

완료 기준: README의 모든 상대 링크가 열리고 환경, 실행, 테스트, 알려진 문제와 출처가 비어 있지 않습니다.

5. 작성 방식이 필요한 이유

README가 세부 문서의 목차 역할을 하면 중복을 줄이면서도 독자가 원하는 깊이로 이동할 수 있습니다. 실행과 한계를 앞에서 숨기지 않아 신뢰를 높입니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ