Azure Content Standardization › 워크샵 이관·표준화 가이드
Guide · Workshop Migration & Standardization

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

개인 리포에서 운영하던 워크샵을 Azure-Samples 조직으로 옮기고 팀 표준 템플릿을 적용하는 방법을 안내합니다. 반복 변환 작업은 AI 에이전트에 맡깁니다. 저자는 이관 방침을 정하고 보안 점검 결과와 변경 내용을 검토한 뒤, 게시와 실행 검증을 진행합니다.

기준일 2026-09-16 · 근거: 표준화 제안과 상세 규격 부록 A~D · 표준을 적용한 실물 예시: AzureAIFoundryWorkshop-Code@standard-v2

개요 · 문서 구성

이관 절차에서 단계별 목적을 확인하고, 빠른 시작에서 저자가 할 일을 순서대로 따라갑니다. 세부 명령과 설정값은 상세 이관 가이드를 참고합니다. 표준 규칙은 Markdown 기준 문서에서 검토·개정하며, 아직 결정되지 않은 항목은 구분해 표시합니다.

사람이 읽는 문서

상세 이관 가이드

전체 절차(Phase 0~6)와 단계별 판단 기준. 유형별 차이는 부록에 정리되어 있습니다.

저자가 채우는 문서

이관 결정 시트

이관 범위, 콘텐츠 유형, history 방침, 라이선스, 제외할 내부 산출물을 기록하는 양식입니다.

AI에 전달하는 문서

AI 변환 지시문

Copilot Agent와 Claude Code에서 사용하는 변환 지시문. 결정 시트 값을 입력 블록에 채워 전달합니다.

이관 절차 (Phase 0~6)

이관은 사전 결정부터 게시·등재까지 일곱 단계로 진행합니다. Phase 0~5에서 변환과 자동 검사를 로컬에서 마친 뒤, Phase 6에서 Azure-Samples 등록과 게시를 진행합니다. 각 단계의 목적은 다음과 같습니다.

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
1
Phase 0 · 사전 결정 (선택). 이관 범위와 처리 방침을 결정 시트에 미리 기록합니다. 생략하면 Phase 1에서 에이전트의 권고안을 검토해 확정할 수 있습니다.
2
Phase 1 · AI 실행과 결정 확정. 저자가 결정 시트를 확정합니다. 시트가 없으면 AI가 리포를 분석해 전체 항목의 권고값과 근거를 제시합니다.
3
Phase 2 · 보안 점검. AI가 커밋 이력 전체에서 시크릿, 개인 리소스 식별자, 노트북 출력을 스캔하고 저자가 결과를 판정합니다. 이 검사는 생략할 수 없습니다.
4
Phase 3 · 콘텐츠 이관 준비 (로컬). 확정한 이력 보존·스쿼시·서브폴더 추출 방침에 따라 AI가 새 리포를 준비합니다. 아직 원격 push는 하지 않습니다.
5
Phase 4 · 표준 적용. AI가 경로, 문서와 랩 구조, 노트북, 실행 환경, 거버넌스 파일에 표준을 적용합니다.
6
Phase 5 · 검증과 리뷰. 하네스 9종을 모두 통과했는지 확인합니다. 저자는 변경 요약과 로컬 diff를 검토하고 남은 TODO를 채웁니다.
7
Phase 6 · 게시와 등재. Microsoft Open Source Management 포털에 리포를 등록합니다.
필수 규칙 보안 점검에서 시크릿이나 개인 식별자가 커밋 이력에서 발견되면, 저자가 선택한 방침과 관계없이 이력을 스쿼시해야 합니다. HEAD에서 지워도 이력에는 남기 때문입니다.

빠른 시작 · 저자가 할 일

기존 리포와 AI 코딩 에이전트를 준비합니다. Claude Code 또는 GitHub Copilot 에이전트 모드를 사용할 수 있습니다. 아래 순서로 변환을 요청하고, 결과를 검토한 뒤 게시합니다.

1
리포를 클론하고 도구를 준비합니다. 본인 GitHub 리포를 로컬에 클론합니다. 하네스 실행에는 gitleaks 8.19 이상과 Python 3.10 이상이 필요합니다. 검사 환경은 devcontainer나 Git Bash입니다.
2
지시문을 전달하고 결정 시트를 확정합니다. AI 지시문을 작업 폴더에 복사하고 "이 파일을 읽고 그대로 수행하라"고 지시합니다. 결정 시트를 미리 채웠다면 지시문의 [입력] 블록에 값을 옮깁니다. 시트가 없으면 에이전트가 전체 항목의 권고값과 근거를 제시하므로, 검토하고 필요한 값을 수정해 확정합니다.
3
변환을 맡기고 확인 요청에 답합니다. 에이전트는 보안 점검부터 표준 적용과 자동 검사까지 로컬에서 진행합니다. 작업은 별도 브랜치에 단계별 커밋으로 남깁니다. 삭제 대상이나 이력 처리 방침처럼 판단이 필요한 항목은 저자에게 확인하며, 원격 push는 하지 않습니다.
4
변경을 검토하고 TODO를 채웁니다. 변경 요약 보고의 단계별 커밋 내역과 로컬 diff를 검토합니다. 하네스 9종의 통과 로그를 확인한 뒤, 소요 시간과 정리 절차 등 저자가 작성할 TODO를 채웁니다.
5
리포를 만들고 변환 결과를 게시합니다. 리포 이름은 <product>-<topic>-workshop-kr 형식입니다. 공개 범위는 Private, 분류는 Non-Production으로 설정합니다. Direct Owners는 개인 2명을 지정하고, 오픈소스 심사는 Yes를 선택합니다. 전체 입력값과 심사 문안은 6-1. 리포 생성에 있습니다. 이후 설정과 업로드는 6-2. 생성 직후 점검, 6-3. push 순서로 진행합니다.
6
실행을 검증하고 공개·등재합니다. Codespaces에서 워크샵을 처음부터 끝까지 완주하고 validated_on에 검증일을 적습니다. 심사 승인을 확인한 뒤 포털의 Publicize로 공개 전환합니다. 허브 리포 카탈로그에 등재하고, 기존 리포의 README를 새 주소 안내로 바꾼 뒤 Archive 처리합니다. 세부 절차는 6-4. 검증과 공개 전환과 6-5. 등재와 정리에 있습니다.
팁 지시문은 AI가 시크릿이나 개인 식별자 노출을 발견하면 임의로 지우지 않고 멈춰서 보고하도록 정하고 있습니다. 저자가 이력 처리 방침을 확인하고 원격 push를 직접 수행합니다.

핵심 규칙

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

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 · 다른 랩의 전용 자산 참조
참고 하네스는 devcontainer(Bash) 기준입니다. Windows 로컬에서는 gitleaks 설치 같은 준비 작업만 PowerShell로 하고, 검사는 devcontainer나 Git Bash에서 실행합니다.

참고 · 콘텐츠 유형과 자료

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

유형 A

포털 클릭스루형

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

유형 B

노트북 실행형

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

유형 C

가이드 + 검증 분리형

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

자료