-
Notifications
You must be signed in to change notification settings - Fork 0
Agent 개발 워크플로우
양해울 edited this page Jun 15, 2026
·
14 revisions
Claude Code를 활용하여 나무런을 개발하는 과정에서의 AI 협업 패턴을 정리합니다.
이 문서는 실제 개발을 진행하면서 지속적으로 업데이트됩니다.
-
기능 단위로 브랜치와 이슈를 나눔 (
feature/game-timer,feature/article-renderer등) - 한 PR에는 하나의 기능만 포함 (리뷰 가능한 크기 유지)
- 컴포넌트가 3개 이상 생기는 기능은 추가로 세분화
| 작업 단위 | 설명 |
|---|---|
feature/data-pipeline |
Python 전처리 스크립트 (1회성) |
feature/article-renderer |
R2 fetch + namumark 렌더링 |
feature/game-core |
타이머, 클릭 카운트, 도착 판정 |
feature/leaderboard |
결과 저장 + 리더보드 UI |
feature/daily-prompt |
일일 문제 조회 + 메인 화면 |
두 가지 워크플로우를 상황에 맞게 선택한다.
1. /create-issue → 이슈 초안 작성 + 질문으로 구체화 + 생성
↓
2. /plan-sprint → 이슈 선택 + 작업 계획 수립 + 이슈 코멘트 추가
↓
3. feature 브랜치 생성 (plan-sprint가 명령어 안내)
→ Docs 업데이트 항목이 있으면 첫 커밋으로 docs 먼저 수정
↓
4. /implement → 구현 스펙 확인 후 커밋 단위별 구현 + lint/build 검증
↓
5. /commit-msg → 커밋 메시지 생성 후 직접 커밋
↓
6. /docs-sync → 코드와 docs 불일치 확인 및 수정 → docs: 커밋
↓
7. /create-pr → docs: 커밋 확인 후 PR 본문 생성 + 사용자 승인 후 PR 생성
↓
8. Squash and merge (feature → dev)
중단 복구: 구현 중 대화가 끊기거나 세션이 바뀐 경우
/status로 현재 파이프라인 위치를 즉시 확인할 수 있다.
이슈가 완전히 구체화되어 있을 때 사용한다. 이슈를 미리 작성해두고 /auto-develop-all 한 번으로 전체를 무인 처리한다.
1. /create-issue → 이슈 초안 + 모호한 항목 전부 질문 → 완전히 구체화 후 생성
(여러 이슈를 미리 작성해 둔다)
↓
2. /auto-develop-all
↓ ┌──────────────────────────────────────────────────────────────┐
│ 이슈 목록 fetch → 의존관계 파싱 → 위상 정렬 │
│ 이슈마다 순서대로: │
│ Phase 1: auto-plan 이슈 검증 → 작업 계획 → 브랜치 생성 │
│ Phase 2: auto-implement 구현 → lint/build → 커밋 (자동) │
│ Phase 3: auto-sync 코드↔docs 불일치 수정 → 커밋 (자동) │
│ Phase 4: auto-pr push → PR 생성 (자동) │
│ Phase 5: git checkout dev && pull (항상 실행) │
│ /compact (컨텍스트 압축) │
└──────────────────────────────────────────────────────────────┘
↓
3. PR 목록 리뷰 후 머지 ← 사람이 처리
단일 이슈 실행:
/auto-develop <N>으로 특정 이슈 하나만 처리할 수 있다.
중단 시 재개: 이슈에 🤖 stop comment가 자동 게시된다. 수정 후/auto-develop <N>재실행 시 완료된 단계는 건너뛴다.
.claude/commands/에 저장된 프로젝트 전용 slash command 목록.
| Skill | 명령어 | 설명 |
|---|---|---|
| create-issue | /create-issue <설명> |
이슈 초안 자동 작성 + 모호한 부분 질문으로 구체화 후 생성 |
| commit-msg | /commit-msg |
변경 파일 목록 보여준 뒤 staged 변경사항 분석 후 CLAUDE.md 컨벤션에 맞는 커밋 메시지 제안 |
| plan-sprint | /plan-sprint |
열린 이슈 목록 조회 후 사용자가 선택한 이슈의 검토 및 작업 계획 수립 |
| implement | /implement <이슈번호> |
이슈 코멘트의 작업 계획을 읽어 커밋 단위별로 구현 진행. lint/build 품질 게이트 포함 |
| create-pr | /create-pr <이슈번호> |
docs-sync 확인 후 현재 브랜치를 push하고 이슈/작업계획 기반으로 PR 본문 생성. 사용자 승인 시 PR 생성 |
| docs-sync | /docs-sync |
구현 결과와 docs 불일치를 찾아 수정. implement 완료 후 또는 설계 변경 시 언제든 독립 실행 가능 |
| status | /status |
현재 파이프라인 진행 상태 확인 및 다음 단계 안내. 대화가 끊긴 후 맥락 복구용 |
| Skill | 명령어 | 설명 |
|---|---|---|
| auto-develop-all | /auto-develop-all [label] |
배치 래퍼. 열린 이슈 전체(또는 label 필터)를 의존관계 순서대로 자동 처리 |
| auto-develop | /auto-develop <이슈번호> |
오케스트레이터. plan → implement → sync → pr 전 단계를 무승인으로 순차 실행 |
| auto-plan | /auto-plan <이슈번호> |
이슈 검증 + 작업 계획 이슈 코멘트 게시 + feature 브랜치 자동 생성 |
| auto-implement | /auto-implement <이슈번호> |
작업 계획 기반 커밋 단위별 구현 + lint/build 검증 + 커밋까지 자동 |
| auto-sync | /auto-sync [이슈번호] |
코드와 docs 불일치를 찾아 자동 수정 후 docs: 커밋 |
| auto-pr | /auto-pr <이슈번호> |
push + PR 자동 생성 (auto-sync 미실행 시 선행 실행 후 진행) |
/create-issue가 생성하는 이슈 본문은 자동화 파이프라인이 파싱하므로 형식이 정확해야 한다.
| 타입 | 필드 |
|---|---|
feat |
배경 / 구현 범위 / 완료 기준 / 탐색 시작점 |
fix |
증상 / 재현 조건 / 관련 코드 / 완료 기준 / 탐색 시작점 |
refactor |
현재 상태 / 목표 상태 / 변경 범위 / 완료 기준 / 탐색 시작점 |
chore |
배경 / 변경 범위 / 완료 기준 / 탐색 시작점 |
test |
테스트 대상 / 테스트 케이스 / 변경 범위 / 완료 기준 / 탐색 시작점 |
모든 필드는 **필드명:** (마크다운 볼드) 형식으로 작성한다. 파이프라인이 이 형식으로 파싱한다.
| 필드 | 파싱 주체 | 규칙 |
|---|---|---|
**완료 기준:** |
auto-plan |
- [ ] 체크리스트 형식만 허용. 모호한 표현("잘", "충분히") 금지 |
**탐색 시작점:** |
auto-plan, auto-develop |
src/... 실제 파일 경로만 허용. 컴포넌트명 단독 사용 금지 |
**의존 이슈:** #N |
auto-plan, auto-develop-all | 코드 의존이 있을 때만 작성. 단순 관련은 해당 없음 |
이 이슈를 구현하려면 다른 이슈의 코드가 먼저 존재해야 할 때 선언한다.
**의존 이슈:** #3
복수 의존:
**의존 이슈:** #3, #7
이 필드가 있으면 /auto-develop-all이 의존 이슈를 먼저 처리하고, 브랜치도 의존 이슈의 feature 브랜치 위에서 생성한다.
의존 이슈가 있으면 feature-on-feature 브랜치를 사용한다.
dev
└─ feature/3-base-util PR → dev
└─ feature/5-use-util PR → feature/3-base-util
#3 PR이 dev에 머지되면 GitHub이 #5 PR의 base를 자동으로 dev로 변경한다.
배치 시작 전 모든 이슈의 **의존 이슈:** 필드를 파싱해 방향 그래프를 구성하고 위상 정렬한다.
처리할 이슈 4개 (의존관계 반영 순서):
1. #1 "기반 유틸 추가" (의존 없음)
2. #3 "설정 파일 정리" (의존 없음)
3. #5 "유틸 사용 기능" (depends on #1)
4. #7 "통합 기능" (depends on #1, #3)
순환 의존이 감지되면 배치 시작 전에 중단하고 이슈 수정을 요청한다.
| 기호 | 의미 | 후속 조치 |
|---|---|---|
| ✓ | 완료 — PR 생성됨 | 리뷰 후 머지 |
| ⏭ | 건너뜀 — 파일 충돌 또는 의존 이슈 미완료 | 충돌 PR 머지 후 /auto-develop <N> 재실행 |
| ✗ | 중단 — 수동 확인 필요 | 원인 해결 후 /auto-develop <N> 재실행 |
파일 충돌 체크 시 의존 PR은 제외한다 — 의도적으로 겹치는 관계이기 때문이다.
- 자유형 설명에서 이슈 타입(
feat/fix/refactor/chore/test) 자동 판단 - 코드베이스를 직접 검색해 탐색 시작점 파일 경로를 채움 (사용자에게 묻지 않음)
- 타입별 고정 마크다운 템플릿으로 초안 작성
- 모호하거나 구체성이 부족한 항목을 전부 질문 (제한 없음)
- 최종 이슈 생성 전 형식 자동 검증 — 완료 기준 체크리스트 형식, 탐색 시작점 파일 경로 형식, 의존 이슈 형식
- 승인 시
gh issue create로 생성
/create-issue는 자동화 워크플로우의 입구다. 이슈가 모호하면auto-implement가 잘못된 방향으로 구현한다. 질문에 충분히 답변하는 것이 중요하다.
- 열린 이슈 전체 fetch (label 인자 있으면 필터)
- 각 이슈 body에서
**의존 이슈:**파싱 → 방향 그래프 구성 - 순환 의존 감지 시 중단
- 위상 정렬 후 실행 순서 확정 및 출력
- 각 이슈마다
/auto-develop실행 - 이슈마다
/compact실행 (컨텍스트 압축) - 완료 후 전체 요약 출력 (✓/⏭/✗ 집계)
각 phase는 완료 상태를 자체 감지해 이미 완료된 단계를 건너뛴다 (재개 지원).
-
Pre-flight:
git pull+ open PR 파일 충돌 체크 (의존 PR 제외) -
Phase 1 — auto-plan: 이슈 검증 → 작업 계획 코멘트 → 브랜치 생성
- 의존 이슈 있으면 의존 PR 브랜치에서 분기 (
git fetch후git checkout) - 작업 계획에
브랜치: feature/xxx (base: <BASE>)형식으로 base 기록
- 의존 이슈 있으면 의존 PR 브랜치에서 분기 (
- Phase 2 — auto-implement: 커밋 단위별 구현 + lint/build + 커밋
-
Phase 3 — auto-sync: 코드↔docs 비교 → 불일치 자동 수정 →
docs:커밋 -
Phase 4 — auto-pr: push → PR 생성 (
--base동적 결정) -
Phase 5 — Cleanup:
git checkout dev && git pull— 어느 phase에서 멈춰도 항상 실행
재개 시: 작업 계획 코멘트가 이미 있으면 auto-plan은 기존 브랜치를 checkout하고 스킵.
lint/build 실패 또는 스펙 불명확 시 이슈에 🤖 stop comment를 게시하고 중단. 수정 후 /auto-develop <N> 재실행으로 해당 단계부터 재개.
-
git status로 변경 파일 전체 확인 후 사용자에게 표시 (staged 여부 포함) - 별도 지시 없으면
git add .자동 실행 -
git diff --staged로 변경사항 분석 -
git log --oneline -3으로 최근 커밋 스타일 참고 - 커밋 메시지 출력 — 커밋은 사용자가 직접 실행
-
gh issue list로 열린 이슈 전체 조회 - 의존관계 파악 후 추천 이슈와 함께 목록 출력
- 사용자가 이슈 번호 선택
- 관련 docs와 코드 읽어 컨텍스트 파악 후 작업 계획 수립
- 사용자 승인 시
gh issue comment로 이슈에 추가
- 작업 계획 코멘트 읽기
- TodoWrite로 커밋 단위 체크리스트 생성
- 단위별 구현 +
npm run lint+npm run build - 완료 보고 + Todo 항목 완료 처리
git push -u origin <브랜치명>- docs-sync 확인 —
docs:커밋 없으면/docs-sync먼저 실행 안내 - PR 본문 생성 후 사용자 승인 시
gh pr create --base dev
-
git diff <BASE>...HEAD로 변경 파일 확인 (BASE는 작업 계획에서 추출) - 관련 docs와 비교 → 불일치 자동 수정 →
docs:커밋
- 현재 브랜치, git status, git log 확인
- 브랜치명으로 이슈 유추 → 작업 계획 코멘트 읽기
- 각 단계 완료 여부 판단 후 현재 위치와 다음 단계 안내
.github/ISSUE_TEMPLATE/에 저장된 YAML form 기반 템플릿.
| 템플릿 | 라벨 | 필드 |
|---|---|---|
| feat.yml | feat | 배경, 구현 범위, 완료 기준, 탐색 시작점 |
| fix.yml | fix | 증상, 재현 조건, 관련 코드, 완료 기준, 탐색 시작점 |
| refactor.yml | refactor | 현재 상태, 목표 상태, 변경 범위, 완료 기준, 탐색 시작점 |
| chore.yml | chore | 배경, 변경 범위, 완료 기준, 탐색 시작점 |
| test.yml | test | 테스트 대상, 테스트 케이스, 변경 범위, 완료 기준, 탐색 시작점 |
직접 템플릿을 채우기 어려우면
/create-issue를 사용한다. 탐색 시작점은 Claude가 코드베이스를 직접 검색해서 채운다.
| 문서 | 독자 | 역할 |
|---|---|---|
CLAUDE.md |
Claude Code | 핵심 컨텍스트 + docs/ 포인터 |
docs/ |
Claude Code | 상세 기술 스펙 |
| Mintlify | 사람 | docs/ 렌더링 사이트 (namurun.mintlify.app) |
README.md |
외부 사람 | 프로젝트 소개 |
| GitHub Wiki | 사람 | 기획 과정, 회고록, 의사결정 배경 |
| 레이어 | 도구 | 시점 |
|---|---|---|
| 작성 기준 | plan-sprint | 브랜치 생성 전 |
| 구현 중 | implement | 커밋 단위마다 |
| 구현 후 | /docs-sync | 커밋 전 |
| 머지 후 | Mintlify Agent | 자동 |
[증상] / [재현 조건] / [관련 코드] / [예상 원인](선택)
[현재 상태] / [목표 상태] / [범위]
"X를 구현할 때 A vs B 트레이드오프를 2-3문장으로 정리해줘."
| 체크포인트 | 이유 |
|---|---|
| namumark 렌더링 결과 | 엣지케이스 많음, 눈으로 확인 필수 |
| 리다이렉트 체인 동작 | 실제 데이터로 테스트 |
| 게임 타이머 정확도 | 백그라운드 탭 전환 시 동작 확인 |
| 리더보드 순위 정렬 | 동점 처리 확인 |
| 모바일 레이아웃 | 터치 편의성 |
- 보일러플레이트 컴포넌트 구조 생성
- Tailwind 클래스 조합
- 타입 정의 초안
- 유틸 함수
| 날짜 | 내용 |
|---|---|
| 2026-05-30 | 초안 작성 |
| 2026-05-30 | 문서 구조 및 관리 전략 섹션 추가 |
| 2026-05-31 | 커스텀 Skill 목록 섹션 추가 (/commit-msg, /plan-sprint) |
| 2026-05-31 | /implement, /create-pr skill 추가 및 개발 사이클 skill 기반으로 업데이트 |
| 2026-06-07 | /docs-sync, /status skill 추가 |
| 2026-06-07 | implement: TodoWrite 체크리스트 + 구현 스펙 확인 단계 추가 |
| 2026-06-07 | plan-sprint: Docs 업데이트 섹션 추가 |
| 2026-06-07 | create-pr: PR 전 docs-sync 확인 단계 추가 |
| 2026-06-07 | docs 관리 전략: docs-as-spec 원칙 + Mintlify 연동 반영 |
| 2026-06-14 | 자동화 파이프라인 추가 — auto-develop/plan/implement/sync/pr skill 5종 |
| 2026-06-14 | create-issue skill 추가 — 이슈 초안 자동 작성 + 질문으로 구체화 |
| 2026-06-14 | GitHub 이슈 템플릿 5종 추가 (feat/fix/refactor/chore/test) |
| 2026-06-14 | 개발 사이클을 수동(3-A)과 자동화(3-B) 두 경로로 분리 |
| 2026-06-16 | auto-develop-all 추가 — 전체 이슈 배치 처리, 의존관계 위상 정렬, 순환 감지 |
| 2026-06-16 | 이슈 간 의존관계 처리 — feature-on-feature 브랜치, PR base 동적 결정 |
| 2026-06-16 | 파일 충돌 처리 개선 — 전체 중단 대신 해당 이슈 SKIP 후 배치 계속 진행 |
| 2026-06-16 | Phase 5 추가 — 어느 phase에서 멈춰도 항상 git checkout dev 실행 |
| 2026-06-16 | create-issue 이슈 형식 강화 — 타입별 고정 템플릿, 생성 전 형식 검증 |
| 2026-06-16 | /compact 이슈마다 실행 — 50개 배치에서 컨텍스트 누적 방지 |
| 2026-06-16 | docs/agent-workflow.md 추가 — Mintlify에서도 동일 내용 확인 가능 |