규칙 문서 충돌 해결하기

📝 한줄 요약

같은 규칙을 두 문서에 쓰다 보니 한쪽만 업데이트되면 다른 쪽이 낡는 문제가 생겼어요. “원본 규칙”과 “구체적 템플릿”을 분리해서 해결했습니다.

👥 이런 분께 추천

• 팀 문서를 관리하거나 여럿이 같은 프로젝트에 쓰는 분

• 같은 내용이 여러 파일에 반복되는 상황을 정리하고 싶은 분

• “이 규칙을 어느 문서에 써야 하지?” 헷갈리는 분

진행 방법

1. 왜 문제가 생겼나

사례글 작성 규칙이 두 곳에 있었어요:

• AGENTS.md (줄 42~162): 사례글 시작 절차 4단계, 프론트매터 필드, 제목 번호 규칙

• CASE.md (줄 11~104): 같은 내용 반복, 추가로 템플릿 구조와 이미지 규칙

같은 규칙이 두 문서에 있으니, AGENTS.md를 수정해도 CASE.md가 안 따라가고, CASE.md를 수정하면 AGENTS.md와 어긋났어요.

ALT

한국어 한국어 한국어 한국어 한국어 한국어 한국어 한국어

2. 근본 원인: 역할 분담이 없었다

각 문서가 뭘 담당해야 하는지 정의가 없었어요.

두 역할을 섞어 놨으니 중복이 생긴 거예요.

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만 업데이트할 때 규칙을 실수로 바꾸지 않음

🛠 사용한 도구

배운 점

💡 핵심 교훈

1. 규칙이 두 곳에 있으면 언젠가는 한쪽이 낡는다

반복(DRY, Don’t Repeat Yourself) 원칙은 코드뿐 아니라 문서에도 적용돼요. 특히 “자주 바뀌는 규칙”은 한 곳에만 둬야 합니다.

2. 문서도 역할 분담이 필요하다

팀원이 늘거나 문서가 많아지면:

• 누가 뭘 수정할지 모르는 상황이 생김

• 규칙을 어디에 추가할지 헷갈림

• “어? 이거 이미 다른 데 있는데?” 하는 중복 발생

미리 역할을 정하면 그런 일이 줄어요.

3. 링크는 중복보다 낫다

완벽한 설명 대신 “상세는 A 참조”가 낫습니다:

• A를 한 번만 수정하면 됨

• 읽는 사람도 한 곳에서 최신 규칙을 봄

• 문서가 너무 길어지지 않음

적용할 점

🎯 결과

📋 다른 문서에 적용할 수 있는 패턴

1. “이 내용, 어디 다른 데도 있나?” 찾기

2. “이 내용은 자주 바뀌나?” 확인

3. 바뀐다면 한 곳에만 두고 링크로 참조

솔직한 소감

또 깨닫게 된 게, 문서도 코드처럼 “유지보수 비용”이 있다는 거예요.

처음엔 “아, CASE.md를 정리해야겠네” 생각했는데, 열어보니 복잡하더라고요. AGENTS.md와 CASE.md가 반복되면서 어느 쪽을 기준으로 고쳐야 할지 헷갈렸어요.

그런데 “원본”과 “설명서” 두 역할로 나누니 깔끔하더라고요. 이 방식이 팀이 커지면 더 빛날 거 같습니다. 지금은 저 혼자이지만, 누군가 여기 와서 사례글을 쓰려면 규칙은 AGENTS.md, 예시는 CASE.md를 보면 되니까요.