Claude Code의 commands와 skills로 개발 플로우를 정비한 이야기
요약
Claude Code의 commands와 skills를 활용하여 프로젝트별로 상이한 개발 플로우에 유연하게 대응하는 방법론을 다룹니다. 특정 작업 단계를 선언하는 command와 코딩 규칙을 강제하는 skill로 역할을 분담하여 개발 일관성을 유지하는 전략을 제시합니다.
핵심 포인트
- 명시적 작업 선언은 command로, 코딩 규칙 준수는 skill로 역할 분담
- 프로젝트마다 다른 개발 플로우에 유연하게 대응 가능
- Agent Skills를 활용해 커맨드 호출 없이도 아키텍처 규칙 유지
- 작업 컨텍스트 선언 위주의 command 구성으로 효율성 증대
특정 프로젝트(언어 및 아키텍처 교체 개발)의 플로우를 전제로 구축했던 Claude Code의 commands를, skills와 역할을 분담하며 여러 팀에서 사용할 수 있는 형태로 다시 정비한 이야기입니다.
"내 팀의 플로우에 최적화해서 커맨드를 구성했더니, 다른 팀에서는 오히려 사용하기 불편해졌다" —— 같은 경험을 하고 있거나, 앞으로 겪게 될 분들을 위해 작성했습니다.
정비 전 ── 교체 개발을 전제로 구축한 커맨드 군
원래 이 메커니즘은 교체 개발을 신속하게 진행하기 위해 만든 것이었습니다. 사양서를 개발과 병행하여 갖추고 싶었기 때문에, 교체 전의 구현 내용을 playbooks에 기록하고, 이를 바탕으로 교체 후의 사양을 확정 및 사양서화하며, 그것을 토대로 구현한다는 흐름을 전제로 하고 있었습니다.
구체적으로는 다음과 같은 커맨드 군을 준비해 두었습니다.
- 기존 구현을 playbooks에 기록 (이때 API 분할 안도 제시)
- API 분할이나 교체 후의 사양을 수정
- playbooks를 바탕으로 API와 프론트엔드 사양서 작성
- API를 구현 (OpenAPI 정의 → 본 구현)
- 프론트엔드를 구현
나아가, 특정 단계의 작업이 끝나면 다음 단계의 커맨드를 안내하는 동선도 마련해 두었습니다. 커맨드에 따라 진행하면 교체 개발이 하나의 길을 따라 흐르는 듯한 이미지입니다.
난관 ① ── 다른 팀의 플로우와 맞지 않음
이 커맨드 군은 "playbooks를 먼저 만든다", "사양서를 먼저 확정한다"라는 전제 위에 성립되어 있었습니다. 교체 개발에는 딱 맞았지만, 뒤집어 말하면 그 전제에서 벗어나는 개발에는 맞지 않습니다.
예를 들어, 굳이 playbooks에 기록할 정도는 아닌 유지보수 개발이나, API만 만드는 개발 등입니다. 이러한 다른 팀의 플로우에는 준비한 커맨드가 잘 들어맞지 않았습니다. 결과적으로 커맨드가 사용되지 않는 케이스가 늘어났고, 구현 코드의 일관성이 곳곳에서 손상되어 갔습니다.
난관 ② ── 마침 skills가 대두됨
프로젝트마다 플로우가 다른 것은 생각해보면 당연한 일입니다. 그렇기에 플로우의 차이는 그대로 두되, 최소한의 아키텍처나 규칙만은 미리 맞출 수 있도록 하고 싶다 —— 그렇게 생각하게 되었습니다.
마침 방침을 고민하던 이 시기에, Anthropic이 제창하여 오픈 스탠다드가 된 Agent Skills (이후 skills라고 함) 가 대두됩니다. skills를 사용하면 커맨드를 명시적으로 호출하지 않아도, 플로우에 의존하지 않고 구현할 때 코딩 규칙이 자연스럽게 지켜진다. 그런 메커니즘을 만들 수 있지 않을까. 그래서 skills 중심의 개발 플로우로 전환하기로 했습니다.
commands와 skills의 역할을 어떻게 나누었는가
전환하면서 결정한 것은 commands와 skills의 역할 분담입니다. 기준은 심플하여, "지금부터 무엇을 할 것인지를 인간이 의도적으로 선언하고 싶은 것"만을 command로 남기고, 그 외에는 모두 skills로 집약했습니다.
command로 남긴 것은 예를 들어 다음과 같은 것들입니다.
- 지금부터 API를 구현할 것인지, batch를 구현할 것인지
- 동일한 프론트엔드 리포지토리 내에서 관리자 화면을 구현할 것인지, 서비스 화면을 구현할 것인지
- ADR을 작성한다
모두 구현 로직 그 자체가 아니라, "지금부터 무엇을 할 것인가"라는 작업 컨텍스트의 선언입니다. (물론 실질적으로는 대부분 skills만으로 충분하다는 것이 밝혀지고 있는 상태라, commands는 거의 사용되지 않고 있습니다.)
반대로 코딩 규칙이나 아키텍처의 규칙처럼, 플로우와 관계없이 항상 지켜지기를 바라는 것은 모두 skills로 몰았습니다. 다음은 API의 아키텍처를 준수하고 있는지 체크하는 skills의 예시입니다.
---
name: api-structure-checker
description: API 구성을 체크하는 도구. 신규 API 추가 후나 기존 API의 구성을 확인할 때 사용. "API 구성을 체크", "API 구성 확인", "check api structure" 등의 요청으로 실행. (project)
...
```bash
# 단일 API를 체크
./scripts/check_api_structure.sh web
# 모든 API를 체크
./scripts/check_api_structure.sh
출력
[OK]녹색: 체크 성공[WARN]황색: 경고
...
api/
├── application/
│ ├── usecase/ # 유스케이스 (선택 사항)
│ ├── service/ # 서비스 (선택 사항)
│ ├── query/ # 쿼리 (선택 사항)
│ └── dto/ # DTO (선택 사항)
├── presentation/
│ └── http/
│ ├── handler/ # 핸들러 (필수)
│ └── middleware/ # 미들웨어 (선택 사항)
...
Scripts
scripts/check_api_structure.sh- 디렉토리 구성 체크
"인간이 명시적으로 선언하고 싶은가" —— 이 경계선을 기준으로 나누면, 고민할 일은 거의 없었습니다.
## 왜 playbook까지 skills로 몰았는가 ── commands와 skills의 차이
애초에 commands와 skills는 트리거(trigger) 메커니즘이 근본적으로 다릅니다.
- **command (slash command)는 인간이** 명시적으로 호출해야만 작동합니다. `/xxx`와 같이 호출해야 비로소 효력이 발생합니다.
- **skills는 Claude가 요청의 문맥(context)과 skills의 설명(description)을 대조하여, 관련이 있다면 자동으로 불러와 사용합니다** (model-invoked).
여기에 첫 번째 시행착오의 답이 있었습니다. playbook 작성을 command로 남겨두면, **그 명령어를 사용하지 않는 팀에서는 전혀 효과가 없습니다**. 반면 skills로 몰아두면, 명시적으로 호출하지 않아도 관련 작업을 하고 있을 때 Claude가 자동으로 참조해 줍니다. "명령어가 사용되지 않으면 일관성이 무너진다"는 문제 그 자체에, skills의 자동 실행이 해결책이 되는 것입니다.
게다가 skills만의 장점이 두 가지 더 있습니다.
- **단계적 노출 (progressive disclosure)** — 평소에는 설명문만 컨텍스트에 두고, 사용할 때 본체를 불러옵니다. 거대한 playbook를 상주시키지 않아도 되므로 효율적입니다.
- **실행 방법을 frontmatter로 제어할 수 있음** — `disable-model-invocation: true`를 추가하면 "수동으로만 호출할 수 있는 (즉, 선언계)" 방식으로, 추가하지 않으면 "자동으로 작동하는 (즉, 규약계)" 방식으로 만들 수 있습니다. 즉, "선언은 command, 작법은 자동인 skills"라는 역할 분담을 설정 하나로 표현할 수 있습니다.
이것이 playbook라는 "특정 플로우를 전제로 한 절차"까지 skills로 몰아넣은 이유입니다.
## 정비 후 ── skills 중심으로, 플로우에 의존하지 않고 품질을 지키다
역할 분담을 결정하면서 개발의 전제가 바뀌었습니다. 이전에는 "명령어를 순서대로 호출하는 것"이 품질 보증의 시작이었지만, 정비 후에는 **skills가 구현 시점에 자동으로 작동**함으로써, 어떤 플로우로 개발하더라도 코딩 규칙이나 아키텍처의 규칙이 지켜지는 —— 형태를 목표로 했습니다.
skills 측에는 플로우와 관계없이 항상 적용하고 싶은 것들을 집약했습니다. 크게 세 종류입니다.
- **구조·의존성 체커** — 레이어 의존성이나 디렉토리 구조, 명명 규칙(naming convention)이 무너지지 않았는지 기계적으로 검증합니다.
- **레이어별 코드 생성** — 핸들러나 유스케이스, 쿼리 등을 "정해진 작법"으로 생성합니다.
- **사양·설계 관련** — 사양서 템플릿이나 OpenAPI 리뷰 기준
흥미로운 점은, 원래 command 측에 있던 "기존 구현을 playbook로 옮겨 적는" 처리도 이 skills 측으로 옮겼다는 것입니다. 특정 플로우를 전제로 한 절차조차 "작법"으로서 skills에 귀속시킬 수 있다는 것을 깨달은 시점이었습니다.
커맨드(command)는 "이제부터 무엇을 할 것인가"를 선언하고 싶을 때만 사용하면 되며, 유지보수 개발이든 API 단일 개발이든 플로우(flow)에 상관없이 최소한의 일관성을 유지할 수 있게 됩니다.
## 어려웠던 점 ── skills가 "반드시 실행되는" 메커니즘을 아직 만들지 못했다
솔직히 말하면, 이관 자체는 힘들지 않았습니다. 어려운 것은 그 다음입니다.
skills는 구현 시 자동으로 실행되어 적용될 것으로 예상했습니다. 그런데, **도저히 제대로 실행되지 않는 경우가 있습니다.** 게다가 그것이 PR(Pull Request)의 코드 리뷰 단계에 이르러서야 비로소 드러납니다. 원래라면 구현 중에 방지할 수 있었어야 할 문제를 리뷰 단계에서 지적받고 나서야 깨닫게 되는 것입니다.
기술적으로는, skills가 실행될지 여부는 해당 설명문(description)의 키워드가 작업 중인 문맥(context)과 일치하는지에 따라 좌우됩니다. skills가 늘어나면 설명문이 컨텍스트 예산(context budget) 내에 담기지 않아 잘리게 되고, 매칭에 필요한 키워드가 누락되는 경우도 있습니다 (`/doctor` 명령으로 상황을 확인할 수 있습니다).
skills를 **반드시 실행시키는 메커니즘**, 이 부분을 아직 완벽히 만들지 못했다는 것이 현재의 솔직한 위치입니다.
## 앞으로의 과제 ── 리뷰까지 포함하여 품질을 일관되게 유지하기
이 "반드시 적용되게 하는 것"을 어떻게 실현하느냐가 앞으로의 과제입니다.
구체적으로는, 코드 리뷰까지 포함하여 일관되게 질 높은 구현을 완수할 수 있는 메커니즘 구축에 힘쓰려 합니다. 그 수단으로 주목하고 있는 것이 **TAKT (TAKT Agent Koordination Topology)** 입니다. 여러 AI 에이전트의 협업이나 인간이 개입하는 지점, 무엇을 기록할지를 YAML로 정의할 수 있는 OSS(Open Source Software)로, 리뷰 루프나 가드레일(guardrail)을 포함할 수 있습니다. 이를 사용한 플로우를 확립할 수 있다면, skills가 적용되지 않았던 부분도 리뷰 단계에서 확실히 잡아낼 수 있을 것이라 생각합니다.
## 요약
처음에는 "우리 팀의 플로우를 빠르게 돌리는 것"만을 생각하며 커맨드를 구성했습니다. 하지만 그 최적화가 그대로 다른 팀에는 걸림돌이 됩니다. 되돌아보면 이는 AI 주도 개발(AI-driven development)에 국한되지 않고, 특정 문맥에 최적화된 도구를 수평 전개할 때 반드시 부딪히는 벽이었던 것 같습니다.
만약 지금 특정 프로젝트를 전제로 커맨드나 skills를 구성하고 있다면, **"이것은 플로우에 의존하는 선언인가, 아니면 플로우와 상관없이 항상 지켜야 하는 규칙인가"**를 한 번 분리해 보시기 바랍니다. 그 경계선을 긋는 것이 여러 팀에서 사용할 수 있는 기반으로 나아가는 첫걸음이 될 것입니다.
skills를 반드시 적용시키는 메커니즘은 아직 과정 중에 있습니다. 진전이 있으면 다시 글을 쓰도록 하겠습니다.
### Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기