코딩 에이전트: Agent skill, MCP, rules 파일 차이점
코딩 에이전트에게 컨텍스트를 제공하는 세 가지 방식의 비용과 차이를 비교합니다. Claude Code 기준 rules 파일의 적정 분량과 MCP server 및 skill 호출 시 발생하는 토큰 소모량을 분석하여 프로젝트 상황에 최적화된 선택 기준을 제시합니다.
Agent skill, MCP server, rules 파일의 차이: 요약
Agent skill, MCP server, rules 파일은 모두 코딩 에이전트에게 지식을 제공하는 수단입니다. 지식의 성격에 따라 선택하십시오. MCP(Model Context Protocol)는 조회할 때마다 내용이 바뀔 수 있는 데이터에 적합합니다. Skill은 오늘 작성해 두면 6주 뒤에도 유효할 절차를 정의할 때 사용합니다. Rules 파일은 모든 세션에서 반드시 지켜야 하는 몇 가지 핵심 사실을 담는 용도입니다.
이 선택에는 비용이 따르며, 그 비용은 곧 컨텍스트입니다. 에이전트가 필요로 하지 않는 지침에 토큰을 낭비하면, 정작 코드를 읽는 데 사용할 토큰이 부족해집니다. 또한 모든 요청마다 전체 컨텍스트 윈도우가 다시 전송되므로, 매 턴마다 해당 비용을 지불해야 합니다. 따라서 중요한 질문은 어떤 메커니즘으로 작업을 '수행할 수 있는가'가 아닙니다. 대부분의 경우 세 가지 모두 가능하기 때문입니다. 핵심은 사용하지 않을 때 가장 적은 비용을 소모하는 방식이 무엇인지 판단하는 것입니다.
사용 전 각 항목의 비용
세 가지 방식은 서로 다른 시점에 로드되며, 이 시점의 차이가 비용의 핵심입니다.
무조건적인 규칙 파일은 관련 여부와 관계없이 제외되지 않는 한 매 세션 시작 시 로드됩니다. Claude Code는 모든 대화 시작 시 CLAUDE.md 파일을 읽고, 코드 블록 외부의 블록 수준 HTML 주석을 제거한 뒤 내용을 주입하며, 4 MiB가 넘는 파일은 건너뜁니다. claudeMdExcludes를 사용하면 관리형 정책 파일을 제외한 나머지 파일을 제외할 수 있습니다. 권장되는 파일당 크기는 200줄 미만입니다. 파일이 길어지면 더 많은 컨텍스트 비용이 발생할 뿐만 아니라 모델이 규칙을 제대로 따르지 않게 되기 때문입니다. 이 두 가지 효과는 동일한 결과를 초래하므로, 900줄짜리 규칙 파일은 무용지물보다 못합니다.
스킬은 두 단계로 로드됩니다. 시작 시에는 각 SKILL.md 프런트매터의 description 줄만 컨텍스트에 입력되므로, 모델은 스킬의 존재와 대략적인 적용 시점만 파악합니다. 스킬 본문은 실제로 호출될 때 로드됩니다. 따라서 400줄짜리 참조 문서라도 필요한 순간까지는 비용이 거의 발생하지 않습니다.
MCP 서버는 과거에 비용이 많이 드는 항목이었으나, 현재 읽을 수 있는 대부분의 비교 자료는 구식 정보입니다. 현재 Claude Code에서는 도구 검색(tool search)이 기본적으로 활성화되어 있습니다. 세션 시작 시에는 도구 이름과 서버의 instructions 필드만 로드되며, 전체 JSON(JavaScript object notation) 스키마는 Claude가 도구를 검색할 때까지 지연됩니다. 이제 서버를 추가한다고 해서 초기에 수천 개의 토큰이 소모되지 않습니다. 여전히 약간의 비용은 발생하며, 도구 검색이 꺼진 설정에서는 여전히 모든 비용이 초기에 발생합니다.
이 차트의 데이터
[
{
"label": "Rules file, 200 lines",
"at_startup": "2,500",
"after_use": "2,500"
},
{
"label": "Skill, 12 KB body",
"at_startup": 40,
"after_use": "3,000"
},
{
"label": "MCP server, tool search on",
"at_startup": 500,
"after_use": "3,200"
},
{
"label": "MCP server, tool search off",
"at_startup": "4,500",
"after_use": "4,500"
}
]위 수치는 실제 측정값이 아닌 추정치입니다. 각 메커니즘이 로드하는 텍스트 크기를 기반으로 하며, 토큰당 약 4글자로 계산합니다. 200줄짜리 규칙 파일은 약 10 KB의 마크다운이며, 스킬 설명은 약 160글자, 12개의 도구를 노출하는 서버는 약 18 KB의 스키마와 2 KB의 instructions 블록을 포함합니다. Claude Code는 서버의 instructions 필드와 초기에 로드되는 각 도구의 설명을 기본적으로 4,096글자로 제한하며, 도구 검색을 통해 로드되는 도구 설명은 16,384글자로 제한합니다. v2.1.296 이전에는 더 짧은 제한이 2,048글자였으며, CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH를 설정하면 두 제한 모두 대체됩니다. 일부 Anthropic 호스팅 MCP 서버의 instructions와 설명은 해당 변수를 설정해도 Claude에게 전체가 전달되므로, 이 제한이 모든 경우에 적용되는 절대적인 상한선은 아닙니다. 다음 섹션에서는 실제 수치를 직접 확인하는 방법을 설명합니다.
첫 두 행을 함께 읽어 보십시오. 규칙 파일은 아무도 사용하지 않은 세션에서 2,500 토큰의 비용을 발생시킵니다. 스킬은 동일한 세션에서 40 토큰을 소모하며, 10번 중 1번꼴로 실행되는 세션에서는 3,000 토큰을 소모합니다. 마지막 두 행은 도구 검색 활성화 여부에 따른 동일 서버의 비용 차이입니다: 500 토큰 대 4,500 토큰. 이 격차가 MCP 컨텍스트 비대화에 관한 과거의 조언이 여전히 회자되는 이유입니다.
2026년 10월 기준으로 Claude Code는 Claude Opus 4, Sonnet 4, Haiku 4.5 이상 모델과 Google Cloud의 Agent Platform에서 Opus 4.5, Sonnet 4.5, Haiku 4.5 이상 모델에 대해 도구 검색을 사용합니다. 이전 모델이나 Azure에서 호스팅되는 Microsoft Foundry 배포 환경에서는 설정과 관계없이 모든 MCP 도구가 초기에 로드됩니다. ANTHROPIC_BASE_URL을 LLM 게이트웨이로 지정한 경우, v2.1.304부터 도구 검색이 기본적으로 활성화됩니다. 이전 버전에서는 사용자가 직접 선택하지 않으면 도구 검색이 꺼져 있었습니다. v2.1.305부터 Claude Code는 400 또는 422 발생 시 도구 검색 없이 게이트웨이 요청을 재시도할 수 있으며, 재시도 성공 시 도구를 초기에 로드합니다. ENABLE_TOOL_SEARCH을 설정하여 이를 제어할 수 있습니다. false는 모든 스키마를 초기에 로드하며, true는 설정하지 않았을 때와 동일한 모델 및 배포 폴백(fallback)을 사용하여 스키마 로드를 지연시킵니다. auto은 정의의 총합이 컨텍스트 윈도우의 10% 미만일 때 초기에 로드하며, 해당 임계값에 도달하면 이후 총합이 줄어들더라도 도구 검색을 계속 활성화합니다. "alwaysLoad": true로 구성된 서버는 ENABLE_TOOL_SEARCH 설정과 관계없이 도구를 초기에 로드합니다.
# Load schemas up front only if they fit in 5% of the window
ENABLE_TOOL_SEARCH=auto:5 claude결정적인 질문: 호출할 때마다 데이터가 변경되는가?
이 질문을 가장 먼저 하십시오. 이 질문 하나로 선택지 하나를 즉시 배제할 수 있기 때문입니다. 에이전트가 다음에 조회할 때 달라질 수 있는 데이터를 읽거나 써야 한다면, 서버가 필요합니다. 이슈 트래커, 데이터베이스, 모니터링 대시보드, 혹은 사내 API(애플리케이션 프로그래밍 인터페이스)가 이에 해당합니다. 기록해 두는 것만으로는 부족합니다. 다른 누군가가 기록을 수정하는 순간, 작성해 둔 내용은 구식이 되기 때문입니다. 여러분의 코드베이스 역시 이 목록에 포함됩니다. 커밋할 때마다 구조가 바뀌기 때문입니다. 이것이 바로 MCP를 통해 에이전트에 저장소의 파싱된 맵을 제공하는 이유입니다. 시간이 지나면 쓸모없어지는 파일에 레이아웃을 기술하는 것보다 훨씬 낫기 때문입니다.
아무도 유지보수하지 않아도 6주 뒤에 여전히 정답인 내용이라면, 스킬(skill)로 만드십시오. 릴리스 체크리스트, 마이그레이션 절차, 에러 응답의 형태, 이 저장소에서 테스트를 작성하는 방식 등이 여기에 해당합니다. 스킬은 git에 저장된 파일입니다. 포트도, 프로세스도 없으며, 잘못된 내용을 담고 있는 것 외에는 실패 모드도 없습니다. 잘못된 내용은 코드 리뷰를 통해 잡아낼 수 있습니다.
아직 생각하지 못한 작업에도 적용되어야 하는 단 하나의 사실이라면, rules 파일에 넣으십시오. Run make lint before committing. Never push to main. Handlers live in src/api/handlers/. 각 항목은 한 줄로 작성합니다. 항목이 단계별 절차로 길어지는 순간, 그것은 더 이상 사실이 아니라 절차가 된 것이므로 스킬로 옮겨야 합니다.
규칙 파일만으로 충분한 경우
규칙 파일은 가장 포괄적인 범위부터 가장 구체적인 범위까지 여러 위치에서 로드됩니다. 관리형 정책 파일, 개인용 ~/.claude/CLAUDE.md, 프로젝트의 ./CLAUDE.md 또는 ./.claude/CLAUDE.md, 그리고 gitignore에 포함된 ./CLAUDE.local.md가 이에 해당합니다. 발견된 모든 파일은 서로를 덮어쓰지 않고 병합되며, 작업 디렉터리에 가까운 파일일수록 나중에 읽힙니다.
v2.1.277 버전부터 Claude Code는 AGENTS.md도 읽지만, 기본적으로는 작업 디렉터리나 그 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 작동합니다. 저장소에 두 가지가 모두 포함된 경우, Claude는 CLAUDE.md 파일만 읽으므로 내용이 달라질 수 있는 두 개의 복사본을 유지하지 마십시오.
ln -s AGENTS.md CLAUDE.md심볼릭 링크는 성공 시 아무것도 출력하지 않습니다. 세션을 시작하고 /context all을 실행한 뒤, Memory files 아래에 CLAUDE.md가 나타나는지 확인하십시오. 목록에 없다면 에이전트가 해당 파일을 인식하지 못한 것이며, 문구를 수정해도 해결되지 않습니다. Claude 전용 줄을 추가하려면 import 형식을 사용하고 import 아래에 해당 내용을 배치하십시오.
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.주의할 점이 하나 있습니다. @path import는 컨텍스트를 저장하지 않습니다. import된 파일은 실행 시점에 이를 참조한 파일과 함께 확장 및 로드되며, 최대 4단계까지 중첩될 수 있습니다. 600줄짜리 규칙 파일을 6개의 import로 나누는 것은 사람을 위한 정리일 뿐이며, 토큰 비용에는 아무런 변화가 없습니다. 레이아웃을 결정하기 전에 AGENTS.md와 그에 대응하는 인간용 문서의 관례를 읽어보는 것이 좋습니다.
비용을 줄이는 방법은 paths 필드가 포함된 .claude/rules/을 사용하는 것입니다. paths 프론트매터(frontmatter)가 포함된 규칙 파일은 에이전트가 해당 패턴과 일치하는 파일을 다룰 때만 로드됩니다.
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its input.
- Use the standard error response shape.paths 필드가 없는 규칙은 .claude/CLAUDE.md와 동일한 우선순위로 실행 시점에 로드됩니다. 따라서 짧고 조건이 없는 규칙을 기본으로 사용하고, 특정 디렉터리 내부에서만 중요한 규칙에는 paths 목록을 추가하는 방식이 효율적입니다.
기술(Skill)이 필요할 때
기술은 내부에 SKILL.md을 포함하는 디렉터리입니다. 개인 기술은 ~/.claude/skills/<name>/SKILL.md에 위치하며 머신의 모든 프로젝트에 적용됩니다. 프로젝트 기술은 .claude/skills/<name>/SKILL.md에 위치하며 저장소와 함께 이동하고, 다른 파일과 마찬가지로 풀 리퀘스트에서 검토할 수 있습니다.
mkdir -p ~/.claude/skills/summarize-changes---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
Run `git status` and `git diff` against the merge base.
Group the changes by intent, not by file.
Call out anything touching auth, migrations or deletions.description은 기술이 실행되기 전 컨텍스트에 포함되는 유일한 파일 부분이며, 두 가지 역할을 수행합니다. 기술이 무엇을 하는지 설명하고, 언제 이 기술을 사용해야 하는지 정의합니다. "배포를 돕습니다"와 같은 설명은 모델이 요청과 매칭할 근거를 제공하지 못하므로, 기술이 조용히 실행되지 않아 사용자는 기술이 작동하지 않는다고 결론 내리게 됩니다.
디렉터리 이름이 명령어가 되므로, 위의 예시는 /summarize-changes를 제공합니다. 개인 또는 프로젝트 기술에서 디렉터리 이름과 다른 프론트매터 name을 설정하면 / 메뉴에 표시되는 명령어를 변경할 수 있습니다. 단, 다른 명령어가 이미 해당 이름을 사용 중이지 않아야 하며, 디렉터리 이름으로도 여전히 기술을 호출할 수 있습니다.
기술이 호출되면 렌더링된 콘텐츠가 단일 메시지로 대화에 진입하며 세션이 끝날 때까지 유지됩니다. Claude Code는 이후 턴에서 파일을 다시 읽지 않습니다. 일회성 단계보다는 상시 지침을 작성하고 본문을 간결하게 유지하십시오. 그 시점부터 모든 줄이 요청마다 반복적인 비용으로 작용하기 때문입니다. 자동 압축 후 Claude Code는 각 기술의 가장 최근 호출을 다시 첨부하며, 각 기술의 처음 5,000 토큰을 총 25,000 토큰 예산 내에서 유지합니다. 한 세션에서 여러 개의 큰 기술을 호출하면 가장 오래된 기술부터 완전히 삭제되므로, 긴 대화 후에는 기술이 더 이상 중요하지 않게 느껴질 수 있습니다. 다시 호출하면 기술이 복구됩니다. 절차 중심적인 기술은 이러한 트레이드오프를 구체화합니다. 게으르지 않은 기술과 Depth Tree 방식은 작업을 일찍 종료한다고 선언하는 에이전트를 방지하는 대가로 게이트와 계획 파일에 실제 컨텍스트를 소비합니다. 동일한 절차가 여러 코드베이스에 적용될 때는 파일을 복사하는 대신 여러 저장소에서 하나의 기술을 공유하십시오.
MCP 서버가 필요한 경우
서버 추가는 단일 명령어로 가능하며, 전송 방식에 따라 서버의 형태가 결정됩니다.
# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Remote HTTP server behind a bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
# Local stdio server: everything after -- is passed through untouched
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server--가 중요합니다. stdio 서버의 경우, 이 구분자는 Claude Code 자체 옵션과 서버를 시작하는 명령줄을 분리합니다. 이를 생략하면 서버용으로 의도된 --port 8080이 claude mcp add의 옵션으로 해석되어 거부됩니다.
claude mcp list
claude mcp get notionclaude mcp add은 Added ... 줄을 통해 확인을 제공하는데, 이는 설정이 디스크에 기록되었음을 알릴 뿐입니다. claude mcp list는 각 서버 옆에 ✔ Connected, ! Needs authentication, 또는 ✘ Failed to connect와 같은 상태를 출력하므로 실제 서버의 상태를 알려주는 명령어입니다. 실패 상태는 목록 명령어가 고장 난 것이 아니라 Claude Code가 해당 서버에 도달할 수 없음을 의미합니다. 세션 내부에서는 /mcp 명령어를 통해 서버별 상태와 도구 개수를 동일하게 확인할 수 있습니다.
MCP 서버에 대한 각 호출은 독립적으로 수행되며 필요한 모든 정보를 포함합니다. 이것이 바로 MCP 서버가 이전 요청을 기억하지 않는 이유입니다. 이는 설계상의 선택이며, 그 결과로 사용자는 유지해야 할 상태를 서버 내부의 데이터베이스나 파일에 직접 저장하고 관리해야 하는 책임을 갖게 됩니다.
MCP 서버는 직접 실행해야 하는 프로세스입니다
벤더 비교 자료에서 간과하는 비용이 있습니다. 스킬은 파일 형태이지만, MCP 서버는 어딘가에서 실행되는 소프트웨어입니다. 그 '어딘가'가 귀하의 VPS(가상 사설 서버)라면, 서버의 가동 시간(uptime)은 직접 관리해야 합니다.
stdio 서버는 비용이 적게 드는 경우입니다. 세션이 시작되면 Claude Code가 이를 자식 프로세스로 생성하고, 세션이 종료되면 프로세스도 함께 종료됩니다. 별도로 모니터링하거나 독자적인 일정에 맞춰 패치할 필요가 없습니다. 반면 원격 HTTP 서버는 장기 실행 서비스이므로, 모든 장기 실행 서비스가 그렇듯 전용 사용자 계정부터 시작하여 필요한 조치를 취해야 합니다. 아래 유닛이 실행될 mcp 사용자를 생성하고, 서버 디렉터리 권한을 부여하십시오.
sudo useradd --system --home-dir /srv/notes-mcp --shell /usr/sbin/nologin mcp
sudo chown -R mcp:mcp /srv/notes-mcp[Unit]
Description=Notes MCP server
After=network-online.target
Wants=network-online.target
[Service]
User=mcp
WorkingDirectory=/srv/notes-mcp
ExecStart=/usr/bin/node /srv/notes-mcp/dist/server.js
Environment=PORT=8931
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now notes-mcp
systemctl is-active notes-mcp
journalctl -u notes-mcp -n 50 --no-pagersystemctl is-active 명령은 active을 출력해야 합니다. 만약 failed이 출력된다면 저널(journal)에 원인이 기록되어 있습니다. 첫 실행 시에는 환경 변수가 누락되었거나 다른 프로세스가 이미 포트를 점유하고 있는 경우가 대부분입니다. MCP 서버가 중단되어도 스스로 알리지 않으므로 Restart=on-failure은 선택 사항이 아닙니다. 에이전트가 이슈 트래커를 읽을 수 없다고 보고할 때 비로소 문제가 발생했음을 알게 됩니다.
프로세스를 127.0.0.1에 바인딩하고 그 앞단에 TLS(전송 계층 보안)를 적용한 리버스 프록시를 배치하십시오. 데이터베이스에 접근하는 MCP 서버를 인증 없이 공개 포트로 노출하는 것은 데이터베이스를 외부에 그대로 공개하는 것과 같습니다. VPS에서 MCP 서버 실행하기에서 프록시, 인증서, 방화벽 설정 방법을 다룹니다.
이제 반복적인 운영 업무를 냉정하게 계산해 보십시오. 서비스는 에이전트와 무관하게 독자적인 일정으로 보안 업데이트를 수행해야 합니다. OAuth 토큰이 만료되면 claude mcp list은 곤란한 순간에 ! Needs authentication을 출력하기 시작할 것입니다. 자격 증명은 설정 파일이나 Authorization 헤더에 저장되므로 다른 보안 정보와 동일하게 관리해야 하며, 이는 그 자체로 하나의 큰 주제입니다. AI 에이전트가 접근할 수 없는 곳에 보안 정보 보관하기를 참고하십시오. 스킬을 사용할 때는 이러한 운영 업무가 전혀 발생하지 않습니다.
구축하기 전에 대안과 비교하여 신중히 결정하십시오. 제안된 서버가 다루는 데이터가 분기별로 한 번 정도 변경된다면, 에이전트에게 데이터 위치와 필드 의미를 알려주는 스킬을 만드는 것이 계속해서 가동 상태를 유지해야 하는 서비스보다 비용 효율적입니다.
자신의 컨텍스트 비용 측정 방법
추측을 멈추고 세션 내에서 /context all를 실행하십시오. 시스템 프롬프트, 메모리 파일, 도구, MCP 서버별 토큰 가중치를 포함한 현재 상세 내역이 출력됩니다.
두 가지를 확인하십시오. Memory files 항목에서 예상한 모든 규칙 파일이 나열되어 있는지 확인하십시오. 파일이 누락되면 에이전트가 해당 파일을 인식할 수 없으므로, 지시 사항이 무시될 때 가장 먼저 확인해야 할 사항입니다. 파일이 목록에 있는데도 규칙이 계속 무시된다면 원인은 다른 곳에 있습니다. 이 경우 에이전트가 보이는 지시 사항을 건너뛰는 이유를 검토한 뒤 줄을 다시 작성하는 것이 좋습니다. 그다음 서버 비용을 확인하십시오. 한 달에 두 번 사용하는 서버가 목록에서 가장 큰 비중을 차지한다면 /mcp에서 해당 서버를 껐다가 필요한 세션에서만 다시 켜십시오. 설정은 그대로 유지됩니다.
계정에서 검색 캐시(discovery cache)가 활성화된 경우, 이전에 사용한 원격 서버가 cached 2h ago · connects on first use · 5 tools와 같은 상태로 표시될 수 있습니다. 이는 Claude Code가 시작 시점에 연결하는 대신 이전 세션의 도구 목록을 읽어왔음을 의미하며, 도구가 처음 호출될 때 연결이 이루어집니다. 도구는 첫 메시지부터 사용할 수 있으므로 수정할 필요는 없습니다. 캐시는 점진적 배포를 통해 활성화되지 않은 한 기본적으로 꺼져 있습니다. 모든 서버가 시작 시점에 연결되도록 하려면 MCP_DISCOVERY_CACHE=0를 설정하고, 캐시를 켜려면 1를 설정하십시오. 전체적인 내용을 파악하려면 Claude Code 컨텍스트 윈도우 관리에서 압축 후에도 유지되는 항목을 확인하고, 토큰의 실제 비용에서 해당 수치가 금전적으로 어떤 의미인지 확인하십시오.
왜 스킬이 실행되지 않습니까?
가장 흔한 원인은 description입니다. 이는 스킬이 실행되기 전 문맥상 유일한 텍스트이므로, 여기에 상황이 명시되지 않으면 일치하는 항목이 없습니다. 트리거를 다음과 같이 문장에 포함하십시오: "사용자가 무엇이 변경되었는지 묻거나, 커밋 메시지를 원하거나, diff 검토를 요청할 때 사용하십시오." 모호한 설명은 오류 메시지 없이 실패하므로 문제를 파악하기 어렵습니다.
두 번째 원인은 프런트매터(frontmatter) 오타이며, Claude Code에서는 이 또한 조용히 실패합니다. 필드 이름은 하이픈을 포함하여 정확히 일치해야 하며, Claude Code는 인식하지 못하는 필드를 오류 보고 없이 무시합니다. 명확한 오류는 스킬을 패키징하거나 claude.ai 또는 Skills API에 업로드할 때만 나타나며, 이때는 허용되지 않는 필드가 포함되면 즉시 거부됩니다:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name세 번째 원인은 위치입니다. 프로젝트 스킬은 작업 디렉터리와 리포지토리 루트까지의 모든 상위 디렉터리에 있는 .claude/skills/에서 로드됩니다. 실행 시점보다 하위 디렉터리에 있는 스킬은 시작 시 로드되지 않습니다. 해당 스킬은 에이전트가 해당 하위 디렉터리 내의 파일을 처음 읽거나 편집할 때 나타나므로, 그전까지는 자동 완성이 되지 않으며 이름으로 호출할 수도 없습니다.
이러한 조용한 실패에 해당하는 MCP 문제는 url은 있지만 type가 없는 .mcp.json 항목입니다. Claude Code는 type가 없는 모든 항목을 stdio 서버로 간주하므로, 해당 항목을 건너뛰고 다음과 같이 보고합니다:
MCP server "notes" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry세 가지를 모두 함께 사용하기
이 메커니즘들은 동일한 역할을 두고 경쟁하지 않습니다. 효율적인 구성은 각 메커니즘을 가장 적합한 곳에 배치합니다. rules 파일에는 어디서나 적용되는 몇 줄의 핵심 규칙을 담습니다. Skills는 절차를 정의하며, 해당 작업이 필요할 때만 로드됩니다. MCP 서버는 내용을 미리 예측할 수 없는 시스템을 연결하며, 보통 하나, 가끔은 두 개를 사용합니다. 이 중 첫 번째 개념에 대한 이해가 부족하다면, 에이전트 스킬의 실제 정의에서 해당 형식을 자세히 다룹니다.
어떤 기능을 어디에 배치할지 결정할 때는 하나의 테스트로 대부분의 논쟁을 해결할 수 있습니다. 해당 기능을 삭제하고 새로운 세션을 시작한 뒤 에이전트에게 작업을 부여해 보십시오. 에이전트가 단순히 느려졌다면, 해당 기능은 skill에 속해야 합니다. 에이전트가 자신 있게 틀린 답을 내놓는다면, rules 파일에 속해야 합니다. 에이전트가 정보를 전혀 가져오지 못한다면, 서버가 필요한 상황이며 이제 해당 서버를 유지 관리할 계획도 세워야 합니다.
FAQ
스킬을 작성해야 합니까, 아니면 MCP 서버를 구축해야 합니까?
정보가 호출할 때마다 변경되는지 여부에 따라 결정하십시오. 이슈 트래커, 데이터베이스, 대시보드와 같이 다른 사람이 편집할 수 있는 실시간 상태를 에이전트가 읽어야 한다면 MCP 서버가 필요합니다. 기록이 변경되는 즉시 작성한 내용은 구식이 되기 때문입니다. 답변을 한 번 작성해 두고 6주 뒤에도 여전히 유효하다면 스킬을 작성하십시오. 스킬은 실행할 프로세스나 노출할 포트, 패치 일정이 없는 git 파일이므로 가능한 경우 항상 더 저렴한 선택지입니다.
MCP 서버가 여전히 컨텍스트 윈도우를 가득 채우나요?
예전보다 훨씬 덜합니다. 현재 Claude Code에서는 도구 검색이 기본적으로 활성화되어 있으므로 세션 시작 시 도구 이름과 서버의 instructions 필드만 로드되며, Claude가 도구를 검색할 때 전체 스키마를 가져옵니다. 이는 v2.1.304 버전부터 ANTHROPIC_BASE_URL를 통해 설정된 LLM 게이트웨이 뒤의 세션에도 적용됩니다. ENABLE_TOOL_SEARCH=false으로 설정된 서버, "alwaysLoad": true로 설정된 서버, Claude Opus 4 및 Sonnet 4보다 이전 모델(Google Cloud의 Agent Platform 기준 4.5 세대 이전), 그리고 Azure에서 호스팅되는 Microsoft Foundry 배포 환경에서는 여전히 사전 로드가 발생합니다. 현재 어떤 상황인지 확인하려면 /context all를 실행하십시오. 이전 비교 게시물의 수치는 사전 로드를 가정하고 작성되었기 때문입니다.
Claude Code가 AGENTS.md를 읽나요?
네, v2.1.277 버전부터 읽습니다. 단, 작업 디렉터리나 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md이 없는 경우에만 기본적으로 작동합니다. 저장소에 두 가지가 모두 있다면 Claude는 CLAUDE.md 파일만 읽으므로, 두 개의 사본을 유지하는 대신 하나를 다른 하나로 연결하십시오. 일반 심볼릭 링크를 만들려면 ln -s AGENTS.md CLAUDE.md을 실행하거나, CLAUDE.md의 첫 번째 줄에 @AGENTS.md을 넣고 그 아래에 Claude 전용 지침을 추가하십시오. 그런 다음 세션을 시작하고 /context all을 실행하여 Memory 파일 아래에 CLAUDE.md가 표시되는지 확인하십시오.
세션 도중에 스킬이 더 이상 효과가 없는 이유는 무엇인가요?
자동 압축(Auto-compaction)이 일반적인 원인입니다. 대화가 요약될 때 Claude Code는 각 스킬의 가장 최근 호출 내용을 다시 첨부하며, 각 스킬의 처음 5,000 토큰을 유지하고 전체 스킬에 대해 25,000 토큰의 통합 예산을 할당합니다. 이 예산은 가장 최근에 호출된 스킬부터 채워지므로, 여러 개의 큰 스킬을 호출했다면 오래된 스킬은 완전히 삭제됩니다. 전체 내용을 복원하려면 스킬을 다시 호출하십시오.
긴 규칙 파일이 모든 세션에서 로드되지 않게 하려면 어떻게 해야 하나요?
일부 상황에서만 중요한 부분은 frontmatter에 paths 필드가 있는 .claude/rules/ 파일로 옮기십시오. 이렇게 하면 에이전트가 일치하는 파일을 다룰 때만 각각 로드됩니다. 파일을 @path로 분할하여 가져오는 것은 도움이 되지 않습니다. 가져온 파일은 참조한 파일과 함께 실행 시점에 확장되어 로드되기 때문입니다. 상시 적용되는 사실이 아니라 다단계 절차인 모든 항목은 스킬로 전환해야 합니다. 스킬 본문은 호출되기 전까지는 비용이 발생하지 않기 때문입니다.