에이전트 스킬을 중심으로 한 개발 방법론을 생각하다

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