[4편] 공식 하나를 세 군데에 복사했다가 전부 틀렸습니다
카테고리: AI 기반 개발 / 문서 관리 태그: 문서관리, CLAUDE.md, 단일소스, AI개발, 기술부채, 1인개발 시리즈: 도구 열 개를 정리하고 방법론 하나를 남겼다 (4/8)
검사 관점을 바꿨더니 다른 게 보였습니다
3편에서 "경계면 교차 확인"이라는 관점을 가져왔습니다. "존재하는가"가 아니라 "양쪽이 같은 걸 기대하는가" 를 보는 겁니다.
이 눈으로 코드를 훑다가, 정작 더 심각한 걸 발견했습니다. 코드가 아니라 문서 쪽이었습니다.
AI한테 시켰더니 문서가 계속 늘었습니다
프로젝트 루트가 이랬습니다.
프로젝트 루트/
├── CLAUDE.md ← AI 도구 A용 작업 지침 (21KB)
├── DESIGN.md ← 디자인 지침
├── BLOG_SYSTEM_STANDARD.md
├── system.md
├── manual.md
├── codex/ ← AI 도구 B용 지침
└── docs/
└── (또 뭐가 있음)왜 이렇게 됐냐면, 도구가 바뀔 때마다 문서를 하나씩 더 만들었기 때문입니다.
"이 도구는 루트의 이 파일을 읽는다더라" → 만듦 "저 도구는 저 폴더를 본다더라" → 또 만듦 "이번엔 다른 이름으로 읽는다더라" → 또 만듦
1편에서 AI 도구를 열 개 깔았다고 했죠. 문서도 같은 속도로 늘어난 겁니다. 각각 만들 때는 합리적이었고, 합쳐놓고 보니 재앙이었습니다.
실제로 터진 사고
가장 크게 터진 건 키워드 분석 점수 공식이었습니다.
이게 세 개 파일에 각각 복사돼 있었습니다.
파일 A: Score = (검색량 × 0.6) - (경쟁도 × 0.4) ← 옛날 공식
파일 B: Score = (검색량 × 0.5) - (경쟁도 × 0.5) ← 중간에 바꾼 것
파일 C: Score = ... 그리고 아래에 또 Score = ... ← 두 개가 같이 있음여기서 진짜 문제는 숫자가 다르다는 게 아닙니다.
세 파일 전부에 "최종 확정"이라고 적혀 있었습니다.
그리고 파일 C는 옛 공식과 새 공식을 동시에 담고 있었습니다. 같은 문서 안에서 자기 자신과 모순되고 있던 겁니다.
이게 왜 무서운 일이냐면
AI에게 "이 공식대로 코드 고쳐줘"라고 시키면 AI는 자기가 읽은 파일의 공식을 씁니다.
어느 파일을 읽느냐에 따라 결과가 달라집니다. 그런데 셋 다 "최종 확정"이라고 적혀 있으니 AI는 자기가 틀렸다는 걸 알 방법이 없습니다.
저도 몰랐습니다. 세 파일을 나란히 열어보기 전까지는요.
왜 복사하면 반드시 갈라지는가
이유는 단순합니다.
공식을 수정할 일이 생김
↓
파일 A를 고침
↓
"파일 B에도 있었나?" ← 이걸 기억해야 함
↓
기억 못 함
↓
파일 B는 옛날 값 그대로 남음
↓
6개월 뒤: 어느 게 맞는지 아무도 모름핵심은 "기억해야 한다"는 단계가 끼어 있다는 겁니다.
사람이 기억해야 하는 규칙은 반드시 언젠가 깨집니다. 저는 3개월 만에 깼습니다.
그리고 이건 AI를 쓸수록 더 빨리 깨집니다. AI는 "이 내용도 여기 넣어두면 좋겠네요" 하면서 친절하게 복사본을 늘려주기 때문입니다.
그래서 이렇게 정리했습니다
원칙 딱 하나
공식·수치·필터값은 한 파일에만 둔다. 나머지는 "→ system.md 3절 참조"로 링크만 건다.
값을 두 곳에 두는 순간 갈라집니다. 예외가 없습니다. 그래서 물리적으로 한 곳에만 둡니다.
문서를 6개로 확정
역할을 명확히 나누고, 겹치는 걸 전부 없앴습니다.
| 문서 | 역할 | 언제 읽나 |
|---|---|---|
docs/agent.md |
작업 지침 · 루프 · 완료 조건 | 항상 먼저 |
docs/system.md |
시스템 구조 + 스펙 단일 소스 | 코드 수정 전 |
docs/design.md |
관리자 UI 디자인 시스템 | UI 작업 전 필독 |
docs/manual.md |
운영 매뉴얼 (고객용) | 기능 동작 확인 |
docs/changelog.md |
날짜별 작업 이력 | "왜 이렇게 됐지?" 추적 |
docs/todo.md |
작업 목록 | 작업 시작·종료 |
공식과 수치는 전부 system.md 한 곳으로 몰았습니다.
다른 문서에서는 참조 링크만 겁니다.
루트 지침 파일은 포인터로 격하
21KB짜리 루트 CLAUDE.md를 15줄로 줄였습니다.
# 작업 지침 위치
이 프로젝트의 작업 지침은 **`docs/agent.md` 하나**다. 먼저 그 문서를 읽는다.
| 문서 | 역할 |
|---|---|
| `docs/agent.md` | 작업 지침 · 루프 · 완료 조건 · 절대 규칙 |
| `docs/system.md` | 시스템 구조 + 스펙 단일 소스 |
| ...
이 파일에는 지침 내용을 넣지 않는다.
AI 도구가 루트에서 자동 로딩하기 때문에 남긴 포인터일 뿐이다.
도구별로(claude/codex/gemini 등) 문서를 나누지 않는다."내용을 넣지 않는다" 는 문장을 문서 안에 박아뒀습니다. 안 그러면 또 늘어납니다. 저도 늘리고 AI도 늘립니다.
재밌는 건, 3편에서 기각한 harness도 똑같은 원칙을 쓰고 있었다는 겁니다.
"CLAUDE.md에 넣지 않는 것: 에이전트 목록, 스킬 목록, 디렉토리 구조, 실행 규칙 상세. CLAUDE.md는 포인터(트리거 규칙) + 변경 이력만 담는다."
도구는 안 썼는데 결론은 같았습니다.
문서 규칙 5개를 못 박았습니다
1. 공식·수치·필터값은 한 파일에만. 나머지는 참조 링크.
2. 날짜 섹션(## 2026-XX-XX)을 지침 문서에 쓰지 않는다. 이력 문서로 간다.
3. 문서와 코드가 충돌하면 코드가 옳다. 문서를 고친다.
4. "최종 확정"이라 쓰지 않는다. 확정은 코드가 하고 문서는 따라간다.
5. 도구별로 문서를 나누지 않는다. 갈라지면 반드시 서로 모순된다.3번과 4번이 특히 중요합니다
3번: 코드가 옳다
문서와 코드가 다를 때 사람은 본능적으로 "문서가 맞으니 코드를 고쳐야지"라고 생각합니다.
그런데 실제로 돌아가고 있는 건 코드입니다. 문서는 누가 언제 왜 그렇게 적었는지 모릅니다. 코드는 최소한 지금 동작한다는 사실이 검증돼 있습니다.
충돌하면 코드가 정답이고, 문서를 고칩니다.
4번: "최종 확정"을 쓰지 않는다
이게 제일 아팠던 교훈입니다.
"최종 확정"이라고 적으면 그 문서를 다시 안 봅니다. 검증 대상에서 빠집니다. 그래서 낡은 채로 영원히 남습니다.
세 파일에 다 "최종 확정"이 적혀 있었던 게 우연이 아닙니다. 확정이라고 적었기 때문에 아무도 다시 안 본 겁니다.
이제 안 씁니다.
정리 결과
━━━ 정리 전 ━━━
루트 문서 5개 + codex/ + docs/ 안에 또 여러 개
같은 공식 3중복 (전부 "최종 확정")
자기 자신과 모순되는 문서 1개
AI 도구별로 지침이 갈라짐
━━━ 정리 후 ━━━
docs/ 아래 6개로 확정, 역할 중복 0
공식·수치는 system.md 단 한 곳
루트 지침 파일은 15줄 포인터
도구 구분 없음. 어떤 AI가 와도 같은 문서를 읽음이렇게 해놓으니 어떤 AI 도구를 붙여도 헤매지 않습니다.
루트에서 포인터를 읽고 → docs/agent.md로 가고 → 필요한 문서로 갑니다.
랜딩 페이지가 하나 생긴 셈입니다.
남는 이야기
첫째, 복사는 반드시 갈라집니다. 예외 없습니다.
"두 곳에 있으면 편하니까"는 3개월짜리 편함입니다. 그다음부터는 평생 부채입니다. 값은 한 곳에, 나머지는 링크. 이거 하나만 지켜도 절반은 막힙니다.
둘째, "최종 확정"이라고 쓰면 그 문서는 죽습니다.
확정 도장을 찍는 순간 검증 대상에서 빠집니다. 낡아도 아무도 안 봅니다. 확정은 코드가 하고, 문서는 코드를 따라갑니다.
셋째, AI를 쓸수록 문서 관리가 더 중요해집니다.
사람은 문서가 좀 어긋나도 "아 이건 옛날 거네" 하고 감으로 거릅니다. AI는 못 거릅니다. 읽은 대로 믿고 그대로 코드를 짭니다.
AI에게 일을 맡길수록, AI가 읽는 문서가 곧 사양서가 됩니다. 문서가 갈라져 있으면 AI가 갈라진 코드를 만들어냅니다.
그런데 여기까지 해놓고 며칠 뒤에 이런 생각이 들었습니다.
"이 문서 6개, 다음 프로젝트에서 쓸 수 있나?"
5편에서 그 이야기를 하겠습니다.
이전 편: [3편] 그래서 30분만 열어보기로 했습니다 다음 편: [5편] 블로그용 지침서는 홈페이지 개발에 못 씁니다
이 글은 실제 운영 중인 시스템의 문서 체계를 정리한 기록입니다. 정리 결과: 문서 6개 확정 · 공식 3중복 해소 · 루트 지침 21KB → 15줄
댓글 0