얼마 전 사내 백엔드 API 리팩토링 작업을 하다가 Cursor에게 모듈 분리를 맡겼는데, 아주 기가 막힌 삽질을 겪었습니다.

처음에는 10분 만에 300줄이 넘는 코드를 깔끔하게 뽑아내길래 “오늘 퇴근 일찍 하겠구나” 싶었습니다. 그런데 PR을 올리기 직전 로컬 테스트를 돌려보니 DB 커넥션 풀이 말라붙고, 기존 유닛 테스트의 절반이 줄줄이 깨지더군요.

원인을 파고들었더니 에이전트 녀석이 빠른 구현에만 눈이 멀어 비동기 리소스 반환 처리를 몽땅 생략해 버렸던 겁니다. 그러고는 제 앞에서는 “모든 리팩토링 작업을 완벽하게 마쳤습니다"라며 뻔뻔하게 보고를 끝내놓았더군요.

결국 AI가 10분 만에 짠 코드를 분석하고 뒷수습하느라 자정까지 야근을 했습니다.

“AI 모델이 덜 똑똑해서가 아니라, 일하는 방식에 최소한의 엔지니어링 제약(Constraints)이 없어서 이런 일이 생기는 건 아닐까?”

이런 고민을 하던 차에, 『JavaScript 디자인 패턴』으로 유명한 구글 크롬 팀의 Addy Osmani가 최근 공개한 agent-skills 오픈소스를 발견했습니다. 깃허브에 올라오자마자 9만 5천 스타를 돌파하며 해외 개발자들 사이에서 난리가 난 레포지토리인데, 직접 뜯어보니 제가 현업에서 겪었던 바로 그 고통을 정확하게 짚어내고 있었습니다.

1. 핵심 철학: 자유 대신 시니어의 규율을 강제하기

agent-skills 프로젝트가 던지는 메시지는 단순합니다. 더 똑똑한 LLM이 나오기를 마냥 기다릴 게 아니라, 지금의 AI에게 올바른 엔지니어링 프로세스와 품질 게이트(Quality Gates)를 쥐어주자는 것입니다.

실제로 저도 그랬지만, 보통 우리는 AI에게 “이 기능 구현해줘"라고 한 줄 던지고 결과를 기대합니다. 하지만 이는 주니어 개발자에게 요구사항 한 줄 주고 “알아서 배포까지 끝내라"고 방치하는 것과 똑같습니다.

이 프로젝트에서는 개발 전 과정을 잘게 쪼개고, 각 단계마다 명확한 검증(Verification)을 통과하지 못하면 다음 단계로 절대 진행할 수 없도록 AI의 행동반경을 시스템 규칙으로 묶어버립니다.

설계의 4가지 원칙

  • 설명이 아닌 프로세스: 단순 지침 문서가 아니라, 에이전트가 순서대로 따라야 할 체크포인트와 종료 기준(Exit Criteria)을 제공합니다.
  • 변명 방지(Anti-Rationalization): AI가 흔히 둘러대는 핑계를 미리 차단하는 규칙 테이블을 둡니다.
  • 타협 없는 검증: “정상 동작하는 것 같습니다"라는 추측은 허용되지 않으며, 실제 테스트 통과 로그나 빌드 성공 결과가 반드시 증빙되어야 합니다.
  • 점진적 컨텍스트 제공: 불필요한 토큰 낭비를 막기 위해, 메인 스킬 문서에서 필요한 세부 가이드만 그때그때 참조하도록 구성했습니다.

⚠️ 실무 프로덕션 적용 시 주의점
규칙을 아무리 촘촘하게 짜더라도, 팀 내 기존 코드베이스의 테스트 커버리지가 0%에 가까운 레거시 시스템이라면 에이전트가 검증의 기준점(Baseline)을 잡지 못해 헛돌기 쉽습니다. 레거시 프로젝트에 도입할 때는 최소한의 핵심 스모크 테스트나 E2E 테스트를 사람이 먼저 뚫어준 뒤 에이전트에게 쥐어주어야 합니다.

2. 뼈 때리는 변명 방지 테이블 (Anti-Rationalization)

프로젝트 내부 문서들을 보며 가장 무릎을 쳤던 부분은 각 스킬마다 들어가 있는 ‘변명 방지 테이블’이었습니다. Addy Osmani 역시 현업에서 AI 코딩 툴을 쓰며 저와 똑같은 분통을 터뜨렸던 게 분명하더군요.

AI 에이전트의 단골 핑계 시스템의 단호한 반박 규정
“이번 수정은 너무 간단해서 테스트를 작성할 필요가 없습니다.” 사소한 변경일수록 테스트 작성이 가장 쉽습니다. 테스트 없이는 1줄도 커밋할 수 없습니다.
“로직상 완벽해 보이므로 정상 동작할 것입니다.” 추측은 검증이 아닙니다. 실제 터미널 실행 로그와 종료 코드 0 증거를 제출해야 합니다.
“기능 구현을 먼저 끝내고 테스트는 마지막에 몰아서 짜겠습니다.” TDD 원칙 위반입니다. 실패하는 테스트(Red)를 먼저 작성해 확인하기 전에는 구현 코드를 작성할 수 없습니다.
“시간 단축을 위해 파일 전체를 덮어쓰겠습니다.” 금지됩니다. 변경이 필요한 최소 단위만 수정하고 diff를 확인해야 합니다.

단순히 “테스트 코드 꼼꼼하게 짜줘"라고 프롬프트를 쓰는 것보다, 에이전트가 핑계를 대고 빠져나갈 구멍을 시스템 규칙으로 미리 차단해 두는 편이 훨씬 높은 코드 신뢰도를 보장합니다.

3. 개발 생애주기 6단계와 커맨드 체계

agent-skills는 기능 구상부터 배포까지의 개발 생애주기를 6단계로 나누고, 이를 9개의 슬래시 커맨드로 매핑해 두었습니다.

graph LR A["1. DEFINE
(/spec, /constraints)"] --> B["2. PLAN
(/plan)"] B --> C["3. BUILD
(/build, /build auto)"] C --> D["4. VERIFY
(/test, TDD)"] D --> E["5. REVIEW
(/review, /webperf)"] E --> F["6. SHIP
(/ship, 릴리스)"]

실무에서 특히 유용한 3가지 기능

1) /build auto (검증 기반 자율 빌드 모드)

기능 명세와 작업 계획을 사람이 한 번 승인하면, 에이전트가 작업을 원자 단위로 쪼개어 [테스트 작성 -> 실패 확인 -> 코드 구현 -> 테스트 통과 -> git 커밋] 사이클을 혼자서 돕니다. 테스트가 실패하거나 위험한 명령이 실행될 때만 사람의 확인을 요청합니다.

⚠️ 실무 프로덕션 적용 시 주의점
자율 빌드 모드를 메인 브랜치에서 바로 쓰는 것은 대단히 위험합니다. 간혹 에이전트가 실패하는 테스트를 통과시키기 위해 기존 비즈니스 제약조건(Validation) 자체를 임의로 완화해 버리는 ‘테스트 오염’이 일어날 수 있습니다. 반드시 격리된 작업 브랜치(feature/*)에서 실행하고, 최종 머지 전에는 인간 개발자의 코드 리뷰를 필수로 거쳐야 합니다.

2) Doubt-driven-development (의심 주도 개발)

에이전트는 자신이 작성한 코드의 결함을 스스로 간과하는 경향이 심합니다. 이 스킬이 켜지면 에이전트는 악마의 변호인 입장에서 자신의 코드를 의도적으로 공격하기 시작합니다.

  • 대량의 동시 요청이 들어왔을 때 락(Lock)이나 병목이 생기지 않는가?
  • 외부 API 통신이 지연되거나 끊겼을 때 적절한 재시도 및 예외 처리가 되어 있는가?
  • 사용자 입력값에 대한 방어 로직이 빠져있지 않은가?

3) /review (5개 축 기반 코드 감사)

풀 리퀘스트(PR)를 올리기 전 시니어 개발자가 꼼꼼히 리뷰하듯 5가지 관점에서 코드를 분리 검토합니다.

  • 기능 정확성: 요구사항 구현 여부 및 경계값 처리
  • 보안: 입력값 검증, 권한 체크, 시크릿 키 노출 방지
  • 성능: 불필요한 I/O, N+1 쿼리, 리소스 누수
  • 아키텍처: 프로젝트 기존 컨벤션과의 일관성
  • 테스트 커버리지: 실패 케이스 검증 여부

4. 로컬 개발 환경에 적용하기

이 프로젝트는 오픈소스 CLI 규격을 지원하므로 Cursor, Claude Code, Copilot 등 다양한 도구에 터미널 명령어로 바로 내려받아 쓸 수 있습니다.

npx를 이용한 빠른 설치

터미널에서 아래 명령어를 실행하면 24개의 엔지니어링 스킬이 현재 작업 환경에 설정됩니다.

# 전체 24개 스킬 일괄 설치
npx skills add addyosmani/agent-skills

# 필요한 스킬만 선택해서 설치 (예: TDD, 코드 리뷰)
npx skills add addyosmani/agent-skills --skill test-driven-development
npx skills add addyosmani/agent-skills --skill code-review-and-quality

Cursor를 사용 중이라면 프로젝트 내 .cursor/skills/ 폴더에 내려받아 에이전트가 작업 시 자동으로 읽도록 연동할 수 있고, Claude Code의 경우 플러그인 디렉토리로 지정해 활용할 수 있습니다.

⚠️ 실무 프로덕션 적용 시 주의점
사내 폐쇄망이거나 외부 npm 통신이 제한된 보안 환경에서는 npx skills 명령어가 실패할 수 있으므로 git clone 후 로컬 경로를 마운트해야 합니다. 또한 24개 스킬을 한 번에 모두 로드하면 LLM의 컨텍스트 윈도우를 과도하게 차지해 매 요청마다 토큰 비용이 급증할 수 있습니다. 실무에서는 팀에 꼭 필요한 핵심 스킬(TDD, 코드 리뷰 등) 3~4개만 선별해서 도입하는 것을 권장합니다.

5. 정리하며

많은 개발자들이 AI 코딩 도구를 쓸 때 더 정교한 ‘마법의 프롬프트’를 찾는 데 시간을 쏟곤 합니다. 저 역시 한동안 프롬프트 깎는 데 많은 시간을 썼지만, 결국 현업에서 생산성을 지켜준 것은 화려한 문구가 아니었습니다.

“테스트를 통과하지 못한 코드는 단 한 줄도 커밋할 수 없다"는 명확한 엔지니어링 규율과, 검증 없이는 완료를 선언하지 못하게 만드는 시스템을 구축하는 것이 백 배 더 중요하더군요.

AI 코딩 툴을 쓰면서 “코드 속도는 빠른데 이상하게 뒷수습할 게 더 많다"고 느껴지셨던 분들이라면, Addy Osmani의 agent-skills 워크플로우를 꼭 한 번 살펴보시고 프로젝트 룰에 녹여보시길 추천합니다.

참고 링크 및 출처