-
Notifications
You must be signed in to change notification settings - Fork 0
개발 워크플로우
trz-21 edited this page Jun 13, 2026
·
2 revisions
GitHub Wiki에 올릴 문서. 내가 Claude Code(서브에이전트 포함)와 협업해서 이 프로젝트를 개발할 때 따르는 흐름. 기반 스킬:
/task-with-harness주요 포인트: 지속 가능한 코드퀄리티 유지, 최대한 사람이 직접 확인 필요한 부분을 배제, 과거 작업 기록을 선택적으로 활용할 수 있도록 문서 작성 엄밀하게
📌 문서화 정책 (현행): 작업 플랜은 GitHub Issue, 작업 로그는 PR 본문(
Closes #N), 스펙 현황은 이 Wiki 에 둔다. 과거 로컬 모델(docs/plans/,docs/works/,specification/)은 이 모델로 대체됐다. 레포 내 규칙:.claude/github-workflow.md.
[사용자: 이슈 등록 (gh issue create)]
↓
[Phase 1] 컨텍스트 로드 ← 메인 Claude (이슈 + Wiki + 코드)
↓
[Phase 2] 구현 계획 수립 ← 메인 Claude → GitHub Issue 본문/체크리스트
↓ (사용자 컨펌)
[Phase 3] 실행 ← feature/issue-<N> 브랜치에서 서브에이전트 병렬 호출
↓
[Phase 4] 검증 ← 메인 Claude (필수)
↓
[Phase 5] 커밋 + PR (Closes #N) ← 메인 Claude, PR 본문이 작업 로그
↓
[사용자: PR 리뷰 → 머지 → 이슈 자동 close]
↓
[Phase 6] Wiki 갱신 ← 스펙 변경분을 해당 Wiki 페이지에 반영
핵심 원칙:
- 서브에이전트에는 훅이 적용되지 않는다 → 메인 Claude 가 검증을 책임진다
- 계획·검증·커밋은 메인 Claude, 구현은 서브에이전트, 스코프·승인·머지는 사용자
- BE / FE / 문서가 한 기능을 위한 변경이면 한 커밋, 한 PR
- 작업 플랜 = Issue, 작업 로그 = PR 본문, 스펙 현황 = Wiki
한 GitHub Issue = 한 vertical slice (사용자가 보기에 동작하는 단위)
GitHub Issue로 묶는 단위. 사용자 시나리오 하나가 끝나는 지점까지.
| 예시 | 포함 범위 |
|---|---|
| "인증 기능" | BE (User 모델 + register/login + JWT 미들웨어) + FE (auth store + 로그인/회원가입 페이지) + 통합 테스트 |
| "분석 흐름 골격(Stub)" | BE (포트 정의 + Stub 어댑터 + AnalysisService + API) + FE (입력 폼 + 폴링 + 결과 페이지) |
| "쿠팡 크롤러 실제 구현" | BE만 (포트 시그니처 그대로, Stub → 실제 어댑터 교체) |
기준:
- 사용자가 "이게 됐다/안 됐다"고 말할 수 있는가 → Yes면 기능 단위
- 종단(end-to-end) 테스트가 가능한가 → Yes면 기능 단위
- 한 issue가 4~8시간 안에 끝날 만한 규모인가 → 적절한 크기
기능 단위 내부에서 병렬 가능한 작업을 쪼개는 단위. TaskCreate로 등록.
| 영역 | 예시 sub-task |
|---|---|
| BE | "User 도메인 모델 + UserRepository 포트 정의" |
| BE | "Postgres UserRepository 어댑터 구현" |
| BE | "register/login 핸들러 + AuthService" |
| FE | "API 클라이언트(토큰 주입)" |
| FE | "Zustand auth store" |
| FE | "로그인 페이지" |
| 문서 | "API 스펙 register/login 업데이트" |
병렬 vs 직렬 판단:
- 같은 파일을 건드리지 않는다 → 병렬 가능
- 한쪽이 다른 쪽의 산출물(타입, 시그니처)을 필요로 한다 → 직렬 (
blockedBy)
예시:
- "Zustand auth store" 와 "로그인 페이지 UI 뼈대" → 병렬
- "FE API 함수" 는 "BE 핸들러 + 스키마 확정" 후에 → 직렬
구현 시작 전, "이 로직이 나중에 다른 구현으로 교체될 여지가 있는가?" 를 먼저 본다.
| 케이스 | trait? |
|---|---|
| 외부 API 어댑터 (Coupang, Naver, Claude) | ✅ 필수 |
| Repository (DB 추상화) | ✅ 필수 |
| 테스트에서 mock으로 교체할 것 | ✅ |
| 현재도 미래에도 구현이 하나뿐 | ❌ 그냥 구현체 |
trait를 추가하면 동시에:
- 결정론적 동작을 검증할 픽스처/단위 테스트 추가
-
.claude/dod.md에 테스트 조건 명시
서브에이전트에게 일을 시킬 때 어떤 맥락을 주고 어떤 형태로 요청할지의 템플릿.
| 파일 | 역할 | 언제 필요 |
|---|---|---|
CLAUDE.md |
프로젝트 전체 맥락 | 항상 |
.claude/dod.md |
작업 완료 기준 | 항상 |
.claude/code-rules.md |
코드 수정 규칙 | 코드 변경 시 |
.claude/commit-rules.md |
커밋 규칙 | 커밋 단계 |
Wiki: Backend/API/Frontend 등 |
기술 스펙 (현황) | 해당 영역 작업 시 |
Wiki: Harness
|
테스트 안전망 | 테스트 추가 시 |
| 관련 GitHub Issue / 최근 PR | 최근 작업 맥락 | 항상 |
## 프로젝트 루트
/Users/.../coupang-review-ai
## 작업 내용
[무엇을 추가/수정할지 구체적으로]
- 대상 파일: <절대 경로>
- 함수/모듈명: <명시>
- 입출력 시그니처: <명시>
## 참고 스펙 (Wiki — 최종 현황)
- Wiki: Backend (Hexagonal 구조)
- Wiki: API (해당 엔드포인트 스키마)
## 완료 조건
- [ ] 파일 수정 전 반드시 현재 내용 읽기
- [ ] BE 수정: cargo check 통과
- [ ] BE 수정: cargo test 통과 (#[cfg(test)] 블록 포함)
- [ ] FE 수정: npm run type-check 통과
- [ ] FE 수정: npm test -- --run 통과
- [ ] FE API 함수 추가 시: types.ts에 {Action}Request/{Action}Response 정의
- [ ] 인라인 타입(`Promise<{ field: T }>`) 금지
## 주의
훅이 적용되지 않으므로 위 조건을 직접 확인하고 완료해야 한다.| 패턴 | 추가로 전달할 맥락 |
|---|---|
| 신규 기능 (BE) | 도메인 모델, 포트 trait 시그니처, AppState 등록 방법 |
| 신규 기능 (FE) | API 스키마, 디자인 가이드(shadcn 컴포넌트), 라우팅 |
| 외부 API 어댑터 | 픽스처 경로, 재시도/딜레이 정책, 에러 매핑 규칙 |
| 버그 수정 | 재현 방법, 기대 동작, 관련 테스트 파일 경로 |
| 리팩터 | 변경 전/후 시그니처, 호출부 목록(grep 결과) |
| 문서 작업 | WAL 원칙(append-only), 문서 종류별 위치 |
- ❌ "알아서 인증 기능 만들어줘" — 컨텍스트 0
- ❌ "이전 대화에서 말한 대로" — 서브에이전트는 이전 대화를 모름
- ❌ "최선의 방식으로" — 판단 기준이 모호
- ❌ 완료 조건 없이 보내기 — 검증 불가
- ✅ 절대 경로 + 구체 시그니처 + 검증 명령어 항상 포함
서브에이전트 완료 후 메인 Claude 가 직접 확인해야 하는 항목. 하나라도 실패하면
SendMessage로 수정 요청. 사용자(나)는 §4.5 머지 전 최종 게이트만 직접 본다.
| 변경 영역 | 컴파일 | 테스트 | 커버리지 | 문서 |
|---|---|---|---|---|
| BE (Rust) | cargo check |
cargo test |
cargo tarpaulin |
PR 본문 |
| FE (TS) | npm run type-check |
npm test -- --run |
(Stop hook 자동) | PR 본문 |
| 스펙만 변경 | — | — | — | Wiki 페이지 + PR 본문 |
| DB 마이그레이션 | cargo check |
cargo test (testcontainers) |
— | PR 본문 |
[4-1] 컴파일 / 타입 통과 확인
↓ 실패 → SendMessage로 수정 요청
[4-2] 테스트 통과 확인 (watch 모드 방지 플래그 포함)
↓ 실패 → SendMessage
[4-3] 커버리지 하락 여부 (이전 대비 떨어지면 보강)
↓ 실패 → SendMessage
[4-4] PR 본문(작업 요약/검증/결정) 작성 확인 — Closes #N
↓ 실패 → 메인 Claude가 직접 작성
[4-5] 코드 규칙 준수 (인라인 타입, mock DB 등) — diff 시각 검토
↓ 실패 → SendMessage
[모두 통과] → TaskUpdate(completed)
- FE: 인라인 타입 (
Promise<{ field: T }>) 없음 → 모두 named type - BE:
unwrap()/expect()가 테스트 외에 없음 - BE:
application//adapters/의.rs파일에#[cfg(test)] mod tests존재 - FE:
src/features/*.ts에 대응되는*.test.ts존재 - 새로 추가된 trait이 있다면 픽스처/단위 테스트도 같이 추가됐는지
- 변경된 외부 API 호출이 있다면 재시도/타임아웃 정책이 적용됐는지
| 항목 | 확인 방법 | 주체 |
|---|---|---|
| 한 기능 = 한 커밋(혹은 BE/FE 각 한 커밋) 인가 | git log |
사용자 |
커밋 메시지가 commit-rules.md 형식인가 |
git log -1 |
사용자 |
PR 본문에 Closes #N + 작업 요약이 있나 |
gh pr view |
사용자 |
| 관련 Wiki 페이지가 업데이트됐나 (스키마 변경이 있다면) | Wiki diff 확인 | 사용자 |
| CI 통과 | GitHub Actions | 자동 |
누가 어떤 결정을 내릴 수 있고, 위임 불가한 영역이 무엇인지.
서브에이전트는 물론, 메인 Claude도 함부로 결정하면 안 되는 항목.
- 스코프 — 이 기능을 v1에 넣을지, v2로 미룰지
- 외부 의존성 추가 — 새 crate / npm 패키지 도입 승인
- API 계약 변경 — 호환성 깨지는 변경인지 / 마이그레이션 전략
- DB 스키마 변경 승인 — 마이그레이션 실행 시점
- 머지 / 배포 — 최종 게이트
- 수익 모델 / 가격 — 사업 결정
기술적·전술적 판단. 사용자가 큰 가이드라인을 줬다면 그 안에서 메인 Claude 가 결정.
- trait 분리 여부 — 교체 가능성 판단
- 서브태스크 분해 방식 — 병렬/직렬, 파일 단위
- 커밋 단위 — 어디서 끊을지
- 테스트 추가 위치/방식
- 에러 처리 패턴 적용 (AppError 분기 등)
- 검증 실패 시 재요청 vs 직접 수정
명확히 정의된 작업만.
- 정해진 시그니처대로의 구현
- 픽스처 기반 테스트 작성
- 명확히 정의된 리팩터 (rename, extract method 등)
- 문서 초안 (검토는 메인 Claude / 사용자)
워크플로우가 끝나면 항상 아래가 생긴다:
GitHub Issue (#N) # Phase 2 산출 — 작업 플랜/체크리스트
GitHub PR (Closes #N) # Phase 5 산출 — 작업 로그(요약/검증/결정)
Wiki: Backend/API/Frontend 등 # Phase 6 — 스펙 현황 갱신 (필요 시)
코드 변경 (BE / FE / 마이그레이션)
git commit (한 기능 = 한 커밋, BE/FE 분리 가능) → feature/issue-<N> 브랜치
| # | 단계 | 주체 |
|---|---|---|
| 1 | 이슈 등록 (gh issue create) |
사용자 |
| 2 | 컨텍스트 읽기 (§3.1) — 이슈 + Wiki + 코드 | 메인 Claude |
| 3 | 서브태스크 분해 → 이슈 본문/체크리스트 (§2) | 메인 Claude |
| 4 | 계획 컨펌 | 사용자 |
| 5 |
feature/issue-<N> 브랜치 + 서브에이전트 호출 (§3.2) |
메인 Claude |
| 6 | 컴파일 / 타입 검증 (§4.1) | 메인 Claude |
| 7 | 테스트 검증 (§4.1) | 메인 Claude |
| 8 | 커버리지 확인 (§4.2) | 메인 Claude |
| 9 | diff 시각 검토 (§4.3) | 메인 Claude |
| 10 | 커밋 + PR 생성 (Closes #N, 본문=작업 로그) |
메인 Claude |
| 11 | 머지 전 최종 게이트 (§4.5) | 사용자 |
| 12 | PR 머지 → 이슈 자동 close | 사용자 |
| 13 | 스펙 변경분 Wiki 반영 (§6) | 메인 Claude |