에이전트 파일 점검하기
TMT요약: 코딩 에이전트의 설정에는 반감기가 있습니다. 모델은 좋아지고, 하네스에는 새 기능이 붙고, 코드베이스는 바뀌는데, 예전 버전을 보고 써 둔 지시문만 그 자리에 남습니다. 최근 연구를 보면 개인화된 스킬이 주는 이득은 일관되지 않습니다. 그래서 저는 요즘 몇 주에 한 번씩 Claude의 /doctor를 돌리고, 메모리는 따로 점검하고, 지시문마다 그 자리를 지킬 이유를 다시 증명하게 합니다.
스킬 파일을 어떻게 다뤄야 하는지, CLAUDE.md와 AGENTS.md는 어떻게 관리해야 하는지를 두고 혼란이 꽤 많다고 느낍니다. 지난 몇 달 동안 트위터에서 개발자들이 주고받는 이야기를 읽으면서 특히 그랬습니다. 스킬과 CLAUDE.md, AGENTS.md 파일을 최신 상태로 유지하는 일이 큰 고충이라는 말이 자주 나옵니다. 에이전트를 원하는 방향으로 이끌려고 이 파일들을 쓰지만, 공식 권고 기준이 200줄인데도 그 안에 맞추기가 어렵다는 사람이 많습니다. 파일을 가볍게 유지하기가 힘들고, 토큰 비용은 올라가고, 이것저것 계속 덧붙이다 보면 오히려 에이전트가 더 나빠질 수도 있습니다.
제가 읽은 공식 가이드는 CLAUDE.md와 스킬, 훅을 두어 달에 한 번씩 주기적으로 지우고 정말 필요한 것만 다시 만들라고 합니다. 그런데 제가 겪어 보니 사람들은 그렇게 했다가 상태가 크게 나빠지지 않을지 두려워합니다. 지웠다가 품질이 확 떨어질까 걱정하고, 빠르게 되돌리거나 가볍게 시험해 볼 방법도 마땅치 않습니다. 모델과 함께 쓸 수 있는 설정 조합은 너무나 많습니다. 그래서 이 조언이 실제로는 그렇게 간단하지 않은데도 쉽게 시도해 볼 수 있는 것처럼 들리기도 합니다. 물론 이런 마크다운 파일과 관행이 낡아서 도움보다 해가 되는 경우도 있습니다. 다만 모델과 하네스가 실제로 훨씬 좋아진다는 점에서, 이 조언에 담긴 취지에는 분명 무언가가 있다고 생각합니다.
저는 스킬을 좋아합니다. 그래도 비판은 타당합니다.
저는 개인적으로 에이전트 스킬을 아주 좋아합니다. 저와 친구 몇 명은 어느 정도 반응을 얻은 에이전트 스킬 패키지를 관리하고 있습니다. 저는 소프트웨어 개발 수명주기(SDLC)에 초점을 맞춘 Agent Skills를 관리하고, 제 친구 폴 바카우스는 디자인에 초점을 맞춘 Impeccable을 관리합니다. 코딩 에이전트와 함께 스킬을 쓰는 개발자들의 반응은 대체로 꽤 좋습니다. 범용 모델을 특정 분야 전문가로 바꿔 주는 좋은 추상화라는 평가를 받고, 여러 코딩 에이전트와 하네스에서 두루 잘 동작합니다. 그래서 사람들이 좋아합니다.
비판 가운데 타당한 것도 있습니다. 당연히 아주 다른 분야의 사람들이 각자 스킬을 쓰고 있고, 어떻게 써야 하는지를 알려 주는 제대로 된 지침서는 없습니다. 그래서 모두가 감으로 하고 있습니다. 서로에게서 배우려 하고, 커뮤니티에서 오는 피드백을 받아 계속 다듬습니다. 그래도 스킬 위생은 여전히 아주 중요합니다. 설명이 부실하거나 작업 절차가 다소 모호한 스킬 팩도 종종 보입니다. 그래서 저는 에이전트 스킬을 여전히 믿고, 가치가 크다고 생각합니다. 다만 지난 몇 달간 사람들이 스킬에 본격적으로 기대게 되면서, 스킬을 점검하는 일도 점점 중요해졌습니다.
어느 날이든 여러 프로젝트나 작업을 동시에 돌리고 있을 수 있습니다. 그중 어떤 작업에는 새로 나온 커뮤니티 스킬을 시험해 보거나, 직접 스킬을 만들어 붙여 보기도 합니다. 짐작하시겠지만 그렇게 두어 달이 지나면 로컬에 스킬이 쌓이고, 그걸 전부 쓰지는 않게 됩니다. 실제로 쓰는 건 아마 그중 일부일 겁니다.
공개된 스킬을 두고 오가는 해커뉴스 토론 스레드를 읽어 보면, 논쟁은 대체로 이렇습니다. 스킬에서 가치를 얻는 사람이 있고, 결과적으로 해롭다고 말하는 사람이 있습니다. 가치를 뒷받침하는 근거가 부족하다고 느끼는 사람도 있고, 잡음만 많이 늘린다고 보는 사람도 있습니다. 토큰 비용이 크고 믿을 만하지 않다는 지적도 나옵니다. 여기에 타당한 피드백이 많다고 생각합니다. 모든 사람의 작업 방식에서 스킬이 실제로 이득이라는 걸 보여 줄 근거를 내놓기란 쉽지 않습니다. 그래도 도움이 된다고 말하는 사람이 많고, 동시에 내 프로젝트에 쓸 만큼 정말 유용한지 보여 달라는 식의 타당한 피드백이 나오는 경우도 많습니다.
에이전트 설정이 낡는 이유
사람들은 에이전트가 엉뚱한 방향으로 끌고 갈 때마다 CLAUDE.md와 스킬에 규칙을 하나 더 붙입니다. 저도 그렇게 해 왔습니다. 그러다 파일이 불어나면 지시를 따르는 정도가 떨어지고, 규칙을 더 붙이다 보면 품질이 오히려 나빠질 수 있습니다. 짧은 판단 지침이어야 할 파일을 결국 지식 베이스처럼 다루게 됩니다. 아주 전형적인 실수입니다.
AGENTS.md와 CLAUDE.md가 비대해지는 문제도 큽니다. 이제는 널리 인정되는 편이라고 봅니다. 실제 저장소를 대상으로 한 연구가 여러 번 있었고, 흔하게 나타나는 설정 문제들이 확인됐습니다. 컨텍스트 비대화(context bloat)가 흔하고, 스킬 누출(skill leakage)과 린트 누출(lint leakage)도 그렇습니다. 이런 연구에서 살펴본 에이전트 파일은 대부분 최소 한 가지 문제를 안고 있었습니다. 파일은 대체로 Anthropic이 권고하는 200줄을 넘기고, 어떤 것은 수백 줄에서 수천 줄까지 커져 세션마다 토큰을 낭비합니다.
저도 여기서 자유롭지 않습니다. 공유용이 아니라 제 환경에서 쓰려고 만들어 둔 CLAUDE.md 파일들을 들여다보면 200줄을 넘긴 것들이 있습니다. 제 파일에서도 반복해서 나타난 실패 유형이 몇 가지 있었습니다. 지나치게 긴 예시, README나 패키지 매니페스트, 스킬 파일에 이미 들어 있는 중복 내용, 에이전트가 실수할 때마다 규칙을 하나 추가하는 습관 같은 것들입니다. 그런 식의 증가는 계속 누적됩니다. 그래서 아주 집중적으로 접근해야 한다고 생각합니다. 또 CLAUDE.md나 AGENTS.md에서 너무 세세하게 지정하는 것이 정작 원하는 결과로 이어지지 않는 경우도 봤습니다.
숫자로 보면 이렇습니다. 인기 저장소 100곳을 살펴본 6월 연구에서 린트 관련 누출이 62%, 컨텍스트 비대화가 42%, 스킬 누출이 35%에서 발견됐습니다. 그리고 Anthropic은 컨텍스트 엔지니어링의 새로운 규칙에서, Claude 5 세대 모델을 위해 Claude Code 시스템 프롬프트의 80% 이상을 덜어냈는데도 내부 코딩 평가에서 측정 가능한 손실이 없었다고 밝혔습니다. 이 결과는 목표치가 아닙니다. 평가는 공개되지 않았고, 특정 하네스의 특정 모델에 해당하는 이야기입니다. 여기서 얻을 교훈은 지시문의 효용에도 유효기간이 있다는 것입니다. 그러니 먼저 보관해 두고, 반드시 항상 지켜져야 하는 규칙이라면 모델이 놓칠 수 있는 산문으로 남기지 말고 테스트나 훅, 권한으로 강제하십시오.
지난 몇 달 동안 정말 좋은 연구를 읽었습니다. 이 논의에 도움이 될 만한 실증 연구들입니다. 그중 일부를 글에서 꼭 다루고 싶었습니다. 이런 논문을 읽을 시간이 없는 분들도 있을 테니까요.
개인화된 스킬은 코딩 에이전트에 도움이 될까
저는 Claude Code나 Codex가 제가 일하는 방식을 조금씩 익혀 간다면 얼마나 유용할지 궁금했습니다. 저는 작은 변경을 선호할 수도 있고, 테스트를 특정 방식으로 돌리기를 원할 수도 있고, 관련 없는 코드를 에이전트가 리팩터링하지 않기를 바랄 수도 있습니다. 이 논문은 그런 상호작용 이력을 재사용할 수 있는 개인 스킬로 바꿔 보려 합니다. 놀라운 결과는 개인화가 그다지 도움이 되지 않았다는 것입니다. 한 개발자의 이력을 바탕으로 만든 스킬은 다른 사람에게서 빌려 온 스킬과 성능이 비슷했습니다. 여러 개발자의 이력을 모아 만든 범용 스킬이 전반적으로 더 유용했습니다.
많은 사람이 자기 작업 방식에 맞춘 스킬을 여러 개 갖추면 큰 차이를 만든다고 생각합니다. 그런데 일부 연구는 반드시 그렇지는 않다고 말합니다. 오히려 더 넓은 엔지니어링 관행, 커뮤니티 전반의 모범 사례에 기반한 스킬이 더 합리적이고 더 큰 가치를 낼 수 있다는 것입니다. 한 가지 덧붙이면, 개인화된 스킬이 가치를 더할 수 있는 지점은 특정 작업에 대한 예시를 더 많이 담고 있을 때입니다. 커뮤니티의 범용 스킬에도 그런 예시가 들어 있는 경우가 있습니다. 예를 들어 스케줄링과 관련된 문제를 다룬다고 해 봅시다. 스케줄링은 접근 방법도 여러 가지고 까다로운 부분도 많습니다. 제가 가진 스킬에 아주 구체적인 예시와 세부 사항이 담겨 있다면, 에이전트를 특정 방향으로 이끄는 데 도움이 될 수 있습니다. 반대로 스케줄링 기본 요소의 서식을 이런 모양으로 해 달라는 정도의 내용만 있다면, 그건 사실 별 도움이 되지 않습니다.
개인화는 비슷한 작업 여러 건에서 같은 선호가 반복될 때 더 유망해 보였습니다. 다만 실험이 LLM 기반 개발자 시뮬레이터를 썼으니, 확정된 결론이 아니라 가능성으로 받아들이는 게 좋습니다. 제 결론은 잘 만든 범용 스킬에서 출발해 개인 규칙을 조금씩 더해 가라는 것입니다. 한 번 언급했다는 이유만으로 어떤 선호를 에이전트의 영구 메모리에 올리지는 않겠습니다.
스킬 이야기로 돌아가면, 여러 회사와 대기업을 만나 보면 그쪽에서도 스킬의 가치를 높게 봅니다. 엔지니어 개인의 스킬도 유용하다고 보지만, 팀이나 조직 단위로 스킬 모음을 갖추면 가치가 복리로 쌓일 수 있다고 생각합니다. 이 점이 꽤 흥미롭습니다. 엔지니어링 문화, 컴플라이언스 규칙, 브랜드, 내부 도구의 특이한 점, 여러 사람과 여러 코딩 에이전트 사이에서 일관성을 어떻게 맞출지, 리뷰 절차와 환경 준비를 어떻게 할지 같은 것들이 거기에 담기게 됩니다.
컨텍스트 파일은 코딩 에이전트에 도움이 될까
저는 AGENTS.md나 CLAUDE.md 같은 파일을 코딩 에이전트의 운영 설명서처럼 써 왔습니다. 이 논문은 그런 파일이 실제로 Claude Code와 Codex가 더 많은 작업을 풀도록 돕는지 묻습니다. 실제 작업 17건을 288회 실행한 결과, 정확성에는 분명한 차이가 없었습니다.
그래도 컨텍스트 파일은 에이전트가 일하는 방식을 바꿨습니다. 어떤 저장소에서는 가이드가 전체 테스트 스위트가 아주 느리다고 경고해 두었습니다. Claude는 여기에 반응해 테스트 범위를 좁혀 실행하면서 시간을 덜 낭비했습니다. 기능을 구현하는 능력이 좋아진 것은 아니지만, 저장소의 작업 방식은 더 효율적으로 따랐습니다. 저는 이 구분이 유용하다고 봅니다. 컨텍스트 파일은 비용이 큰 명령, 자동 생성되는 파일, 아키텍처 경계, 프로젝트에 고유한 안전 규칙 같은 것을 에이전트에게 알려 줄 수 있습니다. 하지만 미묘한 설계 판단을 어떻게 내려야 하는지까지 가르치기는 어렵습니다. 아깝게 놓친 사례들은 대개 구현 판단의 문제였고, 저장소 설명을 더 늘렸다고 해서 풀릴 문제가 아니었습니다.
제 결론은 저장소의 컨텍스트 파일을 모델이 코드만 보고는 알기 어려운 것에 집중시키라는 것입니다. 어떤 검사를 어떻게 돌려야 하는지, 어떤 작업이 비용이 큰지, 무엇을 건드리면 안 되는지, 이 프로젝트의 특이한 관례가 어디에 있는지 같은 것들입니다. 깨끗한 코드를 쓰라는 일반론으로 채우지는 않겠습니다. 관련 연구 하나도 같은 방향을 가리킵니다. 코드 동작에 관한 질문 45개 가운데 산문 요약으로 답할 수 있었던 것은 4개였고, 소스 코드 자체로는 27개에 답할 수 있었습니다. 요약은 정작 중요한 세부를 뭉개기 때문입니다. 에이전트에게는 코드를 설명한 글이 아니라 실제 코드를 가리켜 주십시오.
제 환경을 점검하며 발견한 것
Claude Code에 doctor 명령이 들어온 게 반가웠습니다. 위생 점검에 좋은 명령입니다. 컨텍스트 비용에 비해 쓰이지 않는 스킬과 MCP 서버, 플러그인이 있는지, CLAUDE.md를 너무 세세하게 써 두지 않았는지, 느린 훅이나 잔재가 있는지 같은 것을 훑어 줍니다. 제 환경에서 doctor를 돌려 보고는, 완전히 잊고 있던 것들이 아직 남아 있는 걸 보고 놀랐습니다. 누가 물어봤다면 그게 아직 거기 있다고 짐작조차 못 했을 것들입니다. 그걸 시험해 본 적이 있다는 사실 자체를 잊고 있었습니다.
한 가지 예를 들겠습니다. 네다섯 달쯤 전에, 사람들이 살펴보고 있던 여러 글쓰기 스킬에 관심이 갔습니다. 이른바 안티슬롭(anti-slop) 스킬을 여러 사람이 실험하고 있었고, 저도 그중 여러 개를 시험해 봤습니다. 그런데 그걸 얼마나 많이 설치해 뒀는지 완전히 잊고 있어서 놀랐습니다. 전혀 모르고 있었습니다. 이것들이 함께 발동되고 있을까요? 아니면 하나가 다른 것보다 우선할까요? 아니면 전부 무시되고 있을까요? 그런 게 아직 남아 있다는 사실조차 알아채지 못하고 있었습니다. 그래서 그걸 점검한 게 아주 유용했습니다. 친구들이 만든 디자인 스킬 가운데 시험해 봤다가 잊어버린 것도 있었습니다. 지금은 커뮤니티가 품질 좋은 스킬 몇 개로 수렴한 경우도 있으니, 몇 달 전에 시험해 본 실험적인 것들보다 그런 스킬에 기대는 편을 택하겠습니다.
최근에 어떤 트윗을 봤습니다. 스킬을 점검하기 시작해서 250개에서 25개로 줄였다는 이야기였습니다. 어떻게 하면 스킬이 250개까지 쌓이는 걸까 싶었습니다. 정말 놀랍습니다. 그런데 커뮤니티 스킬을 이것저것 시험해 보다 보면 시간이 지나면서 쉽게 불어납니다. 에이전트를 헷갈리게 만들고 싶지는 않을 겁니다. 그러니 에이전트 환경도 주기적으로 검사하고 정리해야 합니다.
유용한 스킬을 설치하는 것과 그것을 계속 두는 것은 별개의 결정입니다.
양이 아니라 품질을 점검하기
스킬과 관련해 또 하나 중요한 건 품질을 확실히 챙기는 것입니다. Anthropic의 Skill Creator에도 이제 품질을 확인해 보기 위한 평가와 벤치마크 모드가 들어 있습니다. SKILL.md의 품질을 점검해 주는 좋은 커뮤니티 도구들도 있습니다. 설명이 충실한지, 발동 조건이 잘 잡혀 있는지, 단계와 예시가 분명한지 같은 것을 봅니다. 보안에 더 초점을 맞춘 점검 도구와 스킬 작성 모범 사례도 있습니다.
알아 둘 만한 이름 함정이 하나 있습니다. Claude Code에서는 세션 안에서 쓰는 /doctor가 설정 점검이고, 셸에서 실행하는 claude doctor는 설치 진단만 출력합니다. doctor가 상태 확인만 보여준다는 말이 나오는 이유입니다. 그리고 설치된 스킬이 프롬프트마다 본문 전체를 쏟아 넣는 것도 아닙니다. 탐색을 위해 이름과 설명만 로드되는데, 목록 예산의 기본값은 컨텍스트 창의 1%이고 본문은 호출될 때 로드됩니다. 저는 메모리도 /memory로 따로 점검합니다. 프로젝트 파일을 정리해 둔 뒤에도 자동 메모리에 낡은 선호가 남아 있을 수 있기 때문입니다.
주기적으로 점검하고, 지워 보며 확인하기
그래서 저는 몇 주에 한 번, 아니면 한 달에 한 번이라도 스킬과 환경 전체를 대상으로 doctor를 돌려 보고, 지금 하고 있는 것들을 점검하면서 무엇이 아직 유효한지 확인하는 데 큰 가치가 있다고 봅니다. 시간이 되면 한 걸음 더 나가 볼 수도 있습니다. 스킬을 지워 보거나, 에이전트에게 로컬 스킬은 하나도 쓰지 말고 순수한 모델과 하네스만으로 이 작업을 마쳐 보라고 지시해 보는 것입니다. 그리고 이 스킬들이 없어도 정말 괜찮은지 확인합니다. 그러고 나서 스스로 물어볼 수 있습니다. 이 스킬들은 지워도 되지 않을까? 그래도 괜찮지 않을까?
그런데 우리가 설치해 둔 스킬과 온갖 장치에 목발처럼 기대고 있을 때도 있는 것 같습니다. 지우는 게 위험하게 느껴지고, 모델과 하네스가 실제로 좋아졌다는 걸 믿지 못하기 때문입니다. 그래서 시험해 보고 배울 여지가 아직 많다고 생각합니다.
계속 위생을 챙기십시오. 품질과 보안을 점검하고, doctor 명령을 정기적으로 돌리고, 로컬 환경을 필요한 만큼만 구체적으로, 그러면서 최대한 가볍게 유지하십시오.