Guide · Workshop Migration & Standardization

워크샵 Azure-Samples 이관·표준화 가이드

먼저 워크샵 표준화 skill을 설치한 뒤 기존 저장소에서 이관·표준화를 시작하세요. 결정 시트를 미리 작성하거나 표준 규격을 전부 읽을 필요는 없습니다. skill을 사용하는 AI가 이관 초안을 만들면 저자가 확인하고, 변환 결과를 검토한 뒤 실습을 검증합니다.

안내 수정일 2026-10-07 · 규격 기준일 2026-09-16 · 근거: 표준화 제안과 상세 규격 부록 A~D

시작 · skill 설치

준비물은 기존 GitHub 저장소의 접근 권한과 Agent Skills를 지원하는 AI 코딩 에이전트입니다. workshop-standardization skill을 설치하면 이관에 필요한 지침과 참고 문서·템플릿을 함께 사용할 수 있습니다.

skill 설치와 사용 표준 적용 예시 보기 이후 할 일 확인

skill 설치. 설치 가이드에서 사용할 에이전트와 개인용·프로젝트용 범위를 선택합니다. CLI 설치를 권장하며, Node.js·npm이 없는 환경에서는 ZIP 수동 설치를 사용합니다.

작업 폴더와 설치 확인. 기존 저장소를 로컬에 클론해 에이전트에서 엽니다. 프로젝트용 skill은 이 폴더에 설치하고, 새 채팅에서 workshop-standardization이 인식되는지 확인합니다.

skill로 이관·표준화 시작. 에이전트에 skill 이름과 작업 목적을 전달합니다. skill은 먼저 저장소를 분석해 결정 시트 초안을 제시하고 사용자 확인을 기다립니다. 구체적인 사용 방법은 설치 가이드를 따릅니다.

첫 작업은 분석만 진행합니다. 파일 수정·삭제, 검사 도구 설치와 실제 변환은 이관 방침과 작업 범위를 확인한 다음 승인합니다. 원격 push와 공개 전환은 별도 승인 단계입니다.

첫 단계 완료 기준 권고안과 확인할 항목을 받으면 분석 단계가 끝납니다. 아직 파일을 바꾸거나 새 저장소에 게시하지 않습니다. 전체 이관 완료가 아니라, 다음 결정을 위한 초안입니다.

저자가 할 일 · 세 단계

설치한 skill로 분석을 시작한 뒤에는 아래 순서로 진행합니다. 새 워크샵을 만드는 경우에도 같은 skill을 사용하며, 먼저 생성 계획을 확인하고 승인한 범위만 진행합니다.

저자는 판단과 검토, 실습 검증을 맡고 반복 변환과 자동 검사는 AI에 맡깁니다. 등록·심사·등재 절차가 익숙하지 않다면 게시 전에 공동 오너나 팀 카탈로그 담당자에게 함께 확인해 달라고 요청하세요. 게시 권한과 최종 승인은 별도로 확인해야 합니다.

분석 초안 확인. 저장소 주소, 이관 범위와 콘텐츠 유형을 확인합니다. 제외 파일, 이력 처리와 라이선스는 근거를 검토해 확정합니다. 모르는 항목은 확인 필요로 남기고, 삭제나 이력 변경을 먼저 승인하지 않습니다.

변환 요청과 결과 검토. 확정한 초안을 전달하고 skill에 포함된 지침에 따라 변환을 요청합니다. 보안 점검 이후 승인한 범위만 변환하게 합니다. 단계별 변경 요약과 로컬 diff, 자동 검사 9종의 통과 증빙을 확인하고 소요 시간·정리 절차 등 TODO를 채웁니다.

실습 검증과 공개 확인. Private 저장소에 게시한 뒤 Codespaces에서 실습을 처음부터 끝까지 완주합니다. 포털형은 실제 포털에서 검증합니다. 검증일을 기록하고 심사 승인을 확인한 뒤 공개·등재합니다. 상세 설정은 전체 절차와 게시 안내에서 확인합니다.

skill에 포함된 참고 자료

설치용 배포 ZIP에는 아래 지시문과 참고 문서가 포함되어 있어 별도로 복사하거나 첨부할 필요가 없습니다. 아래 링크는 저자가 원문을 확인할 때 사용합니다. 에이전트가 설치된 참고 자료를 찾지 못하면 변환을 멈추고 설치 상태를 확인하세요.

AI가 수행할 작업

AI 변환 지시문

확정한 초안을 입력값으로 전달합니다. 보안 점검, 변환 순서와 자동 검사 명령이 들어 있습니다.

확인·수정할 초안

결정 시트 양식

AI 권고안을 이 양식에 맞춰 확정합니다. 직접 작성은 선택이며, 실제 작성본은 로컬 전용 경로에 보관합니다.

규칙과 예외

표준 규격 · 상세 이관 가이드

skill이 참고하는 규칙과 절차입니다. 저자는 판단이 필요한 규칙과 단계별 예외를 찾아봅니다.

중단 조건 보안 점검에서 실제 노출이 발견되면 AI는 멈춰서 보고합니다. 저자가 결과와 이력 처리 방침을 확인하기 전에는 변환을 계속하거나 원격 push를 하지 않습니다.

전체 절차 · 게시 안내

세 단계 안내에 대응하는 상세 절차입니다. 분석과 결정은 Phase 0~1, 보안 점검·변환·리뷰는 Phase 2~5, 게시·실행 검증·공개는 Phase 6입니다. Phase 0~5는 로컬에서 진행하며 원격 push는 하지 않습니다.

flowchart LR
  P0["0 사전 결정
(선택)"] --> P1["1 AI 실행·
결정 확정"] --> P2["2 보안 점검"] --> P3["3 이관 준비
(로컬)"] --> P4["4 표준 적용
(AI 수행)"] --> P5["5 검증·리뷰"] --> P6["6 게시·등재"]
  style P2 fill:#0078D4,color:#fff,stroke:#0078D4
  style P4 fill:#0078D4,color:#fff,stroke:#0078D4

Phase 0 · 사전 결정 (선택). 이관 범위와 처리 방침을 결정 시트에 미리 기록합니다. 생략하면 Phase 1에서 에이전트의 권고안을 검토해 확정할 수 있습니다.

Phase 1 · AI 실행과 결정 확정. 저자가 결정 시트를 확정합니다. 시트가 없으면 AI가 리포를 분석해 전체 항목의 권고값과 근거를 제시합니다.

Phase 2 · 보안 점검. AI가 커밋 이력 전체에서 시크릿, 개인 리소스 식별자, 노트북 출력을 스캔하고 저자가 결과를 판정합니다. 이 검사는 생략할 수 없습니다.

Phase 3 · 콘텐츠 이관 준비 (로컬). 확정한 이력 보존·스쿼시·서브폴더 추출 방침에 따라 AI가 새 리포를 준비합니다. 아직 원격 push는 하지 않습니다.

Phase 4 · 표준 적용. AI가 경로, 문서와 랩 구조, 노트북, 실행 환경, 거버넌스 파일에 표준을 적용합니다.

Phase 5 · 검증과 리뷰. 하네스 9종을 모두 통과했는지 확인합니다. 저자는 변경 요약과 로컬 diff를 검토하고 남은 TODO를 채웁니다.

Phase 6 · 게시와 등재. Microsoft Open Source Management 포털에 리포를 등록합니다.

필수 규칙 보안 점검에서 시크릿이나 개인 식별자가 커밋 이력에서 발견되면, 저자가 선택한 방침과 관계없이 이력을 스쿼시해야 합니다. HEAD에서 지워도 이력에는 남기 때문입니다.

Private 게시부터 공개까지

리포 이름은 <product>-<topic>-workshop-kr 형식입니다. Microsoft Open Source Management 포털에서 공개 범위는 Private, 분류는 Non-Production으로 설정합니다. Direct Owners는 개인 2명을 지정하고 오픈소스 심사는 Yes를 선택합니다. 리포 생성과 생성 직후 점검을 마친 뒤 저자가 직접 push합니다.

사람이 실습을 완주한 날을 validated_on에 기록합니다. 실행 검증과 심사 승인을 확인한 뒤 포털의 Publicize로 공개 전환합니다. 이어서 허브 카탈로그에 등재하고, 기존 리포의 README를 새 주소 안내로 바꾼 뒤 Archive 처리합니다. 검증과 공개 전환, 등재와 정리에 세부 절차가 있습니다.

핵심 규칙

변환 중 자주 확인하는 규칙입니다. 규격은 표준 문서, 적용 절차와 예외 조건은 상세 이관 가이드를 참고합니다.

history

보존/스쿼시는 저자 선택

기본은 리포별 저자 선택입니다. 단, 보안 점검에서 이력 노출이 확인되면 스쿼시가 강제됩니다.

노트북

출력 제거는 전 유형 공통

outputs와 execution_count 제거는 유형과 무관하게 모든 ipynb에 적용합니다. md 안내서를 페어링하는 규칙만 B·C형에 해당합니다.

경로

랩 폴더 이름은 NN-kebab-name

lab이나 step 대신 번호를 접두어로 씁니다. 최상위에 실행 코드가 있으면 랩을 labs/ 아래에 모으고, 없으면 루트에 바로 둡니다. 랩을 묶는 폴더 이름은 labs/로 통일합니다. 바꿀 경로를 직접 지정하려면 path_map에 기존 경로와 새 경로를 적습니다.

날짜

last_updated와 validated_on은 다른 값

last_updated는 문서 수정일이고 validated_on은 사람이 완주한 날입니다. 최신성(stale) 판정은 validated_on 기준이므로 문서만 고치고 검증일을 채우지 않으면 오래된 자료로 표시됩니다.

본문

AI는 창작하지 않습니다

실습 절차의 내용을 만들거나 지우지 않습니다. 학습 목표·검증 기준처럼 원문에 근거가 있는 항목만 원문 문장을 재배치·요약해 채우고, 근거가 없는 항목은 TODO로 남깁니다.

자산

공용일 때만 shared-assets

이미지·데이터는 해당 랩의 assets/에 둡니다. 다른 랩이 참조하는 파일만 /shared-assets/로 옮기고 참조 링크를 함께 고칩니다. 같은 파일을 여러 랩에 복사하지 않습니다.

검사 결과와 문제 해결

변환을 완료하려면 아래 9종의 자동 검사를 모두 통과해야 합니다. 이 검사들을 하네스라고 부릅니다. AI가 PR 전에 실행하고 저자는 통과 로그를 확인합니다. 병합 후 유지보수에도 같은 검사를 사용합니다. 전체 명령은 AI 지시문과 각 워크샵 리포의 AGENTS.md에 있습니다.

보안 · 커밋 이력을 포함한 시크릿 스캔 · 개인 리소스 식별자 잔존 · 노트북 출력과 execution_count 잔존
구조 · 공백·비ASCII 경로 · 루트 README의 전체 frontmatter 스키마 · 랩 README의 축약 frontmatter
콘텐츠 · 깨진 상대 링크와 이미지 참조 · 빈 alt-text · 다른 랩의 전용 자산 참조

검사 환경 준비

분석 초안을 확인한 뒤 검사 환경을 준비합니다. gitleaks 8.19 이상과 Python 3.10 이상이 필요합니다. 에이전트에 현재 설치 상태와 부족한 도구, 준비 방법을 먼저 정리하도록 요청하세요. 하네스는 devcontainer(Bash) 기준이며 Windows 로컬에서는 준비 작업만 PowerShell로 하고 검사는 devcontainer나 Git Bash에서 실행합니다.

결과 보고 예시

아래는 형식 예시이며 실제 검사 결과가 아닙니다. 에이전트에 통과 로그와 함께 현재 상태, 남은 문제와 다음 행동을 정리하도록 요청하세요.

자동 검사: 9종 중 8종 통과, 1종 실패
남은 문제: 깨진 이미지 링크 2개 — 파일과 위치, 수정할 경로를 제시
저자 확인: 예상 소요 시간, 리소스 정리 절차 TODO 작성
다음 행동: 링크 수정 후 실패한 검사 재실행, 최종 9종 통과 증빙 확인
게시 상태: 보류 — 자동 검사와 저자 검토 완료 전 push 금지
실행 검증: 미완료 — 자동 검사 통과와 별도로 사람이 실습 완주

막혔을 때의 확인 순서

도구 오류라면 실행 환경, 실패한 명령과 오류 메시지를 확인합니다. 콘텐츠 오류라면 해당 파일과 위치, 수정안을 요청하세요. 원인을 해결하기 전에는 다음 단계로 넘어가거나 검사를 건너뛰지 않습니다.

해결이 어렵다면 공동 오너나 팀 카탈로그 담당자에게 실패한 단계와 민감한 값을 제거한 오류 요약을 전달하세요. 시크릿, 개인 리소스 식별자와 원본 보안 로그를 공개 이슈나 공유 문서에 올리지 않습니다.

참고 · 콘텐츠 유형과 자료

결정 시트에서는 콘텐츠를 다음 세 유형으로 구분합니다. 포함된 파일 종류보다 수강자가 주로 무엇을 따라가며 배우는지가 기준입니다. 보조 노트북이 있어도 주로 포털에서 실습하면 A형입니다.

유형 A

포털 클릭스루형

브라우저에서 포털을 따라가며 배우는 워크샵입니다. Fabric처럼 주로 SaaS 포털에서 작업하는 제품에 맞습니다. devcontainer 없이 execution: [portal]로 선언합니다. 유지보수 시에는 포털 변경에 맞춰 스크린샷을 갱신하는 작업이 주를 이룹니다.

유형 B

노트북 실행형

노트북(ipynb)이 설명과 실행을 겸하는 워크샵으로, SDK·코드 실습에 맞습니다. 각 장에 md 안내서를 함께 두고, 노트북 출력을 지운 상태로만 커밋합니다.

유형 C

가이드 + 검증 분리형

md 가이드에 실습 내용을 설명하고 노트북은 동작 검증에만 씁니다. 인프라·정책 실습처럼 산출물이 코드 밖에 있는 주제에 맞습니다. 문서와 실행물을 역할에 따라 나누어 관리합니다.

자료

표준 적용 예시 · AzureAIFoundryWorkshop-Code@standard-v2: 표준을 모두 적용한 파일럿 리포입니다. 폴더 구조와 파일 구성을 참고할 수 있습니다.
상세 문서 · 절차 전문, 결정 양식, AI 지시문과 하네스
표준 근거 · 표준화 제안 부록 A(frontmatter 스키마) · B(랩 문서 템플릿) · C(등록 체크리스트) · D(AGENTS.md 표준)
저장소 안내 · 문서 구성과 변경 절차