아프니까 개발자다 아프니까 개발자다

GitHub 저장소를 플러그인 구조로 만들면 /plugin install 한 줄로 설치할 수 있다. 더 나아가 Anthropic의 공식 마켓플레이스에 제출하면 전 세계 Claude Code 사용자가 이름만으로 설치하는 것도 가능하다. 이 글은 로컬 설치부터 마켓플레이스 배포까지 전체 흐름을 다룬다.플러그인 배포의 세 단계플러그인을 만들면 대개 이 세 단계를 차례로 거친다. 처음에는 로컬 디렉토리를 그대로 설치해 수정-실행 사이클을 빠르게 돌린다. 동작이 검증되면 GitHub에 올려 팀원·외부에 URL을 공유하고, 충분히 안정화된 뒤에만 마지막 단계인 마켓플레이스 제출을 고민한다. 각 단계에서 코드의 모양은 바뀌지 않고 설치 출처만 달라진다는 점이 핵심이다 — 사용자 입장에서는 어떤 단계든 /plugin ..

서브에이전트 파일을 만들었다면 다음 질문이 온다. 이 파일을 어디에 두어야 하는가? Claude Code는 세 위치를 스캔한다 — 사용자 홈의 전역 디렉토리, 프로젝트의 로컬 디렉토리, 그리고 설치된 플러그인 캐시. 어디에 두느냐에 따라 적용 범위·팀 공유·버전 관리가 달라진다.Claude Code가 에이전트를 찾는 세 경로세 위치 모두 스캔되고 통합된다. 같은 name이 여러 위치에 있으면 프로젝트 에이전트가 전역보다 우선한다. 플러그인 에이전트는 설치된 패키지에서 로드된다.전역 배치 — ~/.claude/agents/▲ 전역 배치 구조 — 한 곳에 두면 모든 프로젝트에 적용된다▲ 전역 배치의 장점 — 중앙 관리와 즉시 적용▲ 전역 배치의 단점 — 팀 공유 불가와 Git 추적 부재전역은 "어떤 프로젝트..

서브에이전트의 tools 필드에는 기본 도구(Read, Edit, Bash, Grep)를 지정한다. 그런데 이 기본 도구만으로 커버되지 않는 능력이 필요할 때가 있다. 웹 페이지를 직접 가져오거나, 가설을 단계별로 구조화해서 추론하거나, 외부 API를 호출하거나. 이런 새 도구는 MCP 서버에서 온다. 어떤 MCP 서버를 쓸지를 정의하는 파일이 .mcp.json이다.MCP(Model Context Protocol)는 AI 모델이 외부 시스템·도구를 표준 방식으로 호출하는 프로토콜이다 — USB-C처럼 다양한 장치를 하나의 표준 포트로 연결하는 것과 같다..mcp.json이 없을 때 vs 있을 때▲ .mcp.json 없음 — 기본 도구만, 외부 능력 없음▲ .mcp.json 있음 — MCP 도구로 외부 능..

에이전트 정의 마크다운 파일 하나만 있으면 서브에이전트로 동작하는데, 왜 plugin.json이 필요한가? 그 답은 하나다. plugin.json이 있어야 Claude Code가 그 디렉토리를 "설치 가능한 패키지"로 인식한다. 이 파일이 없으면 디렉토리는 그냥 폴더일 뿐이고, /plugin install로 설치하거나 팀원과 공유하는 것이 불가능해진다.plugin.json이 하는 단 하나의 일파일 수백 바이트가 에이전트의 지위를 바꾼다. plugin.json이 있는 순간 디렉토리는 설치·배포·버전 관리가 가능한 패키지로 격상된다. 에이전트 자체의 능력은 변하지 않는다 — 단지 그 에이전트를 배포하는 방법이 생기는 것이다.플러그인 디렉토리는 어디에 둬도 된다 — 단 내부 구조는 고정먼저 한 가지 오해를 풀..

Claude Code에서 서브에이전트를 만들면 어떤 파일이 어떤 경로에 만들어질까? "마크다운 파일 하나"로 끝나는 단순한 경우도 있고, 네 종류의 파일이 특정 디렉토리 구조로 배치된 플러그인 패키지가 되는 경우도 있다. 이 글은 서브에이전트의 파일 구성 전체 지도를 그린다.두 형태의 갈림길 — 새 도구가 필요한가갈림길은 단순하다. 기존 Claude Code 기본 도구(Read, Edit, Bash, Grep 등)만으로 충분하면 마크다운 파일 하나로 끝난다. 외부 도구가 필요하면 플러그인 패키지로 키운다.단독 에이전트 — 파일 하나의 해부frontmatter가 설정이고 본문이 지시서다. frontmatter가 "이 에이전트를 언제 켜고 어떤 도구를 허용할지"를 정의하고, 시스템 프롬프트가 "켜진 에이전트..

GitHub MCP와 Playwright MCP는 도구 목록만 제공한다. 시스템 프롬프트와 트리거는 사용자가 별도로 만들어야 한다. 반면 debug-pack 플러그인은 다르다. 서브에이전트의 3가지 핵심 구성요소(시스템 프롬프트·도구 목록·트리거)가 모두 패키지 안에 들어 있다. 게다가 슬래시 커맨드(/debug-here)까지 묶여 있어, 설치하는 순간 Python 디버깅 전용 에이전트 생태계가 한 번에 세팅된다.이 플러그인이 흥미로운 이유는 두 가지다. 첫째, 실제 서브에이전트 패키지가 어떻게 구성되는지 가장 완전한 형태로 보여주는 예시다. 둘째, Python 디버깅이라는 구체적인 문제를 풀기 위해 두 개의 MCP 서버(sequential-thinking, fetch)가 함께 포함되어 있어, 단순 역할..