현대적이며 모범적인 바이브코딩 작업을 돕는 파일 3가지 비교
핵심 정리
바이브코딩을 시작한 많은 입문자가 비슷한 경험을 한다. Claude나 Cursor에게 코드를 부탁하면 처음엔 잘 만들어주는데, 세션이 바뀌거나 파일이 늘어날수록 “이전에 우리가 이렇게 하기로 했잖아요”가 통하지 않는다. AI는 대화가 끊기면 모든 것을 잊는다. 이 문제를 해결하는 열쇠가 바로 claude.md, skills.md, agents.md 세 파일이다.
세 파일의 차이를 한 줄로 먼저 정리하면 이렇다.
| 파일 | 한 줄 정의 | 소프트웨어 용어로 비유 |
|---|---|---|
| claude.md | “이 프로젝트가 무엇인지” 알려주는 파일 | README + Architecture Decision Records |
| skills.md | “이렇게 코드를 짜기로 했다”는 패턴 모음 | 디자인 패턴 라이브러리 + 코딩 컨벤션 |
| agents.md | “이런 작업은 AI에게 이렇게 시키자”는 지시서 | Runbook + SOP (표준 운영 절차) |
이 세 파일을 프로젝트 루트에 만들어두면, 새 AI 세션을 시작할 때마다 “우리 프로젝트는 React + Vite고, API 호출은 TanStack Query로 하고, 새 페이지가 필요하면 AGENT-01을 호출하면 돼”라는 맥락이 자동으로 복원된다.
1. claude.md — AI에게 건네는 프로젝트 브리핑서
소프트웨어 개발에서 신입 팀원이 합류하면 가장 먼저 무엇을 주는가. 코드베이스 구조, 기술 스택, 팀의 코딩 규칙, 지금 어떤 기능을 만들고 있는지를 담은 온보딩 문서다. claude.md는 정확히 그 역할을 한다. 단지 대상이 사람이 아니라 AI라는 점이 다를 뿐이다.
claude.md가 없으면 어떤 일이 벌어지는지 보자. 개발자가 Claude에게 “로그인 페이지 만들어줘”라고 요청한다. Claude는 열심히 코드를 만들어주는데, 이미 프로젝트에서 쓰고 있는 React Hook Form은 쓰지 않고 직접 useState로 폼을 구현한다. 라우터 구조도 기존 패턴과 다르고, 인증 상태 관리는 Context API를 쓰는데 프로젝트는 Zustand를 쓴다. 결국 개발자가 직접 뜯어고쳐야 한다.
claude.md가 있으면 Claude는 프로젝트의 기술 스택, 디렉터리 구조, 금지 사항(“any 타입 쓰지 말 것”, “컴포넌트에 API 호출 직접 작성 금지”)을 이미 알고 있는 상태로 코드를 생성한다. 수정 횟수가 줄고, 기존 코드와 어색하게 섞이는 문제도 사라진다.
claude.md에 반드시 들어가야 할 내용:
첫째, 기술 스택과 버전이다. “React 18 + Vite 5, TypeScript strict mode, Tailwind CSS”처럼 구체적인 버전까지 명시해야 한다. AI는 버전에 따라 문법과 API 사용 방식이 달라진다는 것을 알고 있다.
둘째, 디렉터리 구조다. components/ui/에는 재사용 가능한 원자 컴포넌트가 들어가고, components/features/에는 도메인별 복합 컴포넌트가 들어간다는 규칙을 알아야 새 파일을 엉뚱한 곳에 만들지 않는다.
셋째, 명시적인 금지 사항이다. “하지 마라”는 규칙은 “이렇게 해라”보다 더 직접적인 제약이 된다. console.log 커밋 금지, 컴포넌트 내 비즈니스 로직 직접 작성 금지처럼 팀이 과거에 겪은 실수에서 나온 규칙들을 담는다.
넷째, 현재 진행 상황이다. 완료된 기능, 지금 만들고 있는 기능, 다음에 만들 기능을 체크리스트로 관리하면 AI가 “지금 어디까지 왔는지”를 파악하고 이미 만든 것을 중복으로 제안하지 않는다.
claude.md는 프로젝트가 살아있는 동안 함께 살아있어야 한다. 기술 결정이 바뀔 때마다 업데이트하지 않으면 AI에게 거짓말을 하는 셈이 된다.
2. skill.md — “우리 팀은 이렇게 짠다”는 코드 레시피북
소프트웨어 개발에는 디자인 패턴이라는 개념이 있다. 반복되는 문제에 대한 검증된 해법을 이름 붙여 공유하는 방식이다. Observer 패턴, Factory 패턴처럼 말이다. skill.md는 프로젝트 수준의 디자인 패턴 라이브러리다. 팀(또는 혼자라도)이 이 프로젝트에서 반복적으로 쓰는 코드 패턴을 이름 붙이고 예시와 함께 보관한다.
왜 필요한가. API 연동 코드를 예로 들어보자. 세션 1에서 게시글 목록을 가져오는 훅을 TanStack Query로 만들었다. 세션 2에서 사용자 프로필을 가져오는 훅이 필요해 Claude에게 맡겼는데, 이번엔 queryKey 네이밍 방식이 다르고 staleTime 설정도 없고 enabled 옵션도 빠져 있다. 기술적으로 작동은 하지만 프로젝트 전체의 일관성이 깨진다.
skill.md에 “SKILL-01. API 훅 패턴”을 정의해두면, Claude는 새 훅을 만들 때마다 동일한 구조로 코드를 생성한다. queryKey는 [도메인, 리소스, id] 형태로 계층화하고, staleTime은 5분이 기본이고, 조건부 실행은 enabled로 처리한다는 규칙이 코드로 박혀있기 때문이다.
skill.md 작성의 핵심 원칙:
우선 패턴에 이름을 붙여야 한다. “API 훅은 TanStack Query로 만든다”는 글로 쓰는 것보다 “SKILL-01. API 훅 패턴”이라는 이름과 함께 실제 코드 예시를 주는 것이 훨씬 강력하다. AI는 예시 코드를 그대로 모방하는 능력이 뛰어나다.
그리고 “언제 사용”을 명시해야 한다. 패턴이 있어도 AI가 언제 그 패턴을 적용해야 하는지 모르면 소용없다. “서버 데이터를 가져오거나 변경할 때”, “여러 컴포넌트가 공유하는 앱 수준 상태일 때”처럼 적용 조건을 써준다.
마지막으로 새 패턴을 발견하면 즉시 추가한다. 바이브코딩에서 자주 벌어지는 일은 “AI가 만들어준 코드가 너무 좋은데 다음번엔 다르게 만드네”다. 좋은 코드를 발견한 즉시 skill.md에 SKILL-XX로 등록해두면 그 패턴이 프로젝트 표준이 된다.
3. agents.md — 반복 작업을 위임하는 표준 운영 절차서
기업에서는 반복되는 업무에 SOP(Standard Operating Procedure, 표준 운영 절차)를 만든다. “신규 직원 온보딩은 이 순서로 진행한다”, “서버 장애가 발생하면 이 체크리스트를 실행한다”처럼 말이다. agents.md는 개발 과정에서 반복되는 AI 위임 작업의 SOP다.
개발을 하다 보면 생각보다 많은 작업이 패턴화될 수 있다. 새 페이지를 만들 때, 컴포넌트가 너무 커져서 분리할 때, API 엔드포인트 하나가 생겼을 때, PR 올리기 전에 점검할 때. 이 작업들을 매번 Claude에게 자유형으로 설명하면 실행 결과가 일관되지 않는다. agents.md에 정형화된 호출 형식을 정의해두면 “AGENT: 신규 페이지 스캐폴딩 / INPUT: 이름, 경로, 기능 설명”만으로 동일한 품질의 결과물이 나온다.
agents.md와 claude.md, skill.md의 결정적 차이:
claude.md와 skill.md가 “무엇인지”와 “어떻게 짜는지”를 정의하는 상태(State) 문서라면, agents.md는 “어떤 작업을 어떤 순서로 실행하는지”를 정의하는 행동(Action) 문서다. 소프트웨어 아키텍처 관점으로 보면 claude.md와 skill.md는 데이터 모델이고, agents.md는 메서드(함수)다.
잘 만든 에이전트의 구성:
에이전트 하나에는 목적, 호출 형식, 실행 지시, 출력 기대값이 있어야 한다. 목적은 “왜 이 에이전트가 존재하는가”다. 호출 형식은 “어떤 입력을 줘야 하는가”다. 실행 지시는 Claude가 순서대로 따를 단계별 체크리스트다. 출력 기대값은 “어떤 형태로 결과가 나와야 만족인가”다.
실행 지시를 번호 목록으로 작성하는 것이 중요하다. AI는 명확한 순서가 있을 때 빠뜨리는 단계가 줄어든다. “배포 전 점검 에이전트”에 “코드 품질 → 보안 → 성능 → Vercel 설정” 순으로 체크리스트를 주면, Claude는 그 순서대로 빠짐없이 점검한 뒤 심각도별로 분류해 결과를 돌려준다.
세 파일의 관계 — 소프트웨어 레이어로 이해하기
세 파일이 어떻게 맞물리는지 소프트웨어 아키텍처 레이어로 설명하면 더 명확해진다.
┌─────────────────────────────────────────┐
│ agents.md (행동 레이어) │
│ "이 작업은 이 순서로, 이 규칙에 맞게 실행" │
│ ↓ 실행할 때 아래 두 레이어를 참조함 │
├─────────────────────────────────────────┤
│ skill.md (패턴 레이어) │
│ "코드는 이 방식으로 작성한다" │
│ ↓ 패턴의 적용 범위는 아래 레이어가 결정함 │
├─────────────────────────────────────────┤
│ claude.md (컨텍스트 레이어) │
│ "이 프로젝트는 이런 곳이다" │
└─────────────────────────────────────────┘
Claude는 작업 요청을 받으면 자연스럽게 이 레이어를 아래에서 위로 읽는다. “이 프로젝트가 어떤 기술 스택을 쓰는지(claude.md) 파악하고, 그에 맞는 코드 패턴이 무엇인지(skill.md) 확인하고, 지금 요청받은 작업을 어떤 순서로 실행해야 하는지(agents.md) 따른다.”
세 파일 중 하나만 있어도 도움이 되지만, 셋이 함께 있을 때 효과가 기하급수적으로 커진다. claude.md만 있으면 기술 스택은 일관되지만 코드 패턴이 매번 달라진다. skill.md만 있으면 코드 품질은 높지만 AI가 프로젝트 구조를 몰라 엉뚱한 곳에 파일을 만든다. agents.md만 있으면 작업 절차는 정형화되지만 생성된 코드가 프로젝트 컨벤션과 맞지 않는다.
결론: 오늘 당장 시작할 수 있는 액션 3가지
바이브코딩 입문자에게 가장 흔한 실수는 “일단 만들고 나중에 정리하자”다. AI가 빠르게 코드를 만들어주니 초기에는 잘 돌아가는 것처럼 보인다. 그러나 프로젝트가 커질수록 AI가 만든 코드들이 서로 충돌하고, 수정 비용이 새로 만드는 것보다 커지는 시점이 반드시 온다. 세 파일은 그 시점을 늦추거나 아예 방지하는 보험이다.
아래 세 가지를 오늘 바로 실행해보자.
액션 1. claude.md 15분 안에 초안 만들기
새 프로젝트를 시작하거나 기존 프로젝트에 AI를 도입하는 순간이 claude.md를 만들 최적의 타이밍이다. 기술 스택, 디렉터리 구조, 금지 사항 세 가지만 먼저 채워도 충분하다. 나머지는 개발하면서 채운다. Claude에게 “우리 프로젝트의 기술 스택은 X이고 디렉터리 구조는 Y야. 이를 바탕으로 claude.md 초안을 만들어줘”라고 요청하면 시작점을 빠르게 만들 수 있다.
액션 2. 첫 번째 SKILL 등록하기
skill.md는 비어 있는 채로 시작해도 된다. 개발 중에 “이 코드 패턴이 마음에 든다”는 순간이 오면 그것을 SKILL-01로 등록한다. 보통 API 호출 패턴이나 상태 관리 패턴이 첫 번째 스킬이 된다. 스킬이 3개를 넘어가면 그때부터 AI가 일관된 코드를 만들기 시작한다는 체감이 온다.
액션 3. 가장 자주 반복하는 작업 하나를 에이전트로 만들기
“새 컴포넌트 만들 때마다 같은 말을 Claude에게 설명한다”고 느끼는 순간이 agents.md를 시작할 타이밍이다. 가장 자주 반복하는 작업 하나만 골라 AGENT-01로 정의한다. 다음번에 같은 작업이 필요할 때 “AGENT: [이름] / INPUT: [값]”으로 호출해보면 그 효과를 바로 확인할 수 있다.
세 파일은 AI와 함께 일하는 방식을 시스템화하는 첫 번째 단계다. 팀으로 개발할 때는 팀 전체가 AI와 일관된 방식으로 협업하는 토대가 되고, 혼자 개발할 때는 6개월 후의 자신이 과거의 결정을 이해할 수 있는 기록이 된다. 코드를 잘 만드는 것만큼, 코드를 만드는 방식을 잘 설계하는 것이 바이브코딩 시대의 핵심 역량이다.
