HWSS 팀 문서

개발 작업 흐름

작업을 시작할 때 Draft PR 을 먼저 열고, 끝나면 Draft 를 풀어 리뷰를 받고 머지합니다. 누가 지금 무엇을 하는지는 따로 적지 않습니다 — 열린 PR 이 커버리지 맵의 "진행 중 작업"에 그대로 모입니다.

한눈에 보기

  1. 시작브랜치를 만들고 Draft PR 을 연다작업 중 으로 보임
  2. 작업커밋·푸시하며 할 일을 체크한다할 일 2/3 처럼 진행도가 보임
  3. 마무리테스트, 커버리지 표·작업 계획 갱신, 본문 정리아직 Draft
  4. 리뷰 요청Draft 를 푼다리뷰 중 · Slack 알림 · 자동 리뷰
  5. 머지Slack 스레드에 LGTM 또는 GitHub 에서 머지배포 · 맵 상태 갱신

사람이 직접 정하는 것은 세 가지뿐입니다 — 목표일(있을 때), 리뷰 확인, 머지 지시. 나머지는 에이전트에게 맡기거나 자동으로 일어납니다.

단계별로 하는 일

1

시작 — 브랜치와 Draft PR

작업 중

하는 일

  1. dev 최신에서 브랜치를 만든다. dev 에 직접 푸시는 훅이 막는다.
  2. 빈 커밋을 푸시한다. 커밋이 하나는 있어야 PR 이 만들어진다.
  3. Draft PR 을 연다. 본문은 아래 PR 본문 쓰는 법대로.
git fetch origin dev && git switch -c feat/sso-callback origin/dev
git commit --allow-empty -m "chore: SSO 콜백 작업 착수" && git push -u origin feat/sso-callback
gh pr create --draft --base dev --title "feat(backend): SSO 콜백 컨트롤러" --body-file pr-body.md

이때 일어나는 일

  • 1~2분 뒤 커버리지 맵 "진행 중 작업"에 작업 중 으로 뜬다. 닿는 화면 행에도 같은 뱃지가 붙는다.
  • Slack 알림과 자동 코드 리뷰는 아직 돌지 않는다 — Draft 이기 때문이다.
2

작업 — 커밋하고 푸시

작업 중

하는 일

  • 평소처럼 커밋하고 푸시한다.
  • 끝낸 항목은 PR 본문의 체크박스를 체크한다.
  • 일정이 바뀌면 본문의 목표일 줄만 고친다.

이때 일어나는 일

  • 바꾼 모듈(백엔드·프론트엔드·프로토타입)의 검사는 Draft 에서도 푸시마다 돈다.
  • 맵에 할 일 2/3 처럼 진행도가 보인다. 목표일이 지나면 목표 10/08 · 2일 지남 으로 강조된다.
  • 맵의 진행도·목표일은 문서 사이트가 다시 빌드될 때(dev 머지, PR 열림·닫힘) 갱신된다 — 본문만 고쳤을 때는 다음 빌드까지 이전 값이 보인다.
3

마무리 — 리뷰를 요청하기 전에

작업 중

하는 일 (같은 PR 안에서)

  1. 테스트·검사를 돌리고 결과를 확인한다.
  2. 화면에 닿는 작업이면 커버리지 표(docs-site/data/coverage.json)를 맞춘다 — 새 클래스는 has 에, 채운 빠진 것은 gaps 에서 지운다.
  3. 작업 계획(docs/work-plan.md) 완료 기록에 한 줄을 더한다.
  4. PR 본문을 최종 내용으로 정리한다 — 변경 내용, 실행한 검증 명령과 결과. 커버리지 맵: 줄은 남긴다.

왜 여기서 하나

  • 표와 작업 계획이 같은 PR 로 머지돼야, 머지되는 순간 맵의 상태가 맞게 따라온다.
  • Draft 를 풀면 곧바로 리뷰가 시작되므로, 리뷰가 읽을 본문을 먼저 정리해 둔다.
4

리뷰 요청 — Draft 해제

리뷰 중

하는 일

gh pr ready
  • 리뷰 지적은 고쳐서 푸시한다 — 푸시하면 리뷰가 다시 돈다.
  • 고치지 않기로 한 지적은 PR 코멘트로 이유를 남긴다.

이때 일어나는 일

  • 팀 Slack 채널에 PR 알림이 올라가고, 이후 코멘트가 그 스레드에 이어진다.
  • 자동 코드 리뷰가 돌고 결과가 PR 코멘트로 달린다.
  • 맵의 표시가 리뷰 중 으로 바뀐다.
5

머지와 그 뒤

머지

하는 일 (둘 중 하나)

  • Slack 의 그 PR 스레드에 LGTM 으로 시작하는 댓글을 단다 — 5분 안에 머지된다.
  • GitHub PR 화면에서 직접 머지한다(머지 커밋 방식).

머지 뒤 로컬 정리

git switch dev && git pull && git branch -D feat/sso-callback

이때 일어나는 일

  • 원격 브랜치가 지워지고 dev 서버에 배포된다.
  • 문서 사이트가 다시 빌드된다 — 맵의 상태가 다시 계산되고, 그 화면의 관련 PR 이력에 머지된 PR 로 쌓인다.
  • 화면 담당자는 그대로다 — 담당은 PR 이 머지돼도 풀리지 않는다.

PR 본문 쓰는 법

Draft 로 열 때는 이 정도면 됩니다. 변경 내용과 검증 결과는 마무리할 때 채웁니다.

## 할 일
- [ ] SsoCallbackController
- [ ] SiteMinder 헤더 검증
- [ ] 테스트

목표일: 10/08

커버리지 맵: login
줄쓰는 법맵에서 보이는 것
## 할 일 체크리스트이 작업에서 할 항목. 끝낸 것은 - [x] 로 체크한다.할 일 2/3 — 진행 중 작업과 화면의 PR 이력에
목표일:선택. 일정이 있는 작업에만 적는다. 10/08, 2026-10-08, 10월 8일 모두 읽는다.목표 10/08 — 지나면 "N일 지남" 으로 강조되고 목표일 지남 필터에 잡힌다
커버리지 맵:이 PR 이 닿는 화면 id 를 쉼표로. 닿는 화면이 없으면 없음. id 는 coverage.json 의 screens[].id — 맵에서 화면 행 주소의 #cov- 뒤 글자다.그 화면 행에 작업 중·리뷰 중 뱃지, 머지 뒤에는 그 화면의 PR 이력에 쌓임

어디서 보나

알고 싶은 것보는 곳
누가 지금 무엇을 하고 있나커버리지 맵 → 진행 중 작업 — 열린 PR 전체가 작성자별로 묶여 있다(로그인 후). 화면에 닿지 않는 PR 도 여기에 나온다.
언제까지 하기로 했나, 밀린 것은같은 곳의 목표일. 맵의 목표일 지남 필터는 밀린 PR 이 닿는 화면만 남긴다.
이 화면(기능)은 어디까지 됐나화면 행의 상태(프론트·백엔드·AI)와 관련 PR 이력 — 접힌 줄을 누르면 펼쳐진다.
내가 맡은 화면들의 진행커버리지 맵 → 담당 현황 — 담당자별로 상태·남은 것·작업 중/리뷰 중 PR·최근 머지 수.

에이전트에게 시킬 때

이 흐름은 루트 CLAUDE.md §0 「작업 착수 시」에 규칙으로 들어 있어, 에이전트는 작업을 지시받으면 Draft PR 부터 엽니다. 단계마다 한 줄이면 됩니다.

시점지시 예
시작"SSO 콜백 작업 시작해. 목표일은 10/8, 화면은 login."
진행 중"여기까지 커밋하고 푸시해. PR 본문 체크리스트도 맞춰."
마무리"테스트 돌리고 커버리지 표·작업 계획 맞춘 다음, 본문 정리해서 리뷰 요청으로 바꿔."
리뷰 뒤"리뷰 코멘트 반영해서 푸시해."

예외와 자주 묻는 것

규칙의 원문은 저장소 루트 CLAUDE.md §0, 결정 근거는 docs/decisions/20261002-draft-pr-first-workflow.md 입니다.