PR 본문을 에이전트에 쓰게 하려면
에이전트 PR 본문은 “PR을 열었다”가 아니라 리뷰어가 첫 화면에서 의도·범위·검증을 읽을 수 있게 채우는 일입니다. 에이전트에게 고정 템플릿, diff 기반 요약 규칙, 리뷰어용 체크리스트를 주면 빈 본문·파일 나열만 있는 PR이 줄어듭니다.
인접 글과 축을 나눕니다. multi-agent-pr-workflow는 브랜치 소유·병렬·머지 게이트이고, linear-to-agent-pr는 Linear 이슈 패킷 → 위임 → 리뷰 요청 시점입니다. 이 글은 본문 작성만 다룹니다. 요금·플랜·제휴 링크는 없습니다. 근거는 GitHub Creating a pull request, gh pr create입니다.
템플릿은?
한 줄 답: 레포에 PR 템플릿(또는 에이전트 지시용 마크다운) 을 두고, 에이전트에게 “칸을 비우지 말고 채운 뒤 --body-file/gh pr create로 제출”하라고 고정합니다. 제목은 결과 한 줄, 본문은 의도·검증·리스크입니다.
GitHub는 기본 브랜치에 .github/pull_request_template.md(또는 PULL_REQUEST_TEMPLATE/)를 두면 새 PR 본문에 채웁니다. CLI는 gh pr create --title "…" --body-file path로 같은 구조를 강제할 수 있습니다.
에이전트에 넣을 최소 칸:
| 칸 | 에이전트가 채울 것 | 금지 |
|---|---|---|
| Summary | 무엇을/왜 2–4불릿 | 파일 경로 나열만 |
| Motivation | 이슈·버그·요청 한 줄 | 장황한 슬랙 전문 |
| Changes | 관심사별 그룹(API/UI/CI) | “여러 파일 수정”만 |
| Test plan | 실제 돌린 명령·결과 | “테스트함” 한 단어 |
| Risk / rollback | 데이터·API·플래그 | 빈 칸 |
| Out of scope | 이번엔 안 한 것 | 침묵 |
| Reviewer notes | 볼 포인트·트레이드오프 | “LGTM 부탁”만 |
지시 문장 예:
Write the PR body from this template. Fill every section.
Do not invent Test plan results — only commands you ran.
Do not paste secrets, tokens, or raw PII.
Title: <ticket-or-type>: <outcome in one line>
Then open PR with gh pr create --body-file <path> (or paste body).
Do not request reviewers until the human says so.템플릿 파일 예(레포 공용이면 .github/pull_request_template.md에 두고, 에이전트 전용이면 docs/pr-body-agent.md로 복제해도 됩니다):
## Summary
-
## Motivation / linked issue
-
## Changes (by concern)
-
## Test plan
- [ ] `<command>` → result:
- [ ] Manual:
## Risk & rollback
- Risk:
- Rollback:
## Out of scope
-
## Notes for reviewers
-팀이 Conventional Commits·티켓 ID를 쓰면 제목만 fix(auth): … / ENG-1234: …로 맞추고, 본문 칸은 그대로 둡니다. Linear 전용 칸이 필요하면 linear-to-agent-pr 템플릿을 쓰되, 이 글의 Summary·Test·Risk 규칙은 공유합니다.
diff 요약은?
한 줄 답: 에이전트에게 git diff <base>...HEAD를 읽고 관심사로 묶어 요약하라고 하고, 줄 수·파일명 덤프가 아니라 의도·경계·깨질 수 있는 계약을 쓰게 합니다.
좋은 diff 요약의 신호:
| 신호 | 예 |
|---|---|
| 의도 먼저 | “로그인 재시도 한도를 3→5로 올려 flaky를 줄임” |
| 관심사 그룹 | API 계약 / UI 카피 / 테스트 fixture |
| 계약 변경 명시 | 응답 필드 추가·기본값·에러 코드 |
| 비변경 명시 | “스키마 마이그레이션 없음” |
| 근거 링크 | 이슈·실패 CI·스크린샷(민감정보 가림) |
나쁜 요약(에이전트에 금지):
src/a.ts,src/b.ts, … 파일 목록만.- “리팩터링함 / 클린업”처럼 관찰 불가.
- diff에 없는 기능을 Summary에 적기(환각).
- 테스트 실패를 숨기고 “all green”이라고 쓰기.
에이전트 워크플로 스케치:
1. git fetch && git diff origin/main...HEAD --stat
2. git diff origin/main...HEAD (또는 path allowlist만)
3. Group hunks by concern (not by file path alone)
4. Fill Summary + Changes from those groups
5. List contracts touched (API, flags, migrations)
6. Paste only commands you actually ran into Test plangh pr diff·로컬 git diff 중 팀 표준 하나를 고릅니다. 큰 PR이면 “Changes”를 모듈/패키지 단위로만 쓰고, 리뷰어가 볼 1–3개 핫스팟 경로만 Notes에 적습니다. 멀티 에이전트 병렬·경로 락은 multi-agent-pr-workflow로 넘깁니다—여기는 한 PR 본문의 요약 품질만입니다.
Diff summary rules for the agent:
- Lead with why / outcome
- Group by concern (max ~5 bullets)
- Call out breaking or behavioral changes
- Never claim tests you did not run
- If unsure, write "Unknown — needs human" in Notes리뷰어 체크는?
한 줄 답: 본문 안에 리뷰어가 바로 쓸 체크리스트를 넣고, 에이전트는 초안·셀프체크만 하며 Approve·머지는 사람(또는 CODEOWNERS)에게 둡니다.
리뷰어 체크(본문 Notes for reviewers 또는 별도 절) 예:
Reviewer checklist (human):
[ ] Intent matches linked issue / AC
[ ] Scope matches allowlist — no surprise paths
[ ] Contracts (API/flags/migrations) called out above
[ ] Test plan commands are reproducible
[ ] Secrets / PII / debug dumps absent from diff
[ ] Rollback path is believable
[ ] Out of scope is honest (or follow-up linked)에이전트 셀프체크(PR 열기 직전, 사람에게 넘기기 전):
| 항목 | 통과 기준 |
|---|---|
| 템플릿 빈 칸 | Summary·Test·Risk에 -만 남지 않음 |
| Test plan | 실행한 명령 문자열이 본문에 있음 |
| diff ↔ Summary | Summary에 없는 대규모 변경이 diff에 없음 |
| 시크릿 | .env, 키, 토큰 문자열 없음 |
| 리뷰 요청 | 사람 지시 전 --reviewer 자동 호출 금지 |
운영 팁:
- 체크리스트는 팀이 합의한 최소만. 칸이 늘면 에이전트가 형식만 채웁니다.
- CODEOWNERS·필수 상태 검사는 리뷰어 체크를 대체하지 않습니다. 본문은 “어디를 볼지”를 압축합니다.
- 에이전트가 “셀프 Approve” 문구를 넣지 않게 합니다. 초안 품질과 승인 권한을 섞지 않습니다.
- 실패 CI가 있으면 Test plan에 실패 사유·무시 가능 여부를 한 줄로 적습니다. 침묵이 가장 비쌉니다.
한 줄 정리: 템플릿으로 칸을 고정하고, diff에서 의도·계약을 요약하며, 리뷰어 체크로 사람이 볼 포인트를 남깁니다. 브랜치 병렬·Linear 핸드오프 글과 축이 다릅니다.
FAQ
PR 템플릿이 이미 있는데 에이전트 지시가 또 필요한가요?
예. UI 템플릿은 빈 칸을 주고, 에이전트 지시는 채우는 규칙(diff 요약·금지 항목·--body-file)을 줍니다. 둘 다 있을 때 본문 품질이 안정됩니다.
Summary와 Changes를 어떻게 나누나요?
Summary는 왜/결과(2–4불릿), Changes는 어디에 손댔는지 관심사 그룹입니다. Summary에 파일 트리를 넣지 마세요.
multi-agent-pr·linear-to-agent-pr와 무엇이 다른가요?
multi-agent-pr-workflow = 브랜치·경로·머지 게이트. linear-to-agent-pr = 이슈 패킷·리뷰 요청 시점. 이 글은 PR 본문 작성(템플릿·diff 요약·리뷰어 체크) 만입니다.
에이전트가 리뷰어를 자동 지정해도 되나요?
팀이 허용한 기본 리뷰어가 있어도, 본문이 채워지고 사람이 OK한 뒤가 안전합니다. 빈 본문 + 자동 리뷰 요청은 노이즈입니다.
출처 (Sources)
- Creating a pull request — PR 생성·설명
- Creating a pull request template —
.github/pull_request_template.md - gh pr create —
--title·--body·--body-file - 인접: multi-agent-pr-workflow(브랜치·병렬), linear-to-agent-pr(이슈 핸드오프)