claude code - 미니 프로젝트

Об этом предложении

4회차. PRD 스킬과 GitHub MCP로 TodoList 앱 만들기 이번 회차에서는 지금까지 준비한 도구(Claude Code, prd-feature 스킬, GitHub MCP)로 간단한 TodoList 웹앱을 만든다. 목표는 앱 자체보다 팀에서 코드를 관리하는 순서 를 한 번 끝까지 해 보는 것이다. 기획(PRD) → 작업 나누기(Issue) → 규칙 정하기 → [브랜치 → 구현 → 커밋 → PR → 리뷰 → 병합] 반복 모든 Claude Code 요청은 이 문서의 프롬프트를 그대로 복사해 붙여넣으면 된다. 저장소 이름이나 Issue 번호는 Claude가 직접 확인하도록 작성되어 있다. bash 블록은 Git Bash에서, text 블록은 Claude Code 대화창에 입력한다. 각 프롬프트는 "결과를 보여주고 멈춰줘"로 끝난다. 결과를 눈으로 확인한 뒤 다음 프롬프트로 넘어간다. 시간 배분 (30분) 단계 내용 시간 0 사전 준비 확인 3분 1 기획: PRD 작성 5분 2 작업 나누기: Issue 생성 3분 3 팀 규칙 정하기 3분 4 기능 개발 사이클 1회 (Issue 1개) 10분 5 동시 작업과 충돌 해결 4분 6 마무리 2분 시간이 부족하면 4단계까지 수업에서 진행하고, 남은 Issue와 5단계는 과제로 진행한다. 0. 사전 준비 (이전 회차 요약) 이전 회차에서 한 작업이다. 수업 전에 아래 표의 확인 명령이 모두 통과하는지 확인한다. 회차 한 일 확인 명령 1회차 Claude Code 설치, 계정 로그인 claude --version 2회차 prd-feature 스킬 생성 ls .claude/skills/prd-feature/SKILL.md 3회차 연습 저장소 claude-code-practice 생성·클론, GitHub MCP 등록 git remote -v , claude mcp list 이번 회차는 3회차의 claude-code-practice 저장소 폴더에서 이어서 진행한다. 0-1. PAT 권한 추가 3회차에서는 읽기 위주로 토큰을 만들었다. 이번에는 PR 생성·병합까지 하므로 권한을 올린다. GitHub 토큰 설정 → 3회차 토큰 선택 → Edit → Repository permissions를 아래처럼 바꾸고 저장한다. 토큰 값은 바뀌지 않는다. 권한 설정 Contents Read and write Issues Read and write Pull requests Read and write 0-2. 토큰 입력 후 Claude Code 실행 VS Code에서 claude-code-practice 폴더를 열고, Git Bash에서 한 줄씩 실행한다. 첫 줄에서 토큰을 붙여넣고 Enter를 누른다(화면에 표시되지 않음). read -r -s -p "GitHub PAT: " GITHUB_PAT export GITHUB_PAT claude mcp list 목록에 github 가 없으면 3회차 4단계의 claude mcp add ... 명령으로 다시 등록한다. prd-feature 스킬이 이 폴더에 없으면 2회차에서 만든 폴더에서 복사한다: mkdir -p .claude/skills && cp -r <2회차_폴더>/.claude/skills/prd-feature .claude/skills/ claude 0-3. 환경 점검 (Claude Code) 작업 시작 전에 환경을 점검해줘. 1. git remote -v 로 origin 저장소(OWNER/REPO)를 확인하고, 현재 브랜치와 변경 파일이 있는지 알려줘. 2. .claude/skills/prd-feature/SKILL.md 가 있는지 확인해줘. 3. GitHub MCP로 origin 저장소의 기본 브랜치와 열린 Issue, 열린 PR 개수를 조회해줘. 파일은 수정하지 말고, 결과를 표로 보여주고 멈춰줘. 3회차에서 만든 [실습] GitHub MCP 연결 확인 Issue가 열려 있으면 브라우저에서 닫는다. 세 항목이 모두 정상이면 시작한다. MCP 조회가 실패하면 7단계 문제 해결 표를 본다. 현재 브랜치가 main 이 아니거나 모르는 변경 파일이 있으면 먼저 정리한다. 1. 기획: PRD 작성 왜 하나? 무엇을 만들지, 무엇을 만들지 않을지, 어떻게 되면 "완료"인지를 먼저 글로 정한다. 팀원 모두가 같은 기준으로 일하기 위한 문서다. /prd-feature 간단한 TodoList 웹앱의 PRD를 작성해줘. - 기능: 할 일 추가, 할 일 목록 표시, 완료 체크/해제, 삭제, 새로고침해도 목록 유지 - 제외: 로그인, 서버·DB, 마감일, 카테고리, 디자인 프레임워크 - 기술: HTML, CSS, JavaScript만 사용. 빌드 도구 없이 index.html을 브라우저로 열면 실행. 저장은 localStorage - 빈 문자열이나 공백만 있는 할 일은 추가되지 않아야 해 - 완료조건은 "입력 → 기대 결과" 형태로 브라우저에서 직접 확인할 수 있게 써줘 질문이 있으면 한 번에 모아서 물어봐. PRD를 화면에 보여주고 멈춰줘. 파일 저장과 구현은 아직 하지 마. 추가 질문이 오면 직접 답하거나 "나머지는 네가 합리적으로 정해줘"라고 답한다. PRD에서 아래를 확인한다. 범위에 포함/제외 가 분명히 나뉘어 있는가 완료조건이 "잘 동작한다"가 아니라 확인 가능한 문장 인가 (예: "공백만 입력하고 추가 → 목록에 변화 없음") 확인이 끝나면 저장한다. 좋아. 이 PRD를 docs/PRD.md 로 저장해줘. 저장만 하고 멈춰줘. 커밋은 3단계에서 팀 규칙 파일과 함께 한다. 2. 작업 나누기: Issue 생성 왜 하나? 큰 기능을 한 번에 만들면 리뷰도 어렵고 여러 명이 나눠 일할 수 없다. PRD를 한 사람이 하루 안에 끝낼 수 있는 크기 의 Issue로 나눈다. Issue 하나 = 브랜치 하나 = PR 하나가 기본 단위다. docs/PRD.md 를 읽고 구현 작업을 GitHub Issue 3개로 나눠줘. 1) 기본 화면 + 할 일 추가 + 목록 표시 2) 완료 체크/해제 + 삭제 3) localStorage 저장 (새로고침 후 유지) 각 Issue 본문에는 "목적 / 작업 내용 / 완료조건(체크박스)" 을 넣고, 완료조건은 PRD에서 가져와줘. 라벨은 enhancement 를 붙여줘. origin 저장소에 같은 제목의 Issue가 있는지 먼저 확인하고, 생성할 3개의 제목과 본문 초안을 보여주고 멈춰줘. 아직 생성하지 마. 초안을 확인한 뒤 생성한다. 확인했어. GitHub MCP로 3개의 Issue를 생성하고 번호와 URL을 표로 보여줘. 브라우저에서 저장소의 Issues 탭을 열어 3개가 생성되었는지 확인한다. 3. 팀 규칙 정하기 왜 하나? 팀원마다 브랜치 이름, 커밋 메시지 형식이 다르면 기록을 읽을 수 없다. 규칙을 파일로 저장해 두면 사람도 Claude도 같은 규칙을 따른다. 파일 역할 CLAUDE.md Claude Code가 매번 자동으로 읽는 프로젝트 규칙 .github/pull_request_template.md PR을 만들 때 자동으로 채워지는 본문 양식 .gitignore 커밋하면 안 되는 개인 설정 파일 제외 팀 협업 규칙 파일을 만들어줘. 1. CLAUDE.md - 프로젝트: TodoList 웹앱 (HTML/CSS/JS, localStorage). 요구사항은 docs/PRD.md 를 따른다. - 브랜치: main 에 직접 커밋하지 않는다. 작업 브랜치는 최신 main 에서 만들고 이름은 <타입>/<이슈번호>-<짧은-영문-설명> (예: feat/1-add-todo) - 커밋 메시지: <타입>: <한글 요약> (#이슈번호) 예) feat: 할 일 추가 기능 구현 (#1) - 타입: feat(기능), fix(버그), docs(문서), refactor(구조 개선), chore(설정) - 하나의 브랜치에서는 하나의 Issue만 작업한다. Issue 범위 밖의 파일은 수정하지 않는다. - PR 본문에는 "Closes #이슈번호" 를 넣는다. 강제 푸시(force push)는 하지 않는다. 2. .github/pull_request_template.md : 관련 Issue(Closes #), 변경 내용, 확인 방법, 완료조건 체크리스트 섹션 3. .gitignore : .claude/settings.local.json 파일 내용을 보여주고 멈춰줘. 확인한 뒤 커밋·푸시한다. 초기 설정은 코드가 아니므로 이번 한 번만 main 에 직접 올린다. 좋아. docs/PRD.md, CLAUDE.md, .github/pull_request_template.md, .gitignore, .claude/skills/prd-feature 를 커밋해줘. 메시지는 "chore: 프로젝트 기획 문서와 협업 규칙 추가" 로 하고 origin main 에 푸시해줘. 결과를 보여주고 멈춰줘. 스킬 폴더( .claude/skills )를 함께 커밋하면 저장소를 클론한 팀원도 같은 /prd-feature 스킬을 쓸 수 있다. 처음 푸시할 때 브라우저 로그인 창이 뜨면 GitHub 계정으로 인증한다. git push 인증은 MCP 토큰과 별개다. 4. 기능 개발 사이클 (첫 번째 Issue) 이 단계가 이번 회차의 핵심이다. 모든 기능은 아래 6단계를 반복한다. 1 브랜치 생성 → 2 구현 → 3 직접 확인 → 4 커밋·푸시 → 5 PR 생성·리뷰 → 6 병합·정리 1 브랜치 생성 왜? main 은 항상 동작하는 상태로 유지한다. 새 작업은 별도 브랜치에서 하고, 검토가 끝난 뒤에만 main 에 합친다. enhancement 라벨이 붙은 열린 Issue 중 번호가 가장 작은 Issue를 작업할 거야. main 으로 전환해서 origin 의 최신 내용을 pull 받은 뒤, CLAUDE.md 규칙에 맞는 이름으로 작업 브랜치를 만들고 전환해줘. Issue 번호·제목과 만든 브랜치 이름을 보여주고 멈춰줘. Git Bash에서 직접 확인한다. git branch --show-current 2 구현 현재 브랜치의 Issue 내용과 docs/PRD.md 를 기준으로 구현해줘. 이 Issue 범위만 작업하고, 다른 Issue의 기능은 미리 만들지 마. 끝나면 변경한 파일 목록과, 브라우저에서 확인할 방법을 완료조건별로 알려주고 멈춰줘. 커밋은 아직 하지 마. 3 직접 확인 탐색기에서 index.html 을 더블클릭해 브라우저로 연다. Claude가 알려준 확인 방법대로 완료조건을 하나씩 직접 해 본다. 문제가 있으면 본 그대로 전달한다. 브라우저에서 확인해보니 [본 현상]이 발생해. 원인을 설명하고 수정해줘. 수정 후 다시 확인 방법을 알려주고 멈춰줘. 변경 내용도 확인한다. git status --short git diff 4 커밋·푸시 왜? 커밋은 "의미 있는 한 단위의 변경"을 기록하는 것이다. 메시지만 읽어도 무엇을 왜 바꿨는지 알 수 있어야 한다. 이번 Issue와 관련된 파일만 스테이징하고, CLAUDE.md 규칙에 맞는 커밋 메시지를 제안해줘. 커밋할 파일 목록과 메시지를 보여주고 멈춰줘. 좋아. 그 메시지로 커밋하고 현재 브랜치를 origin 에 푸시해줘. 결과를 보여주고 멈춰줘. 5 PR 생성과 리뷰 왜? PR(Pull Request)은 "내 브랜치를 main에 합쳐도 되는지 검토해 달라"는 요청이다. 팀에서는 다른 사람이 코드를 읽고 승인한 뒤에만 병합한다. GitHub MCP로 현재 브랜치 → main PR을 만들어줘. .github/pull_request_template.md 양식을 따르고, 본문에 "Closes #이슈번호", 변경 내용, 확인 방법, 완료조건 체크리스트(내가 3에서 확인한 항목은 체크)를 넣어줘. 같은 브랜치의 열린 PR이 이미 있으면 새로 만들지 말고 알려줘. PR 번호와 URL을 보여주고 멈춰줘. 리뷰어 역할로 Claude에게 코드 리뷰를 맡긴다. 팀에서는 이 역할을 동료가 한다. 방금 만든 PR을 리뷰어 입장에서 검토해줘. PRD 완료조건 충족 여부, 버그 가능성, 이 Issue 범위를 벗어난 변경이 있는지 확인하고, 결과를 GitHub MCP로 PR에 코멘트로 남겨줘. 코드는 수정하지 마. 브라우저에서 PR을 열어 Files changed 탭(변경 내용)과 Conversation 탭(리뷰 코멘트)을 확인한다. 리뷰에서 고칠 점이 나오면 2~4를 같은 브랜치에서 반복한다. 같은 브랜치에 푸시하면 PR에 자동으로 추가된다. 새 PR을 만들지 않는다. 6 병합과 정리 PR의 리뷰 코멘트 중 해결되지 않은 것이 있는지 확인해줘. 없으면 GitHub MCP로 PR을 merge 방식으로 병합해줘. 병합 후 관련 Issue가 자동으로 닫혔는지 확인하고, 로컬에서 main 으로 전환해 최신 내용을 pull 받은 다음, 병합된 작업 브랜치를 로컬과 origin 에서 삭제해줘. 결과를 보여주고 멈춰줘. 브라우저에서 확인한다. PR 상태가 Merged 인가 Issue가 Closed 이고, PR과 연결되어 있는가 main 의 Commits 기록에 방금 커밋이 있는가 첫 번째 Issue 완료. 남은 Issue도 1~6 프롬프트를 그대로 다시 붙여넣어 진행한다. 1의 프롬프트가 enhancement 라벨이 붙은 열린 Issue 중 가장 작은 번호를 자동으로 고른다. 5. 동시 작업과 충돌 해결 (팀 작업 연습) 실제 팀에서는 여러 명이 같은 시간에 서로 다른 브랜치에서 작업한다. 먼저 병합된 변경이 있으면 나중 사람은 최신 main을 자기 브랜치에 반영 해야 한다. 혼자서 두 명의 역할을 하며 연습한다. 첫 번째 Issue를 마치고 남은 Issue가 2개일 때 진행한다. 아래에서는 번호가 작은 Issue를 A (완료·삭제), 큰 Issue를 B (localStorage 저장)라고 부른다. 팀원 두 명이 동시에 작업하는 상황을 연습할 거야. enhancement 라벨이 붙은 열린 Issue 2개 중 번호가 작은 것을 A, 큰 것을 B라고 부를게. 1. 최신 main 에서 A 브랜치와 B 브랜치를 각각 만들어줘. 2. A 브랜치에서 A를 구현·커밋·푸시하고 PR을 만들어줘. 3. B 브랜치로 전환해서 B를 구현·커밋·푸시하고 PR을 만들어줘. B 브랜치에는 A의 변경이 없는 상태여야 해. 브랜치 이름과 커밋 메시지는 CLAUDE.md 규칙을 따르고, 각 단계의 결과와 A, B의 Issue 번호·PR URL을 보여주고 멈춰줘. 병합은 하지 마. 두 PR을 브라우저에서 확인한 뒤 A를 먼저 병합한다. A의 PR을 merge 방식으로 병합해줘. 그 다음 B의 PR이 main 과 충돌이 있는지 확인해서 알려주고 멈춰줘. B 브랜치에 최신 main을 반영한다. 팀에서는 B 담당자가 하는 일이다. B 브랜치로 전환해서 origin/main 의 최신 내용을 merge 해줘. 충돌이 나면 바로 해결하지 말고, 충돌한 파일과 양쪽 변경 내용을 비교해서 설명한 뒤, 두 기능이 모두 살아있는 해결안을 보여주고 멈춰줘. 해결안을 확인한 뒤 진행한다. 좋아. 그 해결안으로 충돌을 해결해서 커밋하고 B 브랜치를 푸시해줘. 강제 푸시는 하지 마. 브라우저에서 확인할 방법(A, B 기능 모두)을 알려주고 멈춰줘. 브라우저에서 추가·완료·삭제·새로고침 후 유지를 모두 확인한 뒤, 4단계 5의 리뷰 프롬프트와 6의 병합 프롬프트로 마무리한다. 기억할 것 충돌은 오류가 아니다. 같은 파일의 같은 부분을 두 사람이 고쳤다는 뜻이다. 양쪽 내용을 이해하고 합친다. 충돌을 줄이는 방법: 작업 시작 전에 main을 pull, 브랜치는 짧게 유지, PR은 작게 자주 올리기. 6. 마무리 결과 확인 docs/PRD.md , CLAUDE.md , .github/pull_request_template.md 가 main 에 있다. 이번 회차 Issue 3개가 모두 Closed이고 각각 PR과 연결되어 있다. 모든 PR이 Merged 상태이고, 본문에 Closes #번호 와 완료조건 체크리스트가 있다. main 의 커밋 메시지가 <타입>: <요약> (#번호) 형식이다. main 의 index.html 을 열면 추가·완료·삭제·새로고침 후 유지가 모두 동작한다. 이번 회차 핵심 정리 도구 역할 규칙 PRD 무엇을·어디까지·언제 완료인지 완료조건은 확인 가능한 문장으로 Issue 작업 단위 한 사람이 하루 안에 끝낼 크기 Branch 작업 공간 main에서 직접 작업하지 않는다, 최신 main에서 시작 Commit 변경 기록 한 커밋 = 한 가지 의미, 규칙에 맞는 메시지 PR 검토 요청 Closes #번호 , 확인 방법 기록, 리뷰 후 병합 Merge main에 반영 병합 후 main pull, 작업 브랜치 삭제 정리 unset GITHUB_PAT 실습이 끝난 토큰은 GitHub 토큰 설정 에서 삭제하거나 유효기간을 확인한다. 7. 문제 해결 증상 확인 순서 /prd-feature 가 안 보임 ls .claude/skills/prd-feature/SKILL.md → 저장소 최상위 폴더에서 claude 를 실행했는지 → Claude Code 재시작 MCP 조회·생성 실패 같은 Git Bash에서 토큰을 입력했는지 → claude mcp list → 토큰 만료 → 0-1의 권한 설정 → Repository access에 저장소 포함 git push 인증 실패 MCP 토큰과 별개다. Git Bash에서 git push 를 직접 실행해 브라우저 로그인 PR 생성 실패 브랜치를 푸시했는지 → main과 차이가 있는 커밋이 있는지 → Pull requests 권한 병합 후 Issue가 안 닫힘 PR 본문에 Closes #번호 가 있는지 → PR이 기본 브랜치(main)로 병합되었는지 실수로 main에서 작업함 커밋 전이라면 아래 프롬프트 사용 Claude가 멈추지 않고 다음 단계까지 진행함 Esc로 중단 → 프롬프트 끝에 "결과를 보여주고 멈춰줘"를 붙여 다시 요청 main에서 작업한 변경을 브랜치로 옮기기: main 브랜치에서 실수로 작업했어. 커밋하지 않은 변경을 그대로 유지한 채, enhancement 라벨이 붙은 열린 Issue 중 번호가 가장 작은 Issue의 작업 브랜치를 만들어 전환해줘. 변경 파일 목록을 보여주고 멈춰줘. 해결되지 않으면 실행한 명령과 오류 메시지를 정리해 질문한다. 토큰 값은 공유하지 않는다. 자주 쓰는 명령 명령 위치 용도 git status --short Git Bash 변경 파일 확인 git diff Git Bash 커밋 전 변경 내용 확인 git branch --show-current Git Bash 현재 브랜치 확인 git log --oneline -10 Git Bash 최근 커밋 기록 확인 /mcp Claude Code GitHub MCP 연결 상태 확인 /exit Claude Code 종료 공식 참고: Skills , Claude Code MCP , GitHub MCP 서버 , Issue와 PR 연결 , 병합 충돌 해결