AI 코딩 에이전트에게 시니어 개발자의 워크플로우를 심는 법 — agent-skills 실전 가이드 (github.com)

한줄 요약

AI 에이전트의 코드 품질을 높이려면 "어떻게 짜라"가 아니라 "어떤 과정을 따르라"는 워크플로우 자체를 주입하는 게 핵심이다.

어떤 상황에서 필요한가?

Claude Code나 Cursor 같은 AI 코딩 에이전트를 실무에 투입해봤다면, 단순 구현은 잘 하는데 스펙 정의, 테스트 작성, 보안 검토 같은 품질 게이트를 스스로 밟지 않는다는 걸 금방 느낀다. 결국 사람이 일일이 프롬프트로 "테스트도 짜", "엣지 케이스도 봐"라고 지시해야 한다. 이 반복 지시가 쌓이면 에이전트를 쓰는 이유가 희미해진다.

에이전시를 운영하면서 느낀 건, 에이전트에게 부족한 건 코딩 실력이 아니라 시니어 엔지니어가 당연하게 밟는 절차 감각이다. 이걸 자동화하는 시도가 agent-skills다.

핵심 구현 방법

agent-skills에 따르면(출처), 이 프로젝트는 개발 사이클 전체를 6단계로 나누고 각 단계마다 AI 에이전트가 따라야 할 스킬을 매핑한다.

개발 사이클 6단계와 슬래시 커맨드

단계	커맨드	핵심 원칙
Define (무엇을 만들지)	/spec	코드보다 스펙 먼저
Plan (어떻게 만들지)	/plan	작고 원자적인 태스크
Build (구현)	/build	한 번에 하나의 슬라이스
Verify (검증)	/test	테스트가 증거다
Review (품질 게이트)	/review	머지 전 코드 건강 개선
Ship (배포)	/ship	빠를수록 안전하다

이 7개 커맨드(/code-simplify 포함) 뒤에는 총 19개의 스킬이 자동으로 활성화된다. 각 스킬은 단순한 지침이 아니라 단계별 검증 게이트와 anti-rationalization 테이블을 포함한 구조화된 워크플로우다.

자동 활성화 스킬 예시

• API 설계 작업 시 → api-and-interface-design 스킬 자동 적용 (Contract-first 설계, Hyrum's Law 고려)
• UI 개발 시 → frontend-ui-engineering 스킬 적용 (WCAG 2.1 AA 접근성 포함)
• 버그 수정 시 → debugging-and-error-recovery 적용 (재현→로컬라이즈→축소→수정→가드의 5단계 트리아지)
• 테스트 작성 시 → test-driven-development 적용 (테스트 피라미드 80/15/5 비율, DAMP over DRY 원칙)

설치 방법 — 도구별

Claude Code라면 마켓플레이스에서 바로 설치할 수 있다.

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Cursor는 SKILL.md 파일을 .cursor/rules/ 디렉토리에 복사하거나 skills/ 디렉토리를 통째로 참조하면 된다.

Gemini CLI, Windsurf, GitHub Copilot, OpenCode 등 주요 AI 에이전트 도구 전부 지원한다. 스킬 파일이 순수 마크다운으로 작성돼 있어서 시스템 프롬프트나 인스트럭션 파일을 받는 어떤 에이전트에도 적용 가능하다는 게 실용적인 포인트다.

19개 스킬 카테고리 요약

• Define: idea-refine, spec-driven-development
• Plan: planning-and-task-breakdown
• Build: incremental-implementation, test-driven-development, context-engineering, frontend-ui-engineering, api-and-interface-design
• Verify: browser-testing-with-devtools, debugging-and-error-recovery
• Review: code-review-and-quality (5축 리뷰 구조)
• 그 외 보안, 성능, 배포 관련 스킬 포함

실전에서 주의할 점

• SSH 키 미설정 문제: 마켓플레이스 설치는 SSH로 레포를 클론한다. GitHub에 SSH 키가 없다면 git config --global url."https://github.com/".insteadOf "git@github.com:" 설정으로 HTTPS 폴백을 먼저 잡아야 한다. 이걸 놓치면 설치 단계에서 막힌다.

• 스킬을 "문서"로 취급하면 안 된다: 각 스킬 파일에는 검증 게이트와 anti-rationalization 테이블이 포함돼 있다. 에이전트가 편법으로 단계를 건너뛰는 걸 방지하는 구조인데, 단순히 지침 텍스트로 인식하게 만들면 효과가 반감된다. 에이전트 설정에서 이 파일들이 실행 지침으로 처리되는지 확인해야 한다.

• 모든 스킬을 한 번에 주입하지 마라: 19개 스킬 전체를 컨텍스트에 한꺼번에 넣으면 토큰 소모와 노이즈가 커진다. 커맨드 기반 자동 활성화 방식을 활용하거나, 작업 성격에 맞는 스킬만 선별해서 로드하는 게 현실적이다.