GitHub에 생각을 적는다

앞 글 머릿속 그림을 말로 옮긴다에서 머릿속 그림이 말이 됐습니다. 이 글에서는 그 말을 둘 자리를 정하고 놓는 일, 즉 리포지토리와 README와 Issue를 다룹니다. AI를 위한 규칙을 적는 CLAUDE.md는 다음 글 AI를 위한 규칙을 적는다에서 이어집니다.

결론부터 말하죠. GitHub 리포지토리 안에 두세요. 메모 앱도, 노션도, 노트도 아닙니다.

중요한 걸 하나 더 먼저 말해 둡니다. 놓는 작업은 여러분이 하지 않습니다. 리포지토리를 만드는 것도, 파일을 쓰는 것도, Issue를 세우는 것도 전부 AI에게 시킵니다. 여러분이 하는 건 말하는 것과 완성된 걸 보는 것뿐입니다.

AI가 읽을 수 있는 곳에 없는 건 존재하지 않는다

도구는 딱 둘 — Claude Code와 GitHub에서 GitHub를 "사람과 AI가 같은 걸 보는 책상"이라고 했습니다. 이 의미를 좀 더 정확히 다시 말하겠습니다.

Claude Code는 리포지토리 안의 내용을 읽고 작업합니다. 뒤집어 말하면 리포지토리 밖에 있는 건 전혀 보이지 않습니다.

여러분 노션에 완벽한 기획서가 있어도 AI에게는 존재하지 않는 것입니다. 머릿속의 "이렇게 하고 싶은데 말이지"는 말할 것도 없고요. 매번 채팅으로 다시 설명하게 되고, 설명할 때마다 조금씩 내용이 어긋납니다.

생각을 리포지토리에 둔다는 건, AI에게 매번 같은 얘기를 반복하지 않아도 되게 만든다는 뜻입니다.

그뿐이 아닙니다. 3개월 뒤의 나 자신도 확실히 잊습니다. 적어 두면 미래의 나에게도 가닿습니다.

나는 말한다. AI가 적는다

"근데 README니 Issue니, 쓰는 법을 모르는데" — 몰라도 됩니다.

진행 방식은 이렇습니다. 앞 글에서 말로 옮긴 것(한 문장과 AI와의 문답 기록)을 Claude Code에게 그대로 건네고 이렇게 말합니다.

"이 내용으로 새 프로젝트를 시작하고 싶어. 리포지토리를 만들고, README에 생각을 정리하고, 첫 Issue를 세우는 것까지 전부 해 줘. 모르는 게 있으면 작업 전에 물어봐."

리포지토리 생성도, 파일 내용도, Issue 문구도 AI가 다듬습니다. GitHub 화면에서 여러분이 조작할 건 기본적으로 없습니다. 완성된 걸 브라우저로 보면서 "여긴 아니야", "이거면 됐어"라고 말할 뿐입니다.

단, 통째로 맡긴 결과를 제대로 판단하려면 뭐가 어떻게 적혀 있어야 하는지는 알고 있어야 합니다. 이 글의 나머지는 그걸 위한 지식입니다. 내가 쓰기 위해서가 아니라 AI가 쓴 걸 채점하기 위한 지식이라고 생각하고 읽으세요.

README.md — 이 세계의 선언문

리포지토리의 얼굴이 되는 파일이 README.md입니다. 기술 설명서라고 생각하기 쉽지만 바이브 코딩에서의 역할은 다릅니다. 이건 선언문입니다.

AI가 쓴 README를 볼 때 체크할 점은 세 가지입니다.

# 건프라 갤러리

## 이것은 무엇인가
전 세계 건프라 빌더가 자기 완성작을 올려 서로 보여 주는 갤러리 사이트.

## 왜 만드는가
SNS에 올린 사진은 타임라인에 묻혀 사라진다. 몇 달 들여 만든 완성작이
3일이면 아무 눈에도 안 띄게 되는 건 아깝다.
작품으로 남는 자리를 만들고 싶다.

## 최종적으로 어떻게 되면 최고인가
전 세계 빌더가 참가하는 도색 콘테스트를
이 사이트에서 연다.

## 누가 쓰는가
건프라를 오래 만들어 왔고, SNS로는 만족 못 하는 사람. 한국어권과 영어권.

## 지금 만들지 않는 것
- 온라인 숍 기능
- 오프라인 대회 결과 관리

"왜 만드는가"가 기능 목록보다 앞에 있는가. 이유가 적혀 있으면 AI는 판단이 애매할 때 이유 쪽을 우선합니다.

최종 목표가 거리낌 없이 적혀 있는가. AI는 요약하면서 여러분의 그림을 "상식적인 크기"로 뭉개 놓을 때가 있습니다. "세계 대회"가 "커뮤니티 사이트"로 희석돼 있으면 되돌리세요. 열량만은 AI가 채워 줄 수 없습니다.

"지금 만들지 않는 것"이 있는가. 이게 없으면 AI는 친절한 마음으로 쓸데없는 걸 만듭니다.

Issue — 그림을 작업으로 바꾸는 장치

README는 전체 생각입니다. 이것만으로는 너무 커서 못 넘깁니다.

그래서 쓰는 게 Issue(도구 글에서 말한 "책상에 붙이는 포스트잇")입니다. Issue의 역할은 하나. 큰 그림을 넘길 수 있는 크기로 쪼개는 것.

"세계 대회를 연다"는 못 넘깁니다. 하지만 이렇게 쪼개면 넘길 수 있습니다.

• 올라온 사진을 목록으로 보여 준다
• 사진에 "등급(HG/MG/RG)" 태그를 달 수 있게 한다
• 영어 표시로 전환할 수 있게 한다

이 쪼개는 작업도 AI에게 시킵니다. "README를 바탕으로 처음 해야 할 Issue 5건을 제안하고 등록해 줘." 여러분의 일은 나온 5건을 보고 "이건 아니야", "이건 나중에"라고 순서를 바꾸는 것입니다.

채점 기준은 "5분 만에 완료 판정이 되는가"

AI가 세운 Issue를 채점하는 기준은 하나만 기억하면 됩니다.

그 Issue가 끝났는지 아닌지, 5분 안에 판단할 수 있는가.

"목록에 사진이 줄지어 있는가"라면 보면 압니다. 5분이면 됩니다. "사이트를 리뉴얼한다"는 판단이 안 됩니다. 그런 Issue를 발견하면 "이건 너무 커. 쪼개 줘"라고 하면 됩니다.

하나 더, 각 Issue에 "이렇게 되면 완료" 항목이 있는지 확인하세요.

## 목적
왜 이걸 하고 싶은가 (README의 어느 부분으로 이어지는가)

## 이렇게 되면 완료
- 항목별로, 보면 알 수 있는 상태
- 3개를 넘으면 Issue를 쪼갠다

## 하지 않을 것
이번엔 건드리지 않기로 정한 것

이 "이렇게 되면 완료"는 앞으로 몇 번이고 나오는 급소입니다. 여기가 애매한 Issue는 넘겨도 애매한 것밖에 안 돌아옵니다. AI는 문구를 다듬는 건 잘하지만 무엇을 완료로 볼 것인가는 여러분의 욕망의 문제입니다. 빈칸이나 애매한 완료 조건을 발견하면 거기만은 여러분의 말로 채우세요.

어디에 무엇을 두는가

오른쪽 두 열이 이 코스의 역할 분담 전부입니다. 쓰는 건 늘 AI. 판단하는 건 늘 나. 이 표는 마지막 글까지 이 형태 그대로 갑니다.

해 보기

1. 앞 글의 결과물(한 문장 + 문답 기록)을 Claude Code에게 건네고 "리포지토리 생성부터 README, 첫 Issue 3건까지 전부 해 줘"라고 넘긴다
2. 완성된 README를 읽고 "왜", "거리낌 없는 최종 목표", "만들지 않는 것" 세 가지로 채점한다. 희석돼 있으면 열량을 채우게 한다
3. Issue 3건을 "5분 만에 완료 판정이 되는가"로 채점한다. 크면 쪼개게 한다

오늘 여러분이 타이핑한 글자보다 리포지토리에 늘어난 글자가 압도적으로 많을 겁니다. 그게 정상입니다.

다음 글: AI를 위한 규칙을 적는다