🔍 클로드 코드 에이전트, 왜 말을 안 들을까? AI 하네스 설정 오류 총정리

 

"설정했는데 왜 작동을 안 하지?" 이 경험, 다들 한 번쯤 있죠

클로드 코드(Claude Code)를 처음 써보고 감탄했다가, 에이전트도 만들어보고 스킬도 추가해봤는데 막상 실행하면 지시를 무시하거나 엉뚱한 도구를 쓰거나 아예 조용히 멈춰버리는 경험. 개발자든 비개발자든 한 번쯤 겪어봤을 겁니다.

문제는 클로드의 실력이 아닙니다. 설정이 잘못된 거예요.

오늘은 AI 하네스 설정에서 자주 틀리는 구조적 오류와 실전 해결법을 정리해드립니다. 2025~2026년 사이 국내외 개발자들이 실제로 부딪힌 삽질 사례와 최신 공식 문서 기준으로 작성했습니다.

AI 하네스, 이게 뭔지부터 잡고 갑시다

"AI 하네스(Harness)"라는 단어가 낯설 수 있는데, 말 그대로 AI를 내가 원하는 방향으로 움직이게 만들어주는 환경 설정 전체를 뜻합니다. 말에 안장과 고삐를 채워야 원하는 방향으로 달리게 할 수 있듯, AI도 하네스 없이는 그냥 달려버리거나 아예 멈춰버립니다.

클로드 코드의 AI 하네스는 크게 네 가지로 이루어져 있습니다.

CLAUDE.md는 매 세션 시작 때 자동으로 읽히는 프로젝트 지시서입니다. 에이전트는 코드 리뷰어, 글쓰기 전문가처럼 역할별로 분리된 서브에이전트고요. 스킬은 반복 작업을 자동화하는 워크플로우 파일입니다. 그리고 MCP 서버는 AI가 외부 도구나 API에 접근할 수 있게 연결해주는 프로토콜이에요.

공식 문서에서도 클로드 코드를 두고 "언어 모델을 능력 있는 코딩 에이전트로 변환하는 도구와 컨텍스트 관리, 실행 환경을 제공하는 에이전트 하네스"라고 정의합니다. 설정이 어긋나면 AI도 그냥 멈춰버리는 이유가 여기에 있습니다.

가장 흔한 실수 1 — 파일 위치가 틀렸다

클로드 코드의 파일 구조는 생각보다 엄격합니다. 에이전트는 반드시 .claude/agents/ 폴더에, 스킬은 .claude/skills/ 폴더에 있어야 합니다. 그런데 AI가 직접 파일을 만들어줄 때 이 두 폴더를 혼용하는 경우가 생각보다 자주 발생합니다.

프로젝트 전용으로 쓸 건지, 내 컴퓨터 전체에 글로벌로 쓸 건지에 따라 저장 위치도 달라집니다. 프로젝트 전용은 my-project/.claude/agents/와 my-project/.claude/skills/ 안에 넣으면 되고, 글로벌 설정은 ~/.claude/agents/와 ~/.claude/skills/에 두면 모든 프로젝트에서 공통으로 쓸 수 있습니다.

단 한 단계 위에 잘못 올라가 있어도 클로드는 그 파일을 아예 인식하지 못합니다. 지금 당장 프로젝트 폴더를 열어서 파일 위치부터 확인해보세요.

가장 흔한 실수 2 — AI가 만들어준 설정도 틀릴 수 있다

"클로드한테 에이전트 만들어달라고 하면 알아서 잘 만드는 거 아닌가요?"

맞는 말처럼 들리지만 실제로는 클로드 코드도 자신의 설정 스펙을 100% 정확하게 구현하지는 않아요. 현장에서 자주 발생하는 오류 패턴이 세 가지 있습니다.

첫째, 공식 에이전트 스펙에 없는 version, author 같은 frontmatter 필드를 자동으로 추가합니다. 파싱 오류는 안 나지만 클로드가 혼동할 수 있는 원인이 됩니다.

둘째, 에이전트의 tools 필드에 MCP 도구를 섞어 넣습니다. tools 필드는 Bash, Read, Write, Edit 같은 내장 도구 전용인데, 여기에 외부 MCP 도구를 넣으면 에이전트가 그 도구를 아예 인식하지 못합니다. 에러도 안 나고 그냥 조용히 안 되는 거라 찾기가 정말 어렵습니다.

셋째, 파일 위치 혼용입니다. AI가 생성한 에이전트가 스킬 폴더에, 스킬이 에이전트 폴더에 들어가는 경우가 실제로 생깁니다.

"AI가 만들어줬다고 무조건 믿지 말고, 생성 후에 직접 구조를 한 번 확인하는 습관이 필요합니다."

tools와 mcpServers는 반드시 분리해야 합니다

이게 핵심 포인트입니다. 많은 분들이 에이전트 설정 파일에서 tools와 mcpServers를 하나로 묶어버리는데, 이 둘은 완전히 별개 필드입니다.

에이전트 frontmatter 기준으로 정리하면 이렇습니다.

tools 필드에는 클로드 코드 내장 도구만 지정합니다. Bash, Read, Write, Edit 등이 해당됩니다. mcpServers 필드에는 외부 MCP 서버를 서버 이름으로 지정합니다. 슬랙, 디스코드, 노션 같은 외부 연동이 여기에 들어갑니다.

두 칸이 섞이면 클로드는 해당 도구를 인식 자체를 못합니다. 에러 메시지도 없어서 원인을 찾기가 매우 어렵습니다. 가장 흔한 함정이자, 한 번 알면 다시는 안 틀리는 포인트이기도 합니다.

CLAUDE.md는 200줄 이내로 유지하세요

CLAUDE.md는 클로드가 매 세션 시작 때 자동으로 읽는 파일입니다. 프로젝트 규칙, 코딩 컨벤션, 워크플로우를 담아두는 곳이죠.

실제로 200줄이 넘으면 클로드가 뒷부분을 흘려읽는 현상이 발생합니다. 정성껏 써놓은 규칙 중 절반을 AI가 읽지 않는 상황이 벌어지는 거예요. 특히 GitHub 내 2,500개 저장소 분석에서도 "모호하거나 너무 장황한 지시사항이 대부분의 에이전트 실패 원인"이라는 결과가 나왔습니다.

해결책은 간단합니다. 모든 세션에 공통으로 필요한 핵심 정보만 CLAUDE.md에 남기고, 특정 에이전트나 스킬 전용 지침은 각 파일로 분리하면 됩니다. CLAUDE.md 내에서 @README.md나 @docs/STYLE_GUIDE.md처럼 다른 파일을 참조하는 방식도 활용할 수 있어요.

스킬 파일과 에이전트 description도 분량 제한이 있습니다

SKILL.md도 500줄 이내로 유지하는 게 권장됩니다. 스킬이 길어지면 별도 파일로 분리해서 references 폴더 등을 활용하면 됩니다.

스킬의 description 필드는 250자 이내로 써야 하고, 트리거 키워드를 앞쪽에 배치하는 게 중요합니다. 250자가 넘으면 잘려서 클로드가 언제 이 스킬을 써야 하는지 판단하는 기준 자체가 손상됩니다.

에이전트의 description도 마찬가지입니다. 250자 이내, 핵심 키워드 앞배치가 원칙입니다. 이 설명이 곧 클로드가 에이전트를 자동 선택하는 기준이 되기 때문입니다. 만약 반드시 자동 위임 방식으로 쓰고 싶다면 description에 "PROACTIVELY use"나 "MUST use" 같은 키워드를 포함하는 것도 효과적인 방법입니다.

에이전트가 도구를 못 찾는다면 이것도 확인해보세요

실제로 많은 사람들이 놓치는 부분인데, 에이전트가 조용히 실패할 때 도구 인식 문제인지 확인하는 방법이 있습니다.

클로드 코드 세션에서 다음 명령을 입력해보세요: "What instructions are you following for this project?" 또는 "What is your definition of done?" 에이전트가 정확히 재현하지 못한다면 지시사항이 너무 장황하거나, 모호하거나, 아예 검색이 안 되는 상황입니다.

설정이 제대로 됐다면 에이전트는 빌드 명령어를 포함해 자신이 따르는 규칙을 명확하게 설명할 수 있어야 합니다.

2025~2026년, AI 하네스 생태계가 빠르게 확장 중입니다

클로드 코드 에이전트 하네스 생태계는 최근 1년간 폭발적으로 성장했습니다. 단순한 CLAUDE.md 설정을 넘어서, 에이전트 팀 전체를 도메인에 맞게 자동 생성해주는 도구들이 등장하고 있어요.

revfactory/harness 같은 오픈소스 프로젝트는 "하네스 구성해줘"라는 한 마디만으로 도메인에 맞는 에이전트 정의와 스킬을 자동 생성합니다. 실제 A/B 실험에서 구조화된 하네스를 적용했을 때 출력 품질이 평균 60% 향상됐다는 결과도 나왔어요.

뿐만 아니라 Claude Code 설정 전체를 자동 점검하는 보안 스캐너도 생겨났습니다. CLAUDE.md, settings.json, MCP 설정, 훅, 에이전트 정의, 스킬까지 시크릿 감지와 권한 감사, 훅 인젝션 분석을 자동으로 수행하는 도구입니다. AI 하네스를 단순한 설정 파일 모음이 아니라, 성능 최적화 시스템으로 바라보는 시각이 확산되고 있는 것입니다.

직접 점검하는 가장 빠른 방법

AI 하네스 설정을 직접 뜯어보는 게 가장 빠른 공부법입니다. 작동하는 설정 파일을 기준으로 CLAUDE.md, 에이전트 파일, 스킬 파일이 각각 어떤 역할을 하고 어떻게 연결되는지 실제 파일을 보면 텍스트 설명보다 훨씬 빠르게 감이 옵니다.

점검 체크리스트가 있다면 활용해보세요. 클로드 코드 세션에서 체크리스트 파일을 멘션하면서 "내 프로젝트의 AI 하네스 구조를 점검하고, 심각도에 따라 수정 방안을 안내해줘"라고 입력하면 파일 위치, frontmatter 구조, CLAUDE.md 줄 수, tools/mcpServers 분리 여부를 자동으로 점검하고 리포트를 줍니다. 에이전트와 스킬이 많이 쌓여 있다면 한꺼번에 점검하면 토큰 소모가 크니, 파일을 하나씩 지정하는 방식이 효율적입니다.

마무리

클로드 코드가 말을 안 듣는다면 99%는 설정 문제입니다. 파일 위치, frontmatter 필드, tools와 mcpServers 분리, CLAUDE.md 분량. 이 네 가지만 점검해도 대부분의 문제가 해결됩니다.

AI 하네스를 제대로 설계한 사람과 그렇지 않은 사람의 생산성 차이는 앞으로 점점 더 벌어질 겁니다. 설정이 잘못 채워진 채로 쓰고 있을 가능성, 생각보다 높습니다. 오늘 내 프로젝트 폴더 한 번만 열어보세요.