agent-skills로 AI 코딩 에이전트의 개발 프로세스 고정하기

AI 코딩 에이전트는 작업을 끝냈다고 판단하는 데는 능숙하지만, 스펙 정리나 테스트, 보안 검토까지 빠짐없이 수행하는 것은 별개의 문제다. Addy Osmani가 공개한 agent-skills는 이 간극을 개발 절차로 메우려는 오픈소스 프레임워크다.

Google 엔지니어링 문화의 모범 사례를 19개의 구조화된 스킬과 7개의 슬래시 커맨드로 정리했다. 목표는 에이전트가 코드 생성에만 머물지 않고 스펙 작성부터 출시까지의 품질 기준을 따르게 하는 데 있다.

지식보다 절차를 에이전트에 전달한다

agent-skills는 AI 코딩 에이전트가 소프트웨어 개발 라이프사이클 전반에서 시니어 엔지니어 수준의 작업 흐름을 수행하도록 만드는 마크다운 기반 스킬 프레임워크다. 핵심 원칙은 “프로세스 우선(Process over Knowledge)”이다.

스킬은 단순한 참고 문서가 아니다. 에이전트가 수행해야 할 단계, 검증 게이트, 종료 조건을 담은 워크플로우다. 특히 작업을 생략하려는 판단에 대응하는 합리화 방지 테이블(Anti-Rationalization Table)을 포함해, 중요한 절차를 건너뛰기 어렵게 만든다.

AI 코딩 에이전트는 완료(done)를 최적화하는 과정에서 스펙, 테스트, 보안 리뷰처럼 프로덕션에 필요한 단계를 빠뜨릴 수 있다. agent-skills는 이 문제를 절차와 증거 기반의 완료 기준으로 다룬다. 마크다운을 수용하는 Claude Code, Cursor, Copilot, Antigravity 등에서 동작한다.

정의부터 배포까지 이어지는 작업 흐름

프레임워크는 개발 과정을 6단계로 나누고, 각 구간에 필요한 스킬과 커맨드를 연결한다.

⤢✕

DEFINE에서는 idea-refine과 spec-driven-development로 아이디어와 요구사항을 다듬는다. PLAN은 planning-and-task-breakdown으로 구현 계획과 태스크를 나누는 구간이다.

BUILD에는 incremental-implementation, context-engineering, source-driven-development, frontend-ui-engineering, test-driven-development, api-and-interface-design이 배치된다. 구현만 지시하는 대신 코드 작성의 맥락, 인터페이스, 테스트까지 함께 다룬다.

VERIFY는 browser-testing-with-devtools와 debugging-and-error-recovery를 통해 결과를 확인하고 오류를 복구한다. REVIEW에서는 code-review-and-quality, code-simplification, security-and-hardening, performance-optimization을 적용한다. 마지막 SHIP 단계는 git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, shipping-and-launch으로 배포와 이후 운영 전환을 다룬다.

SKILL.md에 절차와 증거를 담는 방식

각 스킬은 skills/ 아래의 독립 폴더에 있으며, 중심 파일은 SKILL.md다. 파일의 YAML Frontmatter에는 하이픈으로 연결한 스킬 이름과 트리거 조건을 포함한 설명을 넣으며, 설명은 최대 1024자다.

이후에는 에이전트가 순서대로 실행할 수 있는 단계별 워크플로우를 둔다. “테스트를 검증하라”처럼 해석이 필요한 표현보다 “npm test를 실행하라”처럼 행동이 분명한 지시를 사용하고, 각 단계에 검증 게이트를 연결한다.

합리화 방지 테이블은 작업 생략을 위한 변명과 반박을 짝지은 장치다. 예를 들어 “이 변경은 너무 작아서 테스트가 필요 없다”는 주장에는 “작은 변경이 프로덕션 장애의 주요 원인”이라는 반박을 연결한다. 스킬 끝의 종료 조건은 체크리스트로 구성하며, 모든 항목은 증거로 확인할 수 있어야 한다.

⤢✕

이 구조는 지식이 아니라 절차를 우선하고, 일반론보다 실행 가능한 명령을 택하며, 종료 조건을 객관적으로 검증할 수 있게 설계된다.

컨텍스트와 피드백을 품질 장치로 쓰기

agent-skills의 품질 메커니즘은 컨텍스트 엔지니어링과 구조화된 프롬프트 패턴에 있다. 에이전트가 행동 전에 방향을 잡도록 하는 피드포워드 제어(Guides)와, 행동 뒤에 결과를 교정하도록 하는 피드백 제어(Sensors)를 함께 사용한다.

피드포워드에는 스펙 문서, 계획 문서, CLAUDE.md 같은 프로젝트 컨텍스트 파일이 들어간다. 코드 작성 전에 요구사항을 충분히 이해하게 만드는 역할이다. 피드백에는 테스트 실행 결과, 린트 검사, 코드 리뷰 체크리스트를 사용해 산출물을 객관적 기준으로 평가한다.

TDD 스킬은 에이전트 출력 품질을 가장 일관되게 향상시키는 기법으로 평가되며, Red-Green-Refactor 사이클을 엄격히 따르도록 구성된다. 코드 리뷰 스킬은 Google 코드 리뷰 가이드를 기반으로 Hyrum's Law(API 설계), Beyonce Rule(테스트 커버리지), 변경 크기 제한 등을 적용한다. security-and-hardening 스킬에는 OWASP 기반 보안 체크리스트를 넣어 취약점을 사전에 점검하게 한다.

사람·에이전트·스킬의 역할을 분리한다

agent-skills는 Addy Osmani가 제시한 에이전틱 엔지니어링(Agentic Engineering)을 개발 현장에 적용하는 도구다. 사람은 아키텍트, 리뷰어, 의사결정자로서 아키텍처 설계, 품질 기준 설정, 최종 승인을 맡는다.

에이전트는 구현자, 테스터, 리팩터러로서 코드 작성과 테스트 실행, 반복 개선을 수행한다. 스킬은 이 둘 사이에서 프로세스 가드레일 역할을 하며, 사람이 정한 품질 기준을 에이전트가 일관되게 따르도록 한다.

커맨드	단계	기능
`/spec`	DEFINE	아이디어를 구조화된 스펙 문서로 변환
`/plan`	PLAN	스펙을 검증 가능한 소규모 태스크로 분해
`/build`	BUILD	점진적 구현, 컨텍스트 엔지니어링 적용
`/test`	VERIFY	TDD 기반 테스트 작성 및 브라우저 테스팅
`/review`	REVIEW	코드 품질, 보안, 성능 리뷰 수행
`/code-simplify`	REVIEW	코드 복잡도 감소 및 단순화
`/ship`	SHIP	Git 워크플로우, CI/CD, 출시 체크리스트 실행

프롬프트와 프로젝트 지침만으로 부족한 지점

“좋은 코드를 작성해줘” 같은 일반 프롬프트는 품질 기준을 에이전트가 해석하게 만든다. 그 결과 일관성이 흔들리고 테스트나 보안 리뷰가 자주 생략될 수 있다. agent-skills는 단계별 워크플로우와 검증 게이트를 명시하고, 합리화 방지 테이블과 종료 조건으로 생략과 완료 기준의 문제를 다룬다.

CLAUDE.md나 AGENTS.md는 프로젝트 맥락을 전달하는 데 효과적이지만 절차 자체를 강제하는 장치는 아니다. 프로젝트 컨텍스트(CLAUDE.md)와 프로세스 가드레일(agent-skills)을 함께 두면 맥락과 실행 규율을 조합할 수 있다. agent-skills도 CLAUDE.md를 통해 프로젝트별 커스터마이징을 지원한다.

바이브 코딩은 빠른 프로토타이핑에 맞지만 프로덕션 품질을 보장하지는 않는다. 스킬 기반 개발은 프로토타입과 프로덕션 품질을 구분하고, 그 차이를 작업 흐름으로 관리한다.

작업 유형에 맞춘 적용 장면

신규 프로젝트에서는 /spec → /plan → /build → /test → /review → /ship 순서로 실행할 수 있다. 스펙 문서 없이 바로 코드 작성을 시작하는 흐름을 막는 방식이다.

레거시 코드 리팩토링에서는 code-simplification으로 복잡도를 낮출 지점을 찾고, deprecation-and-migration으로 안전한 마이그레이션 경로를 세운다. 변경 전후의 테스트 커버리지를 비교해 회귀를 방지한다.

CI/CD 파이프라인은 ci-cd-and-automation으로 자동화 워크플로우를 설계하고, git-workflow-and-versioning으로 브랜치 전략과 버전 관리 기준을 맞출 수 있다. 보안 감사에서는 security-and-hardening으로 OWASP 기반 취약점을 점검하며, 코드 리뷰 스킬과 연결해 보안 관련 변경을 자동 검토한다.

팀에 맞게 선택하고 관리하기

설치는 다음 명령으로 할 수 있다.

npx skills add addyosmani/agent-skills

전체 19개 스킬을 한 번에 적용하기보다, 팀에서 가장 큰 페인포인트와 맞닿은 스킬부터 점진적으로 도입하는 편이 권장된다. 모든 스킬을 동시에 로드하면 에이전트의 컨텍스트 윈도우를 과도하게 점유할 수 있으므로 작업 유형에 맞는 스킬만 선택적으로 활성화해야 한다.

각 스킬의 SKILL.md는 프로젝트 특성에 맞게 수정할 수 있다. 합리화 방지 테이블에는 팀에서 반복되는 패턴을 추가하고, 종료 조건에는 프로젝트별 품질 기준을 반영할 수 있다. 마크다운 기반이라 특정 에이전트에 종속되지는 않지만, 슬래시 커맨드 지원 여부는 에이전트별로 확인해야 한다. 팀 전체가 동일한 스킬 세트를 쓰도록 스킬 파일을 버전 관리 시스템에 포함하는 방식도 권장된다.

agent-skills의 핵심은 AI 에이전트가 생략하기 쉬운 개발 절차를 작업 규칙으로 고정하는 데 있다. 코드 생성 능력만으로는 프로덕션 품질을 만들기 어렵고, 스펙·검증·리뷰·출시를 연결하는 흐름이 필요하다. 이 프레임워크는 그 흐름을 마크다운 기반의 실행 가능한 가드레일로 제공한다.