동블

그래프 뷰

MR_MESSAGE_GUIDE

13 min read

MR 메시지 작성 가이드

Status: Implemented

이 문서는 Codex가 git push를 수행했거나, 푸시 후 MR/PR을 만들 수 있는 상태가 되었을 때 채팅방에 제공해야 하는 상세 MR 메시지 작성 규칙을 정의한다. 목표는 리뷰어가 변경 이유, 판단 근거, 영향 범위, 검증 결과를 빠르게 이해하도록 돕는 것이다. 단순 파일 목록이 아니라 “왜 바뀌었고 무엇을 봐야 하는지”를 남기는 것이 기준이다.

목적

Codex는 MR/PR 설명을 작성할 때 아래 목표를 만족해야 한다.

  • 리뷰어가 변경 배경과 맥락을 빠르게 이해하게 한다.
  • 단순 파일 변경 목록이 아니라 의도, 판단, 영향 범위를 설명한다.
  • 사용자가 MR 설명에 그대로 복사해 GitLab/GitHub에 붙여넣을 수 있게 한다.
  • 테스트 여부와 미검증 사항을 숨기지 않는다.
  • ZIP:ON의 제품 목적, MVP 흐름, 변경 이력을 추적 가능한 형태로 남긴다.

적용 시점

Codex는 아래 상황에서 반드시 이 문서를 따른다.

  • git push를 수행한 직후
  • 사용자가 “푸시해줘”, “올려줘”, “브랜치에 반영해줘”라고 요청한 경우
  • MR/PR 생성 전후
  • 사용자가 MR 메시지, PR 메시지, 커밋 요약, 리뷰 요청 메시지를 요구한 경우
  • 작업 완료 보고에 원격 브랜치 반영이 포함된 경우

특히 git push가 성공했다면 사용자가 별도로 요청하지 않아도 채팅방에 상세 MR 메시지를 제공해야 한다.

작성 전 확인 정보

MR 메시지를 작성하기 전에 가능한 범위에서 아래 정보를 확인한다.

git status
git branch --show-current
git log --oneline -n 10
git diff --stat
git diff --name-only

원격 기준 브랜치가 명확하면 아래도 확인한다.

git diff --stat origin/main...HEAD
git log --oneline origin/main..HEAD

기준 브랜치가 main이 아닐 수 있으므로 프로젝트 기본 브랜치나 현재 작업 브랜치 맥락을 먼저 확인한다. 추측으로 작성하지 않는다. 확인하지 못한 항목은 아래처럼 명시한다.

- 확인하지 못함
- 테스트 미실행
- 기준 브랜치 불명확
- 로컬 diff 기준으로 작성

기본 형식

채팅방에는 아래 내용을 복사 가능한 Markdown으로 제공한다.

아래 내용을 MR 설명에 그대로 붙여넣으면 됩니다.
 
```md
# MR 제목
 
<type(scope): 변경 요약>
 
# MR 요약
 
이번 MR은 <무엇을> <왜> 변경했는지 요약합니다.
 
# 작업 배경
 
- 기존 문제:
- 사용자가 겪던 불편 또는 개발상 문제:
- 이 변경이 필요한 이유:
- 관련 맥락:
 
# 주요 변경사항
 
## 1. <변경 영역 1>
 
- 변경 내용:
- 변경 이유:
- 기대 효과:
 
## 2. <변경 영역 2>
 
- 변경 내용:
- 변경 이유:
- 기대 효과:
 
## 3. <변경 영역 3>
 
- 변경 내용:
- 변경 이유:
- 기대 효과:
 
# 변경 파일
 
```text
<주요 변경 파일 목록>
```
 
각 파일은 단순 나열에 그치지 말고 가능한 경우 무엇이 바뀌었는지 짧게 설명합니다.
 
# 테스트 및 검증
 
## 실행한 검증
 
```text
- <실행한 명령 또는 확인 내용>
```
 
## 결과
 
```text
- 성공/실패 여부
- 실패했다면 원인
```
 
## 미실행 항목
 
```text
- <실행하지 못한 테스트>
- <실행하지 못한 이유>
```
 
# 영향 범위
 
* 백엔드 영향:
* 프론트엔드 영향:
* DB/마이그레이션 영향:
* API 응답 영향:
* 인증/권한 영향:
* 문서 영향:
* 배포 영향:
 
해당 없는 항목은 `해당 없음`으로 명시합니다.
 
# 리뷰어가 중점적으로 볼 부분
 
* <리뷰 포인트 1>
* <리뷰 포인트 2>
* <리뷰 포인트 3>
 
# 리스크 및 주의사항
 
* <잠재 리스크>
* <주의할 점>
* <계속 확인이 필요한 사항>
 
# 롤백 관련
 
문제가 생겼을 때 되돌려야 할 주요 변경 지점을 설명합니다.
 
```text
- 되돌릴 파일:
- 되돌릴 설정:
- DB 변경 여부:
- 캐시/환경변수/배포 설정 영향:
```
 
# 후속 작업
 
* [ ] <후속 작업 1>
* [ ] <후속 작업 2>
* [ ] <후속 작업 3>
```

MR 제목 규칙

MR 제목은 가능하면 Conventional Commit 스타일을 따른다.

feat(admin): 관리자 API 상태 점검 화면 추가
fix(auth): 관리자 API 401 응답 처리 수정
refactor(chatbot): 챗봇 관련 코드 제거
docs(agents): MR 메시지 작성 규칙 추가
chore(config): 로컬 실행 환경 문서 정리
test(risk): 전세 위험도 계산 테스트 추가

타입은 아래 기준을 사용한다.

type기준
feat새로운 기능
fix버그 수정
refactor동작 변경 없는 구조 개선
docs문서 변경
test테스트 추가 또는 수정
chore설정, 빌드, 기타 작업
style포맷, 스타일 변경
perf성능 개선

좋은 MR 메시지 기준

좋은 MR 메시지는 아래 질문에 답해야 한다.

  • 이 MR은 왜 필요한가?
  • 기존에는 무엇이 문제였는가?
  • 어떤 판단으로 이 방식을 선택했는가?
  • 실제로 어떤 파일과 흐름이 바뀌었는가?
  • 사용자는 무엇이 달라지는가?
  • 개발자와 리뷰어는 무엇을 주의해서 봐야 하는가?
  • 테스트는 어디까지 수행했는가?
  • 아직 확인하지 못한 것은 무엇인가?

나쁜 MR 메시지 예시

아래처럼 작성하지 않는다.

수정함
작업 완료
버그 수정
프론트 수정
백엔드 수정
문서 업데이트
여러 파일 수정

아래처럼 변경 파일만 나열하는 것도 부족하다.

- UserService 수정
- AdminController 수정
- README 수정

반드시 “왜 바뀌었는지”, “어떤 흐름이 달라졌는지”, “리뷰어가 무엇을 봐야 하는지”까지 설명한다.

테스트 결과 작성 원칙

테스트는 실제로 실행한 것만 적는다. 실행하지 않았다면 이유를 명확히 쓴다.

테스트 미실행
- 사유: 문서 변경만 포함되어 별도 빌드 테스트는 수행하지 않음

또는:

테스트 미실행
- 사유: 로컬 Docker/MySQL 환경이 준비되지 않아 빌드 검증을 수행하지 못함

실패한 테스트도 숨기지 않는다.

테스트 실패
- 명령: npm run build
- 원인: 기존 node_modules EPERM unlink 오류
- 이번 변경과 직접 관련 있는지 추가 확인 필요

ZIP:ON 맥락 반영

MR 메시지는 단순 기술 변경만 적지 말고 ZIP:ON의 목적, MVP, 사용자 흐름, 기능 맥락을 고려해 작성한다.

예를 들어 ZIP:ON 프로젝트에서는 아래 흐름 중 어디에 영향을 주는지 설명한다.

- 주소 입력
- 주소 정제
- 법정동코드 변환
- 건축물대장 기반 물건 유형 판별
- 실거래가/공시가격/건축물 정보 조회
- 전세·월세 위험도 계산
- 추가 확인사항 및 계약 전 체크리스트 제공
- 관리자 페이지
- 커뮤니티 기능
- 인증/권한/JWT/Security
- 외부 공공데이터 API 연동

변경이 위 흐름과 무관한 문서나 설정 작업이라면 “제품 런타임 영향은 없음”처럼 영향 범위를 분리한다.

최종 보고 규칙

Codex가 푸시를 완료한 뒤 사용자에게 보고할 때는 최소한 아래 내용을 포함한다.

1. 푸시 성공 여부
2. 브랜치명
3. 커밋 범위 또는 주요 커밋
4. MR 메시지
5. 테스트/검증 결과
6. 미확인 사항

보고 예시는 아래와 같다.

푸시 완료했습니다.
 
- 브랜치: `feature/example`
- 주요 커밋: `abc1234 docs: add mr message guide`
- 테스트: 문서 변경만 포함되어 별도 빌드 테스트는 실행하지 않았습니다.
 
아래 내용을 MR 설명에 그대로 붙여넣으면 됩니다.
 
```md
# MR 제목
 
docs(agents): MR 메시지 작성 규칙 추가
 
# MR 요약
 
이번 MR은 푸시 후 Codex가 상세 MR 메시지를 반드시 제공하도록 문서 규칙을 추가합니다.
 
# 작업 배경
 
...
```

체크리스트

MR 메시지를 보내기 전에 아래를 확인한다.

  • 제목이 변경 내용을 구체적으로 설명한다.
  • 작업 배경이 “왜”를 설명한다.
  • 주요 변경사항이 영역별로 나뉘어 있다.
  • 테스트 결과가 실제 실행 여부와 일치한다.
  • 미실행 또는 미확인 항목이 숨겨지지 않았다.
  • 영향 범위에서 해당 없는 항목을 해당 없음으로 표시했다.
  • 리뷰어가 볼 포인트가 파일 목록보다 더 구체적이다.
  • 롤백 또는 복구 관점이 있다.
  • ZIP:ON의 위험진단 MVP 맥락과 충돌하지 않는다.

Learning path

  1. First read: 적용 시점, 기본 형식, 테스트 결과 작성 원칙
  2. Then inspect: AGENTS.md의 Required Skills
  3. Then run: git status, git branch --show-current, git diff --stat
  4. Then debug: 기준 브랜치, 테스트 미실행, 로컬 diff 기준 작성 여부를 명시했는지 확인
  5. Key concept to understand: 좋은 MR 메시지는 변경 목록이 아니라 리뷰 가능한 판단 기록이다

관련 문서