Claude Code Skills로 프로젝트 지침 설계하기
최근 새로운 사이드 프로젝트를 시작했다.
Claude Code의 작업 방식을 제대로 익혀보는 동시에, 장기적으로는 작은 부수입 파이프라인의 초석을 만들어보자는 목적이었다. 이번 글은 이 프로젝트를 진행하며
CLAUDE.md, Claude Code Skills, 참고 문서의 역할을 처음 정리한 기록이다.프로젝트 이름은 KitFolio다. 근무시간 계산기, 데이터 포맷터, 문서 생성기처럼 직장인이 업무 중 가볍게 사용할 수 있는 작은 웹 도구를 하나의 사이트에 모으고 있다. 회원가입이나 설치가 필요 없고, 별도의 데이터베이스 저장이나 서버 전송 없이 모든 처리가 브라우저 안에서 끝나는 것이 기본 원칙이다.
GPT와 Claude Code를 병행해 아이디어 검증과 제품 설계부터 수익화, 브랜딩, 디자인, 개발까지 전 과정을 AI와 진행하고 있다. 코드 일부만 맡기는 것이 아니라 하나의 제품을 처음부터 끝까지 함께 만들어보는 End-to-End AI Native 프로젝트다.
도구가 한두 개일 때는 필요한 내용을 그때그때 Claude에게 알려주고, 반복되는 규칙만
CLAUDE.md에 추가했다. 다만 무엇을 이 파일에 남기고, 무엇을 별도 문서나 작업 절차로 분리할지는 아직 정해두지 않았다.프로젝트가 구체화되면서 브랜딩, 신규 도구 선정과 구현, 제품 방향성 검토, SEO와 AEO처럼 반복할 작업도 어느 정도 선명해졌다.
이제는 지침을 더 추가하기 전에 Claude가 프로젝트를 이해하고 작업할 수 있도록 정보의 역할과 위치를 정리할 시점이었다.
이번에 정리하려던 질문은 하나였다.
프로젝트 지침 중 무엇을CLAUDE.md에 남기고, 무엇을 Skill과 참고 문서로 분리해야 할까?
프로젝트 지침을 네 가지 역할로 나눴다
먼저 결론부터 정리하면 다음과 같다.
- 항상 필요한 프로젝트 규칙은
CLAUDE.md
- 특정 작업의 실행 절차는 Claude Code Skill
- 제품 방향과 판단 기준은 별도 참고 문서
- 반드시 실행하거나 차단해야 하는 것은 Hook, 테스트, CI
Claude Code Skills는 특정 작업의 절차와 참고 자료를 정의해두는 기능이다. 각각의 작업 단위를 Skill로 구성하면 Claude가 관련 작업에서 선택해 참고할 수 있고, 사용자가 직접 호출할 수도 있다.
KitFolio의 지침은 다음과 같이 나눴다.
역할 | KitFolio의 예시 | 위치 |
기본 규칙 | 기술 스택, URL 구조, 공통 개발 원칙 | CLAUDE.md |
작업 절차 | 신규 도구 구현, 브랜딩·SEO 검토 | .claude/skills/ |
판단 맥락 | 제품 방향, 수익화, 도구 선정 기준 | docs/ai/ |
강제 규칙 | 필수 검사, 금지 작업, 권한 제한 | Hook, 테스트, CI |
기술 스택은 대부분의 작업에서 필요하지만, SEO 체크리스트와 수익화 전략은 각각 특정 작업과 의사결정에서만 필요했다.
모두 프로젝트에 필요한 정보지만 사용되는 시점과 목적은 달랐다.
반복되는 작업은 Skill로 분리했다
KitFolio에서 반복적으로 발생할 작업부터 정리했다.
select-new-tool과 product-review는 제품의 방향과 우선순위를 판단할 때, build-tool은 실제 구현을 진행할 때 사용한다. branding, seo, aeo는 구현 결과가 프로젝트의 기준에 맞는지 검토하는 역할을 맡는다.신규 도구 구현 Skill에는 대략 다음과 같은 절차가 들어간다.
- 기존 도구와 기능이 중복되는지 확인한다.
- 콘텐츠 레지스트리에 도구 정보를 등록한다.
- 한국어와 영어 페이지를 함께 구현한다.
- 메타데이터와 구조화 데이터를 추가한다.
- FAQ와 관련 도구를 연결한다.
- 빌드와 린트를 실행한다.
여기까지만 보면 일반적인 작업 체크리스트와 크게 다르지 않다.
하지만 Skill을 정리하면서 중요하다고 느낀 것은 항목의 개수가 아니었다.
이 프로젝트에서만 유효한 작업 방식을 얼마나 정확하게 담고 있는가였다.
허브 버튼을 직접 추가하지 마라
신규 도구 구현 Skill을 만들기 전에 Claude Code로 실제 소스 구조를 분석했다.
그 과정에서 KitFolio의 여러 기능이 하나의 콘텐츠 레지스트리를 중심으로 연결되어 있다는 점을 다시 확인했다.
홈에 보이는 도구 카드, 사이트맵, 구조화 데이터, 관련 도구 목록, 검색 인덱스는 각각 따로 관리되지 않는다.
하나의 콘텐츠 레지스트리에서 자동으로 파생된다.
따라서 신규 도구를 추가할 때 홈 화면의 버튼이나 카드 목록을 직접 수정할 필요가 없다.
정확히는 직접 수정하면 안 된다.
레지스트리에 항목을 올바르게 추가하면 나머지 영역은 자동으로 반영된다. 홈 카드와 사이트맵을 개별적으로 수정하면 같은 정보가 여러 곳에 생기고, 이후 서로 다른 값을 가질 가능성이 생긴다.
이 구조를 모른 채 “새 도구를 추가해줘”라고 요청하면 에이전트가 홈 컴포넌트와 사이트맵부터 찾는 것은 자연스럽다.
일반적인 웹사이트라면 맞는 접근이다.
KitFolio에서는 아니다.
그래서 Skill에는 단순히 “홈에 신규 도구를 노출한다”고 적지 않았다.
대신 다음과 같이 작성했다.
홈 카드, 사이트맵, JSON-LD, 관련 도구, 검색 인덱스를 직접 수정하지 않는다. 모든 항목은 콘텐츠 레지스트리에서 파생된다.
해야 할 일뿐 아니라 하지 말아야 할 일도 프로젝트 지식이다.
“홈에 버튼을 추가해줘”라는 요청보다 이 한 문장이 실제 코드 구조를 더 정확하게 설명한다.
좋은 Skill은 베스트 프랙티스 모음이 아니다
일반적인 SEO나 브랜딩 모범 사례도 Skill에 넣을 수 있다.
하지만 우선순위는 Claude가 이미 알 수 있는 일반론보다, 코드베이스를 읽어야만 알 수 있는 저장소의 규칙에 두었다.
KitFolio에서는 다음과 같은 내용이다.
- 한국어 페이지는 루트 URL, 영어 페이지는
/en을 사용한다.
- 홈 카드와 사이트맵은 콘텐츠 레지스트리에서 자동으로 파생된다.
- 브라우저 안에서 처리할 수 없는 기능은 기본 제품 원칙과 맞지 않는다.
이 내용은 코드와 제품 구조를 읽지 않으면 알 수 없다.
결국 좋은 Skill은 “웹 서비스를 잘 만들어라”는 문서가 아니다.
이 프로젝트에서는 무엇이 잘 만든 상태인지 정의한 문서다.
이전 글인 AI에게 키보드를 넘기기 전에 알아야 할 것에서는 AI에게 구현을 맡기기 전에 사람이 정책과 구조를 먼저 정의해야 한다는 이야기를 했다.
이번 작업은 그다음 단계에 가까웠다.
정의한 구조와 기준을 에이전트가 실제 작업에서 사용할 수 있는 형태로 저장소에 배치하는 일이었다.
CLAUDE.md는 지식 창고보다 인덱스에 가깝다
프로젝트의 방향, 개발 절차, 디자인 기준, 검색 최적화 체크리스트를 모두
CLAUDE.md에 넣으면 문서는 계속 길어진다.같은 내용을 여러 파일에 복제하기 시작하면 관리도 더 어려워진다.
그래서
CLAUDE.md에는 항상 알아야 할 내용과 세부 지침의 위치만 남겼다.- 프로젝트의 목적
- 핵심 기술 스택
- 중요한 아키텍처 원칙
- 공통 작업 규칙
- 참고 문서와 Skill의 위치
제품의 수익화 전략, 신규 도구 선정 기준, 콘텐츠 운영 원칙은 각각 별도 문서를 원본으로 관리한다.
예를 들어 신규 도구 선정 기준 전체를
CLAUDE.md와 Skill에 다시 복사하지 않았다.CLAUDE.md에는 관련 Skill과 문서의 위치를 남기고, 선정 기준은 별도 문서에서 관리한다. Skill에서는 작업 중 언제 그 문서를 참고해야 하는지를 안내한다.CLAUDE.md가 모든 답을 직접 들고 있을 필요는 없었다.어떤 상황에서 무엇을 확인해야 하는지 알려주는 인덱스에 가까워도 충분했다.
에이전트의 작업 방식도 버전 관리한다
프로젝트 Skill은
.claude/ 아래에 있기 때문에 개인 설정처럼 보이기 쉽다.하지만 저장소의 구조와 작업 절차를 담은 Skill이라면 개인 프롬프트가 아니다. 프로젝트의 운영 자산에 가깝다.
그래서 로컬 설정 전체를 Git에 올리는 대신, 프로젝트에서 공유할 Skill만 추적하도록 구성했다.
코드는 버전 관리하면서 에이전트에게 그 코드를 수정하는 방법은 각자의 로컬 환경에만 두는 것도 조금 이상하다.
코드 구조나 완료 조건이 바뀌면 관련 Skill도 함께 갱신해야 한다.
Skill 역시 코드와 함께 낡는다.
그리고 이런 문서는 아무도 돌보지 않으면 꽤 성실하게 낡는다.
Skill은 강제 장치가 아니다
Skill은 Claude가 읽고 판단하는 지침이다.
항상 같은 방식으로 실행된다는 보장은 없다. 설명이 모호하거나 여러 지침이 충돌하면 일부 절차를 놓칠 수도 있다.
그래서 Skill을 강제 장치처럼 취급해서는 안 된다.
Claude가 프로젝트의 작업 방식을 이해하도록 돕는 것은 Skill의 역할이다. 실수를 시스템적으로 막는 것은 Hook과 테스트, CI의 역할이다.
필수 검사를 통과하지 못하면 배포하지 않아야 한다면 Claude가 기억해 실행하기를 기대하기보다 CI에서 차단하는 편이 안전하다.
“운영 데이터베이스를 삭제하지 마라”는 문장을 열 번 적는 것보다, 처음부터 삭제 권한을 주지 않는 편이 낫다.
이전에 MCP의 함정, 너무 많은 권한에서도 비슷한 결론을 내렸다.
AI는 지침을 읽지만, 권한 앞에서 주저하지는 않는다.
설명이 필요한 것은 문서로 남기고, 반드시 지켜야 하는 것은 구조로 막아야 한다.
프로젝트에는 에이전트를 위한 인터페이스도 필요하다
AI 코딩 에이전트의 결과를 프롬프트의 문제로만 보는 경우가 많다.
요청을 더 자세히 쓰고, 역할을 지정하고, 출력 형식을 정하면 결과가 좋아지는 것은 맞다.
하지만 같은 프로젝트를 계속 운영한다면 매번 더 긴 프롬프트를 작성하는 방식에는 한계가 있다.
사람이 새로운 프로젝트에 들어오면 온보딩 문서를 읽고, 업무 매뉴얼을 보고, 코드 리뷰를 통해 팀의 방식을 배운다.
에이전트도 크게 다르지 않았다.
항상 알아야 하는 정보와 특정 작업에서 필요한 절차를 분리하고, 이 저장소에서만 유효한 규칙을 명확하게 알려줘야 한다.
KitFolio는 몇 개의 도구를 만드는 실험에서 계속 운영할 제품으로 구체화되고 있었다. 이번 작업은 그 시점에 AI와 일하는 방식을 처음 설계한 일이었다.
이번에 만든 Skill의 효과는 앞으로 신규 도구를 추가하면서 검증할 생각이다.
같은 설명을 다시 입력하는 횟수가 줄어드는지, 불필요한 파일을 수정하려는 시도가 줄어드는지, 다국어와 SEO 항목의 누락이 줄어드는지를 확인해볼 수 있다.
코드를 위한 인터페이스를 설계하듯, 이제는 에이전트가 프로젝트를 이해하고 작업할 수 있는 인터페이스도 설계해야 한다.
AI Native 프로젝트를 만든다는 건 AI에게 모든 일을 맡기는 일이 아니었다.
AI가 일할 수 있도록 프로젝트의 구조와 작업 방식을 설계하는 일이기도 했다.
FAQ
CLAUDE.md와 Claude Code Skill의 차이는 무엇인가?
CLAUDE.md는 프로젝트 전반에서 항상 필요한 규칙을 담고, Skill은 특정 작업에서 사용하는 절차, 참고 자료, 완료 조건을 담는다.기술 스택과 핵심 구조는
CLAUDE.md에 두고, 신규 기능 구현이나 SEO 검토처럼 작업별로 필요한 절차는 Skill로 분리할 수 있다.모든 프로젝트 지침을 Skill로 만들면 되는가?
아니다. 항상 필요한 기본 규칙은
CLAUDE.md, 제품 방향이나 판단 기준은 별도 참고 문서에 두는 편이 적절하다.반드시 실행하거나 차단해야 하는 규칙은 Skill이 아니라 Hook, 테스트, CI, 권한 설정처럼 결정론적인 수단으로 관리해야 한다.
좋은 Claude Code Skill에는 무엇을 적어야 하는가?
좋은 Skill에는 일반적인 베스트 프랙티스보다 해당 저장소에서만 유효한 규칙을 우선해서 적는다.
수정해야 할 파일, 자동으로 파생되는 항목, 직접 수정하면 안 되는 영역, 참고해야 할 정책 문서, 작업 완료 조건 등이 이에 해당한다.