Guide
README 잘 쓰는 법
README는 프로젝트를 처음 설명하는 문서입니다. 코드를 열기 전에 프로젝트 목적, 주요 기능, 실행 방법을 빠르게 파악할 수 있어야 읽기 좋습니다.
- 첫 문단에서 프로젝트의 목적과 문제를 먼저 보여 주세요.
- 주요 기능은 길게 풀기보다 빠르게 훑을 수 있게 정리하는 편이 좋습니다.
- 기술 스택은 이름보다 선택 이유까지 적어 둘 때 더 설득력 있습니다.
첫 문단에서 목적을 분명히 쓰세요
프로젝트가 무엇인지보다 왜 존재하는지를 먼저 설명하면 맥락이 더 빨리 잡힙니다. 해결하려는 문제나 사용 장면을 앞에 두는 편이 읽는 사람에게 훨씬 친절합니다.
예를 들어 "영화 추천 웹앱"이라고만 적는 것보다, "취향 입력 과정을 줄이기 위해 빠르게 추천 결과를 보여주는 영화 추천 웹앱"이라고 쓰면 프로젝트의 목적과 사용 장면이 훨씬 선명해집니다. README 첫 문단은 기능 목록보다 방향을 잡아 주는 문장에 가깝습니다.
주요 기능은 훑어보기 쉽게 정리하세요
모든 구현 세부사항을 README에 길게 적을 필요는 없습니다. 대표 기능을 짧은 문장이나 목록으로 정리해 두면 문서 전체가 훨씬 깔끔해집니다.
- 사용자가 실제로 체감하는 기능부터 먼저 적습니다.
- 비슷한 기능은 묶고, 지나치게 세부적인 항목은 줄입니다.
- 스크린샷이나 짧은 예시가 있으면 이해 속도가 빨라집니다.
기술 스택은 선택 이유와 함께 적어 보세요
어떤 기술을 썼는지보다 왜 그렇게 구성했는지가 더 큰 차이를 만듭니다. 기술 이름만 나열하기보다 선택 이유를 짧게 덧붙이면 프로젝트 이해도가 높아집니다.
예를 들어 "FastAPI 사용"이라고 끝내기보다, "비동기 API 응답과 문서화가 쉬워 FastAPI를 사용했다"처럼 이유를 붙이면 기술 선택의 기준이 보입니다. 이 한 줄 차이가 README를 훨씬 실무적으로 읽히게 만듭니다.
실행 방법과 현재 상태도 중요합니다
설치 방법, 실행 명령어, 필요한 환경 변수, 현재 개발 상태를 함께 적어 두면 다른 사람이 따라오기 쉬워집니다. README는 포장 문서보다 안내서에 가깝다는 점이 중요합니다.
저장소를 보는 사람은 대개 "지금 당장 실행 가능한가", "어디까지 완성됐는가", "무엇이 남아 있는가"를 빠르게 확인하고 싶어 합니다. 실행 명령어와 현재 상태를 적어 두면 프로젝트의 신뢰도가 훨씬 높아집니다.
자주 빠지는 항목도 확인하세요
README에서 자주 빠지는 것은 데모 링크, 환경 변수 안내, 폴더 구조 설명, 트러블슈팅 메모입니다. 모든 항목을 길게 쓸 필요는 없지만, 처음 보는 사람이 막히지 않도록 최소한의 안내는 남겨 두는 편이 좋습니다.