클로드 코드 에이전트, 스킬 구조 점검하세요! (체크리스트 파일 첨부)
클로드 코드 에이전트, 스킬 구조 점검하세요! (체크리스트 파일 첨부)
말 안장을 엉덩이에 다는 꼴 클로드 코드 에이전트 설정을 수십 번 고쳤는데도 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 등이 어떤 구조로 놓여야 하는지 먼저 알아보겠습니다. 프로젝트 전용 (해당 프로젝트에서만 적용) 글로벌 (모든 프로젝트에 적용) 글로벌은 내 컴퓨터 최상위 폴더에 에이전트, 스킬 폴더를 넣는 것이며 이로써 모든 프로젝트에 사용할 수 있는 글로벌 스킬과 에이전트로 활용할 수 있습니다. 지금 프로젝트 폴더를 열어서 이 구조와 맞는지 비교해보세요. 각 파일의 역할과 주의사항 파일 위치가 맞다면, 각 파일이 어떤 역할을 하고 어떻게 구성해야 하는지 알아야 합니다. CLAUDE.md 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 다운로드 사용법은 간단합니다. 아래 링크에서 ai-harness-checklist.md 파일을 다운로드합니다. 프로젝트 아무 위치에 저장합니다. Claude Code 세션에서 @ai-harness-checklist.md 내 프로젝트의 AI 하네스 구조를 점검하고, 심각도에 따라 수정 방안을 안내해줘라고 입력합니다. Claude가 체크리스트 기준으로 파일 위치, frontmatter, CLAUDE.md 줄 수, tools/mcpServers 분리 등을 점검하고 리포트를 줍니다. 에이전트와 스킬이 이미 많이 설치되어 있다면, 모든 파일을 한 번에 점검하면 토큰 소모가 심할 수 있습니다. 먼저 체크리스트를 읽고 구조를 파악한 뒤, 점검하고 싶은 파일을 하나씩 지정해서 요청하는 게 효율적입니다. "설정이 잘못 채워진 채로 쓰고 있을 가능성이 높습니다." 말 잘 듣던 말도, 안장이 뒷다리에 달려있으면 뛸 수가 없으니까요. 점검해봤는데 여전히 막힌다면 톡방에서 편하게 질문해 주세요. 다들 나에게 꼭 맞는 AI 팀을 잘 만들어가시길 바랍니다.
클로드 코드 에이전트 & 스킬, 자동 세팅 파일 공개!
클로드 코드 에이전트 & 스킬, 자동 세팅 파일 공개!
안녕하세요 시몬입니다! 지난 AI 하네스 웨비나에서 약속드린 에이전트, 스킬 자동 설정 파일 링크와 사용법을 안내드려요! 웨비나에서 직접 시연해 드리긴 했지만, 막상 혼자 세팅하려면 여전히 어려운 분들이 많을 거라 생각합니다. 그런 분들을 위해 준비했습니다. 원래 모바일과 웹 범용으로 쓸 수 있게 만들었었는데, 검증 범위가 넓어지다 보니 웹 전용으로 스코프를 줄여서 정리했습니다. 프로젝트에 넣고 클로드에게 이 파일을 읽고 설정해달라고 하면 끝납니다. 가이드 파일이 뭔가요? 파일 이름은 claude-web-agent-setting-guide.md입니다. 에이전트와 스킬 세팅을 어떤 순서로, 어떻게 하라고 단계별 지침을 담은 문서입니다. 사용법은 간단해요. 새로운 폴더를 만듭니다 VS Code에서 해당 폴더를 엽니다 가이드 파일을 폴더에 넣습니다 클로드 코드를 실행합니다 @claude-web-agent-setting-guide.md 로 파일을 멘션하면서 세팅을 진행해달라고 합니다 AI가 질문하면 답변합니다 전체 세팅 시간은 약 10분 정도 걸려요. 기술 스택은 Next.js (App Router) + Tailwind CSS + TypeScript로 고정되어 있습니다. 웹 프로젝트에 집중해서 검증된 구성을 바로 쓸 수 있게 만들었습니다. 세팅이 끝나면 프로젝트에 아래와 같은 구성이 완료됩니다. 에이전트 4개 (project-manager, designer, frontend-dev, reviewer) 파이프라인 스킬 (에이전트 4개를 순서대로 조율하는 오케스트레이터) 디자인 시스템 + 디자인 토큰 파일 (CSS 변수 포함) 프로젝트 지시 파일 (CLAUDE.md) 기술 스택에 맞는 스킬 설치까지 Step 0~7, 어떻게 진행되나요? 파일 하나를 멘션하면 총 8단계가 순서대로 진행됩니다. Step 0: 경로 변수 설정 (에이전트, 스킬, 문서 저장 위치 확인) Step 1: Next.js 프로젝트 초기화 (create-next-app + 빌드 확인) Step 2: 서비스 정의 (서비스명, 타겟, 핵심 기능을 대화형으로 수집) Step 3: 브랜드 아이덴티티 + 디자인 시스템 (키컬러, 토큰, CSS 변수까지) Step 4: 스킬 설치 (find-skills, skill-creator, frontend-design + 스택별 추천) Step 5: 에이전트 4개 생성 (PM, Designer, Frontend-dev, Reviewer) Step 6: 파이프라인 스킬 생성 (에이전트 팀을 조율하는 오케스트레이터) Step 7: 프로젝트 지시 파일 생성 (CLAUDE.md) 설치 후 어떻게 작동하나요? 세팅이 끝나면 "랜딩페이지 만들어줘"처럼 태스크를 요청하면 됩니다. 파이프라인 스킬이 자동으로 실행되면서 아래 순서로 진행됩니다. PM이 기능 명세를 작성합니다 명세를 확인하고 승인합니다 디자이너가 화면을 설계합니다 설계를 확인하고 승인합니다 프론트엔드 개발자가 코드를 구현합니다 리뷰어가 코드를 검토합니다 각 단계 사이에 승인 게이트가 있어서 결과를 확인하고 수정을 요청할 수 있습니다. 현재 디자이너 에이전트는 텍스트 기반의 디자인 계획만 작성합니다. 여기에 Figma MCP나 Pencil MCP를 연결하면 실제 디자인 결과물을 만들고 승인받는 워크플로우로 확장할 수 있습니다. Pencil MCP 사용법은 지난 웨비나 영상에서 다뤘으니 참고하세요. 디자인 시스템 관련 설정도 포함 바이브 코딩으로 만든 앱들이 디자인 시스템 관련 세팅 없이 바로 개발에 들어가는 경우가 많습니다. 그래서 아예 과정 중에 디자인 관련 세팅이 포함되도록 구성했습니다. 키컬러, 브랜드 느낌, 테마 모드를 하나씩 결정하면 Tailwind v4 기반의 디자인 토큰 파일과 CSS 변수가 자동으로 생성됩니다. 뜯어보면서 배우셔도 좋습니다 클로드 코드 서브에이전트 구성을 처음 하려는 분들이 제일 많이 하는 말이 "어디서부터 시작하냐"입니다. 설명을 드려도 막연하고, 예시 코드를 드려도 어떻게 조합해야 할지 모르는 경우가 많습니다. 가이드 파일 자체를 읽어보면 에이전트 파일, 스킬 파일, 프로젝트 지시 파일이 어떤 역할을 하고 어떻게 연결되는지 감을 잡을 수 있습니다. 실제로 돌려보지 않더라도 구조를 이해하는 데 도움이 됩니다. 주의사항 에이전트를 활용한 작업은 토큰 소모가 많습니다. Pro 플랜 사용자분들은 빠르게 리밋에 도달할 수 있으니 참고하세요. 클로드 코드 세팅, 이제 막막하지 않습니다 클로드 코드 사용법을 배우는 과정에서 에이전트 팀 구성은 진입 장벽처럼 느껴지죠. 실제로 해보면 생각보다 단순합니다. 다만 처음엔 어떤 구조로 잡아야 하는지 감이 없을 뿐입니다. 이 가이드 파일이 그 첫 감을 잡는 데 도움이 됐으면 합니다. 아래 이메일을 입력하시면 자료를 보내드려요!
710명이 신청한 AI 하네스 웨비나 후기 & 자료 안내
710명이 신청한 AI 하네스 웨비나 후기 & 자료 안내
710명. 웨비나 신청자 수를 확인했을 때 이 숫자가 맞나 싶었는데 그 만큼 요즘 AI에 대한 관심이 정말 많다는 게 느껴졌습니다. 웨비나 성과와 영상, 그리고 자료를 공유드려요! 710명이 신청한 특강 3월 26일 저녁, "클로드 코드 에이전트 & 스킬 세팅법(AI 하네스)" 무료 웨비나를 진행했습니다. 프리랜서, 디자이너, 서비스기획자, 자영업자, 기술 총괄까지 다양한 분들이 오셨고 다들 AI를 더 잘 쓰고 싶다는 마음으로 3시간이나 자리를 지켜주셨어요. 웨비나 종료 후 후기를 받았는데, 무엇이 가장 도움이 되었는지 질문에 대한 답변 몇 가지를 가져왔습니다. "전체 프로세스가 어떻게 되는지, 파일 및 폴더 구조가 어떻게 되는지, 스킬·에이전트 등의 역할 및 특징에 대한 설명이요!" (퍼블리싱/UIUX 디자이너, 5년차) "밑바닥부터 AI 하네스를 만드는 부분" (기술 총괄, 20년차) "팀을 꾸려서 프로젝트를 진행한다는 것에 영감을 많이 받았어요." (디자이너, 10년차) "버벅임마저 초보인 제겐 복기할 수 있는 시간이라 그것마저 좋았어요. ADHD라 긴 영상 못 보는데 이 악물고 다 봄" (디자이너, 10년차) "정말 디테일하게 알려주신 점이 좋았습니다!" (프로덕트 디자이너, 3년차) 에이전트 설계인 것 같아요. 그리고 스킬을 계속 넣어가면서 디자인 에이전트를 확장시켜가는게 너무 흥미로웠어요. 정말 도움 많이되었습니다. 만수무강하세요 (프로덕트 디자이너, 3년차) 후기는 항상 콘텐츠 만들 때 응원과 도움이 많이 됩니다! 특히 ADHD 후기는 세 번 읽었어요 🥲 AI 하네스, 뭘 배웠냐면 이번 특강의 핵심은 "AI가 내 말을 잘 들을 수 있도록 환경을 설정하는 것"이었습니다. AI 하네스는 말의 고삐처럼, AI를 내가 원하는 방향으로 움직이게 하기 위한 구조적인 세팅법입니다. 핵심 개념은 네 가지입니다. 에이전트 분리 - 역할별로 AI를 나눠서 각자 할 일을 명확히 한다 스킬 파일 - AI가 특정 작업을 일관되게 수행하도록 참조하는 지식 파일 MCP 서버 - AI가 외부 도구(API, 검색 등)에 접근할 수 있도록 연결하는 프로토콜 CLAUDE.md - AI에게 프로젝트 맥락과 규칙을 알려주는 설정 파일 개념 설명 후에는 어떻게 세팅을 하는지 워크플로우를 안내하고, 백지 상태에서 이걸 직접 만드는 과정을 라이브로 시연했습니다. 웹사이트를 만드는 에이전트팀, 그리고 글을쓰고 이미지를 만드는 콘텐츠 프로덕션 팀 두 개를 세팅하는 것이 목표였으나 꼭 웨비나 할 때마다 AI가 말을 참 안 들어서 결국 웹사이트 에이전트팀 하나를 제대로 보여드리는 것에 집중했습니다. 🥲 참고로 웹사이트, 모바일 제작 에이전트와 스킬 세팅을 도와주는 가이드 파일도 함께 드리겠다고 했었는데요. 사용법 없이 파일만 드리면 활용이 어려울 것 같아서, 다음 글에서 사용법과 함께 안내드리겠습니다! 다음 웨비나 예정 일정은 아직 미정이지만 조만간 콘텐츠 프로덕션팀도 웨비나를 준비해보려고 합니다. 이번에 710명의 신청자를 보니 요즘 AI에 대한 관심이 정말 뜨거워졌다는게 느껴집니다. 제가 도울 수 있는 것들이 더 있다는 생각이 들어서 열심히 도와보겠습니다. 웨비나 소식은 항상 바입빌딩클럽 톡방에 가장 먼저 공유됩니다. 카카오톡 오픈채팅 입장하기 입장하셔서 바이브코딩 관련 다양한 질문과 정보를 공유해주세요! 자료 공유 아래 뉴스레터를 구독하시면 이메일로 자료 링크가 자동 전송됩니다!
기획 · 디자인 · 수요조사 · 개발까지, 바이브코딩 A-Z 라이브 웨비나 영상 & PDF
기획 · 디자인 · 수요조사 · 개발까지, 바이브코딩 A-Z 라이브 웨비나 영상 & PDF
AI를 활용해 아이디에이션부터 PRD 작성, Stitch를 활용한 디자인과 제품 제작까지. 2시간동안 바이브 코딩으로 제품 제작 과정을 모두 담았습니다. 진행 순서 이번 웨비나는 약 2시간 동안 아래와 같은 순서로 진행되었어요 즉석에서 AI와 제품 아이디에이션 하나 선정해 AI와 PRD 작성 AI(Stitch)를 활용해 디자인 노션 AI를 활용한 랜딩페이지 제작 & 배포 (Tally와 Kutt 를 이용한 방문자 & 전환률 측정) 안티그래비티와 커서로 제품 제작 실습 비교 아래는 웨비나 스냅샷입니다! [기획 단계 설명] [AI와 아이디에이션] [AI로 디자인] [커서 & 안티그래비티로 제작] 물론 안티그래비티가 중간에 퍼져서 실제 제대로된 비교를 하진 못했지만 전체적인 AI와의 제품 개발 프로세스를 이해하시는데 충분하실겁니다! 아래 뉴스레터를 구독하시면 이메일로 자료 링크가 자동 전송됩니다!