TL;DR
- 개발의 핵심에 Agent Skill(Claude가 동적으로 읽어들이는 지시서 폴더 등)을 두는 개발 스타일
- 「프롬프트에 매번 작성한다」, 「README에만 적어두어 아무도 읽지 않는다」, 「베스트 프랙티스(Best Practice)가 암묵지화된다」, 「작업자에 따른 품질 차이」를, Skill로서 실행 가능한 형태로 정본화(Single Source of Truth) 함으로써 해결
- TDD·DDD·Spec-Driven Development의 연장선상에 있는, AI 에이전트를 전제로 한 레이어의 개발 방법론
왜 새로운 개발 방법론이 필요한가
Claude Code / Claude.ai / Claude API 모두에 Agent Skills가 도입되면서, 「Skill을 어떻게 작성할 것인가」, 「어디에 둘 것인가」, 「언제 호출하게 할 것인가」를 둘러싼 논의가 늘어나고 있습니다. 한편, 프로젝트 전체를 Skills 전제로 구성하는 사상·방법론에는 아직 정해진 방식이 침투하지 않아, 각 기업이 시행착오를 겪으며 진행하고 있는 것으로 보입니다.
본 기사에서는 에이전트 스킬을 개발 프로세스에 어떻게 통합해 나갈지를 해설합니다.
에이전트 스킬 주도 개발의 개요
에이전트 스킬 주도 개발 (Agent-Skill-Driven Development; ASDD)이란, 개발에 필요한 베스트 프랙티스(Best Practice)·규약·절차·도메인 지식을 「AI 에이전트가 동적으로 읽을 수 있는 Skill로서 정본화(Single Source of Truth) 」하여, 인간과 에이전트가 동일한 Skill을 참조하며 개발을 진행하는 방법론입니다.
※ 정식 명칭이 있는 것은 아니며, 가칭입니다. 이하 ASDD라고 표기합니다.
포인트는 3가지입니다.
- 정본(Single Source of Truth)은 Skill── README도, CONTRIBUTING.md도, Slack의 과거 로그도 아닌,
SKILL.md가 프로젝트의 「실행 규칙」의 규범이 된다.
- Skill은 실행 가능── 설명문뿐만 아니라, 필요에 따라 검증 스크립트·템플릿·Lint 설정이 동봉된다.
- 사람도 에이전트도 같은 Skill을 읽는다── 인간의 온보딩 자료도, 에이전트에 대한 지시서도, 출처는 동일하다.
기존 "X-Driven Development"와의 위치 설정
| 방법론 | 구동하는 것 | 중심 산출물 | 주요 이용자 |
|---|
| TDD | 테스트 | 테스트 코드 | 인간 |
| ... | ASDD | Skill | 인간 + AI 에이전트 |
에이전트 스킬 주도 개발은 기존 방법론을 부정하지 않습니다. **TDD로 작성한 "테스트를 작성하는 방식"**이나 **DDD의 "유비쿼터스 언어(Ubiquitous Language)"**는, 그것 자체를 Skill로 굳히면 효과가 강력해집니다. ASDD는 「베스트 프랙티스를 에이전트가 다룰 수 있는 단위로 압축하는」 공정을 개발 프로세스의 일급 작업으로 만드는, 레이어의 제안입니다.
7가지 규칙
1. Skill First: 프롬프트에 2번 쓰면 Skill로 만든다
동일한 지시를 프롬프트에 두 번 쓴 시점에서, 그것은 암묵지화의 신호입니다. 세 번째를 쓰기 전에 SKILL.md를 분리합니다.
2. Single Source of Truth: 「실행 규칙」은 Skill에 집약한다
CONTRIBUTING.md, 사내 Wiki, Slack의 핀 고정, CLAUDE.md ── 규칙의 출처가 분산될수록 사람도 에이전트도 방황하게 되고, 결국 형해화됩니다.
ASDD에서는 모든 문서를 삭제하는 것이 아닙니다. 「왜 그런 설계를 했는가(Why)」라는 배경 지식은 Wiki 등에 남기고, 「어떻게 구현·검증할 것인가(How/What)」라는 실행 규칙의 정본을 Skill에 두는 정보의 책임 분리를 수행합니다.
3. Executable over Descriptive: 설명보다 실행 가능성
「이렇게 해주세요」라고 쓰는 것보다, scripts/recalc.py와 같은 실행 가능한 스크립트를 동봉하는 편이 에이전트는 확실하게 지킬 수 있습니다.
4. Trigger Clarity: 언제 호출할지를 description으로 제약한다
Skill은 프론트매터(Frontmatter)의 description을 토대로 발화합니다. 「Use when ...」「Skip when ...」을 명시하여, 오발화와 누락을 줄입니다.
---
name: api-call-conventions
description: 내부 /api/* 엔드포인트를 호출하는 코드를 추가하거나 수정할 때 사용하십시오. 제3자 SDK 호출의 경우 건너뜁니다.
...
5. Versioned & Reviewed: Skill은 코드와 동일한 리뷰 대상
SKILL.md의 변경은 PR(Pull Request)로 만들고, 코드와 마찬가지로 리뷰합니다. 테스트나 타입(Type)과 동일한 비중으로 CI(Continuous Integration)를 통과시킵니다. Skill의 퇴보는 코드의 퇴보와 동일한 리스크로 간주해야 합니다.
6. Composable: 작게 나누어 합성하기
거대한 하나의 house-rules.md가 아니라, 역할별로 나눕니다:
frontend-conventions
api-error-handling
release-notes
incident-comms
anthropics/skills의 17개가 거의 단일 기능으로 나누어져 있는 것은 바로 이 원칙을 구현한 것입니다.
7. Measurable: 만들기만 하고 방치하지 않기
skill-creator가 설파하듯, Skill은 만들고 끝나는 것이 아니라, 현실적인 프롬프트(Prompt)로 테스트하고 개선해 나가는 것입니다. 주간/월간 단위로 Skill을 점검(Inventory)하고, 효과가 없는 것은 통합하거나 삭제합니다.
ASDD의 실천 플로우
Phase 1. Bootstrap: 프로젝트의 초기 Skill 세트
신규 프로젝트에서는 처음에 다음을 포함합니다.
claude-api (LLM 호출을 포함하는 경우)frontend-design + webapp-testing (프론트엔드를 가지는 경우)mcp-builder (외부 통합을 만드는 경우)skill-creator (Skill을 늘릴 예정이라면 필수)
그다음, 프로젝트 고유의 3~5개 SKILL.md를 가장 먼저 작성합니다. 예:
repo-conventions: 디렉토리 구성·명명·PR 규칙release-process: 릴리스 절차와 릴리스 노트 형식incident-runbook: 장애 발생 시 대응 방법
Phase 2. Develop: Skill을 활용하며 개발하기
에이전트는 요청의 문맥(Context)으로부터 해당 Skill을 자동으로 읽어옵니다. 인간 측은 "이 태스크에 효과적인 Skill은 무엇인가"를 의식하고, 없다면 작성한다는 습관을 갖게 됩니다.
Phase 3. Capture: 새로운 규칙을 Skill화하기
리뷰에서 "다음부터는 이것을 지켜주길 바란다"라는 의견이 나오면, 그 자리에서 SKILL.md의 차분(Diff) PR을 생성합니다. "Slack에서 합의했다"로 끝내지 않는 것이 ASDD의 핵심입니다.
Phase 4. Review: Skill을 PR 리뷰하기
Skill의 변경은 코드와 동등한 리뷰를 거칩니다. 체크 관점은 다음과 같습니다:
description의 트리거(Trigger) 조건이 명확한가 (오발화하지 않는가)- 기존 Skill과 역할이 중복되지 않는가
- 실행 가능한 스크립트로 대체할 수 있는 부분은 없는가
- 예시(Examples)가 현실적인가
Phase 5. Measure: 효과를 측정하기
skill-creator의 평가 프레임워크에 따라, Skill이 의도한 상황에서 발화하고 의도한 출력을 이끌어내고 있는지를 정기적으로 검토합니다. 발화하지 않는 Skill은 description을 다시 쓰거나 폐지합니다.
안티 패턴
| 안티 패턴 | 발생하는 현상 | 해결 방법 |
|---|
| God Skill | 하나의 스킬에 모든 것이 적혀 있고, description도 모호함 | 역할에 따라 분할. description을 「Use when / Skip when」으로 한정 |
| Documentation Skill | 단순한 Markdown 전사. 스크립트나 예시도 없음 | 실행 가능한 스크립트 및 최소 샘플을 동봉 |
| Stale Skill | 반년 전의 규칙. 현실과 괴리됨 | 리뷰 대상에 포함하여 분기별로 재고 조사 |
| Trigger 없는 Skill | description이 「가이드라인 모음」 수준에 그쳐 발화되지 않음 | 구체적인 파일명, 함수명, 상황을 description에 작성 |
| 중복 Skill | 유사한 내용의 Skill이 3개 존재함 | Composable(조합 가능성) 원칙으로 돌아가 통합 또는 역할 분할 |
기존 리포지토리(Repository) 도입 레시피
내일부터 시작한다면, 최소 절차는 다음과 같습니다.
- 공식 Skills를 가져오고,
/plugin marketplace add anthropics/skills를 실행
skill-creator만 활성화하고, 첫 번째 Skill로서 .claude/skills/SKILL.md를 생성repo-conventions.md를 작성 (README + CONTRIBUTING의 압축 버전)- PR 템플릿에 「규칙이 바뀐다면
SKILL.md를 업데이트했는가?」 체크 항목을 추가
- 1 스프린트(Sprint) 운영 후 회고를 통해 Skill의 추가·통합·삭제를 결정
- 3 스프린트째까지 5~10개로 늘어나 있다면, ASDD가 돌아가기 시작했다는 신호
요약
- Agent-Skill-Driven Development는 Skill을 프로젝트의 정본(Single Source of Truth)으로 삼기 위한 개발 방법론
- TDD·DDD·Spec-Driven을 부정하지 않으며, 그것들을 에이전트가 다룰 수 있는 단위(Skill)로 압축하는 레이어를 추가함
- 7원칙: Skill First / Single Source / Executable / Trigger Clarity / Versioned / Composable / Measurable
- 5단계: Bootstrap → Develop → Capture → Review → Measure