프로젝트 이름이 더 이상 프로젝트를 설명하지 못하면, 리팩토링할 때가 된 것이다.
"workspace-skill"이라는 이름으로 시작한 저장소가 있었다. 처음에는 Claude Code 스킬 몇 개를 모아둔 곳이었다. 그런데 스킬 17개, 서브에이전트 1개, museck 브랜드 전용 스킬 6개가 쌓이면서 이 이름이 전혀 맞지 않게 됐다. 이건 단순한 "워크스페이스 스킬"이 아니라, 스킬과 에이전트를 만들고 관리하는 대장간 — forge — 이었다. 180개 파일을 건드리는 대규모 마이그레이션을 결심했다.
기존 구조의 문제를 정리하면 세 가지였다.
변경 내용을 정리하면 이렇다.
skills/, subagents/, museck/ 3계층museck/skills/museck/ 1개로 통합subagents/로 독립가장 긴장됐던 부분은 git의 rename detection이다. 파일을 여러 커밋에 걸쳐 조금씩 옮기면 git이 rename으로 인식하지 못하고 delete + create로 처리한다. 그러면 파일 히스토리가 끊긴다.
해법은 한 번에 큰 커밋을 만드는 것이었다. 디렉토리 이동과 파일 rename을 한 커밋에 모아서 git이 패턴을 인식할 수 있게 했다. git log --follow로 확인했을 때 rename 전후의 히스토리가 연결되는 걸 보고 안심했다.
museck-bi, museck-design, museck-editorial, museck-launch, museck-seo. 이 5개를 삭제하고 하나의 통합 museck 스킬로 만들었다. 왜 처음에 5개로 나눴을까? "관심사 분리"에 취해 있었기 때문이다.
각 스킬의 SKILL.md가 50줄도 안 됐다. 이 정도면 하나로 합쳐도 충분히 관리 가능하다. 마이크로서비스 세계에서 "너무 잘게 쪼개면 오버헤드만 늘어난다"는 교훈이 여기서도 똑같이 적용됐다. 쪼개기 전에 "이게 정말 독립적으로 발전할 수 있는가?"를 물어야 한다.
-er 접미사는 에이전트에만 쓴다는 규칙을 만들었지만, english-humanizer와 korean-humanizer는 스킬이었다. 이걸 english-humanize, korean-humanize로 고치려면 기존에 설치된 모든 경로를 업데이트해야 한다.
# 변경해야 하는 경로들
~/.claude/skills/korean-humanizer/ → ~/.claude/skills/korean-humanize/
~/.agents/skills/korean-humanizer/ → ~/.agents/skills/korean-humanize/
# + install-registry.md 업데이트
# + 참조하는 모든 문서 업데이트명명 규칙은 일찍 정하는 게 맞다. 소급 적용은 가능하지만, 늦을수록 비용이 커진다. 이번에는 "어차피 대규모 마이그레이션이니까 한꺼번에 정리하자"고 결정했다. 다음부터는 새 스킬을 만들 때 이름부터 규칙에 맞추면 된다.
skill-version-manager도 forge로 이름을 바꾸고 v2.0.0을 릴리스했다. 새로운 3계층 디렉토리 구조(skills/, subagents/, museck/)를 인식하고, 새 스킬이나 에이전트를 생성할 때 적절한 위치에 디렉토리를 만들어준다.
agent-forge/
├── skills/ # 범용 스킬
│ ├── forge/ # (구 skill-version-manager)
│ ├── blog-engine/ # (구 museck-blog에서 범용 추출)
│ ├── seo-engine/ # (구 museck-seo에서 범용 추출)
│ └── ...
├── subagents/ # 범용 에이전트
│ └── analytics-advisor/
├── museck/ # 브랜드 전용
│ ├── skills/museck/ # 통합 museck 스킬
│ └── skills/blog-mining/
└── install-registry.md소프트웨어 모노레포를 운영해본 사람이라면 이 과정이 낯설지 않을 것이다. 패키지가 늘어나면 디렉토리를 계층화하고, 작은 패키지들은 합치고, 네임스페이스를 정리한다. AI 스킬 저장소도 똑같은 생애주기를 거친다.
처음부터 구조를 완벽히 설계하지 못한 걸 후회하지 않는다. 4개일 때 3계층 구조를 만들었으면 과잉 설계였을 것이다. 성장에 맞춰 구조를 리팩토링하는 것이 자연스러운 과정이다. 중요한 건 "지금 구조가 한계에 다다랐다"는 신호를 알아채는 것이다. 이름이 실체를 설명하지 못하면, 그게 신호다.
마이그레이션에서 가장 비싼 비용은 코드가 아니라 네이밍이었다. 180개 파일의 경로 변경보다, 모든 install-registry와 참조 문서를 업데이트하는 게 더 오래 걸렸다. 좋은 이름을 처음에 붙이는 투자는 나중에 몇 배로 돌아온다.
리뷰는 확실히 어렵다. 하지만 나누면 git이 rename을 인식 못 해서 히스토리가 끊긴다. 트레이드오프를 따져봤을 때, 히스토리 보존이 더 중요했다. 커밋 메시지에 변경 매핑(A → B)을 상세히 적어서 나중에 추적할 수 있게 했다.
nx나 turborepo는 빌드, 테스트, 의존성 그래프를 관리하는 도구다. 스킬 파일은 빌드도 테스트도 없다. 필요한 건 디렉토리 구조와 버전 추적뿐이라서, 파일 시스템과 git만으로 충분했다. 도구를 추가하는 비용보다 규칙을 정하는 비용이 더 쌌다.
현재 3계층 구조는 50개 정도까지 감당할 수 있다고 본다. 그 이상이면 skills/ 아래에 도메인별 서브디렉토리를 추가하거나, 별도 저장소로 분리하는 방법을 고려할 것이다. 다만 그때 가서 결정해도 늦지 않다. 지금 과잉 설계하는 것보다 성장에 맞춰 진화하는 게 낫다.