agent-skills의 저자 Addy Osmani가 정리한 핵심 설계 철학이다. AI 코딩 에이전트의 기본 동작은 가장 빠른 경로로 “완료”에 도달하는 것이다. 스펙도 없고, 테스트도 없고, 리뷰도 없다. diff에 보이지 않는 작업들 — 가정 검토, 스펙 작성, 검토 가능한 크기로 분할, 결과가 정확하다는 증거 남기기 — 이 부분이 빠진다. addyosmani/agent-skills(★26K)는 이 구멍을 채우는 5가지 원칙을 중심으로 설계됐다.
원칙 1: 에세이가 아닌 프로세스
스킬 파일에 2,000자 테스팅 모범 사례 에세이를 넣으면 에이전트는 그것을 읽고 그럴듯한 텍스트를 생성한 뒤 실제 테스트는 건너뛴다. 에이전트에게 필요한 것은 참조 문서가 아니라 워크플로우다.
| 에세이 형식 (효과 없음) | 워크플로우 형식 (효과 있음) |
|---|---|
| “테스팅 모범 사례 10가지” | “실패하는 테스트를 먼저 작성 → 실행 → 실패 확인 → 최소 코드 구현 → 통과 확인 → 리팩터링” |
| “좋은 코드 리뷰의 요소” | “PR 크기 100줄 이하 → Critical/Nit/Optional/FYI 라벨 → 리뷰어 서명 후 머지” |
핵심 규칙: 단계가 있고 종료 기준이 명확한 것이 스킬이다. 단계가 없으면 스킬이 아니라 에세이다.
원칙 2: 안티-합리화 테이블
LLM은 합리화에 능숙하다. “이 태스크는 스펙이 필요 없다”, “테스트는 나중에 쓴다”, “테스트 통과했으니 배포해도 된다” — 그럴듯한 핑계를 즉석에서 만들어낸다.
안티-합리화 테이블은 에이전트가 아직 하지 않은 거짓말에 대한 미리 작성된 반박이다:
| 에이전트가 할 말 | 반박 |
|---|---|
| “이 태스크는 너무 단순해서 스펙이 필요 없다” | 수용 기준은 항상 필요하다. 다섯 줄이면 충분하다. 제로 줄은 안 된다. |
| “테스트는 나중에 쓰겠다” | “나중”이 핵심 단어다. 나중은 오지 않는다. 실패하는 테스트를 먼저 작성하라. |
| “테스트 통과했다, 배포한다” | 통과하는 테스트는 증거이지 증명이 아니다. 런타임 확인했는가? 사용자 경험 검증했는가? 인간이 diff를 읽었는가? |
| “이 변경은 리뷰 없이도 괜찮다” | 모든 변경에 리뷰가 있다. 리뷰어 서명이 종료 기준이다. |
이 패턴은 AI 에이전트뿐 아니라 팀에도 유효하다. 팀이 스스로에게 하는 거짓말을 적어두면 — “런칭 후에 테스트 고친다”, “이 변경은 너무 작아서 설계 문서가 필요 없다” — 다음에 같은 상황이 왔을 때 논쟁 없이 처리된다.
원칙 3: 검증은 협상 불가
모든 스킬은 구체적인 증거로 종료된다. 테스트 통과, 빌드 출력 클린, 런타임 트레이스가 기대 동작 확인, 리뷰어 서명. “맞는 것 같다”는 종료 기준이 아니다.
잘못된 종료: "기능이 구현됐다고 판단됩니다."
올바른 종료: "npm test — 47 passed, 0 failed. 런타임 로그: 기대 출력 확인."에이전트는 생성기다. 작업이 완료됐다는 별도의 신호가 필요하다. 스킬은 모든 워크플로우에 그 신호를 내재화한다.
원칙 4: 점진적 노출
모든 스킬을 세션 시작 시 컨텍스트에 로드하지 않는다. 라우터 스킬(using-agent-skills)이 현재 페이즈에 맞는 스킬만 활성화한다.
세션 시작:
→ 라우터만 로드 (~500토큰)
"새 기능을 만들어라" 요청 수신:
→ brainstorming 활성화
→ writing-plans 활성화
→ test-driven-development 활성화
버그 리포트 수신:
→ systematic-debugging 활성화이는 에이전트 하네스 엔지니어링의 원칙을 스킬 단위에 적용한 것이다. 모든 토큰이 어딘가에서 성능을 저하시킨다. 관련된 것만 로드하고 나머지는 디스크에 둔다.
원칙 5: 범위 규율
라우터 스킬에 하드코딩된 비협상 원칙: 요청받은 것만 건드린다.
- 인접 시스템을 리팩터링하지 않는다.
- 완전히 이해하지 못한 코드를 제거하지 않는다.
- TODO를 발견하고 파일 전체를 재작성하지 않는다.
나쁜 예: "버그 수정하면서 옆에 있던 레거시 코드도 정리했습니다."
좋은 예: "요청하신 버그만 수정했습니다. 관련 리팩터링은 별도 이슈로 제안합니다."범위 규율은 에이전트 PR이 머지 가능한지를 결정하는 가장 중요한 단일 요소다. 한 가지 이상을 하는 PR은 리뷰가 고무 도장으로 전락한다.
SDLC 6단계 + 20개 스킬 구조
addyosmani/agent-skills의 20개 스킬은 6개 라이프사이클 페이즈로 구성된다:
| 페이즈 | 슬래시 커맨드 | 역할 |
|---|---|---|
| Define | /spec | 무엇을 만들지 결정 |
| Plan | /plan | 작업 분해 |
| Build | /build | 수직 슬라이스로 구현 |
| Verify | /test | 동작 증명 |
| Review | /review | 누락된 부분 확인 |
| Ship | /ship | 안전하게 사용자에게 전달 |
복잡한 기능은 11개 스킬이 순서대로 활성화될 수 있다. 작은 버그 수정은 3개로 처리된다. 범위에 따라 워크플로우가 자동으로 조정된다.
설치 및 사용
# Claude Code
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skillsCursor는 .cursor/rules/에, Gemini CLI는 전용 경로에 마크다운 파일을 직접 추가한다. 어떤 시스템 프롬프트를 받는 도구든 스킬 파일을 로드할 수 있다.
자신의 팀에 적용하기
- 안티-합리화 리스트 작성: 팀이 스스로에게 하는 거짓말을 적는다. 각 핑계에 반박을 붙인다.
- 에세이를 워크플로우로 변환: 2,000자 “접근 방식” 문서를 체크포인트가 있는 400자 워크플로우로 바꾼다.
- 모든 태스크에 검증 종료 기준 추가: “완료”는 증거가 있을 때만 가능하다.
- 50페이지 핸드북 대신 라우터 + 소챕터 구조: 시간 압박 하에서 읽힐 수 있는 구조로 만든다.
참고 자료
- Agent Skills — Addy Osmani (2026-05-04)
- addyosmani/agent-skills — GitHub 공식 저장소