끝에 계속 쌓이는 문서의 머지 충돌은 항목마다 파일을 나눠 없앤다

ADR 목록, 회피 패턴 모음, 변경 로그처럼 파일 끝에 항목이 계속 추가되는 문서가 있다. PR 두 개가 동시에 항목을 추가하면 두 PR 은 같은 끝줄을 건드리고, 머지할 때마다 충돌이 난다. 이 글은 단일 문서를 항목별 파일과 INDEX 로 나눠 이 충돌을 구조적으로 줄이는 방법을 정리한다. 나눈 뒤에도 남는 충돌, 번호와 참조를 지키는 방법, 나눈 결과를 검증하는 방법을 함께 다룬다.

충돌이 반복되는 구조

한 프로젝트에서 adr.md 하나에 ADR 을 계속 덧붙이는 방식으로 관리했다. 한 PR 이 ADR 028 을, 다른 PR 이 ADR 029 를 추가하자 두 변경이 파일 끝줄에서 충돌했다. 번호를 세는 카운트 줄이나 인덱스 줄이 있으면 양쪽이 모두 고쳐서 충돌이 하나 더 생긴다. 매 PR 마다 같은 자리가 겹치는 구조라서 충돌은 우연이 아니라 필연이다.

아래는 이 상황을 로컬 저장소에서 재현한 결과다. 같은 파일 끝에 각자 항목을 붙인 두 브랜치를 합치면 Git 이 자동으로 합치지 못한다.

$ git merge pr1
CONFLICT (content): Merge conflict in adr.md
Automatic merge failed; fix conflicts and then commit the result.

해법: 항목마다 파일 하나, 목록은 INDEX 로

docs/adr/
├── INDEX.md
├── 027-항목-제목.md
├── 028-항목-제목.md
└── 029-항목-제목.md

• 항목 하나를 파일 하나(NNN-slug.md)로 둔다. 새 항목은 새 파일이므로 본문에서는 충돌할 수 없다.
• INDEX.md 가 번호, 제목, 요약과 링크를 모은다. 단일 파일을 처음부터 끝까지 훑던 "한눈에 보기" 를 대신한다.
• 번호는 파일명에 유지한다. 기존에 쓰던 ADR-029 같은 참조 텍스트가 깨지지 않고, 029-*.md glob 으로 slug 를 몰라도 파일을 찾는다.
• 파일 자체가 주소가 되므로 단일 파일 안에서 쓰던 앵커(<a id=...>)가 필요 없다.
• 거대한 문서를 통째로 읽지 않고 INDEX 로 필요한 항목만 읽을 수 있어, AI 에이전트가 읽는 문서라면 토큰도 줄어든다.

남는 충돌

INDEX 의 목록에는 새 줄이 계속 붙으므로 같은 자리에서 충돌이 한 번 더 난다. 본문 충돌은 사라지고 INDEX 한 줄만 남는 것이다.

$ git merge p1
Auto-merging adr/INDEX.md
CONFLICT (content): Merge conflict in adr/INDEX.md

이 한 줄은 양쪽을 모두 남기면 되는 충돌이다. .gitattributes 에 adr/INDEX.md merge=union 을 두면 Git 이 양쪽 줄을 모두 보존해 합친다. 같은 재현 환경에서 이 설정을 넣고 합치자 충돌 없이 두 줄이 모두 남았다. 단 이 방식은 줄 순서를 번호순으로 정렬해 주지 않는다. 위 재현에서도 029 가 028 앞에 붙었다. INDEX 를 번호순으로 유지하고 싶으면 합친 뒤 정렬하는 단계를 따로 둔다.

나누기 전에 확인할 것

단일 문서를 나누면 "잘 찾아지는가" 가 가장 먼저 깨진다. 다음을 나누기 전에 확인한다.

• 기존 문서에서 항목을 가리키는 참조(예: 백여 곳에 흩어진 ADR-NNN 텍스트)가 번호만으로 계속 유효한가
• 이 항목을 추가하거나 갱신하는 스킬과 스크립트가 단일 파일을 전제하고 있지 않은가. 번호 중복을 검사하는 grep 이나 목록 동기화 스크립트가 해당한다.

나눈 결과의 검증

나눈 뒤에는 내용이 바뀌지 않았음을 다음으로 확인한다.

• INDEX 의 번호 집합과 개별 파일의 번호 집합이 양방향으로 모두 차집합 0 인가
• 나누기 전후의 헤더 수가 같은가
• 본문의 바이트가 보존됐는가

번호 점검용 grep 도 실제 파일 이름으로 확인해야 한다. 이 문제는 리뷰 봇이 제안한 명령과 정규식은 실제 데이터에 먼저 돌려 본다에서 다룬다.

나눈 뒤에 남는 위험

다른 브랜치가 아직 단일 문서에 항목을 추가하면서 같은 번호를 쓰면 번호가 겹친다. 병합 전에 대상 브랜치의 현재 번호와 충돌하는지 확인한다.

검증된 구조를 증상이 같은 곳에 옮긴다

이 방식은 새로 만든 것이 아니다. 같은 프로젝트의 회피 패턴 문서(pitfalls)는 이미 패턴 하나에 파일 하나와 INDEX 구조를 쓰고 있었고, 본문 충돌이 거의 없었다. 단일 adr.md 의 충돌을 보고 같은 구조를 ADR 에 옮긴 것이다. 한 곳에서 충돌 없이 동작하던 구조는 증상이 같은 다른 곳에도 그대로 적용해 볼 만하다.

공개 저장소 nhncloud-cli 도 docs/adr/INDEX.md 와 docs/pitfalls/INDEX.md 로 같은 구조를 쓴다. 이 저장소의 리뷰 워크플로는 에이전트가 INDEX 를 먼저 읽고 변경 유형에 맞는 파일만 고르게 한다. 자세한 내용은 GitHub Actions 로 PR 마다 AI 코드 리뷰를 자동으로 돌리는 워크플로 설계에 있다.

정리