오늘의 오픈 소스 프로젝트 (#92): Agent Skills — AI 코딩 에이전트를 위한 엔지니어링 규율 - Insights | Molayo

서론

"AI 코딩 에이전트는 최단 경로를 기본값으로 선택합니다. 이는 종종 명세(specs), 테스트(tests), 그리고 보안 검토(security reviews)를 건너뛴다는 것을 의미합니다."

이 글은 Open Source Project of the Day 시리즈의 #92번째 기사입니다. 오늘의 프로젝트는 Agent Skills입니다. 이는 Google Chrome 팀의 Principal Engineer인 Addy Osmani가 구축한, AI 코딩 에이전트를 위한 프로덕션급 엔지니어링 워크플로우(workflow) 기술 모음입니다.

여러분은 아마도 Claude Code나 Cursor를 사용하여 기능을 작성한 뒤, 나중에 돌아보니 에이전트가 테스트를 전혀 작성하지 않았다는 사실을 깨달은 적이 있을 것입니다. 또는 API 엔드포인트에 입력 유효성 검사(input validation)가 전혀 없었거나, 아키텍처 문서(architecture doc)가 여전히 빈 상태였을 수도 있습니다.

이것은 우연이 아닙니다. AI 에이전트는 최단 경로를 향한 깊은 경향성을 가지고 있습니다. 에이전트에게 작업을 맡기면 코드가 가능한 한 빨리 실행되도록 만든 다음, 작업이 완료된 것으로 간주합니다. 명세(Specs), 테스트 커버리지(test coverage), 보안 강화(security hardening) 등은 "실행(runs)"으로 가는 경로에 포함되지 않기 때문에, 에이전트들은 기본적으로 이를 건너뜁니다.

Agent Skills는 바로 그 관찰에서 시작되었습니다. 시니어 엔지니어들이 가져오는 규율(discipline)을 스킬 파일(skill files)에 인코딩하여, 에이전트가 즉흥적으로 행동하는 대신 모든 개발 단계에서 따라야 할 구조화된 워크플로우(workflows)와 종료 조건(exit criteria)을 갖도록 합니다.

학습 내용

전체 아키텍처(architecture): 24개의 스킬이 개발 생명주기(development lifecycle)의 7개 단계를 어떻게 다루는지
7개의 모든 슬래시 명령어(slash commands): /spec부터 /ship까지의 완전한 워크플로우
SKILL.md 파일의 구조: 반합리화 테이블(anti-rationalization tables) 및 검증 종료 조건(verification exit conditions)
4가지 에이전트 페르소나(agent personas): Code Reviewer, Test Engineer, Security Auditor, Web Performance Auditor
워크플로우에 내장된 엔지니어링 원칙: Hyrum's Law, Beyoncé Rule, Chesterton's Fence
Claude Code, Cursor 및 기타 AI 도구에서의 설치 방법

사전 요구 사항

Claude Code, Cursor 또는 유사한 AI 코딩 도구 사용 경험
기본적인 소프트웨어 엔지니어링 배경 지식 (테스트, 코드 리뷰, CI/CD)
AI 지원 개발을 더 신뢰할 수 있고 규율 있게 만드는 것에 대한 관심

프로젝트 배경

Agent Skills란 무엇인가?

Agent Skills는 AI 코딩 에이전트를 위한 프로덕션급 (production-grade) 엔지니어링 워크플로 (workflow) 파일 세트로, "당신의 AI 에이전트에게 부족한 규율 계층 (discipline layer)"로 정의됩니다.

이 프로젝트가 해결하고자 하는 문제는 에이전트의 능력 (capability) 자체가 아닙니다. 현대의 AI 에이전트들은 코드를 잘 작성합니다. 문제는 기본 동작 (default behavior)입니다. 제약 조건 (constraints)이 없다면, 에이전트는 지름길을 택하는 경향이 있습니다. 즉, 코드를 먼저 실행되게 만들고, 문서는 나중에 작성하며, 테스트는 일단 건너뛰고, 보안은 "나중에 처리"하는 식입니다. 이러한 미뤄진 작업들은 실제 프로젝트에서 유지보수가 불가능한 기술 부채 (technical debt)로 쌓이게 됩니다.

저자 / 팀

저자: Addy Osmani
배경: Google Chrome의 Principal Engineer, _Learning JavaScript Design Patterns_의 저자, 프론트엔드 커뮤니티의 저명한 엔지니어링 목소리
라이선스: MIT
버전: Main branch, 지속적으로 업데이트됨

프로젝트 통계

⭐ GitHub Stars: 51,900+
🍴 Forks: 5,700+
📦 콘텐츠: 24개의 기술 (skills) + 7개의 슬래시 명령어 (slash commands) + 4개의 에이전트 페르소나 (agent personas)
📄 라이선스: MIT

핵심 기능

주요 기능

Agent Skills는 구조화된 엔지니어링 워크플로 (engineering workflows)를 마크다운 (Markdown) 파일로 제공함으로써 작동합니다. 에이전트가 관련 작업을 처리할 때, 가장 짧은 경로를 즉흥적으로 찾는 대신 기술 (skill) 파일을 읽고 정의된 단계와 체크포인트 (checkpoints)를 따릅니다.

기술이 없는 에이전트:
작업 → 즉시 코드 작성 → "완료"
          ↓ (명세, 테스트, 보안 건너뜀)
...

사용 사례

새로운 기능 개발 (New feature development)
- /spec: 코드를 작성하기 전에 반드시 서면 명세(specification)를 작성하도록 강제하며, 요구사항을 테스트 가능한 수락 기준(acceptance criteria)으로 변환합니다.
- /plan: 기능을 원자적 작업(atomic tasks) 단위로 분해하며, 각 작업은 5개 이상의 파일을 수정하지 않도록 합니다.
- /build: 한 번에 하나의 수직적 슬라이스(vertical slice)를 구현하며, 각 슬라이스마다 테스트와 커밋(commit)을 수행합니다.
코드 품질 (Code quality)
- /review: 가독성(readability), 테스트 가능성(testability), 유지보수성(maintainability)을 포괄하여 Staff Engineer 수준의 코드 리뷰를 수행합니다.
- /code-simplify: 일반적인 리팩터링 (refactoring)과는 별개로, 복잡도 감소(complexity reduction)를 구체적인 목표로 삼습니다.
테스트 (Testing)
- /test: 테스트 주도 개발 (TDD) 사이클인 Red-Green-Refactor를 실행합니다.
- 버그 수정을 위한 "Prove-It" 모드: 먼저 버그를 재현하는 실패하는 테스트를 작성합니다. 테스트가 통과되면 수정이 완료되었음을 증명합니다.
보안 강화 (Security hardening)
- security-and-hardening 기술은 보안에 민감한 코드를 작성하기 전에 STRIDE 위협 모델링 (threat modeling)을 의무화합니다.
- LLM 특화 리스크를 위한 별도의 체크리스트: 프롬프트 인젝션 (prompt injection), 컨텍스트 누출 (context leakage), 신뢰할 수 없는 모델 출력 (untrusted model output).
배포 (Shipping)
- /ship: Git 워크플로 (workflow)부터 CI/CD를 거쳐 관측성 (observability)에 이르기까지 전체 릴리스 체인을 다룹니다.

빠른 시작 (Quick Start)

Claude Code에 설치하기:

# 옵션 1: 전체 저장소 클론 (Clone)
git clone https://github.com/addyosmani/agent-skills
cp -r agent-skills/skills ~/.claude/skills/
...

그 다음 대화에서 슬래시 명령어를 직접 사용하세요:

/spec 사용자 인증 모듈이 필요합니다 — 이메일 등록, OAuth 로그인, 비밀번호 재설정

/build auto 위 명세(spec)에 따라 인증 모듈을 구현하세요
...

Cursor에 설치하기:

# 프로젝트 레벨
cp -r agent-skills/skills .cursor/skills/

...

AI 도구 간 호환성:

도구	경로	명령어 지원
Claude Code	`~/.claude/skills/`	✅ 전체 지원
...

7가지 명령어 전체

명령어 (Command)	단계 (Phase)	핵심 원칙 (Core Principle)
`/spec`	정의 (Define)	코드 작성 전 명세(Spec) 작성
...

/build auto는 특별한 모드입니다. 사용자가 계획을 한 번 승인하면, 에이전트가 전체 구현을 자율적으로 수행합니다. 하지만 여전히 각 작업을 개별적으로 커밋(commit)하고 테스트합니다.

심층 분석 (Deep Dive)

스킬 파일 구조 (Skill File Anatomy)

모든 SKILL.md 파일은 네 가지 핵심 섹션으로 구성된 일관된 구조를 따릅니다:

SKILL.md 구조
├── 프론트매터 (Frontmatter) (이름, 설명, 트리거 조건)
├── 단계별 워크플로우 (Step-by-step Workflow) (단계별, 구체적 단계)
...

마지막 두 섹션이 대부분의 가치를 지닙니다.

**반합리화 표 (Anti-rationalization tables)**는 에이전트가 가장 흔히 취하는 지름길과 그에 따른 현실을 나열합니다:

합리화 (Rationalization)	현실 (Reality)
"테스트는 나중에 추가하겠습니다"	버그가 누적됩니다. 슬라이스(Slice) 1의 버그는 슬라이스 2~5를 잘못되게 만듭니다.
...

**종료 기준 (Exit criteria)**은

web-performance-auditor: 실행 가능한 최적화 권장 사항을 포함한 Core Web Vitals 감사.

Claude Code에서 페르소나(Persona) 사용하기:

Use the security-auditor persona to review src/api/auth.ts

Use the web-performance-auditor persona to analyze homepage load performance

내장된 엔지니어링 원칙 (Embedded Engineering Principles)

이 스킬들은 Google의 엔지니어링 문화에서 유래한 여러 원칙을 워크플로(Workflow)에 직접 인코딩합니다:

Hyrum의 법칙 (Hyrum's Law): 일단 API에 충분한 사용자가 생기면, 문서에 무엇이라고 적혀 있든 상관없이 사용자들은 관찰 가능한 모든 동작에 의존하게 됩니다. 실무에서는: 공개된 동작을 변경하기 전에 모든 호출자(Caller)를 검색하십시오. 문서화되지 않은 동작이 사용되지 않을 것이라고 가정하지 마십시오.

비욘세 규칙 (Beyoncé Rule) ("마음에 들었다면, 테스트를 작성했어야 했어요"): 어떤 동작을 유지할 가치가 있다면, 그 동작에 대한 테스트를 작성할 가치도 있습니다. 테스트 커버리지(Test coverage)가 없는 코드는 변경 시 안전망이 없습니다.

체스터턴의 울타리 (Chesterton's Fence): 이해하지 못하는 코드를 제거하지 마십시오. 코드를 삭제하기로 결정하기 전에 그것이 존재하는 이유를 먼저 파악하십시오.

시프트 레프트 (Shift Left): 보안과 테스트를 출시 전 단계에서 개발 단계로 앞당기십시오. 문제를 일찍 발견할수록 수정 비용이 저렴해집니다.

트렁크 기반 개발 (Trunk-based development): 수명이 짧은 기능 브랜치(Feature branch)를 사용하고, 메인 브랜치(Main branch)에 빈번하게 통합하십시오. 이는 오래 지속되는 브랜치에서 누적되는 병합 충돌(Merge conflict)을 방지합니다.

security-and-hardening: LLM 특화 규칙

이 스킬에는 그 자체로 살펴볼 가치가 있는 LLM 애플리케이션 전용 섹션이 포함되어 있습니다:

"모든 모델 출력(Model output)을 신뢰할 수 없는 입력(Untrusted input)으로 취급하십시오."

세부 규칙:

모델 출력을 SQL 쿼리, eval(), 셸 명령(Shell commands), 또는 innerHTML에 직접 전달하지 마십시오.
시스템 프롬프트(System prompt)는 보안 경계(Security boundary)가 아닙니다. 권한은 프롬프트가 아닌 코드에서 강제하십시오.
사용자의 개인 데이터와 다른 사용자의 데이터를 프롬프트에 포함하지 마십시오. 컨텍스트(Context)에 포함된 모든 것은 다시 에코(Echo)되어 출력될 수 있습니다.

이 규칙들은 가상의 위협이 아니라, 현재 LLM 애플리케이션 개발에서 발생하는 실제 취약점 패턴을 다룹니다.

spec-driven-development: 4단계 게이트 단계 (Four Gated Phases)

spec 워크플로우는 4단계 게이트 모델 (four-phase gate model)을 강제하며, 각 단계는 다음 단계로 넘어가기 전 반드시 인간의 검토 (human review)를 거쳐야 합니다:

Phase 1: Specify (명세화)
  → 목표, 구조, 테스트 및 경계(boundaries)를 다루는 요구사항 초안 작성
  → 가정을 명시적으로 드러냄 — 가정을 목록화하고 수정을 요청함
...

이 기술이 경고하는 흔한 함정은 "코드를 짠 후에 명세를 작성하겠다"는 생각입니다. 이는 명세 (specification)가 아닌 문서화 (documentation)를 낳을 뿐입니다. 진정한 가치는 작업이 시작되기 전에 명확성을 강제하는 데서 나옵니다.

링크 및 리소스

공식 리소스

🌟 GitHub: addyosmani/agent-skills
👤 저자: Addy Osmani
📖 도서: Learning JavaScript Design Patterns — Addy Osmani

참조된 엔지니어링 원칙

Hyrum's Law — Hyrum Wright, Software Engineering at Google
The Beyoncé Rule — Google SRE Workbook
Chesterton's Fence — G.K. Chesterton, Orthodoxy
Shift Left Testing — 현대적 DevOps 관행
Trunk-Based Development — trunkbaseddevelopment.com

결론

Agent Skills는 AI 에이전트가 할 수 있는 일을 확장하는 것이 아닙니다. 대신, 그들이 기본적으로 수행하는 행동을 제약합니다.

AI 코딩 에이전트의 역량 상한선 (capability ceiling)은 이미 상당히 높습니다. 문제는 기본 동작 (default behavior)에 있습니다. 명세는 건너뛰어지고, 테스트는 미뤄지며, 보안은 "나중에 처리할 일"로 남겨집니다. 이러한 미룸이 쌓이면 이해하기 어렵고, 변경하기 힘들며, 신뢰하기 어려운 프로젝트가 됩니다.

여기서 보여주는 설계 접근 방식은 이 특정 프로젝트를 넘어 연구할 가치가 있습니다. AI가 "일이 어떻게 처리되어야 하는지"를 스스로 평가하도록 맡기기보다, 전문가의 행동을 실행 가능한 제약 조건 (executable constraints)으로 인코딩하십시오. 반합리화 표 (Anti-rationalization tables)는 가장 흔한 지름길들을 명시적으로 드러냅니다. 종료 기준 (Exit criteria)은 "완료"의 의미를 모호하지 않게 만듭니다. 동일한 패턴이 PM 워크플로우 (pm-skills)와 AI 설계 제약 조건 (taste-skill)에서도 나타납니다. 즉, 구조화된 인간의 전문성을 AI가 소비할 수 있는 형태로 패키징하는 것입니다.

AI 보조 코딩 (AI-assisted coding)을 사용하는 엔지니어라면, agent-skills를 한 번쯤 시도해 볼 가치가 있습니다. 최소한 spec-driven-development와 test-driven-development를 설치한 후, 에이전트의 동작이 변화하는지 관찰해 보십시오.

엄선된 AI 에이전트와 기술(skills)을 위한 마켓플레이스인 PrimeSkills를 탐색해 보세요. 각 기술은 실제 기업 워크플로 (enterprise workflows)에서 검증되었으며, 과장된 광고를 걷어내고 진정으로 작동하는 것만을 유지합니다.

더 유용한 통찰과 흥미로운 제품들을 확인하시려면 저의 홈페이지를 방문해 주세요.

오늘의 오픈 소스 프로젝트 (#92): Agent Skills — AI 코딩 에이전트를 위한 엔지니어링 규율

요약

핵심 포인트

서론