제조업 Cloud Run 검사 Job 프리플라이트를 Claude Code로 만들기
검사 CSV와 사진 메타데이터를 Cloud Run Jobs에 넘기기 전 계약, 승인, secret 경계를 점검합니다.
야간 근무가 끝나기 직전, 품질 담당자가 검사 CSV와 외관 사진 목록을 클라우드 배치로 넘기려는 순간 라인장이 멈춰 세웁니다. 이 로트는 아직 승인되지 않았습니다. CSV에는 pass, hold, fail 행이 섞여 있고, 사진 저장 경로에는 작업자 이름처럼 보이는 문자열이 들어 있으며, 환경 변수 표에는 API key처럼 보이는 값이 평문으로 남아 있습니다. Job은 실행될 수 있지만, 나중에 고객 설명, 감사, 불량 분석에서 왜 그 데이터가 넘어갔는지 설명하기 어려워집니다.
이 글은 제조업 검사 보고서를 Cloud Run Jobs에 넘기기 전에 Claude Code로 프리플라이트를 만드는 방법을 다룹니다. Cloud Run Jobs는 HTTP 요청을 계속 받는 서비스가 아니라, 컨테이너를 시작해 작업을 수행하고 종료하는 배치 처리 방식입니다. 여기서는 Google Cloud에 연결하지 않습니다. 제목도 라이브 연동이 아니라 투입 전 계약 점검으로 범위를 제한합니다.
기술적으로 변할 수 있는 부분은 공식 문서로 확인했습니다. 참고한 문서는 Cloud Run Jobs 생성, Jobs 환경 변수, Jobs secret 설정, Jobs 서비스 ID, Claude Code settings입니다. 이 글의 로컬 검증은 입력 계약만 증명하며 인증, IAM, 스토리지 접근, 운영 환경 실행을 증명하지 않습니다.
핵심 요약
- 검사 CSV, 사진 URI 규칙, Cloud Run Job 설정, 승인 체크리스트를 하나의 투입 전 리뷰로 묶습니다.
- Claude Code에는 열, 값 타입, 승인 상태, 명명 규칙, 환경 변수, Secret Manager 경계를 읽게 합니다.
- 사람은 로트 보류, 고객 설명, 보관 기간, 서비스 계정 권한, 최종 품질 승인을 판단합니다.
- 먼저 가상의 로컬 fixture만 사용합니다. 이 글은 Cloud Run, Cloud Storage, Secret Manager, 공장 MES를 호출하지 않습니다.
- 기본 CTA는 회사 운영 경계를 설계하기 위한 교육 및 상담 하나입니다.
작업 흐름: 검사 보고서를 클라우드 Job 계약으로 바꾸기
대상은 외관 검사, 치수 검사, 설비 점검, 교대 종료 품질 집계처럼 CSV와 사진 메타데이터를 야간 배치로 처리하는 현장입니다. 입력은 보통 inspection_results.csv, 사진 URI 목록, 배치 Job 환경 변수 표, 품질 승인 체크리스트입니다. MES는 제조 실행 시스템으로, 작업 지시, 공정 상태, 검사 결과를 다루는 내부 시스템입니다.
처음 할 일은 AI에게 제품 합격 여부를 판단하게 하는 것이 아니라, Job에 들어갈 수 있는 입력 계약을 정의하는 것입니다. 예시 CSV에는 report_id, line_id, product_code, lot_no, measured_value, unit, status, inspector, approved, photo_uri, retention_until이 필요합니다. status는 pass, hold, fail만 허용합니다. approved가 yes가 아닌 행은 Job 입력으로 넘기지 않습니다.
사진 URI는 메모장이 되어서는 안 됩니다. 권장 형태는 gs://factory-qc-evidence/line-a/2026-09/LOT-1042/report-QC-9001-01.webp처럼 라인, 월, 로트, 보고서 ID만 담는 것입니다. 작업자명, 이메일, 전화번호, 전체 이름을 객체 키에 넣지 않습니다. 관련 글로는 제조업 품질 문제 보고서와 제조업 GKE 매니페스트 릴리스 리뷰가 있습니다. 이번 글은 그 사이에 있는 클라우드 배치 투입 전 계약에 집중합니다.
마지막으로 Cloud Run Job 설정을 봅니다. Google Cloud 공식 문서는 환경 변수가 컨테이너 안 코드에서 접근 가능한 키/값으로 주입된다고 설명하지만, 비밀 정보는 환경 변수에 넣지 말고 Secret Manager를 사용하라고 경고합니다. Google Cloud API에 접근하는 Job이라면 서비스 ID, 즉 Job이 사용하는 서비스 계정도 확인해야 합니다. Claude Code는 이 내용을 체크리스트로 만들 수 있지만, 계정과 역할 승인은 사람이 합니다.
flowchart TD
A[로컬에서 검사 CSV 준비] --> B[사진 URI와 보관 기한 확인]
B --> C[Cloud Run Job env와 secret 경계 확인]
C --> D[Claude Code로 문제 표 작성]
D --> E[품질 책임자가 hold/fail 판단]
E --> F[승인 후 사람이 gcloud 또는 CI로 전달]
Claude Code에 맡길 범위와 사람이 판단할 범위
Claude Code에 맡길 범위는 반복 가능한 계약 검사입니다. 누락된 열, 숫자가 아닌 측정값, 미승인 행, 의심스러운 사진 URI, image가 :latest인 설정, serviceAccount가 default인 설정, 환경 변수 이름에 PASSWORD, TOKEN, API_KEY가 들어가는 문제를 찾게 할 수 있습니다. CSV, JSON Job 설정, 승인표를 나란히 읽고 리뷰 표와 수정안을 만드는 작업에도 적합합니다.
사람은 품질 책임과 운영 위험을 결정합니다. hold 로트를 재검사할지, 출하를 멈출지, 고객이나 공급사에 무엇을 설명할지, 사진 보관 기간이 계약과 맞는지, 서비스 계정에 어느 권한만 줄지, 야간 Job을 언제 중지할지를 사람이 정합니다. Claude Code의 출력은 판단 자료이며 법적 결론, 품질 보증, Google Cloud IAM 검증 완료가 아닙니다.
권한 면에서는 Claude Code settings로 파일 읽기와 Bash 실행 범위를 제한합니다. .env, 운영 CSV, 미마스킹 개인정보는 prompt에 넣지 않습니다. 먼저 고정 fixture로 규칙을 만들고, 리뷰 표만 실제 절차로 옮깁니다. Claude Code에 요청할 말은 “업로드해”가 아니라 “사람 승인 후 업로드해도 되는 형태인지 검사해”입니다.
세 가지 Use case
Use case 1: 검사 CSV 행이 Job에 들어갈 수 있는지 판단
입력: 검사 CSV, 열 정의, 허용 status, 승인 필드, 보관 날짜입니다. 하나의 파일에 pass, hold, fail 행이 섞일 수 있습니다.
출력: 누락 열, 잘못된 날짜, 미승인 행, 숫자가 아닌 측정값, 보관 기한 누락을 표로 냅니다. 투입 가능, 사람 확인, 투입 불가를 분리합니다.
사람 확인: 품질 책임자가 hold와 fail 행을 제외할지, 재검사할지, 로트 전체를 멈출지 판단합니다.
Use case 2: 사진 URI에 개인 정보나 임시 정보가 섞이지 않게 하기
입력: 사진 URI 목록, 명명 규칙, 라인 ID, 로트 번호, 보고서 ID입니다. 현장에서는 급히 저장하면서 작업자명이나 장비명이 객체 키에 남기도 합니다.
출력: 이메일 같은 문자열, 전화번호 같은 문자열, 읽을 수 있는 이름, private, tmp를 탐지합니다. 더 안전한 URI 예시도 제안합니다.
사람 확인: 팀이 최소 추적 ID, 제한된 장부에 남길 정보, 허용할 객체 키 패턴을 정합니다.
Use case 3: Cloud Run Job의 secret 경계 확인
입력: Cloud Run Job 설정 JSON, 환경 변수 표, Secret Manager로 옮길 예정인 키, 서비스 계정명, 재시도 횟수, timeout입니다.
출력: API_KEY, PASSWORD, TOKEN, SECRET이 평문 환경 변수에 있는지, secret 참조가 있는지, 서비스 계정이 전용인지, 이미지가 :latest를 피하는지 표로 냅니다.
사람 확인: 클라우드 관리자가 Secret Manager 리소스, 최소 권한 역할, 실패 Job 재시도 가능 여부를 결정합니다.
복사해서 쓰는 프롬프트
당신은 제조업 검사 보고서를 Cloud Run Job에 넘기기 전 프리플라이트 담당자입니다.
목표는 실행 전에 검사 CSV, 사진 URI 규칙, Cloud Run Job 설정, 승인 체크리스트를 맞추는 것입니다.
입력:
- 검사 CSV 샘플:
- 사진 URI 명명 규칙:
- Cloud Run Job 설정 JSON:
- 승인 체크리스트:
- 보관 및 삭제 규칙:
확인할 것:
1. 필수 열 누락
2. measured_value가 숫자가 아님
3. status가 pass/hold/fail이 아님
4. approved가 yes가 아님
5. photo_uri에 이름, 이메일, 전화번호, tmp, private 포함
6. Cloud Run Job image가 latest 사용
7. env에 API_KEY/PASSWORD/TOKEN류 secret이 평문으로 있음
8. serviceAccount가 default가 아니며 확인할 권한이 열거됨
출력:
- "투입 가능", "사람 확인", "투입 불가" 3분류 표
- 수정안
- 사람이 승인해야 할 항목
- 미검증 경계
제약:
- 실제 클라우드 서비스에 연결하지 않음
- 운영 CSV나 개인정보를 출력에 남기지 않음
- ClaudeCodeLab, 교육 링크, 사이트 CTA를 생성물에 넣지 않음
실행 가능한 로컬 검증 코드
아래 코드는 이 글의 고정 fixture만 검사합니다. Cloud Run API, Cloud Storage, Secret Manager, 공장 MES, 네트워크를 호출하지 않습니다. 저장한다면 tools/inspection-job-preflight.mjs 같은 경로를 사용할 수 있지만, 이 저장소에 이미 존재한다는 뜻은 아닙니다.
const requiredColumns = ["report_id","line_id","product_code","lot_no","measured_value","unit","status","inspector","approved","photo_uri","retention_until"];
const inspectionCsv = `report_id,line_id,product_code,lot_no,measured_value,unit,status,inspector,approved,photo_uri,retention_until
QC-9001,line-a,P-441,LOT-1042,0.31,mm,pass,EMP-014,yes,gs://factory-qc-evidence/line-a/2026-09/LOT-1042/report-QC-9001-01.webp,2027-09-30
QC-9002,line-a,P-441,LOT-1042,not-number,mm,hold,EMP-014,no,gs://factory-qc-evidence/private/[email protected],2027-09-30
QC-9003,line-b,P-882,LOT-2099,12.8,N,review,EMP-091,yes,gs://factory-qc-evidence/line-b/tmp/LOT-2099/report-QC-9003.webp,`;
const jobConfig = { name: "inspection-summary-job", image: "asia-northeast1-docker.pkg.dev/factory/prod/inspection-summary:latest", serviceAccount: "default", maxRetries: 3, timeoutSeconds: 1800, env: { REPORT_BUCKET: "factory-qc-evidence", API_KEY: "plain-text-key" }, secrets: { DB_PASSWORD: "projects/123456789/secrets/qc-db-password:2" } };
function parseCsv(text) { const [headerLine, ...rows] = text.trim().split("\n"); const headers = headerLine.split(","); return rows.map((line) => { const values = line.split(","); return Object.fromEntries(headers.map((header, index) => [header, values[index] ?? ""])); }); }
function looksLikeIsoDate(value) { return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value)); }
function validateRows(rows) { const issues = []; const allowedStatus = new Set(["pass", "hold", "fail"]); for (const [index, row] of rows.entries()) { const rowNo = index + 1; for (const column of requiredColumns) { if (!(column in row) || row[column].trim() === "") issues.push({ scope: `row ${rowNo}`, severity: "block", message: `missing ${column}` }); } if (!Number.isFinite(Number(row.measured_value))) issues.push({ scope: `row ${rowNo}`, severity: "block", message: "measured_value must be numeric" }); if (!allowedStatus.has(row.status)) issues.push({ scope: `row ${rowNo}`, severity: "block", message: "status must be pass, hold, or fail" }); if (row.status !== "pass" || row.approved !== "yes") issues.push({ scope: `row ${rowNo}`, severity: "review", message: "human approval required before handoff" }); if (!looksLikeIsoDate(row.retention_until)) issues.push({ scope: `row ${rowNo}`, severity: "review", message: "retention_until must be an ISO date" }); if (/@|\b\d{2,4}[- ]\d{2,4}[- ]\d{3,4}\b|private|tmp/i.test(row.photo_uri)) issues.push({ scope: `row ${rowNo}`, severity: "review", message: "photo_uri may expose personal or temporary data" }); } return issues; }
function validateJobConfig(config) { const issues = []; if (/:latest\b/.test(config.image)) issues.push({ scope: "job.image", severity: "block", message: "pin the image tag or digest instead of latest" }); if (!config.serviceAccount || config.serviceAccount === "default") issues.push({ scope: "job.serviceAccount", severity: "block", message: "use a dedicated service account" }); for (const key of Object.keys(config.env ?? {})) { if (/(API_KEY|PASSWORD|TOKEN|SECRET)/i.test(key)) issues.push({ scope: `job.env.${key}`, severity: "block", message: "move secrets to Secret Manager references" }); } if (!config.secrets || Object.keys(config.secrets).length === 0) issues.push({ scope: "job.secrets", severity: "review", message: "list required Secret Manager references" }); if (!Number.isInteger(config.maxRetries) || config.maxRetries < 0 || config.maxRetries > 5) issues.push({ scope: "job.maxRetries", severity: "review", message: "confirm retry count with operations" }); return issues; }
const rows = parseCsv(inspectionCsv);
const report = [...validateRows(rows), ...validateJobConfig(jobConfig)];
console.table(report);
process.exitCode = report.some((item) => item.severity === "block") ? 1 : 0;
이 코드는 로컬 문자열 파싱과 고정 fixture 검증만 증명합니다. Cloud Run Job 생성 가능 여부, 서비스 계정 역할, Secret Manager 값 존재, 사진 객체 존재, 운영 배치 완료 여부는 증명하지 않습니다.
Pitfall: 흔한 원인과 구체적 수정
첫 번째 함정은 hold 행을 “나중에 누군가 보겠지”라고 넘기는 것입니다. 원인은 집계와 품질 판단을 같은 배치에 섞는 데 있습니다. 수정은 Job 입력을 만들기 전에 pass, hold, fail을 나누고, hold와 fail은 Cloud Run Job이 아니라 사람 리뷰 큐로 보내는 것입니다.
두 번째 함정은 사진 URI를 편한 메모 칸처럼 쓰는 것입니다. 작업자명, 이메일, 장비명, tmp, private가 객체 키에 들어가면 나중에 삭제와 접근 범위를 설명하기 어렵습니다. 수정은 URI를 라인, 월, 로트, 보고서 ID로 제한하고, 작업자 신원이나 판단 이유는 별도 권한 장부에 두는 것입니다.
세 번째 함정은 환경 변수와 secret을 같은 것으로 보는 것입니다. Cloud Run Jobs는 환경 변수를 쓸 수 있지만, Google Cloud는 secret을 환경 변수에 저장하지 말고 Secret Manager를 쓰라고 안내합니다. 수정은 비밀이 아닌 설정만 env에 두고 연결 문자열, API key, password, token을 secret 참조로 옮기는 것입니다.
네 번째 함정은 서비스 계정을 default로 두는 것입니다. 원인은 Job이 실행되면 권한 설계도 끝났다고 생각하는 데 있습니다. 수정은 Job 전용 서비스 계정을 만들고, Google Cloud API별 최소 역할만 부여하며, 승인자를 체크리스트에 적는 것입니다.
작은 ROI 측정
절감률을 꾸며내지 말고 막힌 작업을 셉니다. 2주 동안 CSV 행 수, block 이슈 수, 사람 확인 이슈 수, 재제출 횟수, CSV export부터 Job handoff까지의 대기 시간, 야간 호출 수를 기록합니다. 프리플라이트 도입 후 같은 항목을 다시 2주 기록합니다. 유용한 신호는 미승인 행 사전 발견, 사진 URI 수정, secret 이관 발견, 야간 전 반려 횟수입니다.
목표는 Claude Code가 항상 몇 분을 줄인다고 말하는 것이 아닙니다. 공장, 라인 수, 승인 구조, Job 빈도에 따라 달라집니다. 첫 ROI 목표는 사람이 아직 근무 중일 때 배치에 들어가면 안 되는 입력을 찾는 것입니다.
자주 묻는 질문
Q. Cloud Run Job 대신 Cloud Run 서비스를 써도 되나요.
A. 계속 HTTP 요청을 받는 처리라면 서비스가 맞습니다. CSV 묶음을 읽고 집계한 뒤 종료한다면 Job이 후보입니다. 이 글은 Cloud Run Jobs handoff 전 로컬 프리플라이트만 다룹니다.
Q. 실제 CSV를 Claude Code에 보여줘도 되나요.
A. 먼저 익명화 fixture로 열과 규칙을 고정하세요. 운영 CSV는 권한, 저장 위치, 감사 로그, 금지 열을 내부 규칙으로 확인해야 합니다. 이 글은 법무나 감사 조언이 아닙니다.
Q. 이 검증기를 CI에 넣으면 충분한가요.
A. 충분하지 않습니다. CI는 입력 계약 일부만 막습니다. 품질 승인, 서비스 ID, Secret Manager 참조, IAM, 실제 Job 로그는 별도로 확인해야 합니다.
Q. Claude Code에는 무엇을 주면 되나요.
A. 고정 fixture, 열 정의, 명명 규칙, Job JSON, 승인 체크리스트를 주세요. .env, 운영 키, 마스킹 안 된 개인정보, 공급사 계약서를 붙여넣지 마세요.
회사 운영에 넣는다면
제조업 클라우드 handoff 프리플라이트는 코드만으로 끝나지 않습니다. 품질, 운영, 정보시스템, 클라우드 관리자가 AI에 맡기는 검사와 사람이 멈추는 판단을 같은 언어로 나누어야 합니다. Cloud Run Jobs와 검사 CSV 주변의 권한 경계, 리뷰 표, 프롬프트, ROI 시트를 설계하려면 교육 및 상담을 활용할 수 있습니다.
실제로 테스트한 결과
실제로 테스트한 것은 위 JavaScript 검증기를 node로 실행하고 로컬 고정 fixture를 검사한 것입니다. 출력에서 숫자가 아닌 measured_value, 미승인 행, 잘못된 status, private와 tmp가 포함된 photo_uri, :latest 이미지, default 서비스 계정, 평문 API_KEY가 검출되는 것을 확인했습니다.
확인한 공식 URL은 Cloud Run Jobs 생성, Jobs 환경 변수, Jobs secret, Jobs 서비스 ID, Claude Code settings입니다. 실행하지 않은 것은 gcloud run jobs create, Cloud Run API 호출, Cloud Storage 읽기, Secret Manager 접근, IAM 검증, MES 연결, 운영 CSV 검사입니다. 따라서 이 글의 증거는 로컬 입력 계약을 검사했다는 데까지이며, 운영 클라우드 연동 성공 증거가 아닙니다.
관련 글
Claude Code로 GCP Cloud Run 배포하기: 실전 가이드
Docker, IAM, Secret Manager, 로그, 롤백까지 Node.js API를 Cloud Run에 안전하게 배포합니다.
소규모 공장(제조업) 작업 표준서와 도면 메모를 생성형 AI로 디지털화하는 실무 절차
베테랑 머릿속에만 있는 작업 순서와 도면 여백의 손글씨 메모. 소규모 공장(제조업) 현장에서 Claude Code로 작업 표준서와 도면 메모를 디지털화해 인수인계하는 실무 절차를 소개합니다.
Claude Code로 제조업 견적 의뢰 폼 개선하기
도면, 리비전, 재질, 수량, 납기, NDA, CTA를 정리해 견적 문의 누락을 줄입니다.
무료 PDF: Claude Code 치트시트
이메일을 입력하면 명령, 리뷰 습관, 안전한 워크플로를 정리한 PDF를 받을 수 있습니다.
개인정보를 안전하게 관리하며 스팸을 보내지 않습니다.
작성자 소개
Masa
Claude Code 실무 워크플로와 팀 도입을 검증하는 엔지니어입니다.