Claude Code로 README 소개 페이지 5분 만에 만들기
README 하나로 소개 화면부터 만들자
README를 잘 써둔 오픈소스는 많지만 링크만 보내면 처음 보는 사람은 어디부터 읽어야 할지 바로 안 잡힐 때가 많습니다. 오늘은 Claude Code에 GitHub README URL 하나를 넣고 소개 화면 한 장으로 바꾸는 흐름을 정리해보겠습니다. 목표는 거창한 사이트를 만드는 게 아니라, 5분 안에 첫 화면을 띄우고 누가 봐도 무슨 오픈소스인지 이해되는 상태까지 가는 겁니다.
이 방식이 좋은 이유는 간단합니다. README 전체를 설명하려고 덤비면 문장이 길어지고, 정작 공유할 때는 핵심이 안 보입니다. 반대로 첫 화면에 제목, 한 줄 설명, 시작 지점만 먼저 세워두면 그다음 수정은 훨씬 단순해집니다. 나중에 내가 다시 찾아볼 때도 문서를 처음부터 다시 읽지 않아도 됩니다.
준비물은 세 개면 된다
필요한 건 GitHub README URL 하나, 작업할 폴더 하나, 그리고 Claude Code뿐입니다. 오늘 흐름은 Claude Code 기준으로 적겠습니다. 파일 하나를 바로 만들고, 문장 톤이나 모바일 화면도 마지막에 `/review`로 같이 손보기 좋기 때문입니다.
여기서 중요한 기준은 처음부터 다 채우지 않는 겁니다. 소개 화면은 설명서가 아니라 입구에 가깝습니다. 그래서 첫 버전에서는 넓게 다루기보다, 이 오픈소스가 누구에게 맞는지와 어디서 시작하면 되는지만 또렷하게 보여주는 쪽이 낫습니다.
첫 단계에서 욕심내지 않는 게 포인트입니다. 카드 여러 개, 설치 설명, 비교 문장까지 한 번에 넣으면 문장도 늘어지고 화면도 금방 복잡해집니다. 제목이 보이고, 첫 문장만 읽어도 무슨 도구인지 감이 오고, 클릭할 것 같은 영역이 하나 잡히면 시작으로는 충분합니다.
이때 보는 기준도 단순합니다. 휴대폰 폭에서 제목이 두 줄 안쪽으로 읽히는지, 첫 설명이 추상적이지 않은지, 버튼처럼 보이는 요소가 화면 밖으로 밀리지 않는지만 보면 됩니다. 첫 버전은 완성본이 아니라 방향을 잡는 바닥 화면이라고 생각하면 편합니다.
이 프롬프트가 잘 먹히는 이유는 범위를 정확히 잘라주기 때문입니다. 문서 전체를 요약하라고 하면 설명투가 길어지고, 카드마다 비슷한 표현이 반복되기 쉽습니다. 기능 3개만 고르면 문장 길이가 줄고, 보는 사람도 무엇부터 읽어야 하는지 바로 잡힙니다.
여기서부터 README 소개 페이지 느낌이 살아납니다. 링크를 보내기 전에 따로 설명해야 했던 내용이 카드 세 장으로 정리되기 때문입니다. 특히 초보 입장에서는 기능 이름보다 쓰는 장면 한 줄이 더 잘 들어옵니다. 그래서 "이런 사람에게 맞는 장면"을 꼭 붙여두는 게 좋습니다.
설치 구간은 길어지는 순간 읽는 흐름이 끊깁니다. `Quickstart`, `Manual install`, `Advanced setup`가 한 번에 들어오면 처음 보는 사람은 무엇부터 입력해야 할지 멈추게 됩니다. 그래서 첫 행동 하나만 남겨두는 편이 낫습니다. 소개 화면은 모든 경우의 수를 담는 문서가 아니라, 시작점을 보여주는 화면이기 때문입니다.
여기서는 `npm install`이든 `docker compose up`이든 첫 명령 하나가 또렷하게 보이면 됩니다. 그 아래에 왜 이 명령부터 치면 되는지 한 줄만 붙이면 흐름이 훨씬 매끈해집니다. 길게 설명하는 대신 복붙 가능한 덩어리를 먼저 세워두는 쪽이 초보에게 더 친절합니다.
마지막 단계에서는 기능 추가보다 읽기 검수가 더 중요합니다. 제목은 멀쩡한데 첫 문장이 비어 있으면 무엇을 하는 오픈소스인지 흐려지고, 카드 간격이 어색하면 한 장짜리 화면인데도 정신없어 보입니다. `/review`를 붙이는 이유도 새 기능을 더하자는 뜻이 아니라, 이미 있는 내용을 보는 사람 기준으로 다듬기 위해서입니다.
이 단계에서는 세 가지만 보면 됩니다. 제목만 읽고도 용도가 잡히는지, 카드 설명이 돌려 말하지 않는지, 모바일 390px 폭에서 코드 줄이 옆으로 새지 않는지입니다. 이 셋이 정리되면 README 소개 페이지는 링크로 바로 보내도 부담이 적습니다.
문장이 흐려질 때는 프롬프트를 더 짧게 자르자
가장 자주 나오는 문제는 말이 번드르르한데 내용이 안 남는 경우입니다. 화면은 깔끔한데 정작 무엇을 하는 오픈소스인지 한 번에 안 들어오는 식입니다. 이럴 때는 프롬프트에 `과장 문구 금지`, `기능 3개만`, `없는 기능 꾸며내지 말기`를 다시 넣고, 카드 설명 길이도 한 단계 더 줄이면 됩니다. 감탄을 늘리는 것보다 이해 속도를 높이는 편이 훨씬 낫습니다.
설치 구간이 길어지는 문제도 자주 보입니다. 옵션 설명과 예외 상황까지 한꺼번에 붙으면 정작 따라 칠 한 줄이 안 보입니다. 그럴 때는 `가장 짧은 시작 명령어만`이라는 문장을 다시 넣어두세요. 첫 행동과 추가 설정을 분리하는 것만으로도 화면이 훨씬 차분해집니다.
다음에는 업데이트 한 줄도 붙여보면 좋다
오늘 만든 화면 아래에 release 변화 한 줄만 더 붙이면 쓰임새가 더 선명해집니다. 저장해둔 오픈소스가 업데이트될 때 바뀐 내용을 짧게 모아두면, 한 번 보고 끝나는 README 소개 페이지가 아니라 다시 찾아보는 개인 보드로 이어질 수 있습니다. 시작은 `index.html` 한 장이어도 충분하고, 그다음 확장은 이렇게 하나씩 붙이면 됩니다.
이런 글도 있어요
관련 검색어
- 🔍 Claude Code 사용법
- 🔍 Claude Code 비교
- 🔍 README 소개 페이지 사용법
- 🔍 README 소개 페이지 비교
- 🔍 GitHub README 사용법
- 🔍 GitHub README 비교
