# Agent Skills

> Clean Markdown view of GeekNews topic #29200. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=29200](https://news.hada.io/topic?id=29200)
- GeekNews Markdown: [https://news.hada.io/topic/29200.md](https://news.hada.io/topic/29200.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-05-06T05:43:36+09:00
- Updated: 2026-05-06T05:43:36+09:00
- Original source: [addyosmani.com](https://addyosmani.com/blog/agent-skills/)
- Points: 1
- Comments: 1

## Topic Body

- [Agent Skills](https://github.com/addyosmani/agent-skills)는 AI 코딩 에이전트가 명세, 테스트, 리뷰 가능한 PR, 신뢰 경계 검토 같은 **시니어 엔지니어링 절차**를 건너뛰지 못하도록 워크플로로 강제하는 스캐폴딩임
- **스킬(skill)** 은 frontmatter가 있는 Markdown 파일로, 참조 문서라기보다 단계 순서, 체크포인트 증거, 종료 기준을 가진 **워크플로**에 가까움
- 저장소의 20개 스킬은 Define, Plan, Build, Verify, Review, Ship의 6개 생명주기 단계와 `/spec`, `/plan`, `/build`, `/test`, `/review`, `/ship`, `/code-simplify` 7개 slash command로 구성됨
- 핵심 원칙은 **산문보다 프로세스**, 반합리화 표, 검증을 종료 기준으로 삼기, 점진적 공개, 범위 규율이며, `using-agent-skills`가 작업에 맞는 스킬만 활성화함
- Claude Code marketplace 설치, Cursor `.cursor/rules/`, Gemini CLI, Codex, Aider, Windsurf, OpenCode 같은 도구에 Markdown을 넣는 방식으로 사용할 수 있으며, MIT 라이선스로 공개됨

---

### 목적과 문제의식
- [Agent Skills](https://github.com/addyosmani/agent-skills)는 AI 코딩 에이전트가 기본적으로 건너뛰는 **시니어 엔지니어링 절차**를 워크플로로 강제하기 위한 스캐폴딩임
- AI 코딩 에이전트는 기능을 요청받으면 보통 가장 짧은 경로로 구현을 끝내며, 명세 작성, 테스트 선행, 신뢰 경계 검토, 리뷰 가능한 PR 구성 같은 절차를 기본적으로 수행하지 않음
- 시니어 엔지니어의 작업에는 diff에 드러나지 않는 부분이 많음
  - 가정 드러내기
  - 명세 작성
  - 리뷰 가능한 단위로 작업 나누기
  - 지루하지만 안전한 설계 선택하기
  - 결과가 맞다는 증거 남기기
  - 사람이 실제로 리뷰할 수 있는 크기로 변경 제한하기
- 에이전트가 이런 단계를 건너뛰는 이유는 주니어 엔지니어와 비슷하게, 보상 신호가 “작업 완료”에 맞춰져 있고 “명세 문서까지 존재하는 작업 완료”에는 맞춰져 있지 않기 때문임
- Agent Skills 저장소는 26K stars를 넘었으며, README를 넘어 설계 선택의 이유, 표준 SDLC와 Google의 공개 엔지니어링 관행과의 대응, 설치하지 않아도 가져갈 수 있는 패턴까지 다룸

### 스킬의 실제 의미
- **스킬(skill)** 은 상황에 따라 에이전트 컨텍스트에 주입되는 frontmatter 포함 Markdown 파일이며, 시스템 프롬프트 조각과 런북 사이에 가까운 형태임
- 스킬은 참조 문서가 아니며, “테스트에 대해 알아야 할 모든 것” 같은 지식 모음도 아님
- 유용한 스킬은 에이전트가 따르는 **워크플로**임
  - 단계의 순서가 있음
  - 체크포인트에서 증거를 생성함
  - 명확한 종료 기준으로 끝남
- 테스트 모범 사례에 대한 2,000단어 에세이를 컨텍스트에 넣으면 에이전트는 그럴듯한 문장을 생성하고 실제 테스트를 건너뛸 수 있음
- 반대로 실패하는 테스트를 먼저 작성하고, 실행해서 실패를 확인하고, 통과에 필요한 최소 구현을 작성하고, 통과를 확인하고, 리팩터링하는 워크플로를 넣으면 에이전트가 수행할 일이 생기고 사람이 검증할 수 있음
- 핵심 구분은 **산문보다 프로세스**, 참조보다 워크플로, 종료 기준 없는 에세이보다 종료 기준 있는 단계임
- 많은 “AI rules” 저장소가 실제로 효과를 내지 못하는 이유는 규칙이 워크플로가 아니라 에세이에 머물기 때문임

### SDLC와 slash command 구조
- 저장소의 20개 스킬은 6개 생명주기 단계로 구성되고, 그 위에 7개 slash command가 놓임
- ## 단계와 명령
  - `/spec`: 무엇을 만들지 결정하는 Define 단계임
  - `/plan`: 작업을 분해하는 Plan 단계임
  - `/build`: 수직 슬라이스로 구현하는 Build 단계임
  - `/test`: 동작을 증명하는 Verify 단계임
  - `/review`: 빠져나간 문제를 잡는 Review 단계임
  - `/ship`: 사용자에게 안전하게 전달하는 Ship 단계임
  - `/code-simplify`: 전체 흐름 아래에 걸쳐 적용되는 단순화 명령임
  - 이 구조는 정상적으로 작동하는 엔지니어링 조직의 SDLC와 같은 흐름이며, 조직마다 어휘만 다름
  - Google에서는 design doc → review → implementation → readability review → launch checklist 흐름으로, Amazon에서는 working-backwards memo와 bar raiser 같은 방식으로 나타남
  - AI 코딩 에이전트의 새로운 문제는 대부분의 에이전트가 이런 단계 대부분을 기본적으로 건너뛴다는 데 있음
  - 기능을 요청하면 구현만 나오고, 명세, 계획, 테스트, 리뷰, 출시 체크리스트는 수행되지 않음
  - 스킬은 시니어 엔지니어가 스스로 강제하는 단계를 에이전트에도 통과시키며, 그런 절차 없이 코드를 배포하면 장애로 이어짐
  - 복잡한 기능은 11개 스킬이 순차적으로 활성화될 수 있고, 작은 버그 수정은 3개만 사용할 수 있음
  - `using-agent-skills` 라우터가 현재 작업에 어떤 스킬이 적용되는지 결정하며, 워크플로는 가정된 범위가 아니라 실제 범위에 맞춰 확장됨

### 작동을 지탱하는 원칙
- ## 1. 산문보다 프로세스
  - 워크플로는 에이전트가 행동으로 옮길 수 있지만, 에세이는 그렇지 않음
  - 사람 팀에도 같은 원리가 적용됨
  - 팀 핸드북이 200페이지라면 압박 상황에서 읽히지 않지만, 체크포인트가 있는 작은 워크플로라면 실제로 실행될 가능성이 커짐
- ## 2. 반합리화 표
  - Agent Skills에서 가장 독특하고 다른 팀이 가져가야 할 설계 선택은 **반합리화 표(anti-rationalization tables)** 임
  - 각 스킬에는 에이전트나 지친 엔지니어가 워크플로를 건너뛰기 위해 사용할 법한 흔한 변명과, 그에 대한 미리 작성된 반박이 함께 들어감
  - 예시는 다음과 같음
    - “이 작업은 너무 단순해서 명세가 필요 없다” → 수용 기준은 여전히 적용됨. 5줄은 괜찮지만 0줄은 안 됨
    - “테스트는 나중에 작성하겠다” → “나중”이 핵심 문제임. 나중은 없음. 실패하는 테스트를 먼저 작성해야 함
    - “테스트가 통과했으니 배포하자” → 통과한 테스트는 증거이지 증명이 아님. 런타임을 확인했는지, 사용자에게 보이는 동작을 검증했는지, 사람이 diff를 읽었는지 확인해야 함
  - LLM은 합리화에 능하며, 특정 작업은 명세가 필요 없다거나 특정 변경은 리뷰 없이 병합해도 된다는 그럴듯한 문단을 만들 수 있음
  - 반합리화 표는 에이전트가 아직 말하지 않은 거짓말에 대한 **미리 작성된 반박**임
  - 이 패턴은 사람 팀에도 유효함
  - 엔지니어링 품질 저하는 대개 누군가가 나쁜 일을 하기로 결정해서가 아니라, 하기 싫은 절차를 건너뛰는 그럴듯한 정당화를 받아들이면서 생김
- ## 3. 검증은 협상 불가
  - 모든 스킬은 구체적인 증거로 끝남
  - 테스트 통과, 깨끗한 빌드 출력, 기대한 동작을 보여주는 런타임 trace, 리뷰어 승인 같은 것이 종료 기준이 됨
  - “그럴듯해 보임”은 충분하지 않음
  - 이는 Anthropic의 하네스(harness)가 실패에서 회복하고, Cursor의 planner/worker/judge 분리가 실제로 버그를 잡고, [long-running agent](https://addyosmani.com/blog/long-running-agents/)가 회복 가능해지는 원리와 같음
  - 에이전트는 생성기이므로, 작업 완료를 판단할 별도 신호가 필요하고 스킬은 그 신호를 각 워크플로에 내장함
- ## 4. 점진적 공개
  - 세션 시작 시 20개 스킬을 모두 컨텍스트에 넣지 않음
  - 현재 단계에 따라 필요한 스킬만 활성화함
  - 작은 메타 스킬인 `using-agent-skills`가 현재 작업에 맞는 스킬을 결정하는 라우터 역할을 함
  - 이는 [harness engineering](https://addyosmani.com/blog/agent-harness-engineering/)의 교훈을 스킬 단위에 적용한 것임
  - 컨텍스트에 로드되는 모든 토큰은 어딘가에서 성능을 떨어뜨리므로, 관련된 것만 로드하고 나머지는 디스크에 남겨야 함
  - **점진적 공개**는 20개 스킬 라이브러리를 5K-token 슬롯에 넣으면서 전체 컨텍스트를 오염시키지 않는 방식임
- ## 5. 범위 규율
  - 메타 스킬은 “요청받은 것만 건드려라”라는 협상 불가능한 원칙을 인코딩함
  - 인접 시스템을 리팩터링하지 말고, 완전히 이해하지 못한 코드를 제거하지 말고, TODO를 보고 파일 전체를 다시 쓰기로 결정하지 않아야 함
  - 에이전트는 버그 하나를 고치려다가 관련 없는 파일 3개를 현대화하려 할 수 있음
  - **범위 규율**은 에이전트의 PR이 병합 가능한지, 아니면 되돌려야 하는지를 가르는 가장 큰 결정 요인임
  - 이는 한 PR이 하나 이상의 일을 하면 리뷰어가 막을 수 있는 Google 코드 리뷰 규범과도 잘 맞음

### Google 엔지니어링 관행과의 연결
- Agent Skills에는 _Software Engineering at Google_과 Google의 공개 엔지니어링 문화에서 나온 관행이 많이 반영되어 있음
- Google 규모의 소프트웨어가 작동하게 만드는 많은 요소는 공개적으로 문서화되어 있으며, 바로 그 부분을 에이전트가 가장 자주 건너뜀
- ## 스킬과 관행의 대응
  - `api-and-interface-design`: **Hyrum’s Law**를 반영함. API의 관찰 가능한 모든 동작은 결국 누군가가 의존하게 되므로 이를 고려해 설계해야 함
  - `test-driven-development`: 테스트 피라미드 `~80/15/5`와 Beyoncé Rule을 반영함. “좋아했다면 테스트를 붙였어야 한다”는 원칙이며, 인프라 변경이 아니라 테스트가 버그를 잡음
  - 테스트의 **DAMP over DRY**: Google의 테스트 철학은 테스트 코드가 중복을 조금 감수하더라도 명세처럼 읽혀야 한다고 봄. 과도하게 추상화된 테스트는 알려진 안티패턴임
  - `code-review-and-quality`: `~100-line PR` 크기와 Critical / Nit / Optional / FYI 심각도 레이블을 반영함. 큰 PR은 실제로 리뷰되지 않고 고무도장처럼 승인되기 쉬움
  - `code-simplification`: **Chesterton’s Fence**를 반영함. 어떤 것이 왜 놓였는지 이해하기 전에는 제거하지 않아야 함
  - `git-workflow-and-versioning`: trunk-based development와 atomic commits를 반영함
  - `ci-cd-and-automation`: Shift Left와 feature flags를 반영함. 문제를 가능한 한 빨리 잡고, 배포와 릴리스를 분리해야 함
  - `deprecation-and-migration`: code-as-liability를 반영함. 유지하는 모든 줄은 영원히 관리해야 하므로 더 작은 표면을 선호해야 함
  - 이런 개념들은 새로운 것이 아니지만, 에이전트에 기본 탑재되어 있지 않음
  - frontier model이 “Hyrum’s Law”라는 문구를 학습 데이터에서 읽었더라도, 새벽 3시에 API를 설계할 때 자동으로 적용하지는 않음
  - 스킬은 이런 관행을 에이전트가 실제 작업 중 적용하게 만듦

### 실제 사용 방식
- ## 방식 1: marketplace로 설치
  - Claude Code를 사용한다면 다음 명령으로 설치함
  ```plaintext
  /plugin marketplace add addyosmani/agent-skills
  /plugin install agent-skills@addy-agent-skills
  ```
  - 설치하면 `/spec`, `/plan`, `/build`, `/test`, `/review`, `/ship`, `/code-simplify` slash command를 사용할 수 있음
  - 에이전트가 컨텍스트에 따라 관련 스킬을 자동으로 활성화함
  - 대부분의 사용자는 이 방식으로 시작하는 것이 권장됨
- ## 방식 2: 원하는 도구에 Markdown 넣기
  - 스킬은 frontmatter가 있는 일반 Markdown 파일임
  - Cursor 사용자는 `.cursor/rules/`에 넣을 수 있음
  - Gemini CLI는 자체 설치 경로가 있음
  - Codex, Aider, Windsurf, OpenCode, 시스템 프롬프트를 받을 수 있는 다른 도구도 읽을 수 있음
  - 중요한 것은 도구 자체보다 그 아래의 워크플로임
- ## 방식 3: 명세처럼 읽기
  - 아무것도 설치하지 않더라도 스킬은 AI 에이전트와 함께 좋은 엔지니어링을 수행하는 방식에 대한 문서화된 설명임
  - `code-review-and-quality.md`를 읽고 5축 프레임워크를 팀 리뷰 프로세스에 적용할 수 있음
  - `test-driven-development.md`를 읽고 “테스트를 먼저 작성해야 하는가” 같은 논쟁에 활용할 수 있음
  - 메타 스킬을 읽고 5가지 협상 불가능 원칙을 자신의 `AGENTS.md`에 가져갈 수 있음
  - 현재 가장 아픈 문제에 가까운 스킬 4~5개를 고르고, 강제하고 싶은 워크플로를 정한 뒤, 런타임을 설치하거나 직접 만들어 강제하는 흐름이 출발점이 될 수 있음

### 설치하지 않아도 가져갈 패턴
- ## 반합리화를 팀 관행으로 만들기
  - 팀이 스스로에게 하는 거짓말을 적어야 함
  - 예시는 “출시 후 테스트를 고치겠다”, “이 변경은 너무 작아서 설계 문서가 필요 없다”, “모니터링이 있으니 괜찮다” 같은 문장임
  - 각 문장에 반박을 붙이고 `AGENTS.md`나 엔지니어링 위키에 넣으면 논쟁을 줄이고 금요일 오후의 지친 지름길을 잡을 수 있음
- ## 내부 문서는 산문보다 프로세스로 쓰기
  - “우리는 X에 어떻게 접근하는가”라는 2,000단어 문서를 쓰고 있다면 참조 자료를 쓰는 것임
  - 이를 체크포인트가 있는 워크플로로 바꾸면 문서는 400단어로 줄고 실제로 실행될 가능성이 커짐
  - 이 원칙은 온보딩 가이드, 런북, 에이전트 스킬 모두에 적용됨
- ## 검증을 단단한 종료 기준으로 삼기
  - 모든 작업의 마지막 단계는 “증거 생성”이어야 함
  - 에이전트, 엔지니어, 개인 작업 모두에 적용됨
  - 증거는 녹색 테스트 실행, 스크린샷, 로그, 리뷰 승인처럼 작업이 끝났음을 입증하는 것이면 됨
  - 증거가 없으면 작업은 끝난 것이 아니며, “그럴듯해 보임”은 루프를 닫지 못함
- ## 모든 규칙집에 점진적 공개 적용하기
  - 50페이지 핸드북을 쓰지 말고, 상황에 맞는 작은 장으로 보내는 작은 라우터를 작성해야 함
  - 이는 `AGENTS.md`, 런북, 장애 대응 플레이북, 압박 상황에서 읽어야 하는 모든 문서에 적용됨
- ## AGENTS.md에 넣을 5가지 협상 불가능 원칙
  - 구축 전에 가정을 드러내야 함. 조용히 유지된 잘못된 가정은 가장 흔한 실패 모드임
  - 요구사항이 충돌하면 멈추고 물어야 함. 추측하지 않아야 함
  - 필요할 때는 반대해야 함. 에이전트나 엔지니어는 예스맨이 아님
  - 지루하고 명확한 해법을 선호해야 함. 영리함은 비쌈
  - 요청받은 것만 건드려야 함

### 하네스 안에서의 위치
- 스킬은 더 큰 관점에서 [agent harness engineering](https://addyosmani.com/blog/agent-harness-engineering/)의 한 계층임
- 하네스는 모델과 그 주변에 구축한 모든 것을 포함하며, 스킬은 시스템 프롬프트에 점진적으로 공개되는 재사용 가능한 워크플로 조각임
- 스킬은 `AGENTS.md`, hooks, tools, session log와 나란히 놓임
  - `AGENTS.md`: 계속 갱신되는 규칙집 역할임
  - hooks: 결정론적 강제 계층임
  - tools: 에이전트가 수행할 수 있는 행동임
  - session log: 지속되는 메모리임
  - skills: 시니어 엔지니어링 프로세스를 담당함
- 스킬은 채팅형 에이전트보다 [long-running agents](https://addyosmani.com/blog/long-running-agents/)에서 더 중요함
- 긴 실행은 모든 지름길을 증폭함
  - 10분 세션에서 테스트를 건너뛴 에이전트는 버그 하나를 만들 수 있음
  - 30시간 세션에서 테스트를 건너뛴 에이전트는 실행 끝에 원래 의도를 아무도 기억하지 못하는 디버깅 고고학 작업을 만들 수 있음
- 실행 시간이 길수록 시니어 엔지니어링 스캐폴딩은 제안이 아니라 강제로 적용되어야 함
- 스킬 형식의 이식성도 중요함
- 같은 `SKILL.md` 파일은 Claude Code, rules를 쓰는 Cursor, Gemini CLI, Codex, 시스템 프롬프트 콘텐츠를 받을 수 있는 다른 하네스에서 사용할 수 있음
- 워크플로를 한 번 작성하면 런타임이 강제할 수 있으며, 이것이 bespoke prompt engineering과 달리 Markdown-with-frontmatter 형식이 주는 이점임

### 결론
- AI 코딩 에이전트는 diff에 드러나지 않는 업무에 대한 본능이 없는, 매우 유능한 주니어 엔지니어처럼 동작함
- 가정 드러내기, 변경 크기 조절, 명세 작성, 증거 남기기, 리뷰할 수 없는 변경 병합 거부 같은 시니어 엔지니어링 작업은 에이전트가 건너뛰지 못하게 만들지 않으면 건너뛸 가능성이 큼
- 점점 더 중요한 일은 이런 규율을 에이전트가 스스로 말로 빠져나갈 수 없는 형태로 인코딩하는 것임
- 스킬은 그 한 가지 형태이며, 반합리화 표, 점진적 공개, 산문보다 프로세스, 종료 기준으로서의 검증, 이미 작동하는 Google 관행을 이식 가능하게 만든 구조가 핵심임
- [Agent Skills 저장소](https://github.com/addyosmani/agent-skills)는 MIT 라이선스로 공개되어 있으며, 더 넓은 스캐폴딩 관점은 [Agent Harness Engineering](https://addyosmani.com/blog/agent-harness-engineering/)과 [Long-running Agents](https://addyosmani.com/blog/long-running-agents/)에서 이어짐

## Comments



### Comment 56893

- Author: neo
- Created: 2026-05-06T05:43:36+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=48015397) 
- **사기성 만병통치약**에 가까움. 읽을 가치는 있고 그럴듯해 보이지만, 그래도 결국 사기성 만병통치약임  
  이유는 슬롯머신 같은 모델이 `AGENTS.md`, `memory.md`, 수십 개의 스킬 마크다운에 적어 둔 **필수 요구사항**을 언제든 빠뜨릴 수 있고, 사실상 보장된다는 데 있음  
  이런 하네스 접근은 LLM이 엄격하고 완벽하게 규칙을 따르며, 문제는 규칙을 충분히 명확히 많이 쓰지 못한 것뿐인 척함. 이는 LLM 작동 방식에 대한 근본적인 인지 오류임  
  결국 신뢰할 수는 없지만 상대적으로 더 신뢰할 수 있는 선택지는 **사람의 검토와 감독**뿐이고, 가능하면 두 번 연속으로 하는 것임  
  나머지는 전부 사기성 만병통치약이고, 그 지점에 이르면 약속된 생산성 향상도 마찬가지라는 걸 깨닫게 됨. 코드를 읽고 머릿속 모델을 만드는 일이, 이미 머릿속 모델이 있는 상태에서 코드로 옮기는 것보다 훨씬 어렵기 때문임
  - 사기성 만병통치약이라는 표현은 좀 과함. 그런 약은 절대 안 듣지만, LLM이 들어간 것은 확률적이어도 꽤 높은 확률로 작동하기 때문임  
    코드 읽기는 어떤 코드냐에 따라 다르지만, 다른 기술처럼 연습하면 쉬워짐. 오래전부터 존재하던 거대하고 복잡한 코드베이스를 다뤄야 할 때처럼, 쓰는 것보다 읽는 코드가 훨씬 많은 상황에서는 흔한 일임  
    더 쉬워지는 경우는 문서, 과거 경험, 동료에게 물어보기 등을 통해 이미 코드에 대한 **머릿속 모델**을 갖고 있을 때임  
    에이전트로도 이게 가능함. 보통 AI에 프롬프트를 넣기 전에 이미 코드 구조를 잘 알고 있고, 작업을 조심스럽게 나누면 생성된 코드 검토가 매우 쉬워짐. 이미 읽은 책을 다시 읽는 느낌이고, 드물게 뭔가 틀리면 바로 눈에 띄어 초기에 대부분 잡을 수 있음. 어느 쪽이든 속도 향상은 큼
  - 사람도 지정한 **필수 요구사항**을 자주 빠뜨리고, 마찬가지로 검토가 필요함. 그래도 프로세스와 리뷰를 통해 사람 산출물의 신뢰성을 높여 왔고, 하네스에서 쓰는 방법 대부분도 신뢰성 있게 전달하기 어려운 인간의 문제를 줄이려던 경험에서 가져온 것임
  - 말한 내용은 모두 가능하고 이론적으로는 동의함  
    하지만 지난 몇 달 동안 spec-kit, 즉 이런 방식의 AI 사용을 해봤고 실제로는 **놀라울 정도로 좋았음**. 훌륭한 것들을 만들고 있으며, 가정으로 제기한 문제들은 아직 겪지 않았음. 언젠가 생길 수는 있고 그래서 조심하고 있음  
    그래도 어느 정도 오래 직접 써본 뒤에는 그냥 사기성 만병통치약이라고 치부할 수 없음. 30년 넘게 프로그래머로 일해 왔고, 실제로 무엇이 통하고 무엇이 안 통하는지 꽤 잘 판단한다고 느낌
  - 이건 +5 검이 있어도 1이 나오면 빗나가니 쓸모없다는 말과 비슷함. **기대값**으로 봐야 함. 누군가가 괜찮은 PR 다섯 개를 머지하고 세 개를 버리는 동안, 그중 하나가 형편없었다고 크게 불평하는 식이면 비교가 안 됨
  - 사람들이 이런 마크다운 제안을 **워크플로**라고 부르는 이유가, 더 구조화된 접근을 다듬는 사이에 구식이 될까 두려워서이길 바람. 기반 모델의 혁신 속도가 영원히 이렇게 유지될 것 같지는 않음  
    앞으로는 요청이 아니라 요구하는 하네스를 보고 싶음. 계획 모드에 있으라고 했는데 정해진 계획 절차를 따르지 않는 에이전트는 죽이는 식임. 완벽하지 않더라도 사람이 끼어 있는 현재 방식보다는 나아야 함

- “스킬은 상황에 맞을 때 에이전트 문맥에 주입되는 frontmatter가 있는 마크다운 파일”이라고 하지만, 그 상황인지 결정하는 건 **LLM**임  
  “에이전트가 따르는 일련의 단계이며, 증거를 만드는 체크포인트와 명확한 종료 기준으로 끝난다”고 하지만, 그 단계를 따를지 결정할 수 있는 것도 LLM임
  - 스킬은 사용자가 **명령형으로 호출**하는 경우가 많음. LLM이 직접 쓰도록 의도된 경우에는 문맥 어딘가에 넣으면 됨. 예를 들면:  
    ```  
    After implementing the feature, read the testing skill for instructions on how to test.  
    ```
  - 공정하게 말하면 Codex 같은 곳에서는 `$my-skill`로 스킬을 직접 호출할 수 있고, 그러면 실제로 그 스킬이 문맥에 주입됨. 그 뒤에는 LLM이 프롬프트, 지시, 문맥의 다른 부분을 따르는 정도만큼 그 스킬도 따름

- 모두가 에이전트 만지작거리며 1년 넘게 보내고 **가짜 생산성** 느낌만 경험했다는 걸 깨닫는 날이 기대됨
  - 어느 정도 회의론은 이해하고, AI가 여러 이유로 나쁘다고 근본적으로 믿을 수도 있음. 하지만 이런 단정적인 표현이 점점 더 이해가 안 됨. AI 개발이 이렇게 망했다고 어떻게 그렇게 확신하는지 궁금함  
    실제 경험과 전혀 맞지 않음. AI 코딩의 필연적 몰락을 그렇게 확신하게 만든 경험이 무엇인지 궁금함. AI가 도덕적으로 나쁘다는 철학적 믿음인지, 아니면 실제로 AI로 뭔가를 만들어 보고 충분히 탐색한 끝에 강한 결론을 낸 것인지 알고 싶음  
    30년 넘게 매일 코드를 썼고, 20년 넘게 직업으로 해왔음. 유행이 왔다가 가는 것도 봤고, 일하는 방식을 바꾼 진짜 발전도 여러 번 봤음. AI로 더 많은 프로젝트를 만들수록, 이것이 소프트웨어를 만들고 컴퓨터를 쓰는 방식에 대한 **지속적이고 근본적인 변화**라는 확신이 커짐  
    AI가 나아지는 것도 봤고, 실제 업무를 끝내는 데 내가 더 능숙해지는 것도 봤음. 그 작업은 이미 현실 세계의 프로덕션 부하로 테스트됐음. 벌어지는 일이 싫고 AI와 일하는 느낌이 싫을 수는 있지만, 그렇다고 그것이 사람들에게 실제 가치를 주고 실제 일을 하고 있지 않다는 뜻은 아님
  - 이런 관점이 궁금함. 선의로 묻자면, AI/에이전트/하네스를 쓰는 사람들은 **기능을 배포하지 않는다**는 전제가 깔린 건가?  
    우리는 9월쯤부터 Claude Code에 전면적으로 들어갔고, 향상을 성공적으로 추적할 수 있었음. 실제 프로덕션에서 쓰이는 기능들을 배포하고 있음. 인프라 쪽도, 비즈니스 로직 구현도, 프론트엔드와 백엔드 모두 마찬가지임  
    사람들이 그렇게 시간을 낭비한다고 보지는 않음. 다만 이런 글 대부분은 허튼소리라는 데는 동의하고, 이 글도 포함됨. 그래도 AI 개발은 전 세계 많은 회사에서 이미 일어나고 있음
  - 사람들이 종이 장부를 그만 쓰고 소위 **데이터베이스**라는 걸 만지작거리느라 생산성을 잃었다는 말과 비슷함
  - 산출물을 측정하는 프로젝트에서 일하고 있는데, 거기엔 “가짜”가 전혀 없음
  - Minecraft 자동화처럼 대함. 그냥 재미와 시간 보내기용임  
    에이전트식 워크플로는 아직 거기까지 도달하지 않았다고 보지만, 수동으로 호출해서 AI와 나란히 일할 때 쓰는 스킬 구현은 확실히 괜찮음. 우리 회사는 요즘 샌드박싱과 안전한 스킬에 많이 집중하고 있음  
    기능 개발은 아직 잘 잡지 못했다고 보지만, 작성해 둔 **리뷰 스킬**과 **Grafana 스킬**은 꽤 탄탄했음

- 예전에 더 큰 에이전트 스킬 묶음을 써봤는데, 너무 많은 일을 하려 해서 시간 낭비처럼 느껴졌음. Vim처럼 스킬을 IDE처럼 통째로 설치하기보다 커뮤니티에서 골라 쓰는 편이 나은 경우가 많음  
  스킬은 개발자와 팀마다 달라서 너무 개인적임. 남의 설정을 대량 설치하기보다, 자기 설정을 만들기 위한 **참고 자료**로 다루는 편이 좋음
  - MCP와 시스템 지시도 마찬가지임. 이해하지도 않고 전부 설치하는 사람이 많고, 필요 없는 도구 때문에 문맥을 어지럽히며 **5만 토큰 이상**을 낭비한 뒤, 한도에 너무 빨리 닿아서 월 100달러 넘게 내야 한다고 불평함

- 검색 최적화나 LLM 최적화 관점에서 보면, 이름을 바꾸지 않으면 이런 스킬의 **발견 가능성**이 어려울 듯함: [https://agentskills.io/](<https://agentskills.io/>)  
  Addy가 본다면, 이것을 Superpowers와 비교해 어떻게 설명할지 궁금함: [https://github.com/obra/superpowers](<https://github.com/obra/superpowers>)
  - 실제로 **superpowers**를 쓰는 사람이 얼마나 되는지 알고 싶음  
    superpowers 이전부터 에이전트 개발 쪽에 있었는데, 직접 만든 프로세스의 50% 이상이 이제 superpowers로 커버되는 것 같아 걱정됨  
    더 이상 GitHub 별을 신뢰하지 않음. 누가 알려줬으면 함. superpowers가 이제 정말 채택된 건가? 정말 가치 있다면 Boris는 왜 아직 그 개념을 통합하지 않았을까?
  - NextJS와 경쟁하려고 React 프레임워크 이름을 **ReactJS**로 짓는 것 같음
  - 플러그인으로 제공되는 미리 만들어진 스킬 묶음처럼 보임
  - superpowers가 실제로 작동하나? 메인 스킬 파일은 그다지 신뢰를 주지 않음:  
    “하고 있는 일에 스킬이 적용될 가능성이 1%라도 있다고 생각하면, 그 스킬을 반드시 호출해야 한다”

- 왜 다들 자기 일자리를 없애는 데 그렇게 신나 하는지 모르겠음  
  이런 것들이나 어떤 “스킬”이 정말 그렇게 하지는 않겠지만, 원칙적으로 말임. 이건 **노동으로부터의 소외**가 대규모로 벌어지는 것 같음
  - 우리는 수십 년 동안 예전 일의 큰 부분을 자동화해 왔음. 그렇지 않았다면 모두가 일이 최대한 오래 걸리도록 가장 비효율적인 방식으로 만들려 했을 텐데, 좋은 생각은 아님  
    인류는 추적 가능한 한 언제나 일정한 산출을 내는 데 필요한 노동을 줄여 왔고, 그게 문명임. 쓰는 노동을 극대화하려고 괭이로 손농사를 짓던 시절로 돌아가야 하나? 가로등을 하나씩 켜던 시대로 돌아가야 하나?  
    자동화에서 뒤처지는 사회는 더 가난해지고 결국 죽음. 그곳에서 태어난 사람들조차 생산성이 더 높은 곳으로 떠나기 때문임. 동유럽에도, Amish에게도, 이민이 생기는 가난한 사회 어디서나 일어났음. **더 적은 것으로 더 많이 하는 것**은 늘 흥미로운 일이었음
  - 컴퓨터 프로그래머로서는 이런 생각을 이해하기 어려움. 평생 컴퓨터가 일을 하게 만들어 사람이 더는 하지 않도록 하는 일을 해왔음. 작성된 모든 소프트웨어는 누군가의 일을 없애기 위한 것임  
    만드는 모든 자동화에 대해 이렇게 느끼는지 궁금함. 예전식 시스템 관리자 중에는 인프라 자동화 발전을 이렇게 보는 사람들도 있었고, 예전에는 손으로 하던 일을 스크립트와 시스템이 하게 만드는 걸 싫어했음  
    우리 팀은 한 직장에서 **3만 대 서버**에 패치를 자동으로 실행하고, 시스템을 자동으로 프로덕션에서 빼고 넣는 자동 패치 시스템을 만들었음. 전체 과정이 손이 안 가게 됐고, 예전에는 그 과정을 수동으로 돌리는 전담 팀이 있었음. 자동화로 그들의 일을 빼앗았나?  
    어떤 의미에서는 그렇지만, 해야 할 다른 일이 있었고 이제 그 일을 할 수 있게 됐음  
    프로그래밍, 컴퓨터, 기술을 좋아하는 이유가 바로 우리 대신 일을 해주기 때문임. 내 유토피아는 로봇이 힘든 일을 다 해서 인간이 원하는 것을 할 수 있는 세상임. AI는 그쪽으로 한 걸음 더 가게 해주고 있음. 인간이 원하지도 않는 일을 하며 바쁘게 지낼 만큼 충분한 일거리를 남겨두려 하기보다, 로봇이 일자리를 가져가는 혜택을 부유한 소유자만이 아니라 전 세계가 누리게 할 방법에 집중하고 싶음
  - 보통 일자리를 잃는 사람은 시장에 적응하지 못한 사람임  
    지금은 모든 것이 어느 방향으로 진화하는지 명확하지 않아서, 사람들이 자기 데이터를 무작위 에이전트에 넘겨 보고, 문맥을 저장하고 접근하는 법을 찾고, 프롬프트를 재사용하고, 이 기술을 다루려는 여러 시도를 하는 중임  
    이 중 대부분은 1년 뒤에는 다음 세대 모델에 깊이 통합되어 쓸모없어질 수도 있음. 그래도 발전을 따라가는 일은 이 분야에서 일하는 재미의 일부였음
  - 생존 본능임. 주변의 모두와 모든 것, 직장까지 “AI를 쓰라”고 외치면 반대 입장을 취하거나 주의를 제기하기 어렵다. 신나서라기보다는 파도를 놓치고 **뒤처질까 봐** 그러는 쪽에 가까움  
    장기 데이터가 평균적으로 생산성 향상은 제한적이었고, 고급 최신 모델의 지원이 있어도 품질 좋은 소프트웨어를 만들려면 여전히 세심함과 사람의 주의가 필요하다는 걸 보여주면 찬성 쪽과 반대 쪽 모두 조금 놀랄 것 같음  
    같은 일인데 드라이버 대신 전동 드릴을 갖게 된 것뿐임. 어떤 사람은 수백 년 버티는 집을 짓고, 어떤 사람은 그렇지 못함
  - 좋은 개발자가 아니던 사람들이 갑자기 “정상”까지 가속된 것처럼 느낀 쪽이 가장 적극적으로 보임. 내가 아는 좋은 개발자들은 모두 도입에 좀 더 조심스러웠음

- 요즘 같은 말을 계속 듣고 있음. 개발자 팀을 관리하는 데 좋은 것들이 **LLM 관리**에도 좋다는 것임  
  좋은 테스트 케이스, 명확하고 간결한 문서, CI/CD, 모범 사례와 온보딩 문서가 그렇음  
  LLM을 관리하는 일이 점점 사람 팀을 관리하는 것과 비슷해지고 있음
  - 맞음. 나도 약 1년 전부터 그렇게 말해 왔고, 내부 발표에서도 정확히 이 일화를 썼음
  - 마찬가지로 에이전트식 코딩 성공담은 처음부터 이런 것들을 모두 갖춘 조직에서 나옴

- 이것이 spec-kit보다 무엇이 더 낫거나 다른지 궁금함. 철학이 매우 비슷해 보이고, 같이 쓸 수 있을지도 궁금함. 아니면 그냥 중복일까?  
  [https://github.com/github/spec-kit](<https://github.com/github/spec-kit>)
  - 아무것도 다르지 않음. 코드를 쓸 때 AI를 신중하게 쓸 생각은 없으면서 대량 해고를 불평하는 개발자들을 위한 같은 쓰레기임

- 몇몇 스킬이 이렇게 길어서 놀랐음. 표, 체크박스 목록, 코드 예제 등으로 여러 페이지에 걸쳐 있음  
  이게 얼마나 일반적인지 궁금함. 이런 것 몇 개만 있어도 문맥을 꽤 많이 채울 것 같음
  - 긴 이유는 이런 스킬들이 대부분 **Claude Code**와 **Opus**로 만들어졌고, 제정신인 사람이라면 그 파일들을 읽지도, 그걸 바탕으로 머릿속 모델을 만들지도 않을 것이기 때문임. 이게 작동한다는 가정이 여러 겹 쌓여 있지만, 현실에서는 작동하지 않고 낭비적임  
    재미있는 실험이 있음. LLM에게 막연하게 익숙한 것을 쓰라고 해보면 됨. 예를 들어 “write a fib”라고 요청하면, 거의 모든 LLM은 코드로 미세조정되어 있어서 비프로그래머에게는 “사소한 거짓말을 써라”라는 뜻일 수 있는데도 **피보나치 수열 알고리즘**으로 답함  
    즉 압축이 일어남. 피보나치 수열이 정확히 무엇인지 자세히 설명하지 않고도, 모호한 토큰 3개만으로 결과를 표현할 수 있음  
    그래서 프롬프트 길이는 중요하지 않다는 걸 알 수 있음. 중요한 건 올바른 단어, 빈도, 순서임. 두 페이지짜리 프롬프트와 두 문장짜리 프롬프트가 같은 결과를 낼 수도 있음
  - 빠르게 훑어보니 적어도 몇 개는 스킬이라기보다 좁은 범위의 하위 에이전트를 위한 **시스템 프롬프트**에 가까워 보였음. 오래 지속되는 작업 세션에서 이런 것들을 많이 쓰고 싶지는 않다는 데 동의함  
    지금까지는 짧고 집중된 스킬로 성공적이었음. 재사용 가능한 문맥 조각처럼 다루되 작게 유지함. 예를 들어 내 프로젝트에서 Python을 어떻게 쓰고 단위 테스트를 어떻게 실행하는지에 대한 몇 문단 정도임  
    또한 에이전트에게 지시를 주지는 않고 필요하면 끌어올 수 있는 유용한 문맥 정보만 담은 짧은 “info” 스킬도 여러 개 있음  
    스킬이 너무 많아도 문제가 될 수 있음. 스킬 이름과 설명 목록이 결국 어느 시점에는 문맥에 들어가기 때문임
  - 스킬을 하나도 작성해 보지 않아서 얼마나 일반적인지는 모르겠음. 몇 개의 단어 수를 세어 보니 대략 **2천 단어** 수준이었음. 스킬 5개면 1만 단어 정도임  
    작은 LLM 문맥인 128k에서도 약 10% 정도이고, 큰 모델의 1M 문맥 창에서는 거의 티도 안 남
  - 기본적으로 문맥에는 스킬의 frontmatter, 즉 이름, 설명, 트리거 등만 로드되므로 스킬 수천 개가 있지 않은 한 그런 일은 잘 생기지 않을 것임
  - 내 프로젝트의 스킬 파일 줄 수를 확인해 보니 상위 3개가 805줄, 660줄, 511줄이었음  
    어쩌면 내가 여기서는 너무 보수적인지도 모름. 더 탐색할 게 많음

- “시니어 엔지니어의 일은 대부분 diff에 보이지 않는 부분이다”  
  Agent Skills는 Addy가 그 일까지 없애려는 시도임. 건배, Addy :P