Claude Code 관련 글을 쓰다 보면 두 부류로 금방 갈린다.
하나는 처음 시작할 때 필요한 가이드북, 다른 하나는 새로운 변화가 생겼을 때 보는 업데이트 글이다.
둘을 섞어버리면 처음 보는 사람도 헷갈리고, 이미 쓰는 사람도 금방 stale을 느낀다.
직접 운영해보니 이 둘은 역할이 꽤 다르다.
가이드북은 기준점이고, 업데이트 글은 변화 로그다.
기준점이 없으면 업데이트가 흩어지고, 변화 로그가 없으면 가이드북이 늙는다.
그래서 Claude Code 운영 글은 가이드북과 최신 업데이트 글을 같이 굴려야 덜 망한다.
Quick Answer
Claude Code 운영 글은가이드북과업데이트 글을 분리해서 굴려야 한다.
가이드북은 설치, 구조, 기본 철학처럼 오래 가는 기준을 담고, 업데이트 글은 새 기능, 바뀐 동작, 실험 결과처럼 자주 변하는 내용을 담는다.
둘을 같이 굴리면 canonical 문서가 늙지 않고, 최신성도 놓치지 않는다.
이 글이 필요한 사람
- Claude Code를 쓰기 시작했는데 글 구조가 자꾸 하나로 뭉개지는 사람
- 가이드북을 만들었는데 금방 outdated가 되는 사람
- 새 기능이 나오면 기존 글을 고쳐야 할지 새 글을 써야 할지 헷갈리는 사람
- 설치기와 운영기를 같은 문서에서 싸우게 만든 사람
- 브랜드 허브와 최신 소식 둘 다 잡고 싶은 사람
지금 결론
가이드북은 변하지 않는 원칙을 담는다.업데이트 글은 바뀐 점과 실험 결과를 담는다.- 둘을 분리하면 유지보수 비용이 낮아진다.
- 가이드북만 있으면 낡고, 업데이트만 있으면 흩어진다.
- Claude Code는 변화가 빠르기 때문에 둘을 같이 가져가야 검색과 신뢰를 둘 다 잡는다.
한 줄로 줄이면 이거다.
기준점은 가이드북, 변동분은 업데이트 글이다.
왜 하나로 합치고 싶어질까
사람은 문서가 많은 걸 싫어한다.
그래서 자연스럽게 한 문서에 다 넣고 싶어진다.
특히 Claude Code처럼 빠르게 바뀌는 도구는 더 그렇다.
하지만 한 문서에 다 넣는 순간 다음 문제가 생긴다.
- 새 기능이 들어오면 글이 산만해진다
- 초보자에게 필요한 기준과 최신 소식이 섞인다
- 수정할 때 어디까지가 기본이고 어디부터가 변동분인지 헷갈린다
- 링크 하나만 틀어져도 전체 문서가 늙어 보인다
이건 나도 직접 몇 번 겪었다.
기본 구조를 설명하는 글에 최신 도구 사용기를 섞어버리면 처음 보는 사람은 따라가기 어렵고, 이미 아는 사람은 새 정보만 따로 찾게 된다.
가이드북과 업데이트 글의 차이
| 구분 | 가이드북 | 업데이트 글 |
|---|---|---|
| 역할 | 기준점 | 변화 기록 |
| 수명 | 길다 | 짧다 |
| 수정 빈도 | 낮다 | 높다 |
| 독자 기대 | 처음 시작할 때 길잡이 | 이미 쓰는 사람이 변화 확인 |
| 관리비 | 초반에 큼 | 누적되면 커짐 |
| 잘 맞는 예시 | 설치법, 구조, 철학 | 새 기능, 패치, 실험 결과 |
이렇게 보면 둘을 합쳐야 할 이유보다 분리해야 할 이유가 더 많다.
직접 운영해보니 어디서 차이가 가장 컸나
가이드북 쪽
가이드북은 AGENTS.md, SKILL.md, hooks, subagents처럼 기본 구조를 이해시키는 데 좋다.
이 글들은 한 번 잡아놓으면 꽤 오래 간다.
대신 너무 빨리 최신 세부사항까지 넣으면 망한다.
가이드북이 설명서가 아니라 릴리스 노트가 되어버리기 때문이다.
업데이트 글 쪽
업데이트 글은 새로운 동작, 바뀐 옵션, 실험 결과를 빠르게 회수하는 데 좋다.
이 글은 길어도 되지만, 핵심은 지금 바뀐 것이다.
이걸 가이드북 안에 다 넣기 시작하면 가이드북이 점점 무거워진다.
언제는 가이드북에 넣지 말아야 하나
아래 상황이면 새 업데이트 글로 빼는 게 낫다.
- 특정 버전에서만 의미가 있는 변화일 때
- 지금은 바뀌었지만 나중엔 또 바뀔 가능성이 클 때
- 실험 결과가 아직 확정이 아닐 때
- 초보자 길잡이보다 현업 업데이트가 먼저 필요한 주제일 때
즉 가이드북은 canonical이어야 하고, 변동은 업데이트가 담당해야 한다.
관리비는 어디서 생기나
이 구조의 장점은 분명하다.
근데 관리비도 분명하다.
- 두 문서를 관리해야 한다
- 내부링크를 더 신경 써야 한다
- 어떤 내용이 canonical인지 정해야 한다
- 업데이트 글이 가이드북보다 많아지면 정리 부담이 커진다
그래서 가이드북과 업데이트 글을 같이 굴릴 때는 무조건 연결 규칙이 있어야 한다.
예를 들면 이런 식이다.
- 가이드북 맨 위에 최신 업데이트 링크를 둔다
- 업데이트 글 맨 위에 canonical 가이드북을 둔다
- 바뀐 게 생기면 업데이트 글에만 먼저 적고, 검증되면 가이드북에 반영한다
이 규칙이 없으면 문서가 둘인데 기준은 하나도 없는 상태가 된다.
실수 TOP 5
1. 가이드북을 업데이트 노트처럼 쓰는 것
기준점이 흔들린다.
2. 업데이트 글을 canonical처럼 쓰는 것
나중에 최신 글이 너무 많아져서 무엇이 본체인지 헷갈린다.
3. 새 기능이 나올 때마다 기존 글 전체를 갈아엎는 것
수정 비용이 너무 커진다.
4. 내부링크 없이 둘을 따로 두는 것
분리만 하고 연결이 없으면 오히려 찾기 어렵다.
5. 유지할 사람 없이 문서만 늘리는 것
업데이트가 쌓일수록 stale debt가 쌓인다.
FAQ
가이드북과 업데이트 글을 몇 개 비율로 가져가야 하나
정답은 없지만, 기준점 하나에 업데이트 여러 개가 붙는 구조가 보통 자연스럽다.
둘을 하나로 합치면 안 되나
가끔은 가능하지만, Claude Code처럼 바뀌는 속도가 빠른 주제는 분리하는 편이 낫다.
업데이트 글은 어느 정도 길이가 적당한가
길이보다 변화가 분명한지가 중요하다.
새로 바뀐 것, 왜 바뀌었는지, 어떻게 쓰는지 이 셋이 있으면 된다.
가이드북은 언제 갱신하나
업데이트 글이 누적돼서 기준이 조금씩 변했을 때다.
즉 먼저 업데이트, 나중에 가이드북 반영이 보통 덜 꼬인다.
다음에 읽을 글
- Claude Code 자동화 용어 정리 2026 — Triage·Compound·LLM Wiki·Harness를 어디에 써야 안 겹칠까
- AI 업데이트 글은 왜 일간 메모로 쌓고 주간 허브로 묶어야 할까 2026 — Simon Willison식 운영 루프
- Claude Code 팀 온보딩 2026 — AGENTS.md·SKILL.md·hooks를 어떤 순서로 깔아야 덜 망할까
마무리
Claude Code는 계속 변한다.
그래서 글도 계속 바뀌어야 한다.
그렇다고 모든 글이 다 똑같이 변하면 안 된다.
기준점은 기준점대로, 변동분은 변동분대로 가는 게 맞다.
가이드북은 오래 가야 하고, 업데이트 글은 빨라야 한다.
둘을 같이 굴리면 검색도 잡고 신뢰도 잡는다.
이건 꽤 귀찮지만, 운영해보면 왜 필요한지 바로 체감된다.