에이전트가 건너뛰는 건 언제나 시니어의 일이다 — Agent Skills가 강제하는 것

1. 이 글은 무엇에 관한 글인가?

Addy Osmani가 쓴 Agent Skills를 읽고 정리한 글입니다. 한 줄로 요약하면 이렇습니다.

시니어 엔지니어의 일은 대부분 diff에 나타나지 않습니다. 스펙, 테스트, 리뷰, 스코프 규율, 검증할 수 없는 걸 내보내지 않는 것. 그리고 에이전트는 그 부분을 기본값으로 건너뜁니다. Agent Skills는 그걸 선택사항이 아니게 만들려는 시도입니다.

지난 글이 "에이전트를 둘러싼 제약"이었다면, 이번 글은 "에이전트에게 집어넣는 절차"입니다. 방향이 반대인데 목적지가 같습니다.

왜 건너뛰는가

원문의 진단이 냉정합니다. 에이전트의 기본 동작은 "완료"까지의 최단 경로를 밟는 것 입니다. 기능을 달라고 하면 기능을 씁니다. 스펙이 있는지 묻지 않고, 구현 전에 테스트를 쓰지 않고, 이 변경이 신뢰 경계를 넘는지 따지지 않고, 리뷰어 눈에 이 PR이 어떻게 보일지 확인하지 않습니다. 코드를 내놓고, 승리를 선언하고, 다음으로 넘어갑니다.

그런데 이건 새로운 실패 양상이 아닙니다.

모든 시니어 엔지니어가 커리어 내내 피하는 법을 배워온 바로 그 실패 양상 입니다.

에이전트가 이 단계들을 건너뛰는 이유는 주니어가 건너뛰는 이유와 같습니다. 보이지 않기 때문 입니다. 보상 신호가 "작업 완료"를 가리키지 "작업 완료 + 설계 문서 존재"를 가리키지 않습니다.

보상이 걸린 것:    돌아가는 코드
보상이 안 걸린 것:  가정을 드러내기 · 스펙 · 리뷰 가능한 크기로 쪼개기
                  지루한 설계 고르기 · 정답이라는 증거 남기기

이 목록이 전부 시니어를 시니어로 만드는 것들 이고, 전부 보상 밖에 있습니다. 그래서 원문의 결론은 이렇습니다 — 시니어 엔지니어링의 비계(scaffolding)를 다시 붙여야 한다.

2. 스킬은 문서가 아니라 워크플로우다

이 글에서 가장 중요한 구분입니다. 그리고 대부분의 "AI 룰" 저장소가 실패하는 지점이기도 합니다.

원문의 정의는 이렇습니다. 스킬은 참조 문서가 아니라 워크플로우 입니다 — 에이전트가 따르는 단계의 순서, 증거를 만들어내는 체크포인트, 그리고 정의된 종료 조건. "테스트에 대해 알아야 할 모든 것"이 아니라는 뜻입니다.

왜 이 구분이 전부인가. 원문의 대비가 명쾌합니다.

프로세스가 산문을 이긴다(Process over prose). 워크플로우가 레퍼런스를 이긴다. 종료 조건이 있는 단계가 없는 에세이를 이긴다.

그리고 이 문장이 뼈아픕니다.

수많은 "AI 룰" 저장소가 실무에서 아무것도 안 하는 이유가 여기 있다. 그 룰들이 에세이이기 때문이다.

CLAUDE.md에 "테스트를 잘 작성하세요"라고 써놓고 지켜지길 기대하는 것 — 그게 에세이입니다. 검증할 산출물이 없으면 지켜졌는지조차 알 수 없습니다.

3. 다섯 가지 원칙 — 나머지는 여기서 따라온다

원문은 프로젝트의 하중을 받치는 설계 결정 다섯 개를 꼽습니다.

3-1. 프로세스가 산문을 이긴다

2절에서 다룬 그것입니다. 원문은 이걸 사람 팀에도 그대로 적용합니다 — 팀 핸드북이 200페이지면 압박 상황에서 아무도 안 읽고, 체크포인트가 있는 작은 워크플로우 몇 개면 사람들이 실제로 돌립니다.

3-2. 안티합리화 표 — 이 글에서 제일 훔칠 만한 것

원문이 "다른 팀이 가장 훔쳐 갔으면 하는 것"으로 꼽는 패턴입니다.

각 스킬에는 에이전트(또는 지친 엔지니어)가 워크플로우를 건너뛰려고 댈 만한 변명 표 가 붙어 있고, 각 변명에는 미리 써둔 반박 이 짝지어져 있습니다. 원문이 든 예를 옮기면 이런 식입니다.

이게 왜 작동하느냐 — 원문의 설명이 정확합니다.

LLM은 합리화에 아주 능하다. 이 작업만은 스펙이 필요 없는 이유를, 이 변경만은 리뷰 없이 머지해도 되는 이유를 그럴듯한 문단으로 만들어낸다.

그래서 안티합리화 표는 에이전트가 아직 하지 않은 거짓말에 대한 선제적 반박 입니다. 사후에 반박하려면 사람이 그 자리에 있어야 하지만, 미리 써두면 컨텍스트에 이미 들어가 있습니다.

그리고 이 패턴이 사람 팀에도 똑같이 좋다는 지적이 좋습니다.

엔지니어링 부패의 대부분은 누군가 나쁜 일을 하기로 선택해서 생기지 않는다. 하기 싫은 부분을 건너뛰는 그럴듯한 정당화를 받아들여서 생긴다.

3-3. 검증은 협상 대상이 아니다

모든 스킬이 구체적 증거 로 끝납니다. 테스트 통과, 깨끗한 빌드 출력, 기대 동작을 보여주는 런타임 트레이스, 리뷰어 승인. "맞는 것 같다"는 절대 충분하지 않습니다.

원문의 표현으로는, 에이전트는 생성기(generator)이고 작업이 끝났다는 신호는 별도로 필요합니다. 지난 글의 제약, 그 전 글의 eval과 정확히 같은 이야기입니다.

3-4. 점진적 공개(progressive disclosure)

스무 개 스킬을 세션 시작에 전부 로드하지 않습니다. 단계에 따라 활성화 하고, 작은 메타 스킬이 라우터 역할로 지금 작업에 어떤 스킬이 맞는지 고릅니다.

근거는 단순합니다. 컨텍스트에 로드되는 모든 토큰은 어딘가의 성능을 떨어뜨리므로, 관련된 것만 올리고 나머지는 디스크에 둔다는 것.

덜어내는 컨텍스트 엔지니어링에서 다룬 이야기를 스킬 단위로 내린 것 입니다. 스무 개짜리 라이브러리를 5K 토큰 자리에 넣는 방법이 라우팅입니다.

3-5. 스코프 규율

메타 스킬이 못박는 비협상 항목 — "요청받은 것만 건드려라." 인접 시스템을 리팩터링하지 말 것. 완전히 이해하지 못한 코드를 지우지 말 것. TODO를 스치고는 파일을 다시 쓰기로 결정하지 말 것.

뻔한 소리처럼 들리지만, 버그 하나 고치려고 무관한 파일 세 개를 현대화하기로 결정하는 에이전트를 보고 나면 달라진다는 관찰이 실무적입니다. 원문은 스코프 규율을 에이전트의 PR이 머지 가능한지, 되돌려야 하는지 를 가르는 가장 큰 단일 변수로 꼽습니다.

4. Google DNA — 이미 공개돼 있는데 기본 탑재가 아니다

스킬들이 Software Engineering at Google 과 Google의 공개된 엔지니어링 문화로 가득 차 있는 건 의도적입니다. 이유가 정확합니다 — Google 규모의 소프트웨어를 굴러가게 하는 것 대부분은 이미 문서화돼 공개돼 있고, 그건 정확히 에이전트가 가장 잘 건너뛰는 부분입니다.

그리고 이 절의 핵심 문장이 나옵니다.

프론티어 모델은 학습 데이터에서 "하이럼의 법칙"이라는 표현을 읽었다. 그러나 새벽 3시에 당신의 API를 설계할 때 하이럼의 법칙을 적용하지는 않는다.

아는 것과 적용하는 것 사이의 간격 — 스킬은 그 간격을 메우는 장치입니다. 모델이 모르는 걸 가르치는 게 아니라, 아는 걸 그 순간에 꺼내 쓰게 만드는 것입니다.

5. 하네스에서 스킬의 자리 — 그리고 이 글의 가장 중요한 한계

원문은 스킬을 하네스의 한 층 으로 위치시킵니다.

여기서 SDLC 플레이북 글에서 정리했던 강제력 축을 겹쳐 읽어야 합니다.

CLAUDE.md · 스킬  → 모델이 따라주기를 기대하는 것
훅 · eval        → 모델이 협조하지 않아도 성립하는 것

스킬은 강제력이 없는 쪽에 있습니다. 아무리 잘 쓴 워크플로우도 컨텍스트에 들어간 텍스트고, 에이전트는 그걸 읽고도 건너뛸 수 있습니다. 안티합리화 표가 존재하는 이유 자체가 그 건너뜀이 실제로 일어나기 때문 입니다.

그래서 저는 이 글을 이렇게 읽었습니다 — 스킬은 "무엇을 할지"를 정의하고, 훅은 "안 하면 못 지나가게" 만듭니다. 둘 다 필요하고, 둘을 헷갈리면 안 됩니다. (7절에서 이 저장소의 실제 사례로 다시 나옵니다.)

한 가지 더, 긴 실행에 대한 지적이 좋습니다. 스킬은 채팅형보다 장시간 실행 에이전트에서 더 중요하다 는 것 — 긴 실행이 모든 지름길을 증폭시키기 때문입니다.

10분 세션에서 테스트를 건너뛴 에이전트는 버그 하나를 만듭니다. 30시간 세션에서 건너뛴 에이전트는 끝날 무렵 아무도 원래 의도를 기억하지 못하는 디버깅 고고학 프로젝트 를 만듭니다. 실행이 길수록 시니어 비계는 제안이 아니라 강제 여야 합니다.

6. 설치하지 않아도 가져올 것

원문은 AI 에이전트를 아예 안 쓰더라도 훔칠 만한 패턴을 꼽습니다. 저도 이쪽이 이 글의 진짜 값어치라고 봅니다.

① 안티합리화를 팀 관행으로. 팀이 스스로에게 하는 거짓말을 적어두라는 것입니다. "테스트는 런칭 후에 고치자", "이 변경은 설계 문서를 쓰기엔 너무 작다", "괜찮아, 모니터링 있잖아." 각각에 반박을 짝지어 위키나 AGENTS.md에 두면 다음 금요일 오후의 지름길을 잡아줍니다.

② 내부 문서에도 프로세스가 산문을 이긴다. "우리는 X를 이렇게 합니다"라는 2,000단어 문서를 쓰고 있다면 그건 레퍼런스입니다. 체크포인트가 있는 워크플로우로 바꾸면 문서는 400단어로 줄고 사람들이 실제로 돌립니다. 온보딩 가이드와 런북에도 똑같이 적용됩니다.

③ 검증을 하드 종료 조건으로. 모든 작업의 종료 단계를 "증거를 만들어라"로 두라는 것. 초록색 테스트, 스크린샷, 로그, 리뷰 승인 — 무엇이든 일이 끝났음을 증명하는 것. 그게 없으면 작업은 끝난 게 아닙니다.

④ 룰북에도 점진적 공개를. 50페이지 핸드북 대신, 상황에 맞는 작은 챕터를 가리키는 작은 라우터 를 쓰라는 것. 압박 상황에서 읽힐 모든 문서에 해당합니다.

그리고 메타 스킬에서 뽑은 비협상 다섯 줄 — 원문은 이걸 내일 당장 어떤 AGENTS.md에든 넣겠다고 합니다.

1. 만들기 전에 가정을 드러낸다      ← 말없이 품은 틀린 가정이 가장 흔한 실패다
2. 요구가 충돌하면 멈추고 묻는다     ← 추측하지 않는다
3. 근거가 있으면 반박한다           ← 에이전트는 예스머신이 아니다
4. 지루하고 뻔한 해법을 고른다       ← 영리함은 비싸다
5. 요청받은 것만 건드린다

다섯 줄짜리 엔지니어링 문화고, 아무것도 설치하지 않아도 채택할 수 있습니다.

7. 이 저장소에 대입해보면 — 스킬은 있는데 강제는 훅이 했다

읽기만 하면 남는 게 없으니 실제로 대봤습니다. 그리고 이 저장소에는 마침 좋은 실증 사례가 하나 있습니다.

이 블로그 저장소에는 하네스 스킬이 여러 개 붙어 있습니다 — frontend-harness(a11y·시맨틱·SEO·TDD·리뷰), product-spec-harness(기획), test-layering-harness(테스트 계층), git-harness(커밋). 원문 기준으로 보면 구성은 이미 갖춰져 있는 셈 입니다.

그런데 바로 직전 글을 커밋할 때 실제로 벌어진 일 이 이 글의 5절을 그대로 증명했습니다.

git-harness:commit 스킬은 커밋 워크플로우를 아주 잘 정의해두고 있습니다 — 전제 조건 확인, 이슈 번호 추출, 타입 결정, 본문 필요 여부 판단, validation 체크리스트, 프리뷰 후 승인, push 문의. 원문이 말하는 "체크포인트와 종료 조건이 있는 워크플로우" 의 교과서적인 예입니다.

그런데 실제로 위험한 명령을 막은 건 스킬이 아니었습니다.

스킬이 한 것:  좋은 커밋 메시지 워크플로우를 제시했다
실제로 막은 것: guard.sh 훅이 `git add -A`를 exit 2로 차단했다

frontend-harness의 guard.sh 훅이 git add -A를 막아서, 파일을 명시적으로 나열하게 만들었습니다. 스킬이 아무리 잘 쓰여 있어도 그건 텍스트고, 실제 차단은 훅이 합니다. 5절에서 정리한 강제력 축이 한 세션 안에서 그대로 재현된 셈입니다.

여기서 얻을 결론은 "스킬이 쓸모없다"가 아닙니다. 역할이 다르다 는 것입니다.

그리고 지난 글에서 이 저장소의 가장 큰 구멍으로 꼽았던 것 — 스킬·CLAUDE.md를 바꿨을 때 그게 나빠졌는지 확인하는 eval이 없다 — 는 이 글 관점에서 더 아픕니다. 스킬이 늘어날수록 그 구멍도 같이 커지기 때문입니다. 워크플로우를 인코딩하는 파일이 스무 개인데 그 파일들에 대한 회귀 테스트가 0개라면, 가장 많이 쓰이는 코드가 가장 검증이 안 된 코드 입니다.

8. 오해하기 쉬운 지점

오해 1 — "스킬 = 잘 쓴 프롬프트"

아닙니다. 구분은 검증 가능한 산출물이 있는가 입니다.

프롬프트:   "테스트를 꼼꼼히 작성해줘"        → 지켜졌는지 확인할 방법이 없다
워크플로우: "실패하는 테스트를 먼저 커밋해라"   → 커밋 로그에 남거나 안 남거나 둘 중 하나다

체크포인트마다 밖에서 볼 수 있는 흔적 이 남는지가 기준입니다. 안 남으면 그건 그냥 잘 쓴 프롬프트입니다.

오해 2 — "스킬을 많이 깔면 좋다"

3-4절이 정면으로 반대합니다. 전부 로드하면 모든 토큰이 어딘가의 성능을 떨어뜨립니다. 스무 개가 성립하는 이유는 스무 개를 다 올리지 않기 때문입니다. 라우터 없이 스킬만 늘리는 건 컨텍스트 오염을 늘리는 것과 같습니다.

오해 3 — "이건 에이전트용 이야기"

6절 전체가 반박입니다. 안티합리화 표, 프로세스 우선, 증거 기반 종료 조건, 점진적 공개 — 전부 사람 팀에 그대로 적용되는 패턴 입니다. 원문이 마지막에 "설치하지 않아도 채택할 수 있다"고 못박는 이유입니다.

오해 4 — "스킬을 깔았으니 절차가 지켜진다"

7절의 실증 사례가 이겁니다. 스킬은 지켜지길 기대하는 것이고, 훅은 안 지키면 못 지나가게 하는 것 입니다. 지켜져야만 하는 규칙을 스킬에만 적어두고 안심하는 게 가장 흔한 실수입니다.

9. 정리

그리고 이건 앞선 글들과 같은 이야기의 다른 축입니다.

• 자가치유 하네스 — 규칙을 더할 때 검증하라
• 덜어내는 컨텍스트 엔지니어링 — 규칙을 덜어낼 때 검증하라
• AI 네이티브 SDLC — 프로세스를 바꿀 때 검증하라
• 코드 품질은 제약에 있다 — 에이전트를 둘러싸는 것 으로 검증하라
• 이번 글 — 에이전트에게 집어넣는 것. 그게 스킬이다

원문의 마지막 문단이 이 글의 마무리로도 맞습니다. AI 코딩 에이전트는 diff에 나타나지 않는 일에 대한 본능이 전혀 없는, 대단히 유능한 주니어 라는 것. 그리고 그 시니어의 일은 건너뛰는 게 불가능해질 때까지는 반드시 건너뛰어진다 는 것.

엔지니어가 모델이더라도, 그 일이 선택사항이 아니라는 건 변하지 않습니다.

참고 문서

• Addy Osmani, Agent Skills (2026-05-03) · 저장소 (MIT)
• Titus Winters 외, Software Engineering at Google (2020)
• 이전 글 — 코드 품질은 제약에 있다 · AI 네이티브 SDLC 플레이북 · 덜어내는 컨텍스트 엔지니어링