Claude Code의 .claude/ 유효기간이 만료되는 문제를 6개월간 운용하며 계속해서 고쳐나간 이야기
요약
Claude Code의 .claude/ 설정 파일이 비대해지며 규칙 준수 능력이 저하되는 문제를 해결하기 위한 메커니즘을 소개합니다. log, review, amend, eval의 4단계 스킬 루프를 통해 규칙을 스스로 갱신하고 품질을 유지하는 자동화된 관리 방법을 다룹니다.
핵심 포인트
- 정적인 규칙 추가 방식의 한계와 규칙 부패 문제 지적
- log-review-amend-eval로 이어지는 4단계 자동 개선 루프 구축
- 구조화된 JSON 로그를 통한 문제 원인 및 규칙 파일 특정
- 반복적인 수정 지시를 줄이고 출력 안정성을 확보하는 방법
TL;DR
.claude/
는 정비하는 순간부터 유효기간이 만료되기 시작합니다. 작성한 규칙이 지켜지지 않게 되고, 에이전트(Agent)가 서두 부분만 읽게 되며, 스스로 작성한 규칙을 잊어버립니다. 해결책으로서,
log → review → amend → eval
의 4가지 스킬(Skill)을 통해 로그(Log)를 기점으로 스스로 규칙을 계속해서 다시 쓰는 메커니즘을 구축했습니다. 6개월간 운용하며 로그 30개, review 6개, amendment 9개를 수행했습니다. 한 예로 「참고문헌 누락」 이슈(Issue) 발생률이
1/5 (20%) → 0/4 (0%)
까지 떨어졌습니다. 본 기사는 4가지 스킬 구성의 내용과, 루프(Loop) 자체가 부패한 순간에 대한 이야기입니다.
이런 증상을 겪고 계시지 않나요?
.claude/CLAUDE.md
나 .claude/agents/
를 정비했는데도, 다음과 같은 상황이 벌어지고 있지는 않나요?
- 매주 똑같은 수정 지시를 내리고 있다 ("문체가 다르다", "참고문헌이 누락되었다", "내부 링크 형식이 다르다")
- 규칙 파일(Rule file)이 비대해져서, 에이전트가 새로운 지시를 놓치게 되었다
- "규칙을 분명히 썼을 텐데"라고 생각하지만, 출력이 안정적이지 않다
- 규칙을 추가할 때마다, 다른 규칙이 지켜지지 않게 된다
이를 잘 해내고 싶어서 수개월 동안 시행착오를 겪어왔습니다.
본 기사는 그 대처에 관한 이야기입니다. .claude/
내부 내용으로 고민하고 계신 분들을 위한 내용입니다.
왜 "정적인 규칙"만으로는 부족하다고 깨달았는가
반년 전, .claude/teams/blog/ghostwriter.md
에 규칙을 계속 추가하고 있었습니다.
어느샌가 50 → 100 → 200행으로 점점 비대해지는데도, 매주 마치 약속이라도 한 듯 똑같은 수정 지시가 내려옵니다.
- "~다/이다 체로 되어 있으니, ~습니다 체로 고쳐줘"
- "참고문헌에 본문의 인용 논문이 누락되었어"
- "내부 링크가 상대 경로로 되어 있어, 절대 URL로 고쳐줘"
매번 ghostwriter.md에 덧붙여 써도, 다음 주에는 다른 곳에서 똑같은 증상이 나타납니다.
파일은 불어나는데 품질은 안정되지 않은 상태였습니다.
도중에 깨달았습니다.
추가하는 방식의 문제가 아니라, 규칙을 관찰하지 못하고 있었던 것이라는 사실을 말입니다.
사람이 머리로 관찰하면 잊어버립니다.
그래서 관찰 자체를 메커니즘화하기로 했습니다.
그것이 log → review → amend → eval
의 4가지 스킬 구성입니다.
4가지 스킬 구성의 내용
Observe（log）→ Inspect（review）→ Amend（amend）→ Evaluate（eval）
각 스킬은 .claude/commands/skill/{log,review,amend,eval}.md
에 위치해 있습니다. 순서대로 설명하겠습니다.
/skill:log
— 워크플로우(Workflow) 완료 시 반드시 출력하는 구조화된 로그(Structured log)
블로그 기사 1건을 다 썼을 때, 코스 교재 1개를 다 만들었을 때, SEO 리라이트(Rewrite) 1건을 마쳤을 때. 모든 완료 시점에 JSON 로그를 출력합니다.
.claude/skills/logs/2026-05-22_blog-new_001.json
내용은 다음과 같은 형태입니다 (발췌).
{
"id": "2026-05-22_blog-new_001",
"skill": "blog:new",
...
효과적인 항목은 corrections와 source_file 두 항목입니다. 스스로 수정 지시가 나왔을 때, 무엇이 원인이었으며 어떤 규칙 파일의 문제였는지를 반드시 남깁니다. 이것이 나중에 개선 대상을 특정하는 근거가 됩니다.
/skill:review
— 로그가 쌓이면 자동으로 실행되는 집계
로그가 5개 쌓이면 자동으로 실행됩니다.
하는 일은 집계와 분류입니다.
TOP ISSUES（당 기간 6개 로그）
1. link-builder.md 의 탐지/indexed 절차 부족 ... 3건/2로그 (recurring) [HIGH amend 후보]
2. GSC site_url 형식 403 .................... 2건 [memory화]
...
recurring (3회 이상 발생)이라고 판정된 이슈(Issue)가 다음 amend 후보가 됩니다.
이 부분은 머리로 기억하려고 하면 안 되며, 로그로부터 기계적으로 추출하게 합니다.
머리로 기억하고 있으면 인상이 강한 문제들만 골라내게 됩니다.
실제로는 미미하게 여러 번 발생하는 문제들이 서서히 품질을 좀먹고 있습니다.
/skill:amend
— 대상 파일을 실제로 다시 쓰는 작업
review에서 recurring(반복적)이라고 판정된 issue를 실제 규칙 파일(.claude/agents/나 .claude/teams/ 하위)의 Edit로서 적용합니다.
예를 들어 2026-03-31에 적용한 amendment(수정)는 다음과 같은 형태였습니다.
{
"target_file": ".claude/teams/blog/ghostwriter.md",
"issue": "본문 인용 논문이 참고문헌 섹션에서 누락됨",
...
이때 ghostwriter.md에 이 1개 섹션을 추가했습니다.
이후, 동일한 issue는 발생하지 않고 있습니다.
change_type은 8종류로 정의되어 있습니다. instruction_strengthening / instruction_addition / instruction_removal / instruction_reorder / output_format_change / tool_usage_change / trigger_refinement / workflow_change.
"더하기"뿐만 아니라 "순서를 바꾸기", "깎아내기"도 선택할 수 있도록 했습니다. 이것이 나중에 효과를 발휘합니다.
/skill:eval
— 효과를 검증하고, 효과가 없으면 롤백(Rollback)
amend 이후에 로그가 3회 이상 쌓이면, Before/After로 대상 issue의 발생률을 비교합니다.
VERDICT: ✅ EFFECTIVE
Issue: 참고문헌 누락
BEFORE: 1/5 (20%)
...
판정은 4단계입니다. EFFECTIVE / PARTIALLY_EFFECTIVE / INEFFECTIVE / HARMFUL.
HARMFUL(부작용으로 인해 다른 품질이 저하된 경우)인 경우에는 git checkout으로 롤백합니다.
루프 자체가 부패해버린 이야기
2026-05-23, link-builder의 수정을 "HIGH 우선순위로 amend 해야 함"이라고 review가 판정했습니다.
amend Step에 들어가서 증거(Evidence)를 수집하던 중, 1주일 전(5/16)에 동일한 amend가 이미 적용 완료되었다는 사실이 판명되었습니다.
직전에 중복 적용을 회피할 수 있었습니다.
왜 발생했을까요? review.md의 Step 2에서 "최신 amendments/ 디렉토리도 먼저 목록 확인하기"를 잊었기 때문입니다.
이것뿐이라면 단순한 절차 누락이지만, 고통스러운 점은 다음 사실입니다.
지난번(5/6)의 review에서도 똑같은 반성을 했음에도 불구하고, 이를 준수하지 못했습니다.
"다음부터는 amendments/를 먼저 보자"라고 review 리포트에 적어두고, 3주 후에 똑같은 사고를 일으켰습니다.
규칙을 작성한 사람(나 자신)이, 작성한 규칙을 잊어버립니다.
루프 자체가 부패하는 순간이었습니다.
영구적인 대책으로서, review.md의 Step 2 서두에 "반드시 ls .claude/skills/logs/amendments/를 실행한 후 recurring 판정을 내린다"를 명문화했습니다.
다음 review에서 이것이 효과가 있을지는 로그를 보기 전까지 알 수 없습니다.
이 메타(Meta)적인 실패는 기록으로 남겨둘 가치가 있다고 생각하여, 최신 review 리포트에도 자기 관찰로서 적어두었습니다.
약 반년 운용하며 알게 된 3가지 함정
1. 로그를 쓰는 것 자체를 잊어버림
워크플로 완료 시 /skill:log를 자동 실행하기로 약속되어 있지만, CLAUDE.md의 Lead 책무에 명시했음에도 누락되는 주가 있었습니다.
구현상의 대책으로서, CLAUDE.md에 "로그 기록은 워크플로의 최종 단계로 포함한다"라고 적고, 사용자에게 완료 보고를 하는 동시에 로그 요약(Summary)을 표시하는 형태로 만들었습니다.
그럼에도 누락됩니다.
수동으로 알아챌 수밖에 없다는 점은 인정하고 있습니다.
2. review를 해도 아무도 amend 하지 않는 주가 찾아옴
review 리포트를 작성하는 것에 만족해버려서, amend의 y/n 단계로 넘어가지 않는 주가 있습니다.
HIGH 제안이 남은 채로 새로운 주의 로그가 쌓여갑니다.
정신을 차려보면 "미처리된 amend 후보"가 쌓여가는 상태가 됩니다.
이것은 Lead(나 자신)의 판단력 문제이므로, 시스템만으로는 완전히 방지할 수 없습니다. /skill:eval 대시보드에 PENDING
의 수를 출력하도록 하여, 육안으로 쉽게 알아챌 수 있도록 했습니다.
3. 규칙 파일 자체가 비대해져서 새로운 규칙이 읽히지 않는 문제
instruction_addition으로 계속 amend(수정)하다 보면, 규칙 파일이 점점 비대해집니다.
결국 에이전트(Agent)가 파일의 앞부분만 읽게 되어, 뒤에 추가된 규칙들은 지켜지지 않게 됩니다.
대책으로서 change_type에 instruction_reorder(지침 재정렬)와 instruction_removal(지침 삭제)을 추가했습니다.
가끔씩 의식적으로 "순서를 바꾸거나" "삭제하는" amend를 수행하지 않으면, 비대화가 또 다른 품질 저하를 불러옵니다.
이는 .claude/CLAUDE.md나 MEMORY.md 본체에도 해당되는 이야기입니다.
항상 로드되는 파일이 상한선을 초과하면 부분 로드(Partial Load)가 발생하는 사고가 일어났기에, 별도의 파일(.claude/rules/memory-hygiene.md)로 사이즈 모니터링과 가지치기(Pruning) 규칙을 분리해 두었습니다.
설계 레벨의 교훈
약 반년 동안 운영하며 깨달은 세 가지가 있습니다.
- 정적인 규칙(한 번 쓰고 끝나는 것)은 최소한으로 유지한다. 부패해도 알아채지 못하기 때문이다.
- "규칙을 관찰하고 다시 쓰는" 메타 프로세스(Meta-process) 자체를 규칙화한다.
- 관찰은 인간의 머리가 아니라, JSON 로그에 맡긴다. 인간의 머리는 인상(Impression)에 휘둘리기 때문이다.
반년 동안 해보니, 올바른 규칙을 쓰는 것보다 규칙이 부패했을 때 알아챌 수 있는 메커니즘이 훨씬 더 효과적이라는 생각이 들었습니다.
Claude Code에만 국한된 이야기는 아니라고 생각합니다.
Cursor나 Cline, 그리고 그 외의 에이전트(Agent) 환경에서도 동일한 구조를 구축할 수 있을 것입니다.
로그를 남길 수 있는 곳과 규칙 파일을 수정할 수 있는 곳이 있다면 작동합니다.
오늘부터 구축할 수 있는 최소 구성
루프 전체를 한꺼번에 구축하려고 하면 지속하기 어렵습니다. 반년 동안 운영하며 느낀 점은, 최소 단위는 이 세 가지라는 것입니다.
- 워크플로 완료 시 로그를 남기기로 약속한다. 스키마(Schema)는 무엇이든 상관없습니다. 처음에는
CLAUDE.md에{date, skill, corrections[], errors[]}라고 한 줄 적는 것만으로도 충분합니다. - 로그가 5개 쌓이면, 스스로 검토하는 날을 정한다. 주 1회 고정된 시간대면 됩니다. 자동 실행(Trigger) 기능은 나중에 추가해도 됩니다.
- 동일한 issue가 3번 발생한 규칙 파일을 딱 한 곳만 수정한다. 한 번에 여러 곳을 건드리지 마십시오. 그러면 eval(평가)이 제대로 작동하지 않게 됩니다.
이것만으로도 "규칙을 쓰고 끝내는 것"에서 "관찰하고 계속해서 수정하는 것"으로 넘어갈 수 있습니다. 4개 스킬 구성으로 확장할 수 있을지는 운영하면서 결정해도 늦지 않습니다.
이어지는 이야기와 조금 더 세부적인 내용
꽤 매니악한 이야기들을 써왔습니다.
어떻게든 AI를 잘 활용하고 싶어서 시도하고 시행착오를 겪은 기록입니다.
4개 스킬의 JSON schema, 자동 실행 조건, 9가지 amendment의 내용, 새틀라이트(Satellite) 관할별 집계 등에 관한 이야기는 나중에 별도의 글로 작성하겠습니다.
평소에는 개인 개발과 운영 설계의 관측 축을 중심으로 블로그와 X를 운영하고 있습니다.
"규칙을 쓰고 끝내는 것"이 아니라 "관찰하고 계속해서 수정하는" 스타일에 관심이 있다면, X (@rkpg10)도 팔로우해 주세요.
Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기