한 줄 정의
README는 저장소나 디렉터리에 처음 들어온 사람이 “이게 뭐고, 어떻게 시작하고, 어디까지 믿어도 되는지”를 먼저 읽는 안내 문서야. GitHub에서는 README.md가 저장소 첫 화면에 자동으로 올라오고, 보통 프로젝트 설명, 설치 방법, 도움 받을 곳, 유지보수자를 확인하는 입구가 돼.
그래서 README는 문서 전체가 아니라 첫 문이야. 문이 너무 커지면 들어가기도 전에 길을 잃는다. GitHub 문서도 500 KiB를 넘는 README는 표시가 잘릴 수 있다고 적어 두고 있어.
어떻게 작동하나
GitHub는 README를 .github, 저장소 루트, docs 순서로 찾아서 보여 줘. 보통은 루트의 README.md가 첫 화면을 맡고, 제목과 섹션 heading은 화면 안에서 바로 이동할 수 있는 목차와 링크가 돼.
실제로는 두 종류가 자주 보여. Activepieces의 리드미는 473 lines, 85.7 KB 안에서 “Zapier 대체”, TypeScript piece, 280+ MCP 노출, 배포 문서 링크를 앞쪽에 배치해. 처음 온 사람이 제품 범위와 다음 링크를 빨리 잡을 수 있는 구조야.
반대로 mikeroyal의 self-hosting README는 7,147 lines, 575 KB야. 이 정도면 README라기보다 셀프호스팅 카탈로그에 가까워. 자료가 많다는 장점은 있지만, 처음 설치할 사람이 명령어와 유지보수 상태를 찾으려면 별도 문서나 목차 품질이 더 중요해져.
왜 중요한가
README를 보면 프로젝트가 자기 자신을 어떻게 설명하는지 알 수 있어. 특히 AI 도구나 AI 에이전트 관련 저장소에서는 “무엇을 자동화한다”는 말보다 설치 조건, 권한 범위, 외부 도구 연결, 실패했을 때 도움 받을 경로를 먼저 확인하는 게 낫다.
예를 들어 Activepieces 문서는 agentic AI와 MCP를 강하게 말하지만, 동시에 문서, 배포, piece 생성 링크를 같이 둬. 이건 “AI가 다 해준다”보다 “자동화 서버를 설치하고 piece를 확장해 쓰는 제품”이라는 쪽으로 읽는 게 정확해.
관련 개념과 비교해서 보면 경계가 더 선명해져. AI 에이전트는 일을 진행하는 실행 구조이고, README는 그 구조를 설치하거나 검토하기 전에 읽는 설명 문서야. Agentic AI는 제품이 주장하는 자동화 범위에 가깝고, README는 그 주장을 설치 조건과 문서 링크로 확인하는 자리야. MCP는 도구 연결 표준이고, README는 그 연결을 어디서 켜고 어떤 권한이 필요한지 알려 주는 첫 링크여야 해.
README가 빈약하면 반대 문제가 생겨. 저장소 star가 높아도 설치 명령, 라이선스, 지원 채널, 예제 입력과 출력이 없으면 PoC 시간이 늘어나. README는 관심을 끄는 소개문이 아니라 첫 실행을 막는 불확실성을 줄이는 문서라고 보는 게 좋아.
주의해서 볼 점
- CHECK: 첫 30초 안에 프로젝트 정체성, 설치 경로, 최소 실행 예제가 보이는지 확인해.
- CHECK: README 안의 숫자와 홍보 문구를 그대로 믿지 말고, release, issue, license, 보안 문서와 나눠 봐.
- CHECK: API 키, OAuth scope, self-host 설정처럼 운영 위험이 큰 내용은 README에 요약만 있고 공식 문서로 이어지는지 봐.
- SKIP: README 하나에 모든 설명을 넣어 500 KiB 근처까지 커졌다면, 그 저장소는 quick start와 reference 문서를 분리했는지 따로 확인해야 해.
README는 짧을수록 좋은 문서가 아니야. 다만 첫 화면에서 독자가 다음 행동을 정하게 해 줘야 해. 설치할지, 문서로 넘어갈지, 코드를 읽을지, 아니면 닫을지. 그 판단이 안 되면 README가 일을 덜 한 거야.