만들기가 쉬워지면 안 만드는 것이 일이 된다: AI 문서의 신호대소음비

한줄 요약: AI가 문서를 대신 써 주면 만드는 비용이 0에 가까워집니다. 그러면 문서의 가치는 “얼마나 만들었나”가 아니라 “무엇을 안 만들었나”로 결정됩니다. 신호대소음비에서 신호를 키우는 것보다 소음을 줄이는 쪽이 훨씬 쌉니다. 저는 프로젝트 루트에 둘 수 있는 md 이름을 다섯 개로 고정하고, 문서를 갱신형과 기록형으로 갈랐고, 그 검사를 에이전트가 아니라 스크립트에 맡겼습니다. 이 글은 그 규칙을 정하기까지의 실측과 판단입니다.

목차

1. 실측: 세션이 길어지면 md가 늘어난다
2. 신호대소음비를 문서에 적용하면
3. 결정 하나, 갱신형과 기록형을 가른다
4. 결정 둘, 루트에 둘 수 있는 이름은 다섯 개
5. 결정 셋, 폴더 위치는 자료의 성격이 정한다
6. 검사는 에이전트가 아니라 스크립트가 한다
7. 만들지 않는 것 목록

1. 실측: 세션이 길어지면 md가 늘어난다

운영 중인 웹 서비스 프로젝트의 docs/ 폴더를 열어 봤습니다. 두 달 동안 에이전트와 세션을 돌린 결과입니다.

같은 현상이 세 프로젝트에서 반복됐습니다.

• 강의 프로젝트: 차수가 늘 때마다 docs/plan/ 아래 계획 문서가 새로 생기고, 같은 강의의 구조 문서가 PRODUCTION-PLAN.md, DIAGRAM-PLAN.md, STRUCTURE.md로 갈라짐
• 웹 서비스: 위 화면 그대로. living document라고 선언한 개요 문서가 두 달간 안 고쳐짐
• 자동화 허브: 루트에 ARCHITECTURE.md, registry.md, README.md, automation-inventory.md가 나란히 놓여, 지금 참인 설명이 어디 있는지 파일 이름만으로는 알 수 없음

공통점은 하나입니다. 에이전트는 문서를 만드는 데 망설임이 없고, 사람은 그 문서를 지우는 데 망설입니다.

2. 신호대소음비를 문서에 적용하면

신호대소음비는 비율입니다. 분자를 키우거나 분모를 줄이면 올라갑니다.

항목	문서에서 무엇인가	올리는 방법
신호 (분자)	지금 참인 상태를 적은 문서	잘 쓰기. 비싸고 느림
소음 (분모)	옛 판, 중복 설명, 읽는 사람 없는 파일	안 만들기, 합치기, 지우기. 싸고 빠름

AI 이전에는 분자를 키우는 게 일이었습니다. 문서 하나를 쓰는 데 반나절이 걸리니 소음이 생길 틈이 없었습니다. 지금은 반대입니다. 프롬프트 한 줄이면 문서가 나오니 분모가 알아서 불어납니다.

그래서 결정을 세 개로 줄였습니다. 셋 다 안 만들기에 관한 결정입니다.

3. 결정 하나, 갱신형과 기록형을 가른다

문서는 두 종류뿐입니다. 시간이 지나면 고쳐야 하는 것과, 쓴 순간 멈춰야 하는 것.

갱신형: 같은 파일을 덮어쓴다

• 대상 지금의 구조, 현재 상태, 규칙 ARCHITECTURE.md, STATUS.md 상단, CLAUDE.md
• 방식 같은 파일을 고친다 판 번호를 붙인 새 파일 금지. 리뷰 결과도 별도 파일이 아니라 본문에 반영
• 이력 git이 가진다 지난 판이 필요하면 커밋 이력에서 본다

파일 하나에 최신 상태 하나

기록형: 쓴 순간 멈춘다

• 대상 회의록, 감사, 세션 인계, 외부에서 받은 원본 docs/2026-09-11-주제.md, docs/handoff/, references/
• 방식 날짜 접두로 새 파일을 쌓는다 파일이 늘어나는 것이 정상. 서브폴더는 handoff/ 하나
• 이력 고치지 않는다 뒤에 이름이 바뀌어도 과거 기록 안의 인용은 그대로. 고치면 역사 왜곡

날짜 접두로 쌓이기만 한다

이 구분이 서면 “PRD와 기획서를 어디에 두는가” 같은 질문이 사라집니다. PRD(만들 것을 정의한 기획 문서)는 지금의 구조를 말하는 문서이므로 갱신형이고, 갱신형은 ARCHITECTURE.md 하나이므로 거기에 합칩니다.

• 마이그레이션 계획, 카탈로그처럼 “지금 어떻게 되어 있나”를 말하는 문서는 전부 기존 갱신형 문서에 붙임
• 백로그, 스크립트가 만드는 인벤토리처럼 항목이 쌓이는 것은 문서가 아니라 데이터. SQLite 같은 파일 하나짜리 데이터베이스로
• 원래 STATUS.md와 LOG.md를 나눴다가 합침. 1인 운영에서는 파일 두 개를 따로 갱신하는 규율이 안 지켜짐

4. 결정 둘, 루트에 둘 수 있는 이름은 다섯 개

프로젝트 루트의 md는 이름을 고정합니다. 새 이름이 필요하다는 생각이 들면 그것이 곧 소음 신호입니다.

파일	성격	갱신 방식	내용
CLAUDE.md	갱신형	덮어씀	규칙과 요약만. 고객 요구나 계약 조건은 넣지 않음
ARCHITECTURE.md	갱신형	덮어씀	지금의 구조. PRD, 기획서, 명세, 기능 설명이 전부 이 파일
STATUS.md	갱신형 + 추가형	상단 덮어씀, 로그는 붙임	현재 상태와 진행 로그
registry.md	갱신형	덮어씀	허브 전용. 자식 프로젝트 목록과 상태
README.md	갱신형	덮어씀	외부 공개용 소개. 선택

허브와 일하는 프로젝트는 세트가 다릅니다.

• 자식 프로젝트를 소유만 하는 허브: CLAUDE.md + registry.md만. 여기에 ARCHITECTURE.md가 생기면 허브가 구현을 들고 있다는 신호
• 여러 프로젝트가 가져다 쓰는 공용 자산 허브(디자인 시스템 등): 예외. 구현을 담는 것이 정상
• 자식, 건별, 상시, 실험 프로젝트: CLAUDE.md + ARCHITECTURE.md + STATUS.md

5. 결정 셋, 폴더 위치는 자료의 성격이 정한다

루트 밖은 폴더 이름이 자료의 성격을 말합니다. 어느 폴더에 둘지 고민이 되면 성격을 잘못 판정한 것입니다.

자료 성격	위치	갱신 방식
외부에서 받은 원본 (메일 첨부, 고객 문서, 계약서)	references/	불변
우리가 남긴 시점 기록 (회의록, 감사)	docs/YYYY-MM-DD-주제.md	기록형
에이전트 간 세션 인계	docs/handoff/	기록형. docs/의 유일한 서브폴더
완성 산출물 (강의자료, 보고서, 원고)	materials/, reports/	갱신
기능 하나의 설명	ARCHITECTURE.md 안의 절	갱신. 파일을 따로 만들지 않음

docs/ 안에 research/, reports/ 같은 카테고리 폴더를 두지 않습니다. 1절의 실측이 그 결과입니다. 카테고리를 만드는 순간 그 폴더가 관리 안 되는 계층이 됩니다.

6. 검사는 에이전트가 아니라 스크립트가 한다

규칙을 정한 뒤 처음에는 CLAUDE.md에 적어 두고 에이전트에게 지키라고 했습니다. 안 됐습니다. 원래 문제가 “세션이 길어지면 에이전트가 규칙을 잊는다”였는데, 검사를 다시 에이전트에게 맡기니 같은 구멍이 그대로 남았습니다.

그래서 검사를 훅 스크립트로 옮겼습니다. 에이전트가 파일을 쓰려는 순간에 끼어들어, 프로젝트 루트에 허용목록 밖 이름으로 새 md를 만들면 사용자에게 묻습니다.

판단이 필요 없는 결정론적 검사, 그러니까 “파일 이름이 허용목록에 있는가” 같은 질문은 스크립트가 맞는 층입니다. 규칙 문서에도 그 한계를 같이 적어 뒀습니다.

보안 경계가 아니라 사고 방지턱이다. Bash heredoc이나 스크립트로 직접 쓰면 이 훅으로 못 잡는다. (운영 규칙 문서 project-docs.md, 2026-09-11)

에이전트가 우회하려면 할 수 있습니다. 목적은 우회를 막는 게 아니라, 즉흥적으로 손이 가는 순간에 한 번 멈추게 하는 것입니다.

7. 만들지 않는 것 목록

이 규칙에서 실제로 일하는 부분은 금지 목록입니다.

만들지 않는 것

• 판 번호 파일 PRD-v0.1.md, PRD-v0.2.md 같은 파일을 고침. 이력은 git
• 기능별 md scripts/기능.md ARCHITECTURE.md의 절로
• 카테고리 폴더 docs/research/, docs/reports/ docs/는 평평하게, 서브폴더는 handoff/ 하나
• 목록 md BACKLOG.md, 인벤토리 md 데이터는 SQLite 같은 데이터 파일로
• 에이전트별 규칙 파일 AGENTS.md CLAUDE.md 하나를 여러 에이전트가 읽게 설정
• 허브 안의 구현 소유형 허브의 ARCHITECTURE.md 구현과 산출물은 자식 프로젝트로

새 이름이 필요하다는 생각이 들면, 먼저 기존 파일의 절로 쓸 수 있는지 본다

규칙은 앞으로 만드는 것에만 적용합니다. 1절의 프로젝트도 한꺼번에 옮기지 않았습니다. 옛 문서를 만나면 그때 참조 범위를 확인하고 병합하거나 삭제합니다. 정리 자체가 또 하나의 소음이 되면 안 되기 때문입니다.