문서마다 역할 나누고 링크로 연결하기
2026.08.05
📓 학습일지 — "규칙은 한 곳에만 둔다"
날짜: 2026-08-05 주제: 두 문서에 같은 규칙을 중복시켜서 생긴 불일치, 그리고 그걸 고친 이야기
✅ 결론부터
규칙이 두 군데 있으면, 언젠가 반드시 한쪽이 낡는다. 해결책은 "완벽한 설명을 두 번 쓰기"가 아니라, 문서마다 역할을 나누고 링크로 연결하기였다.
오늘 겪은 문제는 사실 나한테도 낯설지 않다. 학원 운영 자료(강의안, 수강생 안내문)나 ASK 프로젝트 문서(개발 가이드, 사용법 문서)에서도 똑같은 함정에 빠질 수 있겠다는 생각이 들어서 기록해둔다.
🧩 무슨 일이 있었나
작성 규칙이 AGENTS.md와 CASE.md 두 문서에 거의 똑같이 들어가 있었다.
AGENTS.md: 절차 4단계, 필드명, 제목 규칙 (42~162줄)CASE.md: 위 내용 + 템플릿 구조, 이미지 규칙까지 (11~104줄)
한쪽을 고치면 다른 쪽은 그대로 남아있어서, 어느 게 "진짜 최신 규칙"인지 알 수 없는 상태가 됐다.
🔎 왜 이런 일이 생겼나 — 근본 원인
문서마다 역할이 정해져 있지 않았던 것이 진짜 원인이었다.
문서 | 원래 있어야 할 역할 | 실제로는 |
|---|---|---|
AGENTS.md | 필수 규칙만 (짧고 단단하게) | 규칙 + 절차가 뒤섞임 |
CASE.md | 작성법 · 템플릿 · 예시 | 규칙까지 다시 베껴 씀 |
→ 역할이 겹치니 내용도 겹치고, 내용이 겹치니 둘 중 하나는 필연적으로 뒤처진다.
🛠️ 어떻게 고쳤나
AGENTS.md = "규칙의 원본"으로 재정의 → 필드명, 값, 금지사항만 남김
예:
카테고리: 값은 w1~w4 또는 개인작업
CASE.md = "사용 설명서"로 재정의 → 템플릿·예시·이미지 규칙만 남기고, 규칙이 필요한 부분은 링크만 걸어둠
예:
필수 필드 (상세 규칙은 AGENTS.md 참조): title: 작업 N - 제목 형식
결과: AGENTS.md 하나만 고치면 CASE.md는 자동으로 최신 내용을 "참조"하게 됨. CASE.md만 손대다가 실수로 규칙을 바꿔버릴 위험도 사라짐.
⚠️ 시행착오
처음엔 "CASE.md만 정리하면 되겠지" 했는데, 두 문서 규칙이 겹쳐 있어서 어느 쪽이 기준인지부터 헷갈렸다.
한쪽만 손보는 방식으로는 근본적으로 해결이 안 됐고, "원본 규칙" vs "구체적 템플릿"으로 역할을 쪼개는 순간 실마리가 풀렸다.
💡 배운 점 3가지
DRY 원칙은 코드뿐 아니라 문서에도 적용된다 — 자주 바뀌는 규칙일수록 한 곳에만 둬야 한다.
문서에도 담당 역할이 필요하다 — 사람이 늘고 문서가 늘수록 "이건 어디에 적어야 하지?"라는 혼란이 커진다. 미리 역할을 정해두면 그 혼란이 줄어든다.
링크는 중복보다 낫다 — "상세는 A 참조" 한 줄이면, 한 곳만 고쳐도 모든 문서가 최신 상태를 유지한다.
🎯 내 상황에 적용해보면
돌아보니 나도 비슷한 구조를 여러 군데 갖고 있다.
ASK 프로젝트: 개발 규칙(코드 컨벤션, 환경변수 설정법)이 README와 별도 가이드 문서에 흩어져 있진 않은지 점검 필요
학원 운영 자료: 수강생 안내 규정(환불 규정, 출석 규정 등)이 안내문 · 카페 공지 · 계약서에 각각 따로 적혀 있다면, 규정이 바뀔 때마다 세 군데를 다 고쳐야 하는 구조 — 원본 하나 정해두고 나머지는 링크/참조로 바꾸는 게 안전할 것 같다.
🧭 다음에 할 일
내 문서들 중 "이거 다른 데도 있나?" 점검 (ASK repo 문서부터)
중복된 내용 중 "자주 바뀌는 것"만 골라내기
자주 바뀌는 건 원본 하나로 모으고, 나머지는 링크로 교체
로그인하고 댓글을 남겨 주세요
이런 식으로 규칙을 중복되지 않게 올바른 맥락으로 잘 넣을 수 있게 하는 거를 컨텍스트 엔지니어링이라고 해요. 지금 이미 잘 하고 계시고 이제 여기에 규칙으로 해야 될 거 규칙, 코드로 해야 될 건 코드로 무조건적으로 들어가야 되는 거는 훅 같은 걸로 강제하는 것까지 가면은 이제 하네스를 하게 되는 거죠




문서가 꼬일 때 “내용을 더 잘 정리하자”보다 먼저 “이 문서가 맡을 역할이 뭔가”를 정한 게 좋았습니다. 학원 안내문이나 프로젝트 README처럼 여러 사람이 참고하는 문서일수록, 원본 하나와 참조 문서를 나누는 습관이 나중에 꽤 큰 사고를 막아줄 것 같아요.