GitHub에 생각을 적는다

4편에서 범위, 목적, 제약, 검증 네 줄을 만들었습니다. 이 글은 그 문장들을 어디에 두는가를 다룹니다. 답은 GitHub 리포지토리입니다. README는 이 도구가 무엇인지 선언하는 문서이고, Issue는 그림을 작업 단위로 자르는 장치입니다. 둘 다 사람이 쓰지 않고 AI에게 쓰게 하며, 사람은 채점만 합니다. 다음 편 AI를 위한 규칙을 적는다에서 같은 저장소에 CLAUDE.md를 더합니다.

핵심 요약

AI가 읽을 수 있는 곳에 없는 생각은 존재하지 않는 것입니다. 노션과 메모 앱은 Claude Code가 읽지 못합니다.
README와 Issue는 사람이 말하고 AI가 적습니다. 사람의 역할은 채점입니다.
README는 선언문이고, Issue는 작업입니다. 좋은 Issue의 기준은 "5분 만에 완료 판정이 되는가"입니다.
둘 곳은 정해져 있습니다. README는 루트, 정한 것은 docs/, 작업은 Issue, 규칙은 CLAUDE.md입니다.

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

Claude Code는 작업 폴더 안의 파일을 읽습니다. 공식 문서 기준으로 세션을 시작할 때 CLAUDE.md를 읽고, 작업 중에는 필요한 파일을 스스로 찾아 읽습니다. 반대로 노션 페이지, 카카오톡 메모, 머릿속 계획은 읽지 못합니다. 그러니 기획이 노션에만 있으면 AI에게는 기획이 없는 것과 같습니다. 매번 복사해서 붙여 넣는 방법도 있지만, 그러면 어제 붙여 넣은 것과 오늘 붙여 넣은 것이 달라지고 대화가 어긋납니다. 생각을 한곳에, AI와 내가 같이 보는 곳에 두는 것이 원칙입니다. 그곳이 GitHub 리포지토리이고, 우리 4주차 교재의 첫 문장 "AI는 정리된 데이터를 먹고, 나는 정리된 폴더에서 일한다"가 같은 뜻입니다.

나는 말한다. AI가 적는다

README 쓰는 법을 몰라도 됩니다. 4편의 네 줄을 주고 쓰게 하면 됩니다. Claude Code를 작업 폴더에서 켜고 이렇게 말합니다.

아래 내용으로 이 프로젝트의 README.md를 써 줘.
[범위] 상담 녹음(m4a) 한 건을 상담일지 하나로 바꾸는 도구.
[목적] 상담 직후 30초 안에 기록을 남기기 위해.
[제약] 고객 실명은 홍OO 형태로 가린다. 무료로 쓸 수 있는 방법으로.
[검증] 실제 녹음 1건을 넣어 참석자, 논의, 결정, 할 일 네 항목이 채워지면 성공.
구성은 "이 도구는 무엇인가 / 누가 언제 쓰는가 / 하지 않는 것 / 완료 기준" 네 절로.
기술 이름은 아직 쓰지 마. 쓴 뒤에 커밋하고 푸시해 줘.

여러분이 한 일은 말한 것뿐입니다. 파일 작성, 커밋, 푸시는 AI가 했습니다. 이 분업이 코스 끝까지 유지됩니다.

README.md, 이 세계의 선언문

README는 사용 설명서가 아니라 선언문입니다. 이 저장소 안에서 무엇이 참이고 무엇이 하지 않는 일인지를 정합니다. AI는 앞으로 이 저장소에서 작업할 때마다 README를 참고하므로, 여기 적힌 "하지 않는 것"이 곧 AI의 경계가 됩니다. 네 절이면 충분합니다.

이 도구는 무엇인가. 4편의 핵심 한 문장.
누가 언제 쓰는가. 3편의 세 질문에 대한 답.
하지 않는 것. 장식 더미에서 미룬 것, 처음부터 범위 밖인 것.
완료 기준. 검증 문장. "실제 녹음 1건으로 네 항목이 채워지면 성공."

기술 이름은 아직 쓰지 않습니다. 7편에서 AI가 고른 뒤 docs/tech-choices.md에 따로 적습니다.

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

README가 "무엇인가"라면 Issue는 "다음에 무엇을 할 것인가"입니다. 큰 그림을 한 번에 넘기면 코드가 무거워지고 확인이 불가능해집니다. 우리 5주차 교재의 원칙 그대로, 기능은 한 번에 만드는 것이 아니라 단계별로 조립합니다. Issue가 그 단계입니다. 이것도 AI에게 쓰게 합니다.

README를 읽고, 이 도구를 완성하기까지의 작업을 5~7개의 Issue로 쪼개 줘.
각 Issue는 제목 한 줄, 완료 조건 한 줄, 확인 방법 한 줄로.
아직 GitHub에 올리지 말고 목록만 먼저 보여 줘. 내가 승인하면 올려.

상담 녹음 변환기라면 대략 이런 목록이 돌아옵니다. 녹음 파일을 읽어 텍스트로 바꾼다, 텍스트에서 실명을 홍OO로 가린다, 네 항목으로 정리한다, 결과를 파일로 저장한다, 실제 녹음 1건으로 끝까지 돌려 본다. 승인하면 AI가 Issue를 올립니다. Claude Code는 터미널 명령을 실행할 수 있으므로 GitHub CLI(gh)가 설치돼 있으면 Issue 생성까지 시킬 수 있고, 없으면 목록을 받아 브라우저에서 직접 붙여 넣어도 됩니다. 참고로 공식 문서에는 Claude Code에서 /install-github-app을 실행해 GitHub 앱을 설치하면 Issue나 PR 댓글에서 @claude로 작업을 시킬 수 있는 방법도 있습니다. 이 코스에서는 터미널 방식으로 충분하지만 저장소가 곧 작업대라는 개념이 같습니다.

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

AI가 써 온 README와 Issue를 읽고 여러분이 할 일은 채점입니다. 기준은 하나입니다. 이 Issue가 끝났는지를 내가 5분 안에 판정할 수 있는가.

"녹음을 텍스트로 바꾼다"는 판정이 어렵습니다. 어떤 녹음으로, 얼마나 정확하면 끝인지 없기 때문입니다.
"샘플 녹음 3분짜리 하나를 넣으면 텍스트 파일이 생기고, 내가 들으며 읽었을 때 뜻이 통한다"는 5분이면 판정됩니다.

판정이 안 되는 Issue는 돌려보냅니다. "이 Issue는 완료를 어떻게 확인하는지가 없어. 확인 방법을 한 줄 더 써 줘." 이 채점이 여러분의 일이고, 이것을 잘하는 사람이 바이브 코딩을 잘하는 사람입니다. 우리 수업의 정지 규칙이 증거인 것과 같은 원리입니다. 증거로 판정할 수 없는 작업은 아직 작업이 아닙니다.

어디에 무엇을 두는가

저장소 안의 자리는 정해 두면 헤매지 않습니다. 우리 4주차 교재의 표준 구조를 이 코스에 맞게 줄이면 이렇습니다.

my-tool/
├─ README.md            ← 선언문 (무엇인가, 누가 언제, 하지 않는 것, 완료 기준)
├─ CLAUDE.md            ← AI와의 약속 (6편)
├─ docs/
│  ├─ tech-choices.md   ← 기술을 고른 이유 (7편)
│  ├─ interface.md      ← 어디서 어떻게 만지는가 (8편)
│  └─ output.md         ← 무엇이 나오는가 (9편)
├─ src/                 ← AI가 만드는 코드 (사람은 열지 않음)
├─ data/                ← 샘플 입력 (실명 없는 것만)
├─ .gitignore           ← 올리면 안 되는 파일 목록 (.env 필수)
└─ .env.example         ← 키 이름만 적은 공유용 예시

작업 목록은 파일이 아니라 GitHub Issue에 둡니다. 파일에 두면 AI와 내가 각자 다른 버전을 보게 됩니다. 사람이 손대는 파일은 README, CLAUDE.md, docs/ 세 종류뿐이며 이것은 7편에서 다시 말합니다. 키값은 절대 저장소에 넣지 않습니다. .env는 내 컴퓨터에만 두고 .gitignore에 반드시 올립니다.

해 보기

2편에서 만든 비공개 저장소에서 Claude Code를 켜고, 위의 README 요청과 Issue 요청을 순서대로 시키십시오. 돌아온 Issue 목록을 "5분 판정" 기준으로 채점해 통과하지 못한 것은 돌려보내고, 통과한 것만 올리게 하십시오. 증거는 브라우저에서 보이는 README 화면과 Issue 목록 화면입니다. 그다음 "지금까지 커밋하고 푸시해 줘"로 마무리합니다.

정리

생각은 AI가 읽는 곳, 즉 저장소에 둡니다.
README는 선언문, Issue는 작업이며 둘 다 AI가 씁니다.
사람의 일은 채점이고 기준은 "5분 만에 완료 판정이 되는가"입니다.
자리는 README 루트, 정한 것 docs/, 작업 Issue, 규칙 CLAUDE.md, 키는 .env(저장소 밖)입니다.

자주 묻는 질문

기획서를 노션이나 메모 앱에 두면 안 되나요?

개인 메모로는 괜찮지만 AI의 작업 근거로는 안 됩니다. Claude Code는 작업 폴더의 파일을 읽지 노션을 읽지 못합니다. 노션에 쓴 것을 저장소로 옮기게 하는 식으로 두 벌을 유지하면 반드시 어긋납니다. 정본은 저장소 하나로 두십시오.

README나 Issue 쓰는 법을 모르는데 괜찮나요?

괜찮습니다. 쓰는 것은 AI입니다. 여러분은 4편의 네 줄을 주고 구성만 지정하면 됩니다. 형식보다 중요한 것은 "하지 않는 것"과 "완료 기준"이 들어 있는가입니다.

AI가 쓴 README에서 무엇을 확인해야 하나요?

세 가지입니다. 핵심 한 문장이 내 말과 같은가, 하지 않는 것이 빠지지 않았는가, 완료 기준이 증거로 판정 가능한가. 이 셋이 맞으면 문장이 어색해도 통과시키고, 틀리면 문장이 매끄러워도 돌려보냅니다.

좋은 Issue인지 어떻게 판단하나요?

"내가 5분 안에 끝났는지 판정할 수 있는가"입니다. 확인 방법이 한 줄로 적혀 있고, 그 방법이 실행 화면이나 파일 같은 증거를 가리키면 좋은 Issue입니다. 판정 방법이 없는 Issue는 아직 작업이 아닙니다.

README와 Issue는 누가 쓰고 누가 판단하나요?

쓰는 것은 AI, 판단하는 것은 사람입니다. 이 분업을 거꾸로 하면(사람이 쓰고 AI가 판단) 시간은 시간대로 들고 AI의 판단은 근거가 약합니다. 사람이 채점자 자리를 지키는 것이 바이브 코딩의 핵심입니다.