클로드 코드로 규모 있는 프로젝트를 진행하다 보면 한 세션에서 끝나지 않는 작업이 생기기 마련입니다. 인증 시스템을 추가하려면 DB 스키마부터 설계하고, API 엔드포인트를 만들고, 프론트엔드를 고치고, 테스트까지 작성해야 하죠. 문제는 이 과정에서 어디까지 했고 뭐가 남았는지 추적하기가 쉽지 않다는 겁니다. 🤔 예전에는 Claude Code가 내부적으로 Todo라는 간단한 체크리스트를 사용했는데요. 세션 메모리에만 존재해서 터미널을 닫거나 /clear를 하면 사라져 버렸습니다. 서브 에이전트도 메인 세션의 Todo를 볼 수 없었
이전 글에서 Agent Skills가 무엇인지, 왜 필요한지 살펴보았습니다. 컨텍스트 파일이 "프로젝트 소개서"라면, Skills는 "업무 매뉴얼"이라고 했죠. 이번 글에서는 한 걸음 더 나아가 직접 Skill을 설계하고 SKILL.md로 작성하는 방법을 알아보겠습니다. 🛠️ 좋은 Skill의 조건 Skill을 만들기 전에 어떤 Skill이 잘 동작하는지 생각해 볼 필요가 있습니다. 가장 중요한 건 범위가 명확해야 한다는 점입니다. "웹 개발하기" 같은 광범위한 Skill보다는 "Next.js API 라우트 작성하기"처럼 구체적인
AI 코딩 에이전트를 사용하다 보면 같은 종류의 작업을 반복적으로 요청하게 될 때가 있습니다. 예를 들어, "이 프로젝트에서는 Jest 대신 Vitest를 사용해", "API 테스트를 작성할 때는 이런 패턴을 따라줘", "마이그레이션 스크립트를 작성할 때는 항상 롤백 코드도 함께 작성해" 같은 지시를 매번 반복하게 되죠. 🤔 AGENTS.md나 CLAUDE.md 같은 컨텍스트 파일로 프로젝트 전반에 대한 정보를 제공할 수 있지만, 특정 작업에 대한 세부 지침까지 모두 담기에는 한계가 있습니다. 컨텍스트 파일이 너무 길어지면 AI가
클로드 코드를 사용하다 보면 "이 파일은 자동으로 수정되지 않았으면 좋겠는데", "코드 수정 후에 자동으로 Prettier를 돌리고 싶은데", "Claude가 작업을 마치면 알림을 받고 싶은데"와 같은 생각이 들 때가 있지 않으셨나요? 🤔 이런 요구사항들을 충족시키기 위해 클로드 코드는 Hooks라는 강력한 기능을 제공합니다. Hooks를 사용하면 클로드 코드의 라이프사이클 중 특정 시점에 사용자가 정의한 쉘 명령어나 스크립트를 자동으로 실행할 수 있습니다. Hooks란 무엇인가요? Hooks는 클로드 코드가 특정 작업을 수행하기
클로드 코드에서 서브 에이전트를 쓰면 대화 도중에 특정 작업을 별도의 에이전트에게 위임할 수 있습니다. 코드 탐색은 Explore에게, 리뷰는 커스텀 에이전트에게 맡기는 식이죠. 그런데 가끔은 대화 중에 에이전트를 호출하는 게 아니라, 시작부터 끝까지 하나의 에이전트로 세션 전체를 운영하고 싶을 때가 있습니다. "이번 세션은 코드 리뷰만 할 거야"라거나 "CI 파이프라인에서 린트 체크만 돌리고 싶어"라는 상황이요. 이럴 때 쓰는 게 바로 --agent 플래그입니다. 무엇이 달라지나 보통 클로드 코드를 실행하면 기본 시스템 프롬프트와
클로드 코드로 복잡한 작업을 하다 보면 한 가지 아쉬운 점이 있습니다. 아무리 똑똑한 에이전트라도 결국 하나의 세션에서 순차적으로 작업하니까요. 프론트엔드를 고치고 백엔드 API를 수정하고 테스트까지 작성하려면 한 명이 모든 걸 해야 하는 셈이죠. 🤔 실제 개발팀에서는 어떻게 일할까요? 한 사람이 UI를 만들고 다른 사람이 API를 짜고 또 다른 사람이 테스트를 작성합니다. 서로 진행 상황을 공유하고 막히는 부분이 있으면 의논하면서 병렬로 작업을 진행하죠. 이런 팀워크를 AI에게도 적용할 수 있다면 어떨까요? 바로 이런 아이디어에
클로드 코드로 작업하다 보면 하나의 요청이 여러 단계로 나뉘는 경우가 많습니다. 테스트를 돌려서 실패하는 항목을 파악하고 관련 코드를 탐색한 다음 수정 방안을 정리해서 실제 코드를 고치는 식이죠. 이 과정에서 Claude의 컨텍스트 윈도우에는 테스트 출력이며 탐색 결과며 온갖 정보가 쌓이면서 정작 중요한 맥락이 밀려나 버립니다. 🤯 이런 문제를 해결하려고 Claude Code는 **서브 에이전트(Sub-agent)**라는 구조를 도입했습니다. 메인 대화에서 특정 작업을 별도의 에이전트에게 위임하면 그 에이전트가 독립된 컨텍스트 윈
클로드 코드를 써보셨다면 "이 명령어를 실행해도 될까요?"라는 팝업이 익숙하실 겁니다. 처음엔 안전장치니까 반갑지만 반복되면 점점 피로해지죠. 결국 내용을 대충 훑고 승인 버튼을 누르게 되는데 이러면 오히려 보안에 취약해집니다. Claude Code의 샌드박스는 이 문제를 해결합니다. 명령어를 일일이 검사하는 대신 OS 레벨에서 실행 환경 자체를 격리해서 안전한 경계 안에서는 자유롭게, 경계 밖으로는 절대 못 나가게 만드는 거죠. 왜 샌드박스가 필요한가 클로드 코드 권한 설정에서 다뤘던 권한 시스템은 "이 도구를 써도 되는가?"를
클로드 코드 플러그인을 설치해서 쓰다 보면 "이걸 우리 팀에 맞게 직접 만들 수 있지 않을까?"라는 생각이 들기 마련입니다. .claude/ 디렉토리에 스킬이나 Hooks를 설정해서 잘 쓰고 있다면 이미 플러그인의 반은 만든 셈이에요. 이 글에서는 간단한 스킬 하나짜리 플러그인부터 시작해서 Hooks, MCP 서버, LSP 서버를 포함하는 완전한 플러그인을 만들고 마켓플레이스를 통해 팀이나 커뮤니티에 배포하는 과정까지 다룹니다. 플러그인을 설치하고 관리하는 방법은 플러그인 사용법을 참고하세요. 첫 플러그인 만들기 간단한 인사 스킬을
클로드 코드에 TypeScript LSP를 연결하고, 코드 리뷰 스킬을 추가하고, GitHub MCP 서버까지 설정하려면 건드려야 할 파일이 꽤 많습니다. 스킬, Hooks, MCP 서버를 각각 따로 설정해본 분이라면 이 번거로움을 잘 아실 거예요. 플러그인은 이런 설정을 하나의 패키지로 묶어서 설치 한 번이면 끝나게 해줍니다. 이 글에서는 플러그인을 찾아서 설치하고 관리하는 법을 다루고, 직접 만들어서 배포하는 방법은 플러그인 마켓플레이스 가이드에서 이어집니다. 플러그인이란? 클로드 코드 플러그인은 커스텀 스킬, 에이전트, Hoo
요즘 Cursor나 Claude Code, Codex와 같은 AI 도구로 소프트웨어 개발을 많이 하시죠? 그런데 AI 코딩 에이전트에게 작업을 시키다 보면 프로젝트에 대한 전반적인 지식이 부족하여 엉뚱하게 작업을 진행할 때가 있습니다. 예를 들어, 테스트 파일을 엉뚱한 위치에 생성하거나, 프로젝트의 코딩 컨벤션을 무시하거나, 마음대로 이미 쓰고 있는 라이브러리랑 비슷한 기능을 하는 다른 라이브러리를 설치해버리는 식이죠. 이럴 때는 AI 에이전트에게 좀 더 구체적으로 작업 방향을 알려줄 수 있지만, 새로운 대화 세션을 시작할 때마다
클로드 코드에 프로젝트 규칙을 알려주는 가장 기본적인 방법은 CLAUDE.md입니다. 그런데 프로젝트가 커지면 이 파일 하나가 점점 비대해지죠. 프론트엔드 규칙, 백엔드 규칙, 테스트 컨벤션, 보안 요구사항... 온갖 내용이 한 파일에 뒤섞이면 읽기도 어렵고, 매 세션 전부 로드되니 컨텍스트도 부담스러워집니다. .claude/rules/ 디렉토리는 이 문제를 푸는 방법입니다. 규칙을 주제별로 여러 파일에 나눠 담고, 필요한 순간에만 로드되도록 만들 수 있어요. 이 글에서는 .claude/rules/를 어떻게 구성하는지, 그리고 CL
AI 코딩 에이전트를 쓰다 보면 "이 웹 페이지 좀 열어서 확인해줘"라고 말하고 싶을 때가 종종 있지 않나요? 배포한 사이트에 버그가 있는 것 같을 때, 특정 폼이 제대로 동작하는지 테스트하고 싶을 때, 혹은 경쟁사 사이트의 UI를 참고하고 싶을 때... 하지만 대부분의 AI 에이전트는 터미널 안에서만 동작하기 때문에 브라우저를 직접 다룰 수가 없습니다. 이 문제를 해결하는 것이 바로 Playwright MCP입니다. Microsoft에서 만든 이 MCP(Model Context Protocol) 서버를 AI 에이전트에 연결하면 브
클로드 코드로 작업하다 보면 새 세션을 시작할 때마다 AI가 프로젝트에 대해 아무것도 모른다는 걸 느끼게 됩니다. "테스트는 bun run test로 돌려", "커밋 메시지는 영어로 써줘", "이 프로젝트는 Prettier를 쓰고 있어"... 매번 같은 말을 반복하는 건 꽤 피곤한 일이죠. CLAUDE.md는 이 문제를 해결하는 가장 직접적인 방법입니다. 프로젝트의 빌드 명령어, 코딩 스타일, 아키텍처 결정 같은 규칙을 마크다운으로 적어두면 Claude가 매 세션 시작 시 읽어들이거든요. Git에 커밋하면 팀 전체가 공유할 수 있고
클로드 코드로 작업하다가 "아, 이 방향이 아닌데…"라고 느낀 적 있으신가요? 리팩토링을 요청했더니 파일 10개를 고쳐놓았는데 원래 구조가 나았다거나, 라이브러리를 교체하라고 했다가 오히려 빌드가 깨진다거나. 이런 상황에서 할 수 있는 선택지가 그리 많지 않았습니다. git stash로 코드를 되돌린다 해도 Claude의 대화 컨텍스트에는 잘못된 지시가 그대로 남아 있으니까요. 새 세션을 열면 코드는 원래대로 돌아가겠지만 그동안 쌓아온 맥락이 통째로 날아갑니다. 수동으로 "방금 한 거 취소하고 다시 해줘"라고 설명하자니 토큰만 낭비
클로드 코드에게 "인증 시스템을 추가해줘"라고 요청하면 어떻게 될까요? Claude는 곧바로 파일을 수정하기 시작합니다. DB 스키마를 만들고 미들웨어를 작성하고 라우트를 추가하죠. 그런데 작업이 절반쯤 진행된 시점에 "아, JWT 대신 세션 기반으로 가고 싶었는데…"라는 생각이 든다면? 이미 수정된 파일들을 되돌려야 하는 번거로운 상황이 벌어집니다. 😅 이런 문제를 피하려면 코딩에 들어가기 전에 먼저 설계를 검토하는 단계가 필요합니다. 실제 개발에서도 PR을 올리기 전에 설계 문서를 작성하거나 팀원과 접근 방식을 논의하잖아요.
클로드 코드를 쓰다 보면 "이 파일을 수정해도 될까요?", "이 명령어를 실행해도 될까요?" 하는 승인 팝업이 끊임없이 뜹니다. 한두 번이면 괜찮지만 리팩토링처럼 파일을 수십 개씩 고치는 작업에서는 클릭 노동이 되죠. 반대로 CI/CD 파이프라인에서는 묻더라도 답할 사람이 없습니다. 😅 이처럼 상황마다 필요한 자율성이 다릅니다. 탐색만 할 때는 코드를 건드리지 못하게 막고 싶고, 빌드를 돌릴 때는 편하게 허용하고 싶죠. 클로드 코드의 권한 모드가 이 스펙트럼을 조절해 줍니다. 권한 설정이 "무엇을 허용/차단할까"를 정한다면, 권한
클로드 코드를 쓰다 보면 가장 자주 마주치는 것이 "이 명령어를 실행해도 될까요?"라는 권한 요청 팝업입니다. 처음에는 안전장치로 느껴지지만 매번 답하다 보면 꽤 성가시죠. 이 글에서는 클로드 코드의 권한 시스템을 속속들이 파헤쳐서 안전하면서도 흐름이 끊기지 않는 환경을 만드는 방법을 알아보겠습니다. 권한 시스템의 기본 구조 클로드 코드는 도구 종류에 따라 세 단계의 기본 권한 정책을 적용합니다. | 도구 유형 | 예시 | 승인 필요 | "다시 묻지 않기" 범위 | | ----------- | ---------------------
클로드 코드를 쓰다 보면 파일을 읽거나 코드를 수정하는 것은 사실 Claude가 직접 하는 게 아니라 **도구(Tool)**를 호출해서 처리한다는 걸 알게 됩니다. 코딩 에이전트의 작동 원리에서 다뤘듯이, 언어 모델 자체는 텍스트를 생성하는 것밖에 못 하고 실제 작업은 도구가 대신하는 거죠. 그런데 이 도구 이름을 알아야 하는 이유가 있습니다. 권한 설정에서 Bash(npm run *), Read(./.env) 같은 규칙을 쓸 때 도구 이름이 필요하고, Hooks에서 PreToolUse 매처를 작성할 때도, 서브 에이전트에 허용할
클로드 코드를 설치하고 기본 사용법을 익혔다면 이제 나에게 맞는 환경을 만들어볼 차례입니다. 클로드 코드는 settings.json이라는 설정 파일을 통해 권한 관리부터 모델 선택, 환경 변수, 샌드박스, 커밋 메시지 스타일까지 폭넓게 제어할 수 있는데요. 이 글에서는 설정 체계를 처음 접하는 분도 쉽게 따라올 수 있도록 하나씩 뜯어보겠습니다. 설정 파일의 계층 구조 클로드 코드의 설정은 한 군데 모여 있지 않고 여러 레벨로 나뉘어 있습니다. 각 레벨마다 역할이 다르기 때문에 상황에 맞는 위치에 설정을 놓아야 해요. | 우선순위 |