문서와 체인지로그 자동화가 매주 수작업이 되는 이유#
커밋과 변경 파일에서 릴리스에 포함할 내용을 모으고 사용자에게 필요한 설명으로 바꾸는 일은 반복하기 쉽습니다. 일정한 커밋 메시지 규칙은 분류에 도움이 되지만, 규칙이 없어도 기록을 조사해 초안을 요청할 수 있습니다.
커밋을 모으는 일과 게시할 내용을 결정하는 일은 다릅니다.
| 입력 또는 결정 | 초안 작성에 활용 | 사람이 확인할 것 |
|---|---|---|
| 릴리스 범위 | 이전 태그와 대상 커밋 사이의 기록 수집 | 포함·제외된 변경과 기준 태그 |
| 커밋 메시지 | 변경 주제별 분류의 단서 | 메시지와 실제 코드 변경의 일치 여부 |
| 변경 파일과 diff | README와 릴리스 노트 수정 후보 | 사용자에게 영향을 주는 변경과 누락 |
| 게시 대상 | 공개용 문구와 내부 메모 구분 | 민감 정보, 호환성, 게시 승인 |
Git 공식 문서는 git log A..B가 B에서 도달 가능하지만 A에서는 도달할 수 없는 커밋을 나열한다고 설명합니다. 커밋 메시지 규칙은 변경 분류에 도움이 되지만 필수는 아닙니다. 출처 확인: 2026-11-01.
- 이전 릴리스 태그와 이번 대상 커밋을 명시하고, 비공개 정보의 공개 범위를 정합니다.
- Mirr Code에 해당 범위의 커밋과 변경 파일을 조사하고 변경 유형별 초안을 작성하되, 불확실하거나 확인하지 못한 항목을 표시해 달라고 요청합니다. 기능 구현 가이드처럼 변경 범위와 유지할 내용을 함께 전달하세요.
- 담당자가 diff와 테스트 결과를 대조해 누락·중요 변경·호환성을 확인한 뒤 승인하고 게시합니다. 외부 게시 도구의 연결과 권한은 별도이며, 초안 작성이 자동 게시를 뜻하지 않습니다.
추가 검증 필요: 실제 Mirr 초안과 사람이 쓴 릴리스 노트를 비교한 기록은 없습니다.
Before / After: 문서와 체인지로그 자동화의 현재 비용과 자동화 후 결과#
수작업으로 커밋을 하나씩 살펴보는 대신 범위를 지정해 초안 작성을 요청할 수 있습니다. 다만 생성된 초안이 실제 변경을 빠짐없이 설명하는지는 사람이 확인하세요.
추가 검증 필요: 동일 릴리스에서 수작업과 생성 초안의 누락·수정량 비교는 수행하지 않았습니다.
단계별로 하기: 입력 규칙 → 실행 → 검증#
위의 순서대로 릴리스 범위를 정하고 초안을 요청한 다음 실제 변경과 대조합니다.
요청 예시: “v1.0.0부터 v1.1.0까지 변경된 파일과 커밋을 근거로 사용자에게 영향을 주는 변경을 정리해 줘. 게시하지 말고 확인이 필요한 문구를 표시해 줘.” 태그는 예시이며 실제 저장소의 범위로 바꿔야 합니다.
README 자동 업데이트: 갱신 범위와 diff 검증#
README 자동 업데이트는 게시가 아니라 검토할 초안 변경으로 시작하세요. 릴리스 노트는 특정 버전의 변경을 설명하지만 README는 현재 사용자가 프로젝트를 시작하는 방법을 안내합니다. 커밋 요약을 그대로 붙이는 대신 달라진 사용법의 근거를 찾아 해당 부분만 갱신합니다.
| 변경 근거 | README 수정 후보 | 검증할 자료 |
|---|---|---|
| 실제 설치·실행 경로 변경 | 지원 환경, 설치와 시작 명령 | 패키지·빌드 설정과 승인된 실행 결과 |
| API·옵션 변경 | 예제·입력·환경 변수 설명 | 현재 코드·테스트·공식 API 문서 |
| 파일·문서 이동 | 상대 링크·이미지·목차 | 대상 버전의 경로와 렌더된 링크 |
| 지원·기여 절차 변경 | 도움받는 곳과 기여 안내 | 현재 유지보수·지원 문서 |
- 읽는 사람과 대상 버전을 정하고 갱신할 README의 경로·섹션, 바꾸지 않을 설명과 기존 사용자 편집을 기록합니다. 이미 스테이징한 수정과 추적되지 않은 새 문서도 먼저 보관·확인하세요.
- 실제 코드·패키지 설정·변경 diff에서 근거를 찾습니다. Mirr에는 “설치와 사용 예시에서 현재 코드와 어긋난 부분만 제안하고 근거 경로를 적어 줘. 라이선스·지원·성능 약속은 임의로 바꾸지 마”처럼 범위를 제한해 요청할 수 있습니다.
- 초안 변경 뒤 파일별 diff로 범위를 확인합니다. 다음 코드 블록은 저장소의
README.md가 대상일 때의 미실행 검토 명령 예시이며 다른 위치라면 정확한 경로로 바꿉니다.
git diff -- README.md
git diff --cached -- README.md
git diff --check -- README.md
- 첫 명령은 작업 트리와 인덱스, 둘째는 인덱스와 HEAD를 비교하므로 둘 다 확인합니다. 새 비추적 README는 이 diff에 나오지 않을 수 있어 파일 자체도 살펴보세요.
--check는 공백·충돌 표식 검사이며 내용의 정확성 검증이 아닙니다. - README를 렌더해 상대 링크·이미지·목차를 확인하고 설치·사용 명령은 승인된 격리 환경에서 대상 버전으로 검증합니다. 실행할 수 없다면 이유와 필요한 조건을 기록하세요. CI에서 diff 검사를 하더라도 문서를 자동 커밋·push·게시할 권한까지 준 것은 아닙니다. 검토한 변경만 별도로 승인합니다.
근거: Git diff 공식 설명, GitHub README의 역할·상대 링크(2026-11-02 확인). 실제 README 변경 전후 diff, 명령 검증과 게시 결과는 아직 없습니다. 이 절차가 새 라이선스·성능 수치·지원 약속을 생성할 근거는 아닙니다.
검증: 테스트 출력과 체크리스트#
릴리스 범위의 커밋과 diff, 관련 테스트 결과를 초안과 대조하고 확인하지 못한 내용은 따로 남겨 두세요.
추가 검증 필요: 대상 저장소에서의 명령 출력, 생성 초안, 사람의 검토 결과와 게시 이력은 아직 확보하지 못했습니다.
주의할 점과 한계#
커밋 메시지에 정해진 규칙이 있더라도 메시지만으로는 변경의 영향이나 누락을 모두 판단할 수 없습니다.
커밋 제목만으로 변경 효과를 단정하지 말고 코드와 릴리스 범위를 함께 확인하세요. 외부 게시를 포함한 변경은 /rewind로 자동 취소되지 않습니다.
내용이 빠졌다면 기준 태그와 대상 커밋이 맞는지, 범위에 포함된 실제 diff를 다시 확인하세요. 내부 작업이 사용자 기능처럼 적혔다면 공개 대상과 영향 범위를 재분류합니다. 릴리스 노트의 링크·명령도 대상 버전에서 확인하고, 존재하지 않는 테스트 결과나 태그를 추가하지 마세요.
커밋 범위와 배포 범위를 혼동하지 않기#
릴리스 노트를 만들 때는 먼저 기준 태그와 대상 커밋을 확정하세요. 브랜치의 최신 커밋이 실제 배포 대상과 같지 않을 수 있습니다. A..B의 커밋 목록은 도달 가능성의 차이이고 두 버전 사이의 파일 차이와도 읽는 목적이 다릅니다. 중간에 추가했다가 되돌린 기능은 커밋 제목에 남아도 최종 버전에 없을 수 있습니다. 메시지 목록, 최종 diff와 실제 배포 범위를 함께 검토해야 하는 이유입니다.
태그 이름은 설명 자료지만 조사할 때는 해당 커밋 식별자도 기록하는 편이 좋습니다. 태그가 없으면 임의로 새 태그를 만들지 말고 승인된 기준 커밋을 사용하세요. 저장소가 얕은 이력만 가진 환경이라면 범위에 필요한 기록이 있는지도 확인하세요. 부족한 이력을 가져오는 동작은 네트워크 작업이므로 실행 환경과 권한을 따릅니다. 이 글은 실제 릴리스 태그를 생성하거나 원격 저장소를 변경하지 않습니다.
| 발견한 변경 | 공개 노트에 쓸 판단 | 내부 기록에 남길 것 |
|---|---|---|
| 새 사용자 기능 | 실제 제공되는 동작과 사용 조건 | 관련 코드·검사·미확인 범위 |
| 결함 수정 | 사용자가 겪던 조건과 바뀐 결과 | 재현과 수정 확인 근거 |
| 내부 리팩토링 | 사용자 영향이 있으면 그 영향만 설명 | 유지한 계약과 검증 범위 |
| 되돌린 변경 | 최종 버전에 없으면 제공 기능으로 쓰지 않기 | 원래 변경과 되돌림의 관계 |
| 보안 관련 수정 | 공개 범위와 시점을 담당자 검토 | 민감한 세부 내용의 별도 처리 |
이 표는 분류 규칙의 예입니다. 커밋 접두어가 fix라고 반드시 공개할 버그 수정인 것은 아니고 chore라고 사용자 영향이 없는 것도 아닙니다. 메시지를 초안의 단서로 쓰되 실제 변경을 확인하세요. 사용자에게 필요한 행동이 있다면 먼저 적습니다. 설정을 바꿔야 하는지, 기존 사용법이 유지되는지와 미지원 조건이 무엇인지가 내부 작업 목록보다 중요할 수 있습니다.
초안을 사용자의 언어로 고치는 방법#
“내부 파서 정리”라는 커밋 제목만으로 사용자는 무엇이 달라졌는지 알기 어렵습니다. 실제로 잘못된 입력에서 오류가 더 구체적으로 표시되는 변경이라면 그 조건과 결과를 설명하세요. 다만 테스트하지 않은 효과를 덧붙이면 안 됩니다. 속도가 빨라졌다거나 안정성이 높아졌다는 문구는 측정이나 검증 범위가 있어야 합니다. 기능 이름을 바꾸는 편집과 기능이 실제 제공되는지 확인하는 검토를 나눕니다.
같은 기능의 여러 커밋은 한 항목으로 묶을 수 있습니다. 묶을 때 중요한 제한이나 후속 되돌림이 빠지지 않았는지 봅니다. 반대로 서로 다른 사용자 영향을 하나의 긴 문장에 합치면 확인하기 어렵습니다. 항목마다 근거 변경과 사용자의 행동을 연결하세요. 불확실한 항목에는 확인 질문을 남기고 실제 기능처럼 게시하지 않습니다. AI가 자연스럽게 쓴 문장도 근거가 없으면 초안일 뿐입니다.
README는 현재 시작 방법을 설명하는 문서#
설정 예시를 고쳤다면 문장만 읽지 말고 그 예시가 설명하는 입력과 출력 경로를 쌍으로 검토하세요. 상대 경로의 기준이 현재 작업 폴더인지 설정 파일 위치인지에 따라 사용자가 결과를 찾는 곳이 달라집니다. 기본값이 적용되는 조건도 빠뜨리지 않습니다. 명령을 실행하지 않았다면 코드로 확인한 조건과 실행 검증이 남은 조건을 구분합니다. 링크 존재 검사는 예시가 실행됐다는 증거가 아니며 실제 환경 변수 값이나 비밀 파일을 문서에 넣을 필요도 없습니다.
사람 검토를 자동화 흐름 안에 넣기#
초안 생성 뒤에는 변경 담당자가 기능·호환성·누락을 확인하고 공개 담당자가 표현과 정보 공개 범위를 확인하는 흐름을 검토할 수 있습니다. 한 사람이 두 역할을 맡더라도 항목은 나눠 기록하세요. 문서 생성이 성공했다는 자동 검사와 내용이 정확하다는 승인은 다릅니다. 링크 검사나 맞춤법 검사로 실제 제품 동작을 증명할 수 없습니다. 확인한 본문의 버전이나 해시를 남기면 나중에 수정된 초안과 승인본을 구분하기 쉽습니다.
자동 게시를 붙이는 작업은 별도입니다. 게시 대상, 권한, 검토한 커밋과 본문이 같은지 확인하고 실패·중복 게시를 처리해야 합니다. 외부 산출물을 실행 코드로 취급하지 않으며 PR 제목이나 본문을 셸에 직접 삽입하지 않는 설계를 검토하세요. 게시 권한과 모델 인증을 검증 없이 같은 작업에 몰아주지 않습니다. 이 글은 실제 CI 게시나 Mirr 무인 인증을 수행한 기록이 아닙니다.
잘못 게시한 내용을 정정할 때#
공개 후 오류를 발견하면 원래 게시본과 변경 내용을 확인하고 해당 서비스에서 승인된 정정 절차를 따릅니다. 로컬 문서를 되돌렸다고 외부 릴리스 노트나 알림이 자동으로 바뀌지는 않습니다. 이미 전달된 메시지와 사본도 있을 수 있습니다. 어떤 버전의 설명이 틀렸는지, 사용자에게 필요한 추가 행동이 있는지 명확히 적으세요. 단순 오탈자와 사용법·호환성 오류는 영향이 다릅니다.
정정 문구는 오류의 영향을 설명하세요. 가령 결과 폴더 안내만 틀렸고 생성된 데이터는 바뀌지 않았다면 “저장 위치 설명을 바로잡았다”고 적고 데이터 수정까지 했다고 쓰지 않습니다. 반대로 합계 규칙이 잘못 안내됐다면 영향을 받는 버전과 재처리 필요 여부를 담당자가 확인하세요. 실제로 확인하지 않은 사용자 영향은 단정하지 않습니다. 정정 대상은 문서인지 코드인지, 이미 배포한 파일인지 나눠야 필요한 행동을 독자에게 전달할 수 있습니다.
병합·되돌림이 있는 릴리스의 누락 확인#
다음은 실행하지 않은 가상의 릴리스 추적표입니다. BASE와 TARGET은 설명용 기준점이며 실제 태그가 아닙니다. 그 사이에 CSV 입력의 빈 금액 오류를 고친 변경, 예약 실행 기능 추가와 그 전체 되돌림, 내부 함수 이름 변경이 있다고 가정합니다. 다른 작업 브랜치에는 Excel 내보내기가 있지만 TARGET에는 병합되지 않았다고 정합니다. 이 조건에서 사용할 포함·제외 판단은 「변경 후보」 표와 같습니다.
| 변경 후보 | 범위와 최종 상태라는 가정 | 릴리스 초안의 결정 | 결정에 필요한 근거 |
|---|---|---|---|
| 빈 금액을 실패로 처리 | 범위 안이며 최종 코드에도 남음 | 검증 대기 표지를 붙여 수정 항목 후보로 남김 | 파서의 차이와 재현 테스트 |
| 예약 실행 추가 | 범위 안에서 추가 후 완전히 되돌림 | 제공 기능 목록에서 제외 | 추가·되돌림의 관계와 최종 파일 차이 |
| 내부 함수 이름 변경 | 범위 안이며 공개 결과는 유지 | 사용자 노트에서는 보통 제외, 개발 기록에는 남김 | 호출 계약과 검사 결과 |
| Excel 내보내기 | 다른 브랜치에만 있고 대상에는 없음 | 이번 릴리스에서 제외 | 대상 커밋에서의 파일·기능 존재 여부 |
| 금액 오류 문구 번역 | 수정과 같은 사용자 조건을 설명 | 같은 수정 항목으로 묶을지 검토 | 문구가 실제 수정 범위와 일치하는지 |
빈 금액 수정이 코드에 남아도 실행하지 않은 테스트 결과를 초안에 붙일 수는 없습니다. 이 경우 항목은 검증 대기로 남깁니다. 예약 실행의 일부만 되돌렸다면 표의 가정과 달라지므로 남은 동작을 다시 조사해야 합니다. 내부 이름 변경에 직렬화 필드나 외부 호출자의 계약 변경이 섞였다면 내부 전용이라는 분류도 다시 해야 합니다.
이 표에서 Excel 내보내기는 릴리스 노트의 누락이 아니라 대상 범위 밖입니다. 출시 예정 목록을 따로 만들 수는 있지만 그 항목을 현재 제공 기능과 섞으면 안 됩니다.
문서 자동화의 재실행을 검토하기#
재실행에서는 이전 생성 초안, 사람이 검토한 문서와 새로 생성한 초안을 구분하면 충돌을 설명하기 쉽습니다. 가령 생성 문구의 “예약 실행 지원”을 사람이 “이번 버전에서는 제외”로 정정했는데 같은 입력으로 다시 생성하면 잘못된 주장이 돌아올 수 있습니다. 단순히 새 파일로 덮어쓰지 말고 무엇이 자동으로 다시 만들어졌고 무엇이 사람의 사실 정정이었는지 비교하세요. 앞에서 설명한 스테이징·미스테이징·비추적 파일의 보관은 그대로 전제합니다.
| 이전 생성본과 사람 수정본의 관계 | 새 초안에서 관찰할 차이 | 채택 판단 |
|---|---|---|
| 사람은 표현만 고침 | 같은 사실을 다른 문장으로 다시 생성 | 사실이 같으면 팀 문체를 유지할지 선택 |
| 사람이 범위 밖 기능을 제외 | 새 초안에 그 기능이 다시 들어옴 | 대상 범위의 근거가 바뀌지 않았다면 재삽입 거부 |
| 사람이 검증 대기 표지를 추가 | 새 초안에서 통과로 바뀜 | 실제 검사 자료가 없으면 대기 유지 |
| 이후 코드에 새 수정이 들어옴 | 이전 문구에 없던 사용자 영향 후보 | 기존 정정과 분리해 새 변경 근거부터 검토 |
이 비교는 자동 병합 알고리즘을 실행한 기록이 아닙니다. 검토자가 문장을 채택할 이유를 남기는 방식입니다. 다시 생성할 때 입력 범위와 프롬프트도 기록하면 같은 잘못된 항목이 되살아나는 원인을 찾기 쉽습니다. 단순히 문장을 더 자연스럽게 바꾸기보다 누락한 제외 조건을 생성 입력에 반영해야 합니다. 사람이 고친 결과를 새로운 제품 기능이나 테스트 통과의 근거로 삼지는 않습니다.
다음에 읽을 것#
조사 중 오류가 생기면 관련 명령과 출력에서 민감한 정보를 제거한 뒤 원인을 살펴보세요.
오류 원인 찾기에서 로그를 공유하기 전 민감한 정보를 지우는 방법을 참고하세요.
관련#
편집 메모 (2026-11-02): 커밋 규칙과 게시 승인 FAQ, 누락 진단을 보충했습니다. 실제 릴리스 태그의 명령 출력·생성 초안·사람의 수정본과 체인지로그 화면은 여전히 없습니다.