규칙 문서 충돌 해결하기
2026.08.03

📝 한줄 요약
같은 규칙을 두 문서에 쓰다 보니 한쪽만 업데이트되면 다른 쪽이 낡는 문제가 생겼어요. “원본 규칙”과 “구체적 템플릿”을 분리해서 해결했습니다.
👥 이런 분께 추천
팀 문서를 관리하거나 여럿이 같은 프로젝트에 쓰는 분
같은 내용이 여러 파일에 반복되는 상황을 정리하고 싶은 분
“이 규칙을 어느 문서에 써야 하지?” 헷갈리는 분
진행 방법
1. 왜 문제가 생겼나
사례글 작성 규칙이 두 곳에 있었어요:
AGENTS.md(줄 42~162): 사례글 시작 절차 4단계, 프론트매터 필드, 제목 번호 규칙CASE.md(줄 11~104): 같은 내용 반복, 추가로 템플릿 구조와 이미지 규칙
같은 규칙이 두 문서에 있으니, AGENTS.md를 수정해도 CASE.md가 안 따라가고, CASE.md를 수정하면 AGENTS.md와 어긋났어요.
2. 근본 원인: 역할 분담이 없었다
각 문서가 뭘 담당해야 하는지 정의가 없었어요.
문서 | 현재 | 원래 역할 |
|---|---|---|
AGENTS.md | 규칙 + 자세한 절차 | 필수 규칙만 (필드명, 값, 금지사항) |
CASE.md | 규칙 + 템플릿 + 예시 | 작성 방법만 (템플릿, 이미지, 체크리스트) |
두 역할을 섞어 놨으니 중복이 생긴 거예요.
3. 해결: 역할을 명확히 하고 한쪽은 참조만 하기
AGENTS.md: “규칙의 단원장”
필드명, 값, 금지사항만 씀
예: “
카테고리:값은 w1~w4 또는 개인작업”
CASE.md: “작성 방법의 설명서”
“상세 내용은 AGENTS.md 참조”로 링크만 붙임
대신 템플릿, 예시, 이미지 규칙은 상세히 씀
예: “프론트매터 예시 (주차 작업)”
구체적으로 이렇게 고쳤어요:
# CASE.md (수정 전)
## 프론트매터
**필수 필드:**
- `title`: `작업 N - 제목` 형식 (예: "작업 5 - 구글 폼 자동화하기")
- `date`: YYYY-MM-DD (예: 2026-07-28)
- `공개`: `true` (사례글은 항상 공개)
- (...AGENTS.md와 같은 내용 반복...)
# CASE.md (수정 후)
**필수 필드** (상세 규칙은 AGENTS.md 참조):
- `title`: `작업 N - 제목` 형식 (예: "작업 5 - 구글 폼 자동화하기")
- `date`: YYYY-MM-DD (예: 2026-07-28)
- `카테고리`: w1 | w2 | w3 | w4 | 개인작업 (그룹핑 결정자)
- `프로젝트`: 이 사례가 속한 프로젝트의 파일명 (영문 slug)4. 확인: 수정 후 결과
이제:
AGENTS.md 수정 → 규칙이 바뀜
CASE.md는 자동으로 최신 규칙을 봄 (링크 참조)
CASE.md만 업데이트할 때 규칙을 실수로 바꾸지 않음
🛠 사용한 도구
도구 | 역할 |
|---|---|
텍스트 에디터 | 두 문서 안에서 “규칙” vs “템플릿”이 어디 있는지 찾기 |
깃(Git) | 파일별 수정 이력 확인 (“AGENTS.md는 수정 안 했는데 CASE.md는 수정됐네?”) |
배운 점
💡 핵심 교훈
1. 규칙이 두 곳에 있으면 언젠가는 한쪽이 낡는다
반복(DRY, Don’t Repeat Yourself) 원칙은 코드뿐 아니라 문서에도 적용돼요. 특히 “자주 바뀌는 규칙”은 한 곳에만 둬야 합니다.
2. 문서도 역할 분담이 필요하다
팀원이 늘거나 문서가 많아지면:
누가 뭘 수정할지 모르는 상황이 생김
규칙을 어디에 추가할지 헷갈림
“어? 이거 이미 다른 데 있는데?” 하는 중복 발생
미리 역할을 정하면 그런 일이 줄어요.
3. 링크는 중복보다 낫다
완벽한 설명 대신 “상세는 A 참조”가 낫습니다:
A를 한 번만 수정하면 됨
읽는 사람도 한 곳에서 최신 규칙을 봄
문서가 너무 길어지지 않음
적용할 점
🎯 결과
항목 | 이전 | 이후 |
|---|---|---|
규칙 중복 | 2곳 | 1곳 (AGENTS.md) |
사례글 작성 절차 | 두 문서를 찾아 읽어야 함 | AGENTS.md 한 곳만 참조 |
규칙 수정 | 한쪽만 해서 다른 쪽 낡음 | 한 곳만 수정하면 반영됨 |
📋 다른 문서에 적용할 수 있는 패턴
“이 내용, 어디 다른 데도 있나?” 찾기
“이 내용은 자주 바뀌나?” 확인
바뀐다면 한 곳에만 두고 링크로 참조
솔직한 소감
또 깨닫게 된 게, 문서도 코드처럼 “유지보수 비용”이 있다는 거예요.
처음엔 “아, CASE.md를 정리해야겠네” 생각했는데, 열어보니 복잡하더라고요. AGENTS.md와 CASE.md가 반복되면서 어느 쪽을 기준으로 고쳐야 할지 헷갈렸어요.
그런데 “원본”과 “설명서” 두 역할로 나누니 깔끔하더라고요. 이 방식이 팀이 커지면 더 빛날 거 같습니다. 지금은 저 혼자이지만, 누군가 여기 와서 사례글을 쓰려면 규칙은 AGENTS.md, 예시는 CASE.md를 보면 되니까요.




중요한 부분을 잘 집고 넘어가셨네요. 문서들이 파편화되면 유지보수가 어렵기 때문에 잘 구조해 주면 좋습니다. 그리고 케이스 문서를 따로 관리하시는군요. 이것도 좋은 방법같아요. 스킬을 만들때도 비슷하게 적용학수 있겠네요.