팀 공용 Claude 스킬로 CRM 개발 가이드 다시 쓰기

팀에서 Claude Code 설정을 같이 쓰기 위한 .claude 저장소가 생겼다. 이번 주에는 거기 들어 있는 CRM 개발 스킬을 다시 썼다.

구조는 단순하다. .claude 저장소를 CRM 프로젝트 루트의 .claude 폴더에 받아 두고, CRM 저장소는 .gitignore로 그 폴더를 무시한다. 스킬 파일은 공용 저장소에서 관리하고, 각자의 settings.local.json은 공용 저장소에서도 무시한다.

스킬은 skills/assistfit-crm/SKILL.md 하나와 references 문서 네 개(UI 가이드, 리액트 패턴, 코딩 컨벤션, 폴더 구조)로 되어 있다. 처음 버전은 SKILL.md 안에 기술 스택, 컴포넌트 선언 방식, 훅 제네릭 규칙, St 컴포넌트 import 목록이 전부 들어 있었다. 사람이 읽기엔 친절한데, 스킬이 불릴 때마다 이걸 다 읽는다고 생각하니 너무 길었다.

그래서 역할을 나눴다.

• SKILL.md에는 언제 이 스킬을 써야 하는지, 기술 스택과 핵심 원칙 네 줄, 자주 쓰는 import, 기본 컴포넌트 모양만 남겼다.
• 세부 규칙은 references로 내렸다. 문서마다 목차와 TL;DR을 위에 두어서 필요한 부분만 찾아 읽게 했다.
• 폴더 구조 문서에는 새 기능을 추가할 때 만들 파일 다섯 개를 경로로 적었다. 페이지, 컨테이너 컴포넌트, API 클라이언트, 타입, 필터 훅 순서다.

description도 줄였다. 스킬이 선택되는 기준이 거의 이 한 문단이라, 어떤 프로젝트에서 어떤 작업을 할 때 쓰는지만 남겼다.

다른 저장소도 같이 정리했다. CRM에는 .claude와 Serena 디렉터리를, fit-hr에는 Serena와 worktree 디렉터리를 .gitignore에 넣었다. 어드민은 11월에 CLAUDE.md를 커밋했다가 바로 지우고 무시 목록에 넣은 적이 있다. 개인 작업 지침이 저장소에 섞이면 팀원에게 그대로 적용되기 때문이다.

문서를 쓰면서 독자를 바꿔 생각하게 된다. 사람은 긴 설명도 훑고 넘어가지만 에이전트는 적힌 규칙을 그대로 따른다. 규칙 한 줄을 적을 때도 이게 모든 파일에 그대로 적용돼도 괜찮은지 먼저 따져보게 됐다.