에이전트 설정 파일, 주기적으로 점검하세요

지난 몇 달간 개발자 커뮤니티의 대화를 지켜보면서 스킬 파일, CLAUDE.md, AGENTS.md를 어떻게 관리해야 하는지에 대한 혼란이 상당하다는 걸 느꼈다. 스킬 파일과 CLAUDE.md/AGENTS.md를 최신 상태로 유지하는 게 너무 번거롭다는 얘기가 많다. 에이전트를 원하는 방향으로 이끌려고 이 파일들을 활용하는데, 공식 권장 기준이 200줄임에도 그 안에 담으려면 쉽지 않다는 것이다. 파일을 간결하게 유지하기가 어렵고, 토큰 비용은 늘어나며, 내용을 계속 추가하다 보면 오히려 에이전트 성능이 떨어지기도 한다.

공식 가이드에서는 몇 달에 한 번씩 CLAUDE.md와 스킬, 훅(hook)을 전부 삭제하고 정말 필요한 것만 다시 구성하라고 권한다. 하지만 실제로 해보면 망설임이 생긴다. '삭제했다가 품질이 크게 떨어지면 어쩌지?' 하는 걱정이 앞서고, 빠르게 되돌리거나 쉽게 테스트할 방법도 마땅치 않다. 모델에 적용할 수 있는 설정 조합은 수없이 많고, 막상 해보기엔 부담스럽다. 게다가 이런 마크다운 파일들과 관련 관행은 시간이 지나면 낡아버리고, 도움이 되기는커녕 오히려 걸림돌이 되는 경우도 있다. 그렇다고 모델과 실행 환경이 실제로 크게 발전한다는 이 조언의 핵심을 무시할 수는 없다.

스킬을 지지하지만, 비판도 귀담아듣는다.

필자는 에이전트 스킬을 적극 지지하는 편이다. 몇몇 지인과 함께 어느 정도 호응을 얻은 에이전트 스킬 패키지를 운영하고 있기도 하다. 필자는 SDLC(소프트웨어 개발 생명주기) 중심의 에이전트 스킬 팩을, 지인 Paul Bakaus는 디자인 중심의 Impeccable 팩을 관리한다. 코딩 에이전트에 스킬을 적용하는 개발자들 사이에서는 대체로 긍정적인 반응이 많다. 범용 에이전트를 특정 분야에 특화된 도구로 바꿀 수 있는 좋은 추상화 수단으로 여겨지고, 다양한 코딩 에이전트와 실행 환경에서도 잘 작동하기 때문이다.

물론 비판도 일부 타당하다. 다양한 사람들이 저마다 다른 도메인에서 스킬을 작성하다 보니, 뚜렷한 제작 기준이 없다. 모두가 시행착오를 거치며 서로에게서 배우고, 커뮤니티 피드백을 받아 끊임없이 개선하는 중이다. 그 과정에서 스킬 위생 관리는 여전히 중요한 과제로 남아 있다. 설명이 너무 빈약하거나 워크플로가 두루뭉술하게 기술된 스킬 팩도 적지 않다. 그럼에도 에이전트 스킬의 가치는 여전히 유효하다고 생각한다. 다만 지난 몇 달간 스킬에 대한 관심이 높아진 만큼, 스킬을 주기적으로 점검하는 일도 갈수록 중요해지고 있다.

하루에도 여러 프로젝트나 작업을 병행할 때, 새로운 커뮤니티 스킬을 써보거나 직접 스킬을 만들어보기도 한다. 그러다 보면 몇 달에 걸쳐 로컬에 스킬이 쌓이는데, 실제로 꾸준히 쓰는 건 그중 일부에 불과하다.

Hacker News의 공개 스킬 관련 스레드를 읽어보면 의견이 엇갈린다. 스킬에서 가치를 찾는 사람도 있고, 오히려 해롭다고 주장하는 사람도 있다. 효과를 뒷받침할 근거가 부족하다거나, 노이즈만 늘린다거나, 토큰 비용이 크고 신뢰하기 어렵다는 의견도 있다. 이런 피드백 중 상당 부분은 타당하다. 모든 워크플로에 걸쳐 스킬이 실제로 도움이 된다는 것을 증명하기는 쉽지 않고, 도움이 된다는 사람도, 실망했다는 사람도 모두 있다. "내 프로젝트에 정말 유용한지 보여달라"는 요구는 그래서 당연하다.

에이전트 설정이 낡아가는 이유

에이전트가 엉뚱한 방향으로 흘러갈 때마다 CLAUDE.md 파일이나 스킬에 규칙을 하나씩 추가하다 보면, 파일이 비대해지고 준수율이 떨어지며 품질도 결국 나빠진다. 짧은 의사결정 가이드여야 할 것이 방대한 지식 베이스로 변해버리는 것이다. 이건 아주 전형적인 실수다.

AGENTS.md와 CLAUDE.md의 비대화도 널리 알려진 문제다. 실제 저장소를 대상으로 한 여러 연구에서 흔히 나타나는 설정 문제들이 발견됐다. 컨텍스트 비대화, 스킬 누수(skill leakage), 린트 누수(lint leakage)가 대표적이며, 조사 대상 에이전트 파일의 대부분에서 최소 하나 이상의 문제가 발견됐다. 파일 길이는 대개 Anthropic이 권장하는 200줄을 넘어서고, 수백에서 수천 줄에 달하는 경우도 있어 매 세션마다 토큰을 낭비하게 된다.

필자도 예외는 아니다. 공유용이 아닌 개인 설정에서 직접 작성한 CLAUDE.md 파일들을 돌아봤더니, 역시 200줄을 넘긴 것들이 있었다. 자주 보였던 문제 패턴으로는 지나치게 긴 예시, README나 패키지 매니페스트 또는 스킬 파일에 이미 있는 내용의 중복, 에이전트가 오류를 낼 때마다 규칙을 추가하는 습관 등이 있다. 이런 식으로 쌓이면 걷잡을 수 없이 불어난다. CLAUDE.md나 AGENTS.md에 너무 세세하게 지정하는 것이 오히려 원하는 결과를 이끌어내지 못하는 경우도 봤다.

구체적인 수치를 보면, 6월에 발표된 연구에서 인기 저장소 100개를 분석한 결과 62%에서 린트 관련 누수, 42%에서 컨텍스트 비대화, 35%에서 스킬 누수가 발견됐다. The new rules of context engineering에서 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를 실행해보고는 완전히 잊고 있던 것들이 여전히 남아 있다는 사실에 놀랐다. 물어봤다면 남아 있을 거라고는 상상도 못 했을 것들이었다. 실험했다는 사실조차 잊고 있었다.

예를 들면 이렇다. 4~5개월 전쯤, 커뮤니티에서 화제가 됐던 다양한 글쓰기 스킬들을 이것저것 시험해봤다. 당시 'anti-slop' 스킬이 많이 나돌았고 여러 개를 설치했는데, 나중에 doctor를 실행해보니 그 수에 스스로 놀랐다. 이것들이 동시에 적용되고 있는지, 하나가 다른 것들보다 우선하는지, 아니면 전부 무시되고 있는지도 몰랐고, 아직 남아 있다는 것 자체를 잊고 있었다. 지인들이 만든 디자인 스킬도 시험해봤다가 잊어버린 것들이 있었다. 이제는 커뮤니티에서 어느 정도 검증된 고품질 스킬이 생겼으니, 몇 달 전에 시도했던 실험적인 스킬들보다 그쪽에 기대는 편이 낫다.

얼마 전 트위터에서 스킬을 점검했더니 250개에서 25개로 줄였다는 글을 봤다. 어떻게 250개나 쌓였냐고 의아할 수 있지만, 커뮤니티 스킬을 이것저것 시험하다 보면 충분히 그렇게 될 수 있다. 에이전트를 혼란스럽게 만들어서는 안 되니, 주기적으로 에이전트 환경을 정리하고 불필요한 것들을 제거해야 한다.

유용한 스킬을 설치하는 것과 영구적으로 유지하는 것은 별개의 결정이다.

양뿐 아니라 품질도 점검하라

스킬 관리에서 또 중요한 건 품질이다. Anthropic의 Skill Creator에는 이제 품질을 검증하기 위한 평가(eval)와 벤치마크 모드가 포함돼 있다. SKILL.md의 품질, 즉 설명이 충분한지, 트리거가 명확한지, 단계와 예시가 잘 정리돼 있는지를 점검하는 커뮤니티 도구들도 있다. 보안 측면에서의 점검 도구와 모범 사례도 갖춰지고 있다.

한 가지 혼동하기 쉬운 점이 있다. Claude Code에서 /doctor은 세션 내 설정 점검 명령어인 반면, 셸에서 실행하는 claude doctor는 설치 진단 정보만 출력한다. doctor가 "상태 확인만 보여준다"고 말하는 사람들이 있는 이유가 여기 있다. 또한 설치된 스킬이 매 프롬프트에 전체 내용을 불러오는 건 아니다. 이름과 설명은 목록 예산(기본값: 컨텍스트 윈도우의 1%) 안에서 검색용으로 로드되고, 실제 내용은 호출 시에만 불러온다. 프로젝트 파일을 깔끔하게 정리한 뒤에도 자동 메모리에 오래된 선호 사항이 남아 있을 수 있으므로, /memory로 메모리도 별도로 검토하는 편이다.

주기적으로 점검하고, 삭제도 테스트해보라

몇 주에 한 번, 적어도 한 달에 한 번은 doctor를 실행해 스킬과 설정 전반을 점검하고, 여전히 유효한 것이 무엇인지 따져보는 것이 좋다. 시간이 된다면 스킬을 삭제하거나 에이전트에게 "로컬 스킬 없이 순수한 모델과 실행 환경만으로 이 작업을 수행하라"고 지시해보는 것도 권한다. 스킬 없이도 괜찮다면, 그냥 삭제해도 된다는 뜻이다.

하지만 솔직히 말하면, 설치된 스킬들을 지우는 게 불안해서 그대로 두는 경우가 많다. 모델과 실행 환경이 실제로 나아졌을 거라는 확신이 없기 때문이다. 실험해보고 배울 것들이 아직 많다.

스킬 위생 관리를 꾸준히 실천하라. 품질과 보안을 점검하고, doctor 명령어를 정기적으로 실행하라. 로컬 설정을 꼭 필요한 만큼만, 그러나 충분히 구체적으로 유지하는 것이 목표다.