AI 코딩 에이전트용 스킬을 만들어 본 개발자라면 "이 정도는 알아서 하겠지"라며 수십 줄을 채워본 경험이 있을 것입니다. 그런데 그 안내가 정말 효과가 있는지 확인해본 적은 드물죠. Microsoft의 SharePoint Framework(SPFX) 팀은 자기들이 만든 스킬이 정말 효과가 있는지 의심했고, 그 답을 숫자로 확인하는 전 과정을 공개했습니다. 오늘은 그 과정을 단계별로 살펴보겠습니다.
핵심 개념부터 짚고 갑니다. 스킬(skill)은 AI 코딩 에이전트에게 절차, 규칙, 맥락을 주입하는 안내서입니다. 에이전트가 필요할 때 읽고 따라 하는 문서죠. 기준선(baseline)은 개선 도구를 아무것도 적용하지 않은 상태의 성능입니다. 측정은 언제나 여기서부터 시작됩니다. 그리고 한 가지 중요한 전제가 있습니다. LLM은 비결정적이라 한 번 실행으로는 실력을 알 수 없습니다. 그래서 같은 시나리오를 5회 반복해서 평균을 봐야 합니다.
1단계. 정답을 채점표로 만든다
"올바른 SPFx 업그레이드"가 무엇인지 감이 아닌 체크리스트로 정의했습니다. 4개 분류, 총 150항목입니다. Prerequisite 5항목, Idiomatic use 10항목, Dependency currency(의존성 최신화) 50항목, Configuration correctness(설정 정확성) 85항목. CLI for Microsoft 365 팀이 수년간 축적한 버전별 업그레이드 로직이 채점 기준이 됐습니다. 사람이 매번 자의적으로 판단하는 대신 결정론적으로 채점할 수 있게 만든 거죠.
이 단계가 끝나면 "잘됐다/아니다"가 아니라 34/50 같은 숫자로 상태를 말할 수 있습니다.
2단계. 스킬 없이 기준선을 잡는다
프롬프트는 "Upgrade the project to 1.22.2" 딱 한 줄이었습니다. SPFx라고도 말하지 않았고 문서 위치도 알려주지 않았습니다. 5회 반복 결과는 흥미로웠습니다. 5회 전부 빌드와 실행에 성공했고, 겉보기엔 완벽한 성공이었습니다.
그런데 150항목으로 쪼개보니 의존성은 34/50, 설정은 38/85였습니다. 빌드는 되지만 부분 업그레이드 상태인 프로젝트였던 겁니다. 빌드 성공만 봤다면 이 문제를 영영 못 알아챘 겁니다.
이 단계가 끝나면 에이전트가 무엇을 이미 알고 무엇을 모르는지 목록이 나옵니다.
3단계. 행동을 추적해 실패 원인을 규명한다
숫자만으로는 뭘 고쳐야 할지 모릅니다. 그래서 에이전트의 도구 호출, 문서 읽기, 결정 순서 전체를 추적했습니다. 나온 발견은 이렇습니다.
- 파일 트리만 보고도 SPFx 프로젝트임을 인식했다. 릴리스 노트 URL을 검색 없이 패턴으로 직접 조합했다. 일반 지식은 풍부합니다.
- 1.22.2로의 업그레이드인데 중간 릴리스(1.22.1) 노트를 읽지 않았다. 지식을 결합하는 능력이 약점입니다.
- 계획을 먼저 세운 뒤 문서를 읽어 자기 계획을 확인하는 용도로만 사용했다.
- CLI 도구 팁을 봐도 무시했다. 상세한 수동 마이그레이션 단계가 있으면 그쪽을 고른다.
이 단계가 끝나면 스킬이 채워야 할 진짜 빈 곳이 보입니다.
여기서 가장 중요한 통찰이 하나 나옵니다. 에이전트는 "문서를 읽고 계획을 세우는" 존재가 아니라 "계획을 먼저 세우고 문서를 읽어 자기 계획을 확인하는" 존재라는 것입니다. 이 행동 특성 때문에 아무리 좋은 팁을 문서에 넣어도 에이전트는 자기 계획과 일치하는 내용만 골라 읽고, 계획에 도전하는 문장이 아니면 무시합니다. 스킬을 만들 때 "설명을 잘 쓰면 따르겠지"라는 가정이 무너지는 지점이 바로 여기입니다.
4단계. 가설을 하나씩 테스트한다
이제 가설 하나당 반영 후 재측정하는 루프를 돌립니다.
- 가설 1: 환각 방지 스킬(공식 문서 검증 강제)을 추가한다 → 설정 38/85에서 46/85로, 토큰은 약 9% 절감. 개선은 있지만 여전히 부분 업그레이드 수준. 기각.
- 가설 2: 문서 소스를 더 추가한다(context7 MCP) → 설정 47/85. 미미한 향상. 5회 중 3회는 도구가 있어도 호출하지도 않았다. 도구가 "있다"는 것만으로는 안 됨. 기각.
- 가설 3: 정답 도구(CLI for Microsoft 365의 spfx project upgrade)를 명시적으로 쓰게 한다 → 의존성 34/50에서 50/50, 설정 38/85에서 83/85. 강력한 효과. 채택.
이 단계가 끝나면 어떤 개선이 실제 효과가 있는지 숫자로 구분됩니다.
5단계. 문서 자체를 바꿔가며 실험한다
여기가 이 이야기에서 가장 흥미로운 부분입니다. SPFx 팀은 게시 전 문서 수정을 Dev Proxy로 시뮬레이션해서 테스트했습니다.
- 팁 위치를 옮겼다 → 효과 없음.
- 상세한 수동 마이그레이션 가이드를 삭제했다 → CLI 채택이 0/5에서 5/5로 급등. 하지만 수동 업그레이드를 하던 사람들에게 피해를 준다. 기각.
- 팁 앞에 경고문을 추가했다. "이전 마이너 버전에서의 업그레이드는 패키지, 빌드 설정, 툴체인 전반의 변경이 필요하며, package.json만 수동으로 고치면 빌드 실패한다" → 에이전트가 이미 세운 계획에 정면으로 도전하는 문장이라 효과적이었다. 단, 가이드를 복원하면 다시 0/5로 떨어졌다.
- 최종 해법: 가이드를 "무엇이 바뀌는지 개념 설명 + 적용은 CLI로" 방식으로 재작성했다 → CLI 채택 5/5, 설정 정확성 85/85.
검증된 변경은 그대로 Microsoft Learn에 PR로 반영됐습니다(#10855, #10921). 이제 스킬 없는 개발자와 에이전트도 혜택을 봅니다.
이 단계가 끝나면 문서 한 문장이 에이전트 행동을 바꾼다는 게 숫자로 증명됩니다.
6단계. 측정 결과만 스킬에 남긴다
최종 스킬인 SPFx Dev Skills는 긴 설명서가 아니라 결정 규칙의 집합입니다.
- 버전 감지 → Node/TypeScript 호환성 확인 → CLI로 변경사항 적용 → 클린 빌드로 마무리
- 테스트에서 토큰을 낭비하던 행동(의존성 설치를 터미널 폴링으로 기다리기)에 대한 규칙: 설치는 동기 실행
이 단계가 끝나면 스킬의 모든 문장이 "측정에서 나온 이유"를 가지게 됩니다.
보안/주의
- 에이전트 출력은 검증 후 커밋/배포할 것 (원문도 강조)
- 도구가 "있다"는 것만으로 호출된다는 보장 없음. 워크플로에 명시적으로 연결할 것
- 빌드 성공을 성공의 증거로 쓰지 말 것. 세부 항목 채점이 필요
트러블슈팅
1. 스킬을 넣었는데 효과가 없다 → 기준선부터 측정했는지 확인. 기준선 없이는 개선 여부 자체를 알 수 없음
2. 에이전트가 스킬의 도구를 무시한다 → 팁은 "대안"일 뿐. "네 현재 방식은 틀렸다"는 경고문 형태여야 계획이 바뀜
3. 도구를 호출하지 않는다 → 가용성과 관련성은 별개. 계획 세우기 전에 도구 선택 규칙이 보여야 함
4. 문서를 고치면 사람이 피해를 본다 → 개념 설명 + 도구 안내로 재작성. 삭제가 아니라 재구성
5. 한 번 성공했다고 끝이 아니다 → LLM 비결정성 때문에 5회 반복 측정이 기본
마무리
스킬은 에이전트가 이미 아는 것을 반복하는 곳이 아니라, 일반 지식이 신뢰 불가한 지점의 결정 규칙을 담는 곳입니다. 그 지점을 찾으려면 기준선 측정, 행동 추적, 가설 검증의 루프가 필요합니다. 직감으로 만든 스킬은 토큰만 먹는다고 기억하시면 됩니다.
이 방법론은 SPFx가 아니어도 적용됩니다. 자기 스킬이나 규칙 파일에 정답 채점표를 만들고 5회 돌려보는 것부터 시작할 수 있습니다.
0 댓글