클로드 코드 에이전트, 스킬 구조 점검하세요! (체크리스트 파일 첨부)
Claude Code의 에이전트, 스킬, CLAUDE.md 설정이 잘못되면 AI가 제대로 작동하지 않습니다. 파일 구조와 frontmatter를 점검하는 체크리스트를 공유합니다.
말 안장을 엉덩이에 다는 꼴
클로드 코드 에이전트 설정을 수십 번 고쳤는데도 Claude Code가 지시를 무시했습니다.
파일도 생기고, 설정도 채워졌는데 실제로 실행해보면 뭔가 어긋납니다. 지시를 무시하거나, 엉뚱한 도구를 쓰거나, 아예 작동 자체를 안 하는 경우도 있죠.
AI 하네스(에이전트, 스킬, CLAUDE.md)를 직접 설계하면서 수십 번 이 상황을 겪었습니다. "문제는 Claude Code의 실력이 아니었습니다. 설정이 잘못되어 있었던 거죠."
말의 등이 아니라 엉덩이에 안장을 달고, 왜 말이 제대로 달리지 않냐고 묻는 것과 같습니다.
AI가 만든 설정도 틀릴 수 있습니다
"AI한테 에이전트 만들어달라고 하면 알아서 잘 만드는 거 아닌가요?"
그렇게 생각할 수 있습니다. 하지만 Claude Code도 자신의 설정 스펙을 100% 정확하게 구현하지는 않습니다. 직접 겪은 사례들이 있습니다.
- 없는 frontmatter 필드를 추가합니다. 공식 에이전트 스펙에 없는 version, author 같은 필드가 생성됩니다. 파싱 오류는 안 나지만, Claude가 해당 필드를 읽고 혼동할 수 있습니다.
- 파일 위치를 잘못 잡습니다. 에이전트는 .claude/agents/에, 스킬은 .claude/skills/에 있어야 합니다. 그런데 혼용하는 경우가 생깁니다.
- tools 필드에 MCP 도구를 섞습니다. 에이전트의 tools 필드는 내장 도구 전용입니다. 여기에 mcp__discord__reply 같은 MCP 도구를 넣으면 에이전트가 해당 도구를 인식하지 못합니다.
이런 오류는 Claude Code를 어느 정도 아는 사람도 눈으로 잡기 어렵습니다. 초보자라면 사실상 파악이 불가능하죠. 그 상태로 계속 쓰게 됩니다.
파일이 어디 있어야 하는지부터 확인하세요
AI 하네스를 구성하는 CLAUDE.md, 에이전트, 스킬, MCP 등이 어떤 구조로 놓여야 하는지 먼저 알아보겠습니다.
프로젝트 전용 (해당 프로젝트에서만 적용)
1my-project/
2├── CLAUDE.md # 프로젝트 지시서
3├── .mcp.json # MCP 서버 설정
4└── .claude/
5 ├── agents/
6 │ └── code-reviewer.md # 에이전트
7 ├── skills/
8 │ └── deploy/
9 │ ├── SKILL.md # 스킬 본문 (필수)
10 │ ├── references/ # 참조 문서
11 │ ├── scripts/ # 실행 스크립트
12 │ ├── evals/ # 스킬 테스트 케이스
13 │ ├── examples/ # 사용 예시
14 │ ├── assets/ # 템플릿, 아이콘 등
15 │ └── ... # 자유 구성 가능
16 ├── rules/
17 │ └── testing.md # 규칙 (파일별 조건부 적용)
18 ├── settings.json # 팀 공유 설정
19 └── settings.local.json # 개인 설정
글로벌 (모든 프로젝트에 적용)
글로벌은 내 컴퓨터 최상위 폴더에 에이전트, 스킬 폴더를 넣는 것이며 이로써 모든 프로젝트에 사용할 수 있는 글로벌 스킬과 에이전트로 활용할 수 있습니다.
1~/.claude/
2├── CLAUDE.md # 글로벌 지시서
3├── agents/
4│ └── general-helper.md # 글로벌 에이전트
5├── skills/
6│ └── commit/
7│ └── SKILL.md # 글로벌 스킬
8└── settings.json # 글로벌 설정
9
10~/.claude.json # 글로벌 MCP 서버 설정
지금 프로젝트 폴더를 열어서 이 구조와 맞는지 비교해보세요.
각 파일의 역할과 주의사항
파일 위치가 맞다면, 각 파일이 어떤 역할을 하고 어떻게 구성해야 하는지 알아야 합니다.
CLAUDE.md
Claude Code가 매 세션 시작할 때 읽는 프로젝트 지시서입니다. 프로젝트 규칙, 코딩 컨벤션, 워크플로우 등을 담습니다.
- 200줄 이하로 유지하세요. 초과하면 Claude가 뒷부분을 흘려읽습니다.
- 매 세션 공통으로 필요한 정보만 담으세요. 특정 에이전트나 스킬 전용 내용은 해당 파일로 옮겨야 합니다.
에이전트(.claude/agents/*.md)
특정 역할을 수행하는 서브에이전트입니다. 코드 리뷰어, 글쓰기 전문가 등 역할별로 분리해서 만듭니다. 파일 상단에 YAML frontmatter로 설정을 지정합니다.
- name, description: 필수. description은 250자 이내로, Claude가 언제 이 에이전트를 쓸지 판단하는 기준이 됩니다.
- tools: Claude Code 내장 도구만 지정 (Bash, Read, Write, Edit 등)
- mcpServers: MCP 서버는 반드시 여기에 서버 이름으로 지정
- model: sonnet, opus, haiku 중 선택 (기본값은 상위 세션 상속)
- version, author 같은 공식 스펙에 없는 필드는 제거하세요.
"tools에 MCP 도구를 넣으면 에이전트가 그 도구를 인식조차 못합니다." 에러도 안 나고, 그냥 조용히 작동을 안 하죠. tools와 mcpServers는 반드시 분리해야 합니다.
스킬 (.claude/skills/{name}/SKILL.md)
반복 작업을 자동화하는 워크플로우입니다. /스킬이름으로 직접 실행하거나, Claude가 상황에 맞게 자동으로 불러옵니다.
- name: 소문자+하이픈, 디렉토리명과 일치
- description: 250자 이내. 트리거 키워드를 앞쪽에 배치하세요. 초과하면 잘립니다.
- allowed-tools: 스킬 실행 중 승인 없이 쓸 수 있는 도구 목록
- context: fork로 설정하면 격리된 서브에이전트에서 실행
- SKILL.md는 500줄 이내로 유지하세요. 길어지면 별도 파일로 분리합니다.
체크리스트로 바로 점검해보세요
위 내용을 보고 직접 점검해보셔도 되지만, 하나하나 확인하는 게 귀찮은 분들을 위해 파일을 하나 준비했습니다. 저는 이걸 스킬로 만들어서 사용하고 있는데, 플러그인으로 배포해서 여러분이 설치하게 하려면 오히려 복잡해질 것 같아서 공식 문서 기준으로 정리한 체크리스트 파일을 직접 올려드립니다.
사용법은 간단합니다.
- 아래 링크에서 ai-harness-checklist.md 파일을 다운로드합니다.
- 프로젝트 아무 위치에 저장합니다.
- Claude Code 세션에서 @ai-harness-checklist.md 내 프로젝트의 AI 하네스 구조를 점검하고, 심각도에 따라 수정 방안을 안내해줘라고 입력합니다.
Claude가 체크리스트 기준으로 파일 위치, frontmatter, CLAUDE.md 줄 수, tools/mcpServers 분리 등을 점검하고 리포트를 줍니다.
에이전트와 스킬이 이미 많이 설치되어 있다면, 모든 파일을 한 번에 점검하면 토큰 소모가 심할 수 있습니다. 먼저 체크리스트를 읽고 구조를 파악한 뒤, 점검하고 싶은 파일을 하나씩 지정해서 요청하는 게 효율적입니다.
"설정이 잘못 채워진 채로 쓰고 있을 가능성이 높습니다." 말 잘 듣던 말도, 안장이 뒷다리에 달려있으면 뛸 수가 없으니까요.
점검해봤는데 여전히 막힌다면 톡방에서 편하게 질문해 주세요. 다들 나에게 꼭 맞는 AI 팀을 잘 만들어가시길 바랍니다.