AI 자동화 워크플로를 만들 때 가장 흔한 실수는 처음부터 문서를 쓰는 겁니다. 머릿속에 있는 단계를 그대로 옮기면 그럴듯해 보이지만, 실제로는 자신의 가정을 코드처럼 굳혀버리는 셈입니다.

incident.io의 엔지니어 Lawrence Jones가 Claude Code의 스킬(Skill) 기능으로 매일 아침 AI 비용 분석 리포트를 자동화하는 과정을 공유했습니다. 핵심 메시지는 하나입니다. 스킬은 완성하는 것이 아니라 반복 테스트를 통해 만들어진다는 것. 그리고 그 출발점은 항상 직접 문제를 먼저 푸는 것이어야 한다는 겁니다.

출처: Building AI skills like checklists – Lawrence Jones 블로그

Claude Code 스킬이란

Claude Code의 스킬은 에이전트가 읽고 실행하는 마크다운 파일입니다. 팀원이 반복 업무를 설명하기 위해 쓰는 런북(runbook)과 같지만, 독자가 사람이 아니라 에이전트라는 점이 다릅니다. 사람은 막혔을 때 문서를 꺼내 참고하지만, 에이전트는 매번 실행 전에 처음부터 끝까지 읽습니다.

이 차이가 중요합니다. 사람이 읽는 문서는 맥락이 일부 빠져 있어도 읽는 사람이 채워넣을 수 있습니다. 에이전트는 그럴 수 없습니다. 쓰여진 것만 실행합니다.

왜 첫 초안은 실패하는가

스킬을 처음 쓸 때 우리는 자신이 기억하는 단계를 적습니다. 하지만 기억하는 단계와 에이전트에게 알려줘야 하는 단계는 다릅니다.

Jones는 이를 Atul Gawande의 『체크리스트 선언문』에 빗대어 설명합니다. 수술실과 항공에서 쓰이는 체크리스트는 처음 쓰고 나서 완성된 게 아닙니다. WHO 외과 안전 체크리스트는 수십 차례의 실제 수술실 테스트를 거쳤습니다. 실제로 써보면서 불필요한 항목을 빼고, 첫 초안에는 없었던 실제 실패 원인을 새로 추가했습니다. 가치의 대부분은 반복 과정에서 나왔습니다.

AI 스킬도 마찬가지입니다. 처음 쓴 초안은 당신이 이미 알고 있는 것, 즉 사전 가정을 반영합니다. 그 가정이 틀렸을 때 스킬은 그럴듯해 보이지만 잘못된 결과를 냅니다.

먼저 직접 풀어라

Jones가 비용 리포트 스킬을 만들 때 처음 몇 시간은 스킬 초안을 쓰지 않았습니다. Claude에게 전날 지출 데이터를 분석해달라고 요청하고, 결과를 보며 질문을 이어갔습니다.

이 과정에서 처음엔 몰랐던 문제들이 드러났습니다. 코드 가이던스 생성이 backfill로 잘못 분류되어 있었고, turn_phase 컬럼은 아예 연결이 안 되어 있었으며, 비용 분포가 이중 피크를 보이고 있었는데 그 안에 실제 신호가 숨어 있었습니다. 이것들은 처음부터 스킬을 썼다면 그대로 굳어버렸을 잘못된 가정들입니다.

신뢰할 수 있는 분석 결과를 얻은 뒤에야 스킬 초안 작성을 시작했습니다. 스킬의 핵심 원칙도 이 과정에서 나왔습니다. “이상 징후를 발견하면 반드시 원인을 파고들고 나서 리포트하라.”

컨텍스트 없는 에이전트로 드라이런

초안을 쓴 다음에는 서브에이전트(sub-agent)로 테스트합니다. 이를 드라이런(dry-run)이라고 부릅니다. 서브에이전트를 시작하면 이전 대화 컨텍스트가 초기화되기 때문입니다. 서브에이전트는 스킬 파일에 적힌 것만 갖고 실행합니다.

머릿속 컨텍스트에 의존하던 단계가 있다면, 서브에이전트는 그 지점에서 실패합니다. 그 실패가 정확히 스킬에 써야 할 내용입니다.

테스트 결과는 세 카테고리로 받습니다.

1. 모호한 것 — 두 가지로 해석될 수 있는 부분
2. 잘못된 것 — 쿼리 오류, 경로 불일치 등 실제 실패
3. 개선 가능한 것 — 더 나은 결과를 낼 수 있었던 부분

첫 드라이런에서는 세 카테고리 모두에서 피드백이 나오고, 두 번째도 보통 마찬가지입니다. Jones의 비용 리포트 스킬에는 이 과정을 거치며 추가된 규칙들이 있습니다. 컬럼명에 반드시 테이블 별칭을 붙일 것(한 번 애매한 컬럼 오류가 병렬 쿼리 전체를 취소시킨 뒤), 런북에 없는 쿼리를 새로 만들지 말 것 같은 것들입니다.

드라이런은 출시 전 한 번 하는 검수가 아닙니다. 팀원이 매일 아침 스킬을 실행하고, 더 잘할 수 있는 부분을 발견하면 스킬을 수정하고, 다음 날 실행 전에 드라이런을 돌립니다. 몇 달 동안 수정되지 않은 스킬은 쓰이고 있지 않거나, 조용히 나빠지고 있을 가능성이 높다고 그는 말합니다.

문서가 실행 코드가 된 시대

스킬 작성이 흥미로운 건 마크다운 문서의 성격이 달라졌기 때문입니다. 예전의 런북은 막혔을 때 꺼내보는 정적인 참고 문서였습니다. 이제는 매번 처음부터 읽히고 그대로 실행되는 코드에 가깝습니다. 모호함이나 빠진 가정이 버그가 됩니다.

이 변화는 문서를 더 가치 있게 만들지만, 잘 쓰기도 더 어렵게 만듭니다. 『체크리스트 선언문』의 교훈이 AI 워크플로에 그대로 이식되는 이유입니다. 처음 완성하는 것이 아니라, 실제로 써보며 틀린 부분을 고쳐나가는 것이 만드는 방식입니다. 스킬 파일을 어떻게 구조화하고 참조 문서를 분리하는지, 에이전트가 드라이런을 자율 반복하게 하는 방법도 원문에서 다룹니다.