Claude Code를 며칠 쓰다 보면 두 가지 벽에 반드시 부딪힌다. 하나는 같은 에러에 대해 조금씩 다른 시도를 반복하는 '루프', 다른 하나는 "이 문제는 수동 개입이 필요합니다"라며 공을 되던지는 '포기 선언'이다. 여기서 많은 사람이 대화를 처음부터 다시 시작하거나, 그냥 직접 고친다. 그런데 실제로는 둘 다 세션을 날리지 않고도 해결 가능하다.
루프를 끊는 법: 수정 요청을 진단 요청으로 바꾼다
dev.to의 builtbyzac이 정리한 방식은 직관적이다. 루프가 발생하는 근본 원인은 Claude가 에러에 대해 '패턴 매칭'으로 해결책을 시도하기 때문이다. 같은 종류의 해결책을 변형해서 반복하는 구조상, 근본 원인이 다르면 아무리 시도해도 빠져나오지 못한다.
이때 효과적인 전환은 "고쳐줘"에서 "진단해줘"로 요청을 바꾸는 것이다. 루트 원인이 무엇인지, 지금까지 시도한 것들이 왜 실패했는지, 실제 원인을 파악하려면 어떤 정보가 더 필요한지—이 세 가지를 먼저 설명하게 하면 Claude가 해결책 탐색 모드에서 추론 모드로 전환된다. 그리고 대부분의 경우, 진단 1번 항목에서 실제 루트 원인이 나온다. 그 이후에 '하나의 구체적인 수정'만 요청하면 된다.
포기 선언은 조금 다르게 접근해야 한다. "해결할 수 없습니다"라는 말은 사실 세 가지 중 하나를 의미한다: 필요한 정보가 없거나, 해당 도메인 지식이 부족하거나, 긴 세션 끝에 컨텍스트 압박으로 자신감이 떨어진 것이다. 이 셋은 해결 방식이 전혀 다르다.
"해결하려면 어떤 정보가 필요한가, 그 정보를 어디서 얻을 수 있나"라고 되물으면 놀랍도록 구체적인 답이 돌아온다—특정 설정 파일을 읽거나, 특정 커맨드를 실행하거나, 특정 임포트를 확인하라는 식으로. '못 한다'는 게 실제로는 '정보가 부족하다'였던 것이다.
세션이 길어질수록 쌓이는 잘못된 시도와 모순된 상태들이 문제를 실제보다 어렵게 보이게 만든다. 이럴 때는 컨텍스트 리셋이 유효하다. 현재 상태—무엇이 실패하고 있는지, 무엇을 시도했는지, 실제 목표가 무엇인지—를 파일로 저장하고, 새 세션에서 그 파일만 읽어 시작하면 막혀 있던 문제가 풀리는 경우가 많다.
settings.json: 대부분의 팀이 그냥 넘기는 파일
.claude/settings.json은 Claude Code의 동작 방식을 실질적으로 바꾸는 설정 파일이다. builtbyzac의 분석에 따르면, 대부분의 개발자가 이 파일을 아예 건드리지 않은 채 사용한다. 실무에 바로 영향을 미치는 옵션들이 있는데도.
핵심은 세 가지다. defaultMode: "acceptEdits"로 설정하면 파일 편집 시 매번 승인 요청이 뜨는 것을 없앨 수 있다—셸 명령어는 여전히 확인을 요청하므로 완전 방치는 아니다. allowedCommands에 프로젝트에서 쓰는 커맨드(npm, npx, git, tsc 등)를 등록하면 반복적인 승인 클릭이 사라진다. ignorePatterns로 node_modules, dist, .env* 같은 파일들을 컨텍스트에서 아예 제외하면 불필요한 토큰 낭비와 비밀값 노출 위험을 동시에 줄인다.
설정 파일의 우선순위도 알아둘 필요가 있다. 전역(~/.claude/settings.json), 프로젝트(.claude/settings.json), 로컬(.claude/settings.local.json) 순으로 좁아질수록 덮어쓴다. 프로젝트 단위 설정을 git에 커밋하면 팀 전체가 일관된 Claude 동작 환경을 갖게 된다—이건 단순한 편의가 아니라 AI 워크플로우의 팀 표준화다.
SKILL.md: 에이전트에게 프레임워크 규칙을 가르치는 방식
AI 코딩 에이전트는 프레임워크의 관용적 패턴을 기본으로 알지 못한다. SKILL.md는 이 격차를 메우기 위해 라이브러리 저자들이 에이전트용으로 직접 작성하는 구조화된 파일이다. Angular, shadcn/ui, Prisma, Supabase, Playwright 같은 팀이 이미 공식 SKILL.md를 배포하고 있다.
dev.to의 finfin이 만든 awesome-frontend-skills는 이 생태계를 프론트엔드 관점에서 큐레이션한 결과물이다—React, Vue, Next.js, Nuxt, Svelte, TanStack부터 Tailwind v4, Three.js, Framer Motion, Playwright, Clerk, Prisma, React Native까지 12개 카테고리 70개 이상의 스킬이 npx skills add 하나로 설치된다.
여기서 중요한 구분이 있다. SKILL.md는 .cursorrules, CLAUDE.md, AGENTS.md, llms.txt와 다른 목적의 파일이다. 전자가 특정 라이브러리의 올바른 사용 패턴을 에이전트에게 가르치는 것이라면, 후자들은 프로젝트 컨텍스트나 에이전트 행동 규칙을 다룬다. 혼용하거나 대체 관계로 오해하면 컨텍스트가 오염된다.
세 레이어가 만드는 실전 워크플로우
이 세 가지—막힘 탈출 전략, settings.json 최적화, SKILL.md 기반 스킬 주입—는 사실 Claude Code 운용의 서로 다른 레이어를 다룬다. settings.json이 에이전트가 '어떻게 행동할지'를 결정하는 환경 설정이라면, SKILL.md는 에이전트가 '무엇을 알고 있는지'를 확장하는 지식 주입이고, 루프·포기 탈출 전략은 세션 중 '실시간 제어'다.
세 레이어가 모두 갖춰졌을 때 Claude Code는 비로소 '알아서 돌아가는 도구'에 가까워진다. 반대로 하나라도 빠지면—설정 없이 승인 클릭을 반복하고, 프레임워크 패턴을 매번 프롬프트로 설명하고, 루프에 빠지면 세션을 날리는—비효율이 쌓인다.
시사점: 도구의 한계가 아니라 운용법의 문제
Claude Code가 막히거나 느리게 느껴지는 경험의 상당수는 도구 자체의 한계가 아니라 설정과 운용 방식의 부재에서 온다. 이 세 가지 레이어는 복잡한 커스터마이징이 아니라—사실 몇십 줄의 JSON과 CLI 한 줄로 구성된—최소한의 환경 정비에 가깝다.
AI 코딩 에이전트의 생산성 격차는 점점 '어떤 모델을 쓰는가'보다 '에이전트를 어떻게 설계하고 운용하는가'에서 벌어지고 있다. settings.json을 한 번도 열어보지 않은 채 Claude Code를 평가하는 건, IDE 기본 설정 그대로 쓰면서 생산성을 논하는 것과 다르지 않다.