최정우

Copilot Technical Specialist

AI 에이전트에게 SPFx 업그레이드를 맡겨도 될까? 증거로 답한 SPFx Dev Skills 개발기

AI 코딩 에이전트는 SharePoint Framework 솔루션을 만들 수 있습니다. 그런데 툴체인과 패키지 버전을 스스로 고르고, 모든 업그레이드 단계를 정확히 적용하는 것까지 믿어도 될까요?

Microsoft 365 Developer Blog의 이번 글은 이 질문에 증거로 답합니다. SPFx Dev Skills를 공개하기 전, SharePoint Framework 팀과 Developer Relations가 함께 에이전트가 이미 아는 것과 어려워하는 것을 파악하고, 어떤 안내가 결과를 개선하는지 측정했습니다.

원문의 문제의식이 인상적입니다.

우리의 전문성을 스킬로 포장해서 개발자에게 “믿고 쓰세요” 라고 말하는 건 쉽습니다. 스킬이 어디서 가치를 더하는지 증명하는 일은 더 많은 노력이 들지만, 훨씬 유용한 결과를 냅니다.

스킬 없이 시작했다

참여자와 접근

OneDrive·SharePoint SPFx 팀의 Vesa Juvonen, Bert Jansen, Developer Relations의 Garry Trinder, Waldek Mastykarz가 함께했습니다. 올바른 업그레이드가 어떤 모습이어야 하는지 정의하고, 평가를 설계하고, 에이전트의 전체 행동 시퀀스를 추적해 실패 원인을 짚었습니다.

평가는 CLI for Microsoft 365 메인테이너들의 수년간 작업 위에 세워졌습니다. 이들은 spfx project upgrade 명령에 결정론적이고 버전별로 정확한 SPFx 업그레이드를 인코딩해 두었습니다.

첫 번째 시나리오

SPFx 1.21.1 → 1.22.2 업그레이드입니다. 단순 패키지 버전 변경으로 끝나지 않습니다. SPFx 1.22에서 gulp → Heft로 전환되면서 구성과 프로젝트 구조가 함께 바뀌었기 때문입니다.

Windows의 Visual Studio Code에서 GitHub Copilot Chat + Claude Sonnet 4.6에게 이렇게만 요청했습니다.

Upgrade the project to 1.22.2

의도적으로 SPFx를 언급하지 않았고, 문서를 가리키지도 않았으며, 스킬 없이 실행했습니다. 이것이 기준선입니다 — 프로젝트 맥락과 기존 지식만으로 에이전트가 무엇을 할 수 있는가.

언어 모델은 비결정론적이므로 같은 시나리오를 5회 반복했습니다.

기준선 결과

분류 통과 전체
전제 조건(Prerequisite) 5 5
관용적 사용(Idiomatic use) 7 10
의존성 최신성(Dependency currency) 34 50
구성 정확성(Configuration correctness) 38 85

모든 실행이 실행 게이트를 통과했습니다. 프로젝트가 빌드되고 동작했다는 뜻이죠. 언뜻 성공처럼 보입니다.

하지만 자세히 보면 에이전트는 대표 SPFx 버전만 올리고 의존성과 마이그레이션 세부사항을 놓쳤습니다. 구성 정확성이 85점 만점에 38점입니다.

기준선을 먼저 잡은 덕분에, 에이전트가 이미 아는 지식을 반복하면서 정작 개발자에게 영향을 주는 문제는 놓치는 큰 스킬을 쓰는 일을 피할 수 있었습니다.

Copilot은 이미 SPFx를 꽤 알고 있었다

평가에서 드러난 에이전트의 강점입니다.

  • 도구를 호출하기도 전에 파일 트리만 보고 SPFx 프로젝트임을 인식했습니다
  • Microsoft 패키지를 업데이트해야 한다는 것과 TypeScript 툴체인 변경을 예상했습니다
  • 릴리스 노트가 필요할 때 검색하지 않고 Microsoft Learn URL을 직접 구성했습니다. 수년간의 SPFx 릴리스에서 확립된 URL 패턴을 따른 것입니다

약점은 그 지식을 찾아낸 정보와 결합하는 부분이었습니다.

구체적인 실패 패턴

1. 중간 릴리스를 건너뜀

1.22.2로 업그레이드하라는 요청에 1.22 릴리스 노트만 가져왔습니다. 요청한 버전과 문서 버전이 다르다는 것은 알아챘지만 중간 릴리스 페이지를 모두 가져오지는 않았습니다.

SPFx 업그레이드는 증분(incremental) 이라 1.22.0과 1.22.1의 변경 사항도 여전히 중요한데도요.

2. 문서를 읽기 전에 계획을 세움

에이전트는 문서를 읽기 전에 계획을 먼저 형성하고, 그다음 문서로 계획을 확인했습니다. CLI for Microsoft 365를 권하는 팁이 있었지만 접근 방식을 바꾸지 못했습니다. 같은 페이지에 실행 가능해 보이는 상세 수동 마이그레이션 단계가 함께 있었기 때문입니다.

에이전트가 이미 SPFx를 인식하고 문서를 찾을 수 있다면, 스킬은 무엇을 더해야 할까요? 일반 지식이 신뢰할 수 없는 지점에 대한 정밀한 결정 규칙입니다.

뻔한 답을 먼저 시험했다

SPFx 팀은 이미 환각 방지(anti-hallucination) 스킬을 별도로 만들어 두었습니다. 권위 있는 문서로 SPFx 사실을 검증하도록 지시하는 스킬입니다. 여기에 context7 MCP 서버를 추가해 다른 문서 소스가 도움이 되는지도 봤습니다.

분류 기준선 + 환각 방지 스킬 + 환각 방지 스킬 & context7
전제 조건 5 / 5 5 / 5 5 / 5
관용적 사용 7 / 10 10 / 10 8 / 10
의존성 최신성 34 / 50 40 / 50 39 / 50
구성 정확성 38 / 85 46 / 85 47 / 85

환각 방지 스킬은 결과를 개선했고 평균 토큰 사용량도 약 9% 줄였습니다. 하지만 권위 있는 문서로 안내하는 것만으로는 프로젝트가 여전히 부분적으로만 업그레이드됐습니다.

context7은 의미 있는 추가 향상을 주지 못했습니다. 5회 중 3회에서 도구가 사용 가능했지만 한 번도 호출되지 않았습니다.

가용성만으로는 도구가 에이전트의 계획에 관련성을 갖게 되지 않습니다.

원문은 여기서 멈추지 않은 이유를 이렇게 밝힙니다. 환각 방지 스킬을 답으로 삼는 것은 “믿고 쓰세요”의 에이전트 개발 버전이었을 것이라고요.

최고의 업그레이드 안내는 이미 존재했다

CLI for Microsoft 365의 spfx project upgrade 명령은 소스와 대상 버전을 분석해 증분 업그레이드에 필요한 버전별 변경 사항을 생성합니다.

에이전트에게 명시적으로 CLI를 쓰라고 했을 때의 결과입니다.

분류 기준선 + CLI for Microsoft 365
전제 조건 5 / 5 5 / 5
관용적 사용 7 / 10 4 / 10
의존성 최신성 34 / 50 50 / 50
구성 정확성 38 / 85 83 / 85

의존성 최신성 34→50(만점), 구성 정확성 38→83. 압도적입니다.

기존 제품 도구가 가장 강력한 결과를 냈습니다. 이미 업그레이드 로직을 인코딩하고 있었기 때문입니다.

문제는 에이전트가 스스로 그것을 발견하지 못했다는 점입니다. 그래서 SPFx Dev Skills는 업그레이드가 필요할 때 에이전트를 CLI로 안내하는 데 초점을 맞추게 됩니다.

문서 한 문장이 에이전트의 계획을 바꿨다

여기서부터가 이 글의 백미입니다.

SPFx 릴리스 노트에는 이미 CLI for Microsoft 365에 대한 팁이 있었습니다. 정확한 명령어를 추가해도 에이전트는 계속 수동 계획을 밀고 나갔습니다.

왜 팁은 안 통했나

팁은 대안을 제시할 뿐, 에이전트에게 현재 접근이 틀렸다고 말하지 않기 때문입니다.

반면 링크된 마이그레이션 가이드에는 npm 명령과 JSON 스니펫으로 뒷받침된 상세한 수동 단계가 있었습니다. 에이전트는 일관되게 그 실행 가능한 콘텐츠를 선택했습니다.

Dev Proxy로 검증

팀은 Dev Proxy를 사용해 검증되지 않은 아이디어를 Microsoft Learn에 게시하지 않고 문서 변경을 테스트했습니다.

실패한 시도들:

  • 팁의 위치를 옮기는 것 → 차이 없음
  • 마이그레이션 가이드를 제거 → 수동 실행 품질만 떨어지고 CLI 채택은 안정적으로 늘지 않음

통한 것: 계획에 정면으로 도전하는 경고

팁 바로 앞에 경고를 추가했습니다.

이전 마이너 버전에서 업그레이드하려면 패키지 버전, 빌드 구성 파일, 툴체인 설정에 걸친 변경이 필요하며, 이는 소스 버전에 따라 달라집니다. package.json만 수동으로 업데이트하면 빌드가 실패합니다.

상세 마이그레이션 링크를 제거한 상태에서 CLI 채택률이 0/5 → 5/5로 바뀌었습니다.

경고가 통한 이유는 에이전트가 이미 형성한 계획에 도전했기 때문입니다.

사람도 배려해야 한다

하지만 사람 독자에게 유용한 안내를 그냥 없앨 수는 없었습니다. 단계별 마이그레이션 가이드를 복원하자 CLI 채택이 다시 0/5로 떨어졌습니다.

해결책은 가이드를 다시 쓰는 것이었습니다. gulp→Heft 마이그레이션에서 무엇이 바뀌는지 설명하되, 그 변경을 적용하려면 CLI for Microsoft 365를 쓰도록 안내하는 개념적 가이드로요.

결과: CLI 사용 5/5, 구성 정확성 85/85 만점.

문서에 반영

이 개선 사항은 SPFx 문서에 제출됐습니다.

  • PR #10855 — 릴리스 노트 버전 변경
  • PR #10921 — 경고와 재작성된 마이그레이션 가이드

수정 사항을 소스에 두었기 때문에 SPFx Dev Skills가 없는 개발자와 에이전트를 포함해 모두에게 적용됩니다.

평가가 SPFx Dev Skills를 만들었다

SPFx Dev Skills 미리 보기는 SPFx 관련 결정 규칙을 하나의 집중된 spfx 스킬로 패키징하고, 각 요청을 자체 완결적인 플레이북으로 라우팅합니다.

현재 다루는 영역

  • SPFx 웹 파트, 확장, 라이브러리, Adaptive Card Extensions 생성
  • CLI for Microsoft 365로 프로젝트 업그레이드
  • SPFx 1.22.0 이상은 Heft, 이전 버전은 gulp 선택
  • Fluent UI v9로 React 인터페이스 구축
  • PnPjs로 SharePoint·Microsoft Graph 데이터 접근

업그레이드 안내에 반영된 관찰

평가에서 관찰한 내용이 그대로 규칙이 됐습니다.

  • 행동 전에 설치된 버전을 감지하고 Node·TypeScript 호환성을 확인하도록 지시
  • CLI for Microsoft 365로 생성된 모든 변경을 순서대로 적용
  • 깨끗한 빌드로 마무리해야 함
  • 전역 안내에서 긴 SPFx 의존성 설치는 동기적으로 실행하도록 지시 — 테스트 중 시간과 토큰을 소모하던 반복적인 터미널 폴링을 방지

스킬은 문서와 CLI를 대체하지 않고 보완합니다. 에이전트가 올바른 소스를 선택하고 제대로 사용하도록 돕습니다.

협업이 스킬 이상을 개선했다

조사 과정에서 SPFx를 넘어서는 기회도 발견됐습니다.

Microsoft Learn이 페이지를 Markdown으로 직접 반환할 수 있다는 점입니다. 전체 HTML 페이지를 변환하는 것보다 에이전트에게 더 깨끗한 콘텐츠를 줍니다.

이 발견을 GitHub Copilot 팀과 공유했고, 그 결과 GitHub Copilot Chat과 GitHub Copilot CLI에 Accept: text/markdown 지원이 추가됐습니다.

에이전트 경험 문제는 스킬 밖에서 비롯될 수 있습니다. 이 사례에서 일부 수정은 문서나 CLI에 속했고, 또 하나는 콘텐츠를 가져오는 플랫폼에 있었습니다. 기준선을 확립한 덕분에 어디서 작업해야 할지 알 수 있었습니다.

한국 개발자·팀 리더를 위한 시사점

이 글은 SPFx 이야기이지만, AI 에이전트를 사내 개발에 도입하려는 모든 팀에게 적용되는 방법론을 담고 있습니다.

  • 기준선 없이 스킬부터 만들지 마세요: 에이전트가 이미 아는 것을 반복하는 문서를 쓰면서 정작 실패 지점은 놓치기 쉽습니다. 먼저 측정하세요.
  • “빌드가 되는가”는 충분한 기준이 아닙니다: 5회 모두 빌드에 성공했지만 구성 정확성은 38/85였습니다. 부분 성공과 올바른 결과를 구분하는 평가 항목을 설계해야 합니다.
  • 비결정론성을 감안한 반복 실행: 같은 시나리오를 5회 반복했습니다. 한 번 잘 됐다고 해결된 것이 아닙니다.
  • 기존 도구가 최고의 답일 수 있습니다: 새 스킬을 쓰는 것보다 이미 로직이 인코딩된 CLI로 안내하는 것이 훨씬 효과적이었습니다. 사내에도 이미 검증된 스크립트나 CLI가 있다면, 스킬의 역할은 그것을 쓰게 만드는 것일 수 있습니다.
  • 문서 문구가 에이전트 행동을 바꿉니다: “이런 방법도 있습니다”(팁)와 “이렇게 하면 실패합니다”(경고) 는 전혀 다른 효과를 냅니다. 사내 개발 문서를 에이전트가 읽는다면 이 차이를 고려하세요.
  • 사람과 에이전트를 함께 배려: 에이전트를 위해 유용한 문서를 없애는 것은 답이 아니었습니다. 개념 설명은 남기되 실행은 도구로 안내하는 재작성이 해답이었습니다.
  • 가용성 ≠ 사용: context7 도구가 있어도 5회 중 3회는 호출조차 되지 않았습니다. 도구를 붙이는 것과 에이전트가 쓰게 만드는 것은 다른 문제입니다.

마무리

SPFx Dev Skills는 현재 미리 보기입니다. 생성·디자인 플레이북과 툴체인·데이터 플레이북은 이번 평가 범위를 넘어서며, 팀은 실제 사용을 통해 계속 검증할 예정입니다. 원문도 개발자가 커밋하거나 배포하기 전에 출력을 검토해야 한다고 명시합니다.

GitHub의 SPFx Dev Skills에서 포터블 spfx 스킬과 작업별 참조, 호환 AI 코딩 에이전트용 수동 설치 안내를 확인할 수 있습니다. 결과가 잘못되거나 예상 밖이면 이슈를 등록해 달라고 합니다. 그 증거가 스킬이 다음에 무엇을 가르쳐야 할지, 그리고 다른 어디를 고쳐야 할지를 결정하는 데 쓰입니다.

“믿고 쓰세요” 대신 숫자로 답한 개발기입니다. 사내에서 에이전트 스킬을 만들려는 팀이라면 방법론 자체를 참고할 만합니다.

출처

자세한 내용은 원문을 참조하세요.

You May Also Enjoy