mle-workflow

머신러닝 엔지니어링 워크플로우(Machine Learning Engineering Workflow)

이 스킬을 사용하여 모델 작업을 명확한 데이터 계약(data contract), 반복 가능한 학습(repeatable training), 측정 가능한 품질 게이트(measurable quality gates), 배포 가능한 아티팩트(deployable artifacts), 운영 모니터링(operational monitoring)을 갖춘 프로덕션 ML 시스템으로 전환하세요.

활성화 시점

• 프로덕션 ML 기능, 모델 갱신, 랭킹 시스템, 추천기, 분류기, 임베딩 워크플로우 또는 예측 파이프라인을 계획하거나 검토할 때
• 노트북 코드를 재사용 가능한 학습, 평가, 배치 추론, 또는 온라인 추론 파이프라인으로 변환할 때
• 모델 승격 기준(promotion criteria), 오프라인/온라인 평가, 실험 추적, 또는 롤백 경로를 설계할 때
• 데이터 드리프트(data drift), 레이블 누수(label leakage), 오래된 특징(stale features), 아티팩트 불일치(artifact mismatch), 일관되지 않은 학습 및 서빙 로직으로 인한 장애를 디버깅할 때
• 모델 모니터링, 카나리(canary) 롤아웃, 섀도 트래픽(shadow traffic), 또는 배포 후 품질 검사를 추가할 때

범위 조정(Scope Calibration)

현재 시스템에 적합한 부분만 사용하세요. 이 스킬은 랭킹, 검색, 추천, 분류기, 예측, 임베딩, LLM 워크플로우, 이상 탐지, 배치 분석에 유용하지만, 모든 시스템에 하나의 아키텍처를 강요해서는 안 됩니다.

• 모든 모델이 지도 학습 레이블, 온라인 서빙, 피처 스토어, PyTorch, GPU, 사람의 검토, A/B 테스트, 또는 실시간 피드백을 가진다고 가정하지 마십시오.
• 데이터 계약, 기준선, 평가 스크립트, 롤백 노트만으로 변경 사항을 검토 가능하게 만들 수 있다면, 무거운 MLOps 도구를 추가하지 마십시오.
• 프로젝트에 레이블, 지연된 결과(delayed outcomes), 슬라이스 정의(slice definitions), 프로덕션 트래픽, 또는 모니터링 주체가 없는 경우, 가정을 명시적으로 드러내십시오.
• 예제는 상호 교환 가능한 템플릿으로 취급하세요. 지표, 서빙 모드, 데이터 저장소, 롤아웃 메커니즘을 프로젝트 고유의 것들로 대체하십시오.

관련 스킬

• python-patterns 및 python-testing: Python 구현 및 pytest 적용 범위
• pytorch-patterns: 딥러닝 모델, 데이터 로더, 디바이스 처리, 학습 루프
• eval-harness 및 ai-regression-testing: 승격 게이트 및 에이전트 지원 회귀 검사
• database-migrations, postgres-patterns, clickhouse-io: 데이터 스토리지 및 분석 표면
• deployment-patterns, docker-patterns, security-review: 서빙, 시크릿, 컨테이너, 프로덕션 강화

SWE 표면 재사용(Reuse the SWE Surface)

MLE를 소프트웨어 엔지니어링과 분리하여 취급하지 마십시오. 대부분의 ECC SWE 워크플로우는 ML 시스템에 직접 적용 가능하며, 종종 더 엄격한 장애 모드를 가집니다.

권장되는 minimal --with capability:machine-learning 설치는 이 스킬과 함께 핵심 에이전트 표면을 사용 가능하게 유지합니다. 스킬 전용 또는 에이전트 제한 하네스의 경우, 대상이 에이전트를 지원하는 경우 skill:mle-workflow를 agent:mle-reviewer와 함께 사용하십시오.

SWE 표면	MLE 용도
product-capability / architecture-decision-records	모델 작업을 명시적인 제품 계약으로 전환하고, 되돌릴 수 없는 데이터, 모델 및 롤아웃 결정을 기록합니다
repo-scan / codebase-onboarding / code-tour	병렬 ML 스택을 도입하기 전에 기존 학습, 피처, 서빙, 평가 및 모니터링 경로를 찾습니다
plan / feature-dev	모델 변경 사항을 데이터, 평가, 서빙 및 롤백 단계가 있는 제품 기능으로 범위를 지정합니다
tdd-workflow / python-testing	구현 전에 피처 변환, 분할 로직, 메트릭 계산, 아티팩트 로딩 및 추론 스키마를 테스트합니다
code-reviewer / mle-reviewer	코드 품질과 함께 ML 특화 누수, 재현성, 승격 및 모니터링 위험을 검토합니다
build-fix / pr-test-analyzer	손상된 CI, 불안정한 평가, 누락된 픽스처, 환경 특화 모델 또는 의존성 장애를 진단합니다
quality-gate / test-coverage	변환, 메트릭, 추론 계약, 승격 게이트 및 롤백 동작에 대한 자동화된 증거를 요구합니다
eval-harness / verification-loop	오프라인 메트릭, 슬라이스 검사, 지연 시간 예산 및 롤백 훈련을 반복 가능한 게이트로 전환합니다
ai-regression-testing	모든 프로덕션 버그를 회귀 테스트로 보존합니다: 누락된 피처, 오래된 레이블, 잘못된 아티팩트, 스키마 드리프트 또는 서빙 불일치
api-design / backend-patterns	예측 API, 배치 작업, 멱등 재학습 엔드포인트 및 응답 봉투를 설계합니다
database-migrations / postgres-patterns / clickhouse-io	레이블, 피처 스냅샷, 예측 로그, 실험 메트릭 및 드리프트 분석을 버전 관리합니다
deployment-patterns / docker-patterns	상태 확인, 리소스 제한 및 롤백을 통해 재현 가능한 학습 및 서빙 이미지를 패키징합니다
canary-watch / dashboard-builder	모델 버전, 슬라이스, 드리프트, 지연 시간, 비용 및 지연된 레이블 대시보드로 롤아웃 상태를 가시화합니다
security-review / security-scan	모델 아티팩트, 노트북, 프롬프트, 데이터셋, 로그에서 시크릿, PII, 안전하지 않은 역직렬화 및 공급망 위험을 확인합니다
e2e-testing / browser-qa / accessibility	설명 가능성 및 폴백 UI 상태를 포함하여 예측을 소비하는 중요한 제품 흐름을 테스트합니다
benchmark / performance-optimizer	처리량, p95 지연 시간, 메모리, GPU 사용률 및 예측 또는 재학습당 비용을 측정합니다
cost-aware-llm-pipeline / token-budget-advisor	가장 큰 모델을 기본값으로 사용하는 대신 품질, 지연 시간 및 예산에 따라 LLM/임베딩 워크로드를 라우팅합니다
documentation-lookup / search-first	코딩 전에 모델 서빙, 피처 스토어, 벡터 DB 및 평가 도구에 대한 현재 라이브러리 동작을 확인합니다
git-workflow / github-ops / opensource-pipeline	명확한 범위, 생성된 아티팩트 제외, 재현 가능한 테스트 증거를 사용하여 MLE 변경 사항을 검토용으로 패키징합니다
strategic-compact / dmux-workflows	데이터 계약, 평가 하네스, 서빙 경로, 모니터링 및 문서로 긴 ML 작업을 병렬 트랙으로 분할합니다

10가지 MLE 작업 시뮬레이션(Ten MLE Task Simulations)

MLE 작업을 계획하거나 검토할 때 적용 범위 확인으로 이러한 시뮬레이션을 사용하세요. 강력한 MLE 워크플로우는 각 작업을 명시적 계약, 재사용 가능한 SWE 표면, 자동화된 증거 및 검토 가능한 아티팩트로 축소해야 합니다.

ID	일반적인 MLE 작업	간소화된 ECC 경로	필수 출력	적용되는 파이프라인 레인
MLE-01	모호한 예측, 랭킹, 추천, 분류, 임베딩 또는 예측 기능 구성	product-capability, plan, architecture-decision-records, mle-workflow	반복 컴팩트: 관심 대상자, 의사 결정자, 성공 메트릭, 허용 불가 실수, 가정, 제약 조건 및 첫 번째 실험 명명	제품 계약, 이해관계자 손실, 위험, 롤아웃
MLE-02	메트릭 목표, 레이블, 데이터 소스 및 실수 예산 정의	repo-scan, database-reviewer, database-migrations, postgres-patterns, clickhouse-io	엔티티 그레인, 레이블 시점, 레이블 신뢰도, 피처 시점, 시점 조인, 분할 정책 및 데이터셋 스냅샷을 포함한 데이터 및 메트릭 계약	데이터 계약, 메트릭 설계, 누수, 재현성
MLE-03	복잡성을 추가하기 전에 기준 모델 및 채점 경로 구축	tdd-workflow, python-testing, python-patterns, code-reviewer	혼동 행렬, 보정 노트, 지연 시간/비용 추정, 알려진 약점, 점수 형태 및 결정론에 대한 테스트를 포함한 기준 채점자	기준, 채점, 테스트, 서빙 동등성
MLE-04	결과를 구분하는 가설에서 특징 생성	python-patterns, pytorch-patterns, docker-patterns, deployment-patterns	신호 소스, 누락 값, 이상치, 상관관계, 누수 검사 및 학습/서빙 동등성을 포함한 피처 계획 및 변환 모듈	피처 파이프라인, 누수, 학습, 아티팩트
MLE-05	절충점 하에서 임계값, 구성 및 모델 복잡성 조정	eval-harness, ai-regression-testing, quality-gate, test-coverage	정밀도, 재현율, F1, AUC, 보정, 그룹 슬라이스, 지연 시간, 비용, 복잡성 및 허용 가능한 오류 클래스를 비교하는 임계값/구성 보고서	평가, 임계값, 승격, 회귀
MLE-06	오류 분석을 실행하고 실수를 다음 실험으로 전환	eval-harness, ai-regression-testing, mle-reviewer, silent-failure-hunter	거짓 양성, 거짓 음성, 모호한 레이블, 오래된 특징, 누락된 신호 및 배운 교훈이 포함된 버그 추적에 대한 오류 클러스터 보고서	오류 분석, 버그 추적, 반복, 회귀
MLE-07	배치 또는 온라인 추론용 모델 아티팩트 패키징	api-design, backend-patterns, security-review, security-scan	전처리, 구성, 의존성 제약, 스키마 검증, 안전한 로딩 및 PII 안전 로그를 포함한 버전 관리 아티팩트 번들	아티팩트, 보안, 추론 계약
MLE-08	피드백 캡처와 함께 온라인 서빙 또는 배치 채점 제공	api-design, backend-patterns, e2e-testing, browser-qa, accessibility	응답 봉투, 타임아웃, 배치 처리, 폴백, 모델 버전, 신뢰도, 피드백 로깅 및 제품 흐름 테스트를 포함한 예측 엔드포인트 또는 배치 작업	서빙, 배치 추론, 폴백, 사용자 워크플로우
MLE-09	섀도 트래픽, 카나리, A/B 테스트 또는 롤백으로 모델 롤아웃	canary-watch, dashboard-builder, verification-loop, performance-optimizer	트래픽 분할, 대시보드, p95 지연 시간, 비용, 품질 가드레일, 롤백 아티팩트 및 롤백 트리거를 명명하는 롤아웃 계획	배포, 카나리, 롤백
MLE-10	출시 후 프로덕션 모델 운영, 디버그 및 갱신	silent-failure-hunter, dashboard-builder, mle-reviewer, doc-updater, github-ops	드리프트 검사, 지연된 레이블 상태, 알림 소유자, 런북 업데이트, 재학습 기준 및 PR 증거를 포함한 관찰 원장 및 갱신 계획	모니터링, 사고 대응, 재학습

반복 컴팩트(Iteration Compact)

모델 코드를 건드리기 전에 작업을 하나의 검토 가능한 아티팩트로 압축하세요. 이는 PR 설명에 들어갈 만큼 짧고 다른 엔지니어가 절충점에 이의를 제기할 수 있을 만큼 정확해야 합니다.

목표:
관심 대상자:
의사 결정자:
모델에 의해 변경되는 사용자 또는 시스템 작업:
성공 메트릭:
가드레일 메트릭:
실수 예산:
허용 불가 실수:
허용 가능한 실수:
가정:
제약 조건:
레이블 및 데이터 스냅샷:
기준:
후보 신호:
임계값 또는 구성 계획:
평가 슬라이스:
알려진 위험:
다음 실험:
롤백 또는 폴백:

이 컴팩트는 강력한 SWE 설계 노트에 해당하는 MLE 버전입니다. 이는 팀이 누구도 신뢰하지 않는 메트릭을 최적화하거나, 실제 오류 모드를 해결하지 않는 피처를 추가하거나, 롤백 없이 복잡성을 출시하는 것을 방지합니다.

결정 브레인(Decision Brain)

작업이 모호하거나, 영향이 크거나, 메트릭이 많은 경우 이 루프를 사용하세요:

1. 모델이 아닌 결정부터 시작하세요. 다운스트림 동작을 변경하는 작업의 이름을 지정하세요.
2. 관심 대상자가 누구이고 그 이유를 지정하세요. 다양한 이해관계자는 거짓 양성, 거짓 음성, 지연 시간, 컴퓨팅 비용, 불투명성 또는 놓친 기회에 대해 서로 다른 비용을 지불합니다.
3. 모호함을 가설로 전환하세요. 어떤 신호가 결과를 구분할지, 어떤 증거가 이를 반증할지, 어떤 간단한 기준선이 깨기 어려워야 하는지 물어보세요.
4. 맞춤형 시스템을 발명하기 전에 이전 사례 또는 근처의 알려진 문제를 조사하세요.
5. (확률, 신뢰도) x (비용, 심각도, 중요성, 영향)으로 선택지를 점수화하세요.
6. 적대적 행동, 인센티브, 선택적 공개, 분포 변화 및 피드백 루프를 고려하세요.
7. 가장 중요한 실수를 줄이는 가장 간단한 변경을 선호하세요. 단순함은 게으름이 아닙니다. 이는 반복 속도를 유지하면서 실수를 최소화하는 방법입니다.
8. 결정, 증거, 반론 및 다음 되돌릴 수 있는 단계를 캡처하세요.

메트릭 및 실수 경제학(Metric and Mistake Economics)

습관이 아닌 실패 비용에서 메트릭을 선택하세요:

• 초기에 혼동 행렬을 사용하여 팀이 추상적인 정확도 대신 구체적인 거짓 양성 및 거짓 음성에 대해 논의할 수 있도록 하세요.
• 잘못된 양성 결정 비용이 지배적인 경우 정밀도를 선호하세요.
• 놓친 양성 비용이 지배적인 경우 재현율을 선호하세요.
• 정밀도/재현율 트레이드오프가 진정으로 균형 잡히고 설명 가능한 경우에만 F1을 사용하세요.
• 단일 임계값보다 순서 품질이 더 중요한 경우 AUC 또는 랭킹 메트릭을 사용하세요.
• 지연 시간, 처리량, 메모리 및 비용을 일급 메트릭으로 추적하세요. 이는 실현 가능한 모델 복잡성을 형성하기 때문입니다.
• 오프라인 이득을 축하하기 전에 기준선 및 현재 프로덕션 모델과 비교하세요.
• 실제 피드백 신호를 편향, 지연 및 적용 범위 격차가 있는 지연된 레이블로 취급하고, 분석 없이 실제값으로 취급하지 마세요.

모든 메트릭 선택은 어떤 실수를 더 저렴하게 만들고, 어떤 실수를 더 가능하게 만들며, 누가 그 비용을 부담하는지 명시해야 합니다.

데이터 및 특징 가설(Data and Feature Hypotheses)

특징은 분리 이론(separation theory)에서 비롯되어야 합니다:

• 텍스트, 범주형 필드, 숫자 이력, 그래프 관계, 최신성, 빈도 및 집계는 후보 신호 패밀리이지 자동 특징이 아닙니다.
• 모든 특징 패밀리에 대해, 그것이 결과를 구분해야 하는 이유와 미래 정보를 누출할 수 있는 방법을 명시하세요.
• 노이즈가 많은 레이블의 경우, 중재, 레이블 신뢰도, 소프트 타겟 또는 신뢰도 가중치를 고려하세요.
• 클래스 불균형의 경우, 가중치 손실, 리샘플링, 임계값 이동 및 보정된 결정 규칙을 비교하세요.
• 누락 값의 경우, 부재가 정보를 제공하는지, 대체 가능한지 또는 기권 이유인지 결정하세요.
• 이상치의 경우, 잘라낼지, 버킷화할지, 조사할지 또는 드물지만 중요한 신호로 보존할지 결정하세요.
• 상관된 특징의 경우, 중복되는지, 불안정한지, 사용할 수 없는 미래 상태의 프록시인지 확인하세요.

오류 분석이 기준선이 추가 신호 또는 용량이 그럴듯하게 수정할 수 있는 이유로 실패하고 있음을 보여줄 때까지 모델 복잡성을 추가하지 마십시오.

오류 분석 루프(Error Analysis Loop)

각 기준선, 학습 실행, 임계값 변경 또는 구성 변경 후:

1. 실수를 거짓 양성, 거짓 음성, 기권, 낮은 신뢰도 사례 및 시스템 장애로 나누세요.
2. 공유 특성(언어, 엔티티 유형, 소스, 시간, 지리, 디바이스, 희소성, 최신성, 특징 신선도, 레이블 소스 또는 모델 버전)별로 오류를 클러스터링하세요.
3. 모델 실수와 데이터 버그를 분리하세요.
4. 데이터 버그: 누락된 신호, 잘못된 라벨, 파이프라인 누수, 손상된 특징 또는 오래된 스냅샷. 여기서는 SWE 도구가 필요합니다.
5. 전처리 및 서빙 환경 간의 불일치를 확인하세요.
6. 배치에서 가장 비용이 많이 드는 상위 K 실수 클러스터를 식별하고 정량화하세요.
7. 각 클러스터에 대해 다음 실험 가설을 공식화하세요: 어떤 추가 특징, 모델 변경, 임계값 이동 또는 데이터 품질 수정이 이 클러스터의 실수를 해결할 수 있을까요?
8. 각 가설을 가드레일, 전제 조건 및 반증 기준을 포함한 테스트 가능한 예측으로 변환하세요.

배포 및 롤아웃 원칙

프로덕션에 제공하기 전에 결정하세요:

• 롤아웃 전략: 섀도(트래픽 미러링), 카나리(증분 트래픽), A/B 테스트(제어 대비 측정), 또는 빅뱅(위험함, 드물게 정당화됨).
• 배포 자동화: 컨테이너화된 학습/서빙, CI/CD 파이프라인, 롤백 핸들.
• 모니터링: 예측 스키마, 특징 분포, 지연 시간, 처리량, 오류율, 점수 신뢰도 및 다운스트림 영향.
• 설명 가능성 및 감사: 예측을 특징 속성, 모델 버전 및 입력에 연결합니다.
• 피드백 루프: 예측 + 지연된 레이블을 로그하고, 드리프트 탐지를 설정하고, 재학습 트리거를 정의합니다.

방어 코딩 원칙

프로덕션 ML 파이프라인에 보호 장치를 추가하세요:

• 입력 스키마 검증: 서빙 진입 시 특징 유형, 누락 값 처리, 허용 범위를 확인합니다.
• 점수 신뢰도 임계값: 특정 신뢰도 이하의 경우 폴백 또는 기권을 설정합니다.
• 모델 아티팩트 검증: 로딩 시 예상 스키마, 서명 및 메타데이터와 비교하여 확인합니다.
• 드리프트 탐지: 특징 및 예측 분포를 시간이 지남에 따라 모니터링하고, 기준을 위반하는 경우 경고 또는 자동 롤백합니다.
• 리소스 가드레일: 학습 및 서빙 작업에 대한 최대 메모리, GPU 시간 및 비용 한도를 설정합니다.
• 종속성 고정: 학습 및 서빙 환경 모두에 대해 패키지 종속성의 잠금 파일 또는 해시를 유지합니다.
• 재현성 시드: 학습 파이프라인에 대해 데이터 셔플, 모델 초기화 및 기타 무작위 구성 요소의 시드를 수정합니다.
• 출력 스키마 검증: 추론 결과가 예측된 응답 형식과 일치하는지 확인합니다.

팁

• 이 워크플로우는 조정 가능한 프레임워크입니다. 각 파이프라인 레인(데이터, 특징, 모델링, 평가, 배포, 모니터링)에는 표면이 있습니다. 전체가 아닌 필요한 것만 사용하세요.
• AI 에이전트에 설명할 때, 논의 중인 ML 문제의 결정론, 재현성 및 오류 비용 측면에 특히 주의하세요.
• 모델이 사용자에게 보이지 않는 결정을 내리는 경우(예: 콘텐츠 순위, 자동화된 태깅, 이상 상태 플래그 지정), 'who cares' 관점을 명시화하는 것이 ML 시스템에 대한 인간의 가드레일을 구축하는 데 중요합니다.