Cursor Composer로 PR 단위 작업하는 루틴

한 줄 요약: Composer는 "레포 전체를 맡기는 버튼"이 아니라 PR 크기만큼 범위를 잘라서 멀티파일 패치를 받는 도구다. 회사 FE 기준으로는 (1) 이슈를 PR 한 장으로 쪼개고 (2) 브랜치를 먼저 딴 뒤 (3) 넣을 파일·빼야 할 파일을 정하고 (4) 테스트·린트는 기준을 두고 맡기며 (5) 리뷰 프롬프트로 사람 검수를 고정하는 루틴이 제일 덜 깨진다.

이전 글에서 Cursor 하루 루틴을 정리했다면, 이 글은 Composer만 깊게 판다. Chat으로 묻고 파일 하나 고치다 보면 "PR이 커질 때"가 온다. 그때부터는 범위 지정이 성패를 가른다.

---

이 글에서 다루는 것

• 이슈 → 브랜치 → Composer 범위 지정
• 컨텍스트에 넣을 파일 / 빼야 할 파일
• 테스트·린트까지 맡기는지 기준
• 리뷰 프롬프트 예시
• 머지 전 체크리스트

---

1. 이슈 → 브랜치 → Composer 범위 지정

이슈를 "PR 한 장"으로 자르기

Composer에 넣기 전에 티켓 문장부터 줄인다. 기준은 단순하다.

좋은 PR 단위	나쁜 PR 단위
주문 상세에 쿠폰 배지 + 타입 + 스토리	"주문 도메인 전체 UX 개선"
필터 칩 UI + URL 쿼리 동기화	"검색 리팩터 + API 교체 + 디자인 토큰"
버그 하나 + 회귀 테스트 한 줄	"성능 전반 + 폴더 구조 이동"

리뷰어가 한 화면·한 흐름으로 설명할 수 있으면 Composer 범위도 잡힌다. "관련 파일 전부"는 범위가 아니다.

회사에서는 보통 티켓 제목을 그대로 브랜치·PR 제목에 옮긴다. Composer 프롬프트 첫 줄에도 그 제목을 그대로 넣으면, 나중에 diff를 볼 때 "이 PR이 뭐 하려던 건지"가 안 흐려진다.

브랜치를 먼저 딴다

습관 순서:

1. main(또는 팀 기본 브랜치) 최신화
2. feat/order-coupon-badge 같은 브랜치 생성
3. 그다음에 Composer 열기

브랜치 없이 Composer로 여러 파일을 손보면, 실험 diff와 본 PR이 섞인다. FE 작업은 화면 한 장만 건드린다고 해도 타입·스토리·테스트까지 파일이 늘어나기 쉽다. 작업 시작 전에 브랜치를 고정하는 편이 안전하다.

Composer에 "범위"를 문장으로 박기

프롬프트 상단에 범위를 명시한다.

목표 PR: 주문 상세 OrderSummary에 쿠폰 배지 추가
범위 폴더: features/order, components/ui (Button만)
하지 말 것: API 스키마 변경, 라우트 구조 변경, 새 디자인 토큰
먼저 변경 예정 파일 목록만 제안하고, 내가 OK하면 패치해.

"먼저 목록 → 동의 후 패치"를 넣으면 Composer가 갑자기 열 개 파일을 갈아엎는 빈도가 줄어든다. 목록이 티켓과 안 맞으면 그 시점에서 끊는다.

FE에서 자주 쓰는 범위 패턴

작업 유형	Composer에 같이 넣는 것	한 줄 제약
UI 섹션 추가	대상 컴포넌트 + 유사 화면 1개 + Button/Input	기존 variant만
훅·상태 분리	훅 + 사용처 2곳 + 타입	전역 스토어 신설 금지
라우트/페이지	page.tsx + loading/error + 레이아웃 조각	App Router 패턴 유지
버그 수정	재현 컴포넌트 + 관련 테스트	최소 diff

---

2. 컨텍스트에 넣을 파일 / 빼야 할 파일

Cursor 품질은 모델 이름보다 넣은 파일 세트에 더 좌우되는 날이 많다. PR 단위면 더 그렇다.

넣으면 좋은 파일

• 수정 대상과 바로 붙는 부모·자식 컴포넌트
• 팀 패턴 예시 1개 ("이 파일 스타일 따라")
• 공유 UI (Button, cn, 디자인 토큰 일부)
• API 타입·zod 스키마·DTO
• 이미 있는 테스트·스토리북 파일 (업데이트 유도용)
• 관련 page.tsx / layout.tsx (라우트 경계가 필요할 때)

React/Next 예시로, 쿠폰 배지 PR이라면 대략 이렇게 @한다.

@features/order/OrderSummary.tsx
@features/order/types.ts
@features/order/OrderSummary.stories.tsx
@components/ui/Badge.tsx
@lib/cn.ts
@features/cart/CartCouponBadge.tsx

마지막 CartCouponBadge는 이미 있는 유사 구현이다. "새 패턴을 발명하지 말고 저거 따라"라고 쓰면 톤이 맞기 쉽다.

빼야 할 파일 (일부러 안 넣는 것)

빼는 것	이유
node_modules, lockfile, 빌드 산출물	노이즈·토큰 낭비
관련 없는 레거시 폴더 통째	엉뚱한 import·패턴 복사
.env, 시크릿, 내부 전용 URL 목록	유출·정책 리스크
거대한 생성 타입 파일 전체	필요한 타입만 잘라 넣기
모노레포의 다른 앱 루트	제안이 앱 경계를 넘음
"참고용" PR diff 전문	맥락이 섞여 목표 PR이 흐려짐

"일단 폴더 전체 @"는 편해 보이지만, Composer가 안 건드렸으면 하는 파일까지 손대게 만든다. PR 리뷰에서 "왜 이 파일?"이 나오는 대부분의 경우가 여기다.

컨텍스트 체크 질문 3개

프롬프트 보내기 전에 스스로 묻는다.

1. 이 파일 없으면 Composer가 패턴을 모를까? → 없으면 넣기
2. 이 파일 있으면 다른 도메인으로 새어 나갈까? → 있으면 빼기
3. 시크릿·개인정보·고객 데이터가 있나? → 있으면 절대 넣지 않기

사내 가이드가 있으면 그 가이드가 프롬프트보다 우선이다.

---

3. 테스트·린트까지 맡기는지 기준

"생성만 하고 끝" vs "검증까지 한 호흡"을 매번 고민하게 된다. 기준을 표로 고정해 두면 편하다.

맡기기 좋은 경우

• 기존 테스트 파일이 이미 있고, 같은 패턴으로 assertion만 추가하면 될 때
• ESLint/Prettier 위반이 뻔히 날 수정(미사용 import, 타입 좁히기)
• Storybook controls·기본 story 한 장 업데이트
• 범위 좁은 유닛 테스트 실행·실패 수정

프롬프트에 이렇게 적는다.

패치 후:
1) 관련 유닛 테스트가 있으면 업데이트 제안
2) 로컬 린트·관련 유닛 실행이 가능하면 돌리고, 실패 시 최소 수정으로 맞춰
새 테스트 프레임워크/라이브러리는 추가하지 마.

사람이 직접 하는 편이 나은 경우

상황	왜 사람이
E2E 전체 스위트	시간·환경 의존
시각/디자인 QA (피그마 대비)	여백·토큰은 사람이 보는 편이 정확
접근성 실사용 (키보드·스크린리더)	클릭 경로를 사람이 밟아야 함
서버/클라 경계 (use client 전파)	한 줄이 번들·보안에 영향
의존성 메이저 업	팀 합의·락파일 리뷰 필요
테스트 통과 주장만으로 머지	실행 로그를 안 보면 안 됨

에이전트(자동 실행) 권한이 있는 환경이어도, FE PR에서는 네트워크·패키지 설치·파일 삭제는 최소 권한으로 두는 편이 마음 편하다. 편집과 좁은 테스트면 대부분 충분하다.

실무에서 쓰는 절충

1. Composer에게 유닛/스토리 업데이트 제안까지 맡긴다.
2. 린트·타입체크는 실패하면 고쳐까지 허용한다.
3. 브라우저에서 해당 플로우 한 번 클릭은 무조건 사람이 한다.
4. CI가 빨간 이유는 로그를 읽고, 원인 모를 때만 Composer에 로그를 붙여 재질문한다.

"테스트까지 AI가 돌려줬다"는 문장만으로 리뷰를 건너뛰지 않는다. 실행하지 않은 코드는 머지하지 않는 규칙이 Composer 시대에도 그대로다.

---

4. 리뷰 프롬프트 예시

생성 직후 Chat/Composer에 리뷰 전용으로 한 번 더 돌린다. 목적은 AI 칭찬이 아니라 머지 전에 빠지기 쉬운 FE 함정을 체크하는 것이다.

예시 A — PR diff 셀프 리뷰

이 PR은 주문 상세에 쿠폰 배지를 추가하는 작업이야.
변경된 파일만 기준으로 리뷰해줘.

반드시 볼 것:
- 'use client'가 불필요하게 전파됐는지
- 서버 fetch가 클라이언트로 내려갔는지
- a11y: 배지 텍스트·버튼/링크 역할·포커스
- 로딩/빈값/에러 UI 누락
- 하드코딩 시크릿·내부 URL
- 기존 디자인 시스템 이탈(새 색/새 컴포넌트)

출력 형식:
1) Blocking 이슈 (있으면)
2) Nit (선택)
3) 사람이 로컬에서 클릭해볼 경로 3개
추측으로 "문제없음"만 쓰지 마. 근거 파일을 짚어.

예시 B — 멀티파일 일관성

@features/order/OrderSummary.tsx @features/order/types.ts @features/order/OrderSummary.stories.tsx
세 파일 사이의 타입·props·story args가 일치하는지 확인해.
불일치만 bullet로 나열하고, 수정 패치는 내가 OK한 뒤 제안해.

예시 C — 리뷰어에게 넘길 PR 본문 초안

위 diff를 보고 GitHub PR 본문 초안을 한국어로 써줘.
섹션: 요약 / 변경 점 / 테스트 방법 / 스크린샷 자리 / 리스크
마케팅 문장 금지. 사실만. 내가 채울 [ ] 표시를 남겨.

PR 설명의 한 줄 의도는 사람이 최종 수정한다. AI 초안은 뼈대용이다.

리뷰 후 사람이 꼭 보는 FE 항목

• App Router 경계: 서버/클라 나눔이 티켓 의도와 맞는지
• 불필요한 클라 번들 증가 (use client·무거운 라이브러리)
• i18n 키 / 하드코딩 문자열 혼입
• 이미지·아이콘 CLS, sizes
• 모바일 폭에서 배지·칩 줄바꿈
• 스토리·테스트가 깨진 채로 남아 있지 않은지

---

하루 루틴으로 붙이는 순서 (요약 표)

순서	행동	Composer 포인트
1	티켓을 PR 한 장으로 축소	목표 문장 1줄
2	브랜치 생성	작업 전 분리
3	@ 파일 선정 (넣기/빼기)	유사 구현 1개 포함
4	범위·금지 사항을 프롬프트에 명시	목록 먼저 → 패치
5	좁은 린트/테스트 요청 여부 결정	E2E·디자인 QA는 사람
6	리뷰 프롬프트로 Blocking 점검	근거 파일 요구
7	로컬 클릭 + PR 본문 다듬기	의도 한 줄은 사람

이전 Cursor 워크플로 글의 "질문은 Chat, 패치는 Composer" 규칙은 여기에도 그대로 쓴다. PR이 커질수록 Chat으로 설계만 떠보고, 손대는 순간 Composer로 넘어가는 편이 덜 헷갈린다.

---

피하면 좋은 Composer PR 습관

습관	결과	대안
이 폴더 전부 정리해줘	리뷰 불가 diff	파일 목록 먼저
브랜치 없이 본업 브랜치에 실험	커밋 히스토리 오염	feature 브랜치 먼저
lockfile·env를 컨텍스트에	노이즈·보안	명시적으로 제외
테스트 로그 없이 머지	조용한 회귀	사람 클릭 + CI
리뷰 프롬프트 생략	use client 전파 등 놓침	예시 A를 템플릿화

처음엔 배지·필터 칩처럼 UI 작은 PR로 Composer 루틴만 굳히는 편이 낫다. 범위 감각이 생기면 훅 분리·페이지 추가 쪽으로 넓히면 된다.

---

체크리스트 (머지 전)

• 티켓 목표가 PR 제목·프롬프트 첫 줄과 동일한가
• feature 브랜치에서 작업했는가
• @한 파일에 시크릿·무관 레거시·다른 앱이 없는가
• "하지 말 것"이 프롬프트에 적혀 있는가
• 변경 파일 목록을 한 번 승인한 뒤 패치했는가
• 린트/타입/관련 유닛은 돌렸거나, 왜 안 돌렸는지 메모했는가
• 리뷰 프롬프트로 Blocking을 한 번 걸렀는가
• 해당 화면 플로우를 로컬에서 클릭해 봤는가
• PR 본문에 테스트 방법·리스크가 사람이 읽기 좋게 있는가

---

마무리

Cursor Composer로 PR 단위 작업을 안정적으로 하려면 모델보다 범위 루틴이 먼저다.

1. 이슈를 PR 한 장으로
2. 브랜치 먼저
3. 넣을 파일 / 빼야 할 파일 구분
4. 테스트·린트는 좁게만 맡기기
5. 리뷰 프롬프트 + 사람 클릭

이 다섯 줄을 고정하면 "멀티파일은 편한데 리뷰가 지옥"인 상태가 많이 줄어든다. 내일 티켓 하나를 위 체크리스트 순서대로만 돌려 보면, Chat만 쓸 때와 Composer PR 루틴의 차이가 바로 느껴진다.