문서화를 세 번 포기한 사람이 /docs-init 스킬 하나로 유지하게 된 방법

복잡한 구조가 문서를 죽인다 — 살아남은 건 index.md와 log.md 단 두 파일이었다

“매번 정리하다 포기하거든.”

마이위키 아이디어를 처음 꺼내던 날, 제가 내뱉은 말이에요. 노션에 프로젝트 공간을 만들고, README를 정성껏 썼고, Obsidian 볼트도 세팅해봤습니다. 다 해봤고, 다 중단했어요. 공통점이 있었는데 — 만들 때는 의욕이 넘치고, 유지하는 건 아무도 안 한다는 거였습니다. 정확히는, 제가 안 했어요.

복잡한 문서가 죽는 이유

처음에는 잘 분류된 구조가 잘 정리된 프로젝트를 만든다고 믿었습니다. product/, architecture/, policy/, guide/, reference/, roadmap/ — 이름만 봐도 체계적인 느낌이 들잖아요. 그런데 두 달쯤 지나면 어떻게 되는지 아세요? 다 비어 있거나 낡아 있어요.

이유가 있습니다. 코드 짜다가 중요한 결정을 했을 때, “이걸 어느 폴더에 넣지?”를 고민하는 순간 이미 너무 무거워진 거예요. 게다가 프로젝트 두 개, 세 개를 운영하다 보니 .md 파일이 200개가 넘어가는데, 이게 정리가 아니라 파편화가 장소만 옮긴 거더라고요. 채팅에 흩어진 게 폴더에 흩어진 걸로 바뀐 것뿐이었어요.

문서를 관리하는 일이 실제 일보다 무거워지는 임계점이 분명히 있습니다. 그 선을 넘으면 아무도 안 해요.

살아남은 것들의 공통점

그래서 한 번 솔직하게 들여다봤어요. 어떤 프로젝트에서 어떤 파일이 끝까지 살아 있었는지. 결과가 꽤 명확했습니다. index.md와 log.md 두 파일이에요.

왜 이 둘이냐 — 실용적인 이유가 있습니다. 아무 때나 프로젝트를 열었을 때 “지금 이 프로젝트 어디 있지?”를 1분 안에 알 수 있어야 하는데, 현재 상태를 한 곳에 담은 index.md가 그걸 해줬어요. log.md는 ## [YYYY-MM-DD] feat | 한 줄로 append-only로 쌓는데, 무겁지 않으니까 계속 쓰게 되더라고요.

거기에서 원칙 하나가 나왔습니다. “현행화가 무거우면 아무도 안 한다.” 한 줄 append-only가 지속 가능한 최소 단위예요. 결정은 간단했어요 — 진입점은 고정하고, 타입 폴더는 내용이 생길 때 만든다.

/docs-init 스킬: 이 교훈을 코드로 굳히기

그런데 프로젝트가 늘어날수록 이 판단을 매번 수작업으로 하는 게 번거로웠어요. 새 프로젝트를 시작할 때마다 “이 프로젝트엔 어떤 폴더가 필요하지?” 고민하는 시간도 아깝고, 실수도 나고요.

그래서 Claude Code 스킬로 만들었습니다. /docs-init을 치면 Claude가 그 프로젝트를 읽고 필요한 것만 만들어줘요. 핵심 원칙은 두 가지입니다.

첫째, 진입 3종(index/todo/log)은 단일 파일 고정입니다. 흩어지면 현행화가 안 돼요. 이 세 파일은 어느 프로젝트든 항상 만들어요.

둘째, 빈 폴더는 두지 않습니다. 해당되는 폴더만 만들어요.

이게 실제로 어떻게 보이냐면 — 한새암 온라인 미술관 프로젝트에서 /docs-init을 한 번 실행했는데, 6개 타입 폴더 중 architecture/와 guide/ 두 개만 생성됐어요. product/ 폴더는 안 만들었습니다. 왜냐면 요구사항 문서가 없기 때문이에요. “있는 것만 만든다”가 눈에 보이는 순간이었습니다.

매번 직접 구조를 짜지 않아도 됩니다. 경험이 스킬에 결정(結晶)되면 다음 프로젝트도 같은 판단을 해요. Claude Code를 제대로 쓰는 것이 이런 의미이기도 합니다.

문서는 다음 세션의 준비입니다

잘 만든 index.md 하나는 오랜만에 프로젝트를 열었을 때 컨텍스트 복원에 1분이면 충분해요. 저는 이걸 경험하고 나서 관점이 바뀌었어요.

log.md는 뭘 했는지 까먹지 않으려고 쓰는 게 아니에요. 다음 Claude Code 세션에게 주는 인수인계서입니다. LLM은 새 세션마다 당신을 처음 만나거든요. 새 세션이 열릴 때 log.md를 읽으면 어디까지 왔는지 바로 알 수 있거든요. 에이전트 컨텍스트 끊김 문제를 문서로 푸는 방법이기도 해요.

문서화를 “나중에 정리하는 것”이 아니라 “작업과 같은 커밋에 묶는 것”으로 재정의하면 부담이 사라집니다. 코드 바꿨으면 log.md 한 줄 추가, index.md 상태 한 줄 업데이트 — 이 두 가지만 지켜도 프로젝트 문서가 살아있어요.

지금 작업 중인 프로젝트 하나에서 /docs-init을 실행해보거나, 없다면 docs/index.md 파일 하나만 만들어보세요. “지금 이 프로젝트는 어떤 상태인가”를 한 단락으로 쓰는 것부터 시작합니다. 거기서 낡지 않는 문서의 첫 페이지가 시작됩니다.

<- 이전 편: 스킬의 비밀: 자연어가 로직이 되는 순간 배경: LLM은 새 세션마다 당신을 처음 만난다 · 함께 보기: 에이전트 컨텍스트 끊김, second 브레인으로 풀기 · Claude Code 4레버 방법론