Agent Skills

Senior 엔지니어의 업무는 diff 에 드러나지 않는 부분들이 대부분입니다. 스펙 (Spec). 테스트 (Tests). 리뷰 (Reviews). 범위 관리 (Scope discipline). 검증되지 않은 것을 배포를 거부하는 것. AI 코딩 에이전트는 기본적으로 이 부분들을 건너뜁니다. Agent Skills 는 이를 선택적이지 않게 만드는 시도입니다.

어떤 AI 코딩 에이전트의 기본 동작은 "완료" 에 가장 짧은 경로를 취하는 것입니다. 기능을 요청하면 해당 기능을 작성합니다. 스펙이 있는지 묻지 않고, 구현 전에 테스트를 작성하지 않으며, 변경 사항이 신뢰 경계를 넘어선다고 고려하지도, 리뷰어가 PR 을 어떻게 볼지 확인하지도 않습니다. 코드를 생성하고 승리 선언하며 다음으로 나갑니다.

이는 모든 Senior 엔지니어가 경력 동안 피하려 했던 동일한 실패 모드입니다. 어떤 작업의 Senior 버전은 diff 에 드러나지 않는 작업을 포함합니다: 가정을 표면화 (surfacing assumptions), 스펙 작성, 리뷰 가능한 조각으로 작업 분할, 지루한 디자인 선택, 결과가 올바른 증거를 남기며, 사람이 실제로 리뷰할 수 있도록 변경 사항을 크기 조정. 이 단계들은 신뢰성 있는 소프트웨어를 대규모로 배포하는 엔지니어와 파손된 코드를 푸시하는 사람들 사이의 대부분을 구분합니다.

에이전트는 Junior 와 같은 이유로 이 단계를 건너뜁니다. 그들은 보이지 않습니다. 보상 신호는 "작업 완료" 가 아닌 "작업 완료 및 디자인 문서가 존재" 를 지향합니다. 따라서 우리는 Senior 엔지니어의 스프링클 (scaffolding) 을 다시 부착해야 합니다.

Agent Skills 는 그 스프링클을 시도한 것입니다. 27K stars 를 넘었으므로, 분명히 제가 혼자서 원하는 것이 아닙니다. 이 포스트는 README 가 다루지 않는 부분입니다: 각 디자인 선택이 왜 존재하는지, 표준 SDLC 와 Google 의 공시된 엔지니어링 관행에 어떻게 매핑되는지, 그리고 단일 스킬을 설치하지 않더라도 프로젝트에서 무엇을 훔쳐야 하는지 설명합니다.

"Skill" 이 실제로는 무엇인가

"Skill" 은 Claude Code / Anthropic 용어에서 많은 일을 하고 있습니다. 명확하게 해야 합니다. Skill 은 상황 호출 시 에이전트 컨텍스트에 주입되는 마크다운 파일입니다. 시스템 프롬프트 조각과 러너북 사이 어디선가.

Skill 은 참조 문서 (reference documentation) 가 아닙니다. "테스트에 대해 알아야 할 모든 것" 이 아닙니다. 워크플로우 (workflow) 입니다: 에이전트가 따르는 단계의 시퀀스, 증거를 생성하는 체크포인트로 끝나며 정의된 종료 기준을 갖습니다.

이 구별이 전체 게임입니다. 에이전트 컨텍스트에 테스트 모범 사례에 대한 2,000 단어 에세이를 넣으면, 에이전트는 그것을 읽으며 합리적으로 보이는 텍스트를 생성하고 실제 테스트를 건너뜁니다. 워크플로우 를 넣으면 (실패하는 테스트 먼저 작성, 실행, 실패 관찰, 최소 코드 작성 통과, 통과 관찰), 에이전트에게 할 일을 주며, 검증할 것을 제공합니다.

프로세스가 글보다 우선합니다. 워크플로우가 참조보다 우선합니다. 종료 기준이 있는 단계가 종료 기준이 없는 에세이보다 우선합니다. 이 단일 구별이 유용한 스킬과 아름다운 마크다운 파일을 구분합니다. 또한 많은 "AI 규칙" 저장소가 실제로 아무것도 하지 않는 이유를 설명합니다. 규칙은 에세이입니다.

스킬이 인코딩하는 SDLC

저장소의 20 개의 스킬은 6 가지 라이프사이클 단계에 조직되며, 7 개의 슬래시 명령어가其上에 있습니다. Define (/spec) 는 실제로 무엇을 구축할지 결정하는 곳입니다. Plan (/plan) 은 작업을 분해합니다. Build (/build) 는 이를 수직 슬라이스에서 구현합니다. Verify (/test) 는 작동함을 증명합니다. Review (/review) 는 통과한 것을 잡습니다. Ship (/ship) 은 사용자에게 안전하게 도달시킵니다. /code-simplify 는 전체 아래에 위치합니다.

이것은 우연이 아닙니다. 작동하는 모든 엔지니어링 조직이 실행하는 SDLC (Software Development Life Cycle) 의 동일한 프로세스일 뿐, 단순히 다른 용어로 표현된 것입니다. 구글은 이를 '디자인 문서 → 리뷰 → 구현 → 가독성 리뷰 → 출시 체크리스트'라고 부릅니다. 아마존은 이를 '작업 뒤로 작업하는 메모 (working-backwards memo)'와 '바를 높이는 사람 (bar raiser)'이라고 부릅니다. 건강한 팀에는 이 루프의 어떤 버전이 항상 존재합니다.

AI 코딩 에이전트에서 새로운 것은 대부분의 에이전트가 기본으로 이 단계 중 대부분을 건너뜀 것입니다. 기능을 요청하면 구현만 제공되고, 스펙, 계획, 테스트, 리뷰, 출시 체크리스트는 모두 발생하지 않습니다. 스킬은 세니어 엔지니어가 스스로 강요하는 동일한 단계를 에이전트를 통해 통과시킵니다. 왜냐하면 이 스킬 없이 코드를 배포할 경우 사고를 발생시키기 때문입니다.

복잡한 기능은 11 개의 스킬을 순차적으로 활성화할 수 있습니다. 작은 버그 수정은 3 개만 사용할 수도 있습니다. 라우터 (using-agent-skills) 는 어떤 것이 적용되는지 결정합니다. 핵심은 워크플로우가 예상된 범위가 아닌 실제 범위에 따라 확장된다는 점입니다.

작업하는 데 필요한 다섯 가지 원칙

프로젝트의 5 가지 디자인 결정이 하중 지지 역할을 합니다. 나머지 시스템은 이 것들에서 파생됩니다.

1. 프로세스보다 글 (Process over prose)

이미 다뤄졌습니다. 워크플로우는 에이전트가 실행 가능한 반면, 에세이는 아닙니다. 인간 팀에도 동일합니다. 팀 핸드북이 200 페이지라면 시간 압박 아래에서는 아무도 읽지 않습니다. 작은 워크플로우 세트와 체크포인트가 있다면 사람들이 실제로 실행합니다.

2. 반합리화 표 (Anti-rationalization tables)

이것은 프로젝트에서 가장 특징적인 디자인 결정이며, 다른 팀들이 가져갈 수 있는 가장 중요한 결정입니다.
각 스킬에는 에이전트 (또는 지친 엔지니어) 가 워크플로우를 건너뛰기 위해 사용할 수 있는 일반적인 합리화 목록과 이에 대한 서면 반박이 포함됩니다. 원본에 가까운 몇 가지 예시:

"이 작업은 스펙을 필요로 하지 않는 간단한 것입니다." → 수용 기준은 여전히 적용됩니다. 5 줄이면 괜찮습니다. 0 줄은 아닙니다."테스트는 나중에 작성하겠습니다." → '나중에'는 하중 지지 단어가 아닙니다. '나중에'는 없습니다. 실패하는 테스트를 먼저 작성합니다."테스트가 통과되어 배포하세요." → 통과된 테스트는 증거일 뿐, 증명이지 않습니다. 런타임 확인을 했습니까? 사용자 가 볼 수 있는 동작을 검증했습니까? 사람이 디프 (diff) 를 읽었습니까?

이것이 작동하는 이유는 LLM 이 합리화에 매우 뛰어남니다. 그들은 특정 작업에 스펙이 필요하지 않거나, 특정 변경 사항을 리뷰 없이 병합해도 괜찮다고 설명할 수 있는 그럴듯한 단락을 생성합니다. 반합리화 표는 에이전트가 아직 말하지 않은 거짓말에 대한 미리 작성된 반박입니다.

이 패턴은 인간 팀에도 동일하게 적용됩니다. 대부분의 엔지니어링 부패는 누군가가 나쁜 일을 선택해서 하는 것이 아닙니다. 사람들은 하고 싶지 않은 부분을 건너뛰기 위한 그럴듯한 합리화를 받아들이는 것입니다. 자신의 반합리화를 기록하는 팀은 더 적은 수의 반합리화를 가집니다.

3. 검증은 불가피하다 (Verification is non-negotiable)

각 스킬은 구체적 증거로 종료됩니다. 테스트가 통과됩니다. 빌드 출력이 깨끗합니다. 런타임 트레이스에는 예상 동작이 표시됩니다. 리뷰어가 서명합니다.*"그렇다, 괜찮다"*는 결코 충분하지 않습니다.

이는 안틱리프의 허니 (harness) 가 실패에서 회복할 수 있게 하는 것과 동일한 원칙이며, 커서스의 플래너/워커/재판자 분리가 실제로 버그를 잡게 하는 원리입니다. 또한 장기 실행 에이전트가 회복 가능하게 만드는 원리입니다. 에이전트는 생성기입니다. 작업이 완료되었음을 나타내는 별도의 신호가 필요합니다. 스킬은 이를 모든 워크플로우에 담습니다.

4. 점진적 공개 (Progressive disclosure)

세션 시작 시 20 개의 스킬을 모두 컨텍스트로 로드하지 마세요. 단계를 기반으로 활성화하세요. 작은 메타 스킬 (using-agent-skills

현재 작업에 적용되는 기술 (skill) 을 결정하는 라우터 역할을 합니다.

이것은 토큰 단위의 성능 저하를 고려한 엔지니어링 수업입니다. 컨텍스트로 로드되는 모든 토큰은 어느 정도 성능을 저하시키기 때문에, 관련성 있는 것만 로드하고 나머지는 디스크에 두세요. 진보적 공개 (Progressive disclosure) 는 20 개의 기술 라이브러리를 5K 토큰 슬롯에 넣지 않고도 우물을 오염시키지 않는 방법입니다.

5. 범위 규율 (Scope discipline)

나는 모든 에이전트에 적용할 수 있다면 다음과 같이 절대적이지 않을 수 없는 것을 코딩할 것입니다: "요청받은 것만 만져야 한다." 인접한 시스템을 리팩토링하지 마세요. 완전히 이해하지 않은 코드를 제거하지 마세요. TODO 를 문지르고 파일을 다시 쓰기로 결정하지 마세요.

이것은 에이전트가 하나의 버그를 수정하기 위해 세 개의 관련 없는 파일을 현대화해야 한다고 판단할 때까지는 명백해 보일 수 있습니다. 범위 규율 (Scope discipline) 은 에이전트의 PR 이 병합되거나 해체되어야 하는지를 결정하는 가장 중요한 요소입니다. 또한 구글의 코드 리뷰 규범에 가장 잘 매핑되는 원칙이기도 합니다. 리뷰어는 하나의 작업 이상을 수행하는 PR 을 막습니다.

구글 DNA

기술은 소프트웨어 엔지니어링 가이드 (Software Engineering at Google) 와 구글의 공개적인 엔지니어링 문화에서 유래한 실천법으로 포화 상태입니다. 이는 의도적입니다. 구글 규모의 소프트웨어가 작동하는 대부분의 내용은 문서화되어 있고 공개되어 있으며, 에이전트가 가장 생략할 가능성이 높은 부분이기도 합니다.

각 기술이 어떤 실천법을 코딩하는지 일부 지도:

Hyrum's Lawinapi-and-interface-design
. API 의 모든 관찰 가능한 동작은 결국 누군가에 의해 의존될 것이므로, 이를 염두에 두고 디자인하세요.테스트 피라미드 (~80/15/5) 와 Beyoncé Ruleintest-driven-development
."좋아했다면 테스트를 작성해야 한다." 인프라 변경은 버그를 잡지 못합니다. 테스트가 그 역할을 합니다.테스트에서 DAMP 과 DRY 의 우선순위incode-review-and-quality
. 구글의 테스트 철학은 테스트 코드가 일부 중복을 감수하더라도 규격처럼 읽어야 한다는 것을 명시적으로 밝힙니다. 과도하게 추상화된 테스트는 알려진 반패턴입니다.~100 라인의 PR 사이즈, Critical / Nit / Optional / FYI severity 레이블incode-review-and-quality
. 구글의 코드 리뷰 규범에서 바로 가져온 것입니다. 큰 PR 은 검토되지 않고 스탬프 처리됩니다.Chesterton's Fenceincode-simplification
. 왜 추가되었는지 이해하지 않은 것까지 제거하지 마세요.트렁크 기반 개발과 원자 커밋ingit-workflow-and-versioning
.시프트 왼쪽 (Shift Left) 과 기능 플래그inci-cd-and-automation
. 가능한 한 일찍 문제를 발견하고 배포와 릴리스를 분리하세요.코드-as-liabilityindeprecation-and-migration
. 유지해야 하는 모든 줄은 영원히 유지해야 하므로, 더 작은 표면적을 선호하세요.

이것들은 새로운 아이디어가 아닙니다. 중요한 점은 에이전트에서 기본적으로 이 것들이 없다는 것입니다. 프론티어 모델은 훈련 데이터에서 "Hyrum's Law"이라는 표현을 읽었지만, 3 시에 API 를 설계할 때 Hyrum's Law 를 적용하지 않습니다. 기술 (Skills) 은 그것이 어떻게 작동하는지 보장합니다.

실제로 사용하는 방법

약간 증가된 헌신으로 세 가지 모드입니다.

Mode 1: 마켓플레이스를 통해 설치. Claude Code 를 사용 중이라면:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

슬래시 명령어 (/spec, /plan, /build, /test, /review, /ship, /code-simplify) 를 얻고, 에이전트는 컨텍스트에 따라 관련 기술을 자동으로 활성화합니다. 이것이 가장 많은 사람들이 시작할 수 있는 경로입니다.

Mode 2: 마크다운을 도구 선택에 그대로 적용하세요. 스킬은 프론트매터가 포함된 평범한 마크다운입니다. Cursor 사용자는 .cursor/rules/ 에将它们放置합니다.

Gemini CLI 는 별도의 설치 경로를 가집니다. Codex, Aider, Windsurf, OpenCode, 시스템 프롬프트를 받는 모든 도구는 이를 읽을 수 있습니다. 도구 자체보다 그 이면에 있는 워크플로우가 더 중요합니다.

Mode 3: 이를 스펙으로 읽어보세요. 설치하지 않는다고 해도 스킬은 AI 에이전트와 좋은 엔지니어링이 어떻게 보이는지에 대한 문서화된 설명입니다. code-review-and-quality.md 를 읽어보시고 팀의 리뷰 프로세스에 5 축 프레임워크를 적용하세요.

test-driven-development.md 를 읽어보고 다음 “테스트를 먼저 작성해야 하나?”라는 논쟁을 해결하는 데 사용하세요. 메타 스킬을 읽고 AGENTS.md 에 자신의 비조건적 5 가지 원칙을 가져와보세요.

이 세 번째 모드가 실제로 시작할 곳입니다. 현재 가장 고통스러운 문제와 가장 가까운 4~5 개의 스킬을 선택하고, 강제하고 싶은 워크플로우를 결정하세요. 그런 다음 실행 환경을 설치하거나 직접 만들어서 제약을 부과하세요.

설치하지 않아도 가져야 할 것들

AI 코딩 에이전트를 사용하든 안 하든 상관없이 프로젝트에서 몇 가지 패턴을 가져와야 합니다.

팀 실천으로서 반이성화. 팀이 스스로에게 속삭이는 거짓말들을 적어보세요. “우리는 출시 후 테스트를 수정할 것입니다.” “이 변경사항은 설계 문서에 너무 작습니다.” “괜찮아요, 모니터링이 있습니다.” 각것마다 반박을 짝지어보세요. AGENTS.md 나 엔지니어링 위키에 넣으세요. 이는 논쟁을 절약하고 다음 지친 금요일 오후의 단축을 잡게 할 것입니다.

내부 문서 작성 시 프로세스보다 글쓰기. 2,000 단어짜리 “우리가 X 를 어떻게 접근하는가”라는 제목의 문서를 쓰신다면, 당신은 참고 자료를 작성한 것입니다. 이를 체크포인트가 포함된 워크플로어로 변환하세요. 문서의 길이는 400 단어로 줄어듭니다. 이는 에이전트 스킬뿐만 아니라 온보딩 가이드와 런북에도 적용됩니다.

검증은 필수 종료 기준. 모든 작업의 종료 단계로 “증거 생성”을 만들어보세요. 에이전트를 위한 것, 엔지니어를 위한 것, 그리고 나 자신을 위한 것입니다. 증거는 작업이 끝났음을 증명하는 모든 것: 녹색 테스트 실행, 스크린샷, 로그, 리뷰 승인입니다. 이를 없애면 작업은 완료되지 않습니다. *“그렇다”라는 말은 결코 루프를 닫지 못합니다.

어떤 규칙서에도 점진적 공개. 50 페이지의 매뉴얼을 쓰지 마세요. 상황에 맞는 작은 장을 지목하는 작은 라우터 작성을하세요. 이는 AGENTS.md, 런북, 사고 대응 매뉴얼, 그리고 시간 압박 아래에서 누구나 읽을 모든 것에 해당합니다.

메타 스킬에서 가져온 비조건적 5 가지 원칙이 내일 어떤 AGENTS.md 에도 들어갈 것입니다:

• 빌드하기 전에 가정을 표출하세요. 잘못된 가정이 침묵으로 유지되는 것은 가장 흔한 실패 모드입니다.
• 요구사항이 충돌할 때 멈추고 물어보세요. 추측하지 마세요.
• 정당화될 때 반박하세요. 에이전트 (또는 엔지니어) 는 예스 머신이 아닙니다.
• 지루하고 명확한 해결책을 선호하세요. 재능은 비싼 것입니다.
• 요청된 것만 만져보세요.

이 5 줄에서 가치 있는 엔지니어링 문화가 있으며, 이를 채택하기 위해 설치할 필요는 없습니다.

이 것이 허니에 어떻게 들어가는지

넓은 그림에서 스킬은 에이전트 허니 엔지니어링의 한 층입니다. 허니는 모델과 그 주변에 구축된 모든 것; 스킬은 점진적으로 시스템 프롬프트로 공개되는 재사용 가능한 워크플로우 조각들입니다. 이는 AGENTS.md 옆에 위치합니다.