Linear 이슈를 Cursor 에이전트 PR로 넘기는 방법

Linear Cursor 에이전트 PR 핸드오프의 핵심은 이슈 본문을 “읽기 좋은 티켓”이 아니라 에이전트가 실행할 작업 패킷으로 만드는 것입니다. Linear에 Cursor를 연결했다면 이슈를 Cursor에 할당하거나 댓글에 @Cursor를 멘션해 Cloud Agent를 띄울 수 있습니다. 에이전트는 이슈 맥락을 읽고 작업이 끝나면 PR을 열어 Linear에 상태를 돌려줍니다.

이 글은 이슈에서 무엇을 복사·보강할지 · PR 설명 템플릿 · 리뷰 요청 시점만 다룹니다. 멀티 에이전트용 브랜치 소유·경로 락 규칙은 다루지 않습니다. 가격·플랜·개인 후기도 없습니다. 근거는 Cursor Linear 연동과 Cloud Agents입니다.

이슈에서 무엇을 복사하나?

한 줄 답: 제목·목표·수락 기준·재현/검증 명령·범위(경로)·비목표·링크·레포/베이스 힌트를 한 덩어리로 넘깁니다. 배경 소설과 비밀값은 빼거나 가립니다.

에이전트(또는 로컬 Agent 프롬프트)에 넣을 최소 패킷:

필드왜 필요한가복사/보강 팁
이슈 ID·제목PR·커밋·Linear 역추적ENG-1234: …를 목표 첫 줄에 유지
목표 한 문장“끝나면 무엇이 달라지나”동사 중심. “로그인 flaky를 고친다”
수락 기준(AC)통과/실패를 사람이 판정관찰 가능: 테스트·화면·로그 한 줄
재현·검증 명령에이전트 루프의 Done 조건npm test -- path처럼 exit 0 기준
범위·비범위과잉 수정 방지허용 경로 / 건드리지 말 것
링크맥락 압축Figma·실패한 CI·관련 PR·스크린샷
레포·베이스잘못된 클론 방지[repo=owner/name], [branch=main] 등

Linear → Cursor를 직접 위임할 때도 본문이 비어 있으면 결과가 흔들립니다. 할당 전에 위 필드를 채우거나, @Cursor 멘션 댓글에 보강 패킷을 붙입니다. 문서상 설정 키 예시는 이슈/댓글의 [key=value] 문법입니다.

Goal: ENG-1234 — <끝나면 달라지는 상태 한 문장>
Acceptance:
  - <관찰 가능한 기준 1>
  - <관찰 가능한 기준 2>
Repro / Verify (must exit 0 when done):
  <command>
Scope: <paths>
Out of scope: <list>
Links: <Linear URL, failing CI, design>
Hints: [repo=owner/repo] [branch=main]
Do not: push secrets, widen scope, force-push shared branches

복사하지 말 것

  1. 시크릿·토큰·개인 데이터 — Cloud Secrets·로컬 키체인에 두고 이슈에는 이름만.
  2. 장황한 슬랙 스레드 전문 — 결정·재현·거절 사유만 요약.
  3. 모호한 “더 깔끔하게” — AC를 명령·체크리스트로 바꿉니다.
  4. 이미 폐기된 시도 전부 — “시도함 / 실패 이유” 2–3줄이면 충분합니다.

로컬 Agent에 붙여 넣을 때도 같은 패킷을 씁니다. Linear 위임은 패킷을 이슈에 남기는 쪽이고, 로컬은 채팅 첫 메시지에 붙이는 쪽입니다. 형태는 같습니다.

PR 설명 템플릿은?

한 줄 답: Linear ID·요약·AC 대조·테스트·스크린샷/로그·리스크·비범위를 고정 칸으로 둡니다. 에이전트 초안을 사람이 한 번 다듬은 뒤 리뷰어에게 보입니다.

에이전트에게 “PR 본문은 아래 템플릿을 채워라”고 지시합니다.

## Linear
- ENG-1234 — <이슈 제목>
- Link: <Linear URL>

## Summary
- <무엇을 / 왜 바꿨는지 2–4불릿>

## Acceptance checklist
- [ ] <AC1 — 관찰 방법>
- [ ] <AC2>

## Test plan
- Commands run: `<…>`
- Result: pass / fail + 한 줄
- Manual: <해당 시 화면·환경>

## Risk & rollback
- Risk: <데이터·API·마이그레이션 영향>
- Rollback: <revert 단위 / feature flag>

## Out of scope
- <이번 PR에서 안 한 것>

## Notes for reviewers
- <헷갈릴 파일·의도적 트레이드오프>

채울 때 규칙:

  1. Summary는 diff 나열이 아닙니다. 의도·경계만 적습니다.
  2. AC 체크리스트는 이슈 AC와 1:1로 맞춥니다. 빠진 AC는 “후속 이슈”로 명시합니다.
  3. Test plan에 실제 돌린 명령을 남깁니다. “테스트함”만 있으면 리뷰어가 다시 묻습니다.
  4. 시크릿·내부 URL은 가리거나 사내 문서 링크로 대체합니다.
  5. 에이전트가 연 PR이라면 Linear 쪽 상태·PR 링크가 붙는지 확인하고, 본문이 비면 위 템플릿으로 덮어씁니다.

PR 제목은 ENG-1234: <짧은 결과>처럼 이슈와 맞추면 Linear·GitHub 양쪽에서 검색이 쉽습니다. 제목에 구현 세부(파일명 나열)를 넣지 않습니다.

리뷰 요청은 언제 걸까?

한 줄 답: AC·테스트 계획이 본문에 채워지고, CI(또는 합의된 최소 검증)가 녹색(또는 실패 사유가 본문에 설명)이며, diff가 이슈 범위 안일 때 요청합니다. “에이전트가 PR을 열었다”만으로 리뷰를 돌리지 않습니다.

요청 전 체크리스트:

  1. 이슈 AC ↔ PR 체크리스트가 같은 말을 하는가.
  2. 범위 밖 파일이 섞이지 않았는가. 있으면 분리하거나 Out of scope에 이유를 적는다.
  3. 재현/검증 명령을 리뷰어가 그대로 돌릴 수 있는가.
  4. 실패 중인 체크가 있으면 “왜 무시해도 되는지 / 후속인지”가 본문에 있는가.
  5. 시크릿·디버그 로그·개인정보가 diff에 없는가.

요청을 미루는 신호:

  • 에이전트가 아직 후속 @Cursor 지시로 고치는 중.
  • AC가 “UI가 나아짐”처럼 주관적이고 스크린샷·기준이 없음.
  • 이슈에 레포/베이스가 없어 잘못된 저장소 PR이 열림 → [repo=…]·라벨·대시보드 기본값부터 수정.
  • PR 본문이 비어 있고 Linear 링크만 있음.

요청을 바로 걸어도 되는 신호:

  • AC 체크가 채워졌고, 최소 테스트가 통과.
  • 리스크·롤백이 한 줄이라도 있음.
  • 리뷰어가 볼 포인트(의도적 트레이드오프)가 Notes에 있음.

리뷰 코멘트 반영은 Linear 댓글에 @Cursor로 요약을 붙여 이어가거나, 로컬 Agent/사람이 diff를 고칩니다. 인라인 PR 코멘트만 보고 에이전트가 항상 따라가진 않으니, 고칠 항목을 Linear나 채팅에 한 번 더 적는 편이 안전합니다. 승인·머지는 사람(또는 팀 게이트)이 합니다.

마무리

Linear → Cursor 에이전트 PR은 이슈 패킷(목표·AC·검증·범위·레포 힌트) → 템플릿 채운 PR → AC·검증 통과 후 리뷰 요청 순서입니다. 위임 버튼만으로는 부족하고, 복사·보강할 필드를 고정하는 것이 핵심입니다. 브랜치 병렬 규칙은 별도 글로 두고, 이 글은 핸드오프 축만 다룹니다.

출처