외주 개발사 납품 코드·에셋 규격 AI 자동 검수 파이프라인 구축 가이드

핵심 요약

외주 납품 검수는 담당자의 감각에만 의존하지 않고 manifest.json으로 정의한 규격과 자동화된 증거 수집으로 운영할 수 있습니다. 파일 포맷·용량·네이밍·경로는 결정론적 규칙 엔진으로 검사하고 코드의 의도와 에셋의 용도처럼 규칙만으로 판단하기 어려운 항목은 AI를 보조 수단으로 활용할 수 있습니다.

핵심 원칙은 세 가지입니다.

1. 납품 기준을 문서가 아닌 버전 관리 가능한 규격 파일로 만든다.
2. SHA-256 해시, 확장자, 파일 크기, 경로, 네이밍처럼 기준이 명확한 항목은 자동 검사한다.
3. AI 판정에는 반드시 근거 파일, 라인, 프리뷰 이미지, confidence를 함께 남긴다.

외주 납품 검수는 왜 반복해서 실패하는가?

외주 개발사와 검수 지연이 반복되는 원인 중 하나는 계약과 기준의 불명확성일 수 있습니다. “최적화된 텍스처를 납품해 주세요”라는 문장은 담당자마다 해석이 다를 수 있습니다. 반면 “PNG, 2048×2048 이하, RGBA 허용, 파일당 8MB 이하, env_ 접두사 사용”처럼 조건을 구체화하면 자동 검사 규칙으로 만들 수 있습니다.

검수에서 발생할 수 있는 문제는 다음과 같습니다.

• 동일한 에셋이 Building_Final.fbx, building_final2.fbx처럼 서로 다른 규칙으로 전달된다.
• Unity 프로젝트에서 스크립트와 .meta 파일이 함께 오지 않는다.
• 텍스처 해상도와 압축 설정이 플랫폼 기준과 다르다.
• 코드가 컴파일되지만 개발용 로그, 임시 경로, 테스트 계정이 남아 있다.
• 검수자가 오류를 발견해도 근거와 수정 요청 형식이 매번 달라진다.

따라서 PM은 “검수해 달라”가 아니라 “어떤 조건이면 자동 통과 또는 반려되는가”를 정의해야 합니다.

무엇을 납품 규격으로 고정해야 하는가?

아래 기준은 Unity 2022.3 LTS와 Unreal Engine 5.3 프로젝트에서 사용할 수 있는 예시입니다. 실제 값은 타깃 플랫폼, 메모리 예산, 빌드 파이프라인에 맞춰 프로젝트별로 조정해야 합니다.

대상	검사 항목	예시 기준	실패 시 조치
Unity 컴포넌트 스크립트	인코딩, 컴파일, 파일명	UTF-8, 컴파일 성공, MonoBehaviour 클래스명과 파일명 일치	자동 반려
Unity 파일	메타데이터	모든 에셋에 .meta 존재	자동 반려
모델	포맷, 용량, LOD	FBX, 파일당 25MB 이하, LOD0~LOD2	자동 반려 또는 검토
텍스처	포맷, 해상도, 색상	PNG/TGA, 2048×2048 이하, 용도별 suffix	자동 반려
오디오	포맷, 샘플레이트, 용량	WAV 원본 또는 OGG 런타임용, 48kHz 기준	자동 반려
네이밍	접두사와 토큰	env_building_01_lod0.fbx	자동 반려
경로	허용 디렉터리	Assets/Art/Environment/ 아래만 허용	자동 반려
코드 품질	로그와 비밀정보	API 키, 로컬 절대 경로, 과도한 Debug.Log 금지	AI 검토 후 판정

네이밍 규칙은 어떻게 설계해야 하는가?

네이밍은 사람이 읽을 수 있으면서 기계가 분해할 수 있어야 합니다. 권장 형식은 다음과 같습니다.

[domain]_[asset]_[variant]_[lod-or-purpose].[ext]

예시는 다음과 같습니다.

• env_building_01_lod0.fbx
• env_building_01_d.png
• env_building_01_n.png
• char_knight_01_albedo.png
• sfx_ui_confirm_01.ogg

final, new, latest, 진짜최종처럼 의미가 불분명한 토큰은 금지하는 편이 좋습니다. 버전은 파일명에 임의로 추가하기보다 Git 태그, 납품 ID, manifest의 spec_version으로 관리합니다.

AI 자동 검수 파이프라인은 어떻게 구현할까?

파이프라인은 다음과 같이 결정론적 검사와 AI 검사를 분리합니다.

flowchart LR
 A[납품 패키지] --> B[파일 목록 및 SHA-256]
 B --> C[규칙 엔진]
 C -->|실패| D[자동 반려]
 C -->|통과| E[AI 의미 검수]
 E --> F[증거 포함 JSON]
 F --> G[PM 승인 또는 예외 승인]

1. 납품 계약을 manifest.json으로 바꾼다

외주 개발사가 제출하는 ZIP에는 파일만 넣지 말고 manifest.json을 함께 요구합니다. manifest에는 납품 ID, 규격 버전, 파일 목록, 파일 유형, 예상 용량, SHA-256 해시를 기록합니다.

{
  "delivery_id": "ENV-2026-0824-01",
  "spec_version": "1.3",
  "engine": "Unity 2022.3.45f1",
  "files": [
    {
      "path": "Assets/Art/Environment/env_building_01_lod0.fbx",
      "type": "model",
      "max_mb": 25,
      "sha256": "수령 전에 기록한 예상 SHA-256"
    }
  ]
}

ZIP 안에 함께 들어 있는 manifest만 신뢰하면 파일과 해시를 함께 바꾸는 경우를 알아낼 수 없습니다. 변경 방지가 필요하다면 해시 기준을 승인된 커밋이나 서명된 manifest 등 신뢰할 수 있는 별도 출처와 대조해야 합니다.

규격 파일은 Git 저장소에서 관리하고 변경 시 반드시 리뷰를 거칩니다. PM은 v1.2와 v1.3의 차이를 릴리스 노트로 남겨야 합니다. 그래야 외주사가 어느 버전을 기준으로 작업했는지 분쟁 없이 확인할 수 있습니다.

2. 결정론적 규칙 엔진으로 먼저 차단한다

확장자, 파일 크기, 경로, 해시, 이미지 해상도, 오디오 샘플레이트는 AI가 판단할 이유가 없습니다. Python 3.12나 Node.js 20 기반 검사기를 CI에 연결하면 같은 검사기 버전과 입력에 같은 결과를 얻을 수 있습니다.

아래 코드는 FBX·PNG·WAV의 확장자, 용량, 파일명, 해시만 검사하는 최소 예제입니다. 경로, 이미지 해상도, 오디오 샘플레이트와 TGA·OGG 허용 규칙은 실제 프로젝트 규격에 맞게 별도로 추가해야 합니다.

from pathlib import Path
import hashlib

MAX_BYTES = {
    '.fbx': 25 * 1024 * 1024,
    '.png': 8 * 1024 * 1024,
    '.wav': 50 * 1024 * 1024,
}


def sha256(path):
    digest = hashlib.sha256()
    with path.open('rb') as stream:
        for chunk in iter(lambda: stream.read(1024 * 1024), b''):
            digest.update(chunk)
    return digest.hexdigest()


def valid_name(path):
    stem = path.stem
    forbidden = ['final', 'latest', 'new', '진짜최종']
    tokens = stem.split('_')
    return stem == stem.lower() and ' ' not in stem and not any(token in tokens for token in forbidden)


def inspect_file(path, expected_sha256):
    errors = []
    suffix = path.suffix.lower()
    actual_sha256 = sha256(path)

    if suffix not in MAX_BYTES:
        errors.append('허용되지 않은 확장자')
    elif path.stat().st_size > MAX_BYTES[suffix]:
        errors.append('파일 용량 초과')

    if not valid_name(path):
        errors.append('네이밍 규칙 위반')

    if actual_sha256.lower() != expected_sha256.lower():
        errors.append('SHA-256 불일치')

    return {
        'path': str(path),
        'sha256': actual_sha256,
        'status': 'fail' if errors else 'pass',
        'errors': errors,
    }

Unity 프로젝트라면 Assets 파일과 .meta 파일의 쌍을 확인할 수 있습니다. 다음 명령은 프로젝트를 배치 모드로 여는 예이며, CI에서 컴파일 오류를 반려하려면 로그를 수집하거나 별도의 검증·빌드 메서드와 종료 코드를 확인해야 합니다.

Unity.exe -batchmode -nographics -quit -projectPath ./delivery-project -logFile ./unity-editor.log

Unreal Engine 프로젝트는 에디터 실행 검사와 AutomationTool 기반 패키징 검사를 분리하는 편이 좋습니다. 엔진별 실행 명령은 프로젝트의 빌드 스크립트와 CI 환경에 맞춰 고정해야 합니다.

3. AI는 의미와 맥락을 검수한다

AI의 역할은 “8MB를 넘었는가”가 아니라 “이 파일이 실제 요구사항에 맞는 구현인가”를 확인하는 것입니다.

AI 입력에 포함할 수 있는 정보는 다음과 같습니다.

입력	AI가 확인할 내용
C# AST 또는 diff	이벤트 구독 해제 누락, 임시 코드, 예외 처리 부족
코드 주석과 티켓	요구사항과 구현 의도의 일치 여부
에셋 프리뷰 이미지	요구된 방향, 실루엣, 누락된 구성 요소
에셋 메타데이터	머티리얼 수, 본 개수, LOD 존재 여부
검사 엔진 결과	규칙 엔진 오류의 원인 요약과 우선순위

AI 결과는 자유로운 문장 대신 구조화된 JSON을 요청하고, 응답을 파싱해 필수 필드와 자료형을 검증합니다. 파일 경로와 라인 번호 같은 근거가 실제 납품물에 존재하는지도 별도 규칙으로 확인하고, 검증에 실패하면 재시도하거나 검토 대상으로 보냅니다.

{
  "verdict": "review",
  "confidence": 0.86,
  "severity": "medium",
  "evidence": [
    {
      "file": "Assets/Scripts/Inventory/InventoryService.cs",
      "line": 42,
      "reason": "씬 종료 시 이벤트 구독 해제 코드가 보이지 않음"
    }
  ],
  "suggested_action": "수명 주기 확인 후 OnDisable 또는 Dispose 처리"
}

판정 기준은 프로젝트 데이터로 조정해야 합니다. 아래 수치는 검증 전 임시 예시이며, confidence를 정확도나 정답 확률로 간주하지 말고 실제 리뷰 결과로 임계값을 조정해야 합니다.

• 규칙 엔진 fail: 즉시 반려
• AI confidence 0.90 이상이며 증거가 명확함: PM 검토 큐에 우선 등록
• confidence 0.70 이상 0.90 미만: 담당 개발자 리뷰
• confidence 0.70 미만: 참고 의견으로만 기록

AI가 외부 모델을 호출한다면 소스 코드, 고객 데이터, API 키, 미공개 에셋을 그대로 전송하지 않도록 비밀정보 마스킹과 접근 권한을 먼저 설계해야 합니다. 보안 등급이 높은 프로젝트는 사내 모델이나 격리된 실행 환경을 검토할 수 있습니다.

4. 검사 결과를 승인과 이슈 관리에 연결한다

검수 결과에는 반드시 다음 필드를 포함합니다.

• delivery_id: 어떤 납품인지 식별
• spec_version: 어떤 규격으로 검사했는지 기록
• status: pass, fail, review, exception
• severity: blocker, high, medium, low
• evidence: 파일 경로, 라인, 해시, 프리뷰 등 근거
• owner: 수정 책임자
• due_at: 재납품 기한
• exception_id: 예외 승인과 연결되는 식별자

“수정 요청”이라는 제목만으로 이슈를 만들면 재작업이 반복됩니다. 다음과 같은 템플릿을 사용하면 협업 비용을 줄일 수 있습니다.

[납품 반려][ENV-2026-0824-01] env_building_01_n.png 해상도 초과

규격: spec_version 1.3
근거: 4096x4096, 허용 최대 2048x2048
영향: 모바일 메모리 예산 초과 가능성
조치: 2048x2048 이하로 재출력 후 동일 경로에 재납품
담당: 외주 아트팀
기한: 2026-08-26 18:00 KST

예외는 구두 승인으로 처리하지 않고 exception_id, 승인자, 사유, 만료일, 영향 범위를 남깁니다. 예외가 누적되면 다음 규격 버전에 반영할지 PM이 판단합니다.

PM은 어떤 일정과 우선순위로 도입해야 하는가?

처음부터 모든 에셋과 모든 품질 기준을 자동화하면 범위가 빠르게 커집니다. 납품 지연에 직접 영향을 주는 항목부터 단계적으로 도입하는 것이 현실적입니다.

단계	우선 대상	완료 조건
1단계	확장자, 용량, 경로, 네이밍	CI에서 자동 반려 가능
2단계	Unity .meta, 이미지 해상도, 오디오 속성	엔진 임포트 오류 감소
3단계	컴파일, 패키징, 의존성	통합 브랜치 병합 전 검증
4단계	AI 코드·에셋 의미 검수	근거 포함 리뷰 큐 생성
5단계	예외 분석과 규격 개선	반복 오류율 감소 확인

권장 일정은 다음과 같습니다.

1. D-10: 납품 규격과 샘플 파일 확정
2. D-7: 외주 개발사에 spec_version 배포
3. D-5: 정상·오류 샘플로 드라이런
4. D-3: CI와 이슈 템플릿 연결
5. D-1: 차단 기준과 예외 승인자 최종 확인
6. D+0: 자동 검사 결과를 근거로 검수

초기 MVP의 완료 기준은 AI 모델의 정확도가 아니라 “규격 위반을 같은 방식으로 반복 검출하고 담당자가 5분 안에 수정 방법을 이해하는가”로 잡는 편이 좋습니다.

어떤 지표로 효과를 판단할까?

검수 자동화의 성과는 검사 건수보다 재작업과 대기 시간의 감소로 평가해야 합니다.

$$\mathrm{FirstPassRate}=\frac{\mathrm{첫\ 검사에서\ 통과한\ 납품\ 수}}{\mathrm{전체\ 납품\ 수}}\times100$$

함께 볼 지표는 다음과 같습니다.

• 최초 통과율: 납품 품질의 직접 지표
• 평균 검수 소요 시간: PM과 QA의 대기 시간
• 동일 오류 재발률: 규격 문서와 교육의 개선 필요성
• AI false positive 비율: 불필요한 리뷰 발생 정도
• 예외 승인 비율: 규격이 현실과 맞는지 판단하는 지표
• 자동 반려 후 재납품 리드타임: 외주사의 수정 대응 속도

AI를 도입했는데 리뷰 큐만 늘어난다면 모델 문제가 아니라 입력 자료, 판정 기준, 이슈 템플릿이 불완전할 가능성이 큽니다.

자주 묻는 질문 (FAQ)

모든 검수를 AI로 처리하면 안 되나요?

안 됩니다. 포맷, 용량, 해시, 해상도처럼 정답이 명확한 검사는 규칙 엔진이 더 빠르고 재현성이 높습니다. AI는 요구사항과 코드·에셋의 의미를 비교하는 보조 검수에 적합합니다.

외주사에게 검사기를 제공해야 하나요?

가능하면 제공합니다. 납품 직전에만 반려하는 방식보다 외주사의 로컬 환경에서 사전 검사를 실행하게 하는 편이 재작업 비용을 줄입니다. 단, 최종 판정은 중앙 CI에서 다시 실행해야 합니다.

규격 예외는 어떻게 관리해야 하나요?

예외마다 승인자, 사유, 만료일, 영향 범위를 기록하고 exception_id를 납품 결과에 연결합니다. 같은 예외가 반복되면 일회성 승인으로 유지할지 다음 규격에 정식 반영할지 검토합니다.

정리

외주 납품 자동화의 핵심은 AI 모델을 붙이는 일이 아니라 납품 계약을 실행 가능한 규격으로 바꾸는 일입니다. manifest.json, SHA-256, CI 규칙 엔진, 엔진 배치 검증, 근거가 포함된 AI 리뷰 결과를 연결하면 PM은 파일을 직접 열어보는 검수자에서 일정·스코프·예외·품질 기준을 운영하는 관리자로 역할을 전환할 수 있습니다.