데이터 가져오기/내보내기 정확성을 위한 Claude Code: 실용적 단계

CSV와 JSON 가져오기에서 무엇이 잘못되는가

가져오기가 실패하는 이유는 보통 코드가 “틀려서”가 아닙니다. 실제 데이터는 지저분하고 일관성이 없으며, 여러분의 가정(assumptions)을 본 적 없는 사람이 만든 경우가 많습니다.

CSV 문제는 보통 형태(shape)와 포맷에 관한 것이고, JSON 문제는 의미와 타입에 관한 경우가 많습니다. 둘 다 작아 보이는 문제로 보이지만 혼란스러운 결과를 만들 수 있습니다.

지원 티켓에서 반복되는 이슈들:

• 필수 필드(e-mail, id, country) 누락 또는 누군가가 파일을 "정리"하면서 컬럼 이름 변경
• 이상한 날짜 형식(01/02/03, 2024-13-01, Excel 일련번호, 혼합된 시간대)
• 다른 도구가 추가한 예상치 못한 추가 컬럼 또는 중첩된 JSON 객체
• 타입 변화("00123"가 123으로, true/false가 "yes"/"no"로 변형)
• 중복 및 거의 중복(동일 id가 두 번, 또는 같은 사람의 다른 대소문자 표기)

정확성은 단순히 “가져와졌나”를 넘습니다. 어떤 결과를 허용할지 결정해야 합니다. 사용자는 조용한 실수(silent mistakes)를 시끄러운 실패보다 더 먼저 알아차립니다.

대부분의 팀은 세 가지 결과에 합의할 수 있습니다:

• Accepted: 모든 행 또는 레코드가 유효하고 가져와짐
• Rejected: 파일 전체를 신뢰할 수 없으므로 아무 것도 가져오지 않음(잘못된 헤더, 잘못된 인코딩, 읽을 수 없는 JSON 등)
• Partially accepted: 유효한 레코드는 가져오고, 유효하지 않은 레코드는 명확한 이유와 함께 건너뜀

에지 케이스는 사람들이 무엇이 잘못되었는지, 어떻게 빨리 고칠 수 있는지 모를 때 재작업으로 이어집니다. 흔한 시나리오: 고객이 5,000행짜리 CSV를 올렸는데 임포터가 "Invalid format"만 표시하면 고객은 임의로 편집해 세 번 재시도합니다. 그러면 여러 티켓과 함께 여러분 쪽에서 로컬로 파일을 재현하려는 작업이 생깁니다.

사이클을 줄이기 위한 목표를 세우세요: 재시도 감소, 빠른 수정, 예측 가능한 결과. 규칙을 작성하기 전에 ‘부분 허용(partial)’의 의미(허용 여부 포함), 행 수준 문제를 어떻게 보고할지, 사용자가 다음에 무엇을 해야 하는지(파일 편집, 필드 매핑, 수정된 버전 내보내기 등)를 결정하세요. Koder.ai(koder.ai) 같은 비브 코드 플랫폼을 사용해 검증기와 테스트를 빠르게 생성하더라도, 가져오기 계약(import contract)이 제품이 진화해도 동작을 일관되게 유지하게 합니다.

규칙을 작성하기 전에 가져오기 계약을 결정하세요

검증 규칙을 한 줄도 쓰기 전에, 제품에서 “유효한 입력”이 무엇인지 결정하세요. 대부분의 가져오기 버그는 사용자가 업로드한 것과 시스템이 묵시적으로 가정한 것 사이의 기대 불일치에서 옵니다.

먼저 형식을 명확히 하세요. “CSV”는 콤마 또는 세미콜론, 헤더 행 유무, UTF-8 또는 “엑셀이 만든 포맷”을 의미할 수 있습니다. JSON의 경우 단일 객체를 허용할지, 레코드 배열을 허용할지, JSON Lines(한 줄에 하나의 JSON 객체)를 허용할지 결정하세요. 중첩 JSON을 허용한다면 읽을 경로와 무시할 경로를 정의하세요.

그런 다음 필드 계약을 확정하세요. 각 필드에 대해 필수인지 선택인지, 또는 기본값이 있는 선택인지 결정하세요. 기본값은 구현의 세부사항이 아니라 계약의 일부입니다. country가 없으면 빈값으로 둘 것인지, 특정 국가로 기본값을 정할 것인지, 해당 행을 거부할 것인지 결정하세요.

파싱 동작은 관대하게 허용하면 장기적으로 문제를 만들기 쉽습니다. 공백 제거(trim), 대소문자 정규화, yes/true/1 같은 변형 수용 등을 얼마나 엄격하게 할지 미리 정하세요. 관대함은 예측 가능하고 문서화되어 있다면 괜찮습니다.

중복은 정확성과 신뢰에 영향을 주는 또 다른 계약 결정입니다. 무엇을 중복으로 볼지(같은 이메일, 같은 external_id, 또는 필드 조합), 어디에서 감지할지(파일 내, 기존 데이터와 비교, 또는 둘 다), 발생 시 어떻게 처리할지(첫 항목 유지, 마지막 항목 유지, 병합, 또는 거부)를 정의하세요.

사양에 붙여 넣을 수 있는 체크리스트:

• 허용 형식 및 인코딩(CSV 구분자, JSON vs JSON Lines, 중첩 지원)
• 필드 규칙(필수/선택/기본값, 허용 값)
• 정규화 규칙(공백 제거, 대소문자, 날짜/숫자 형식)
• 중복 정의 및 처리(감지 범위, 선택된 동작)
• 검증 위치(클라이언트, 서버, 또는 둘 다)

예: “customers”를 가져오는 경우. 이메일이 고유 키라면 \" [email protected] \"이 \"[email protected]\"과 같은지, 이메일 누락 시 external_id가 있을 때 허용할지, 파일 내 중복을 DB에 매치가 없어도 거부할지 등을 정하세요. 이 계약을 고정하면 UI와 API 전반에서 일관된 동작을 구현하기가 훨씬 쉬워집니다(구현이 Koder.ai이든 다른 곳이든 상관없음).

읽기 쉽고 테스트 가능한 검증 규칙

지저분한 가져오기는 보통 하나의 거대한 validate() 함수에서 시작합니다. 더 깔끔한 접근법은 이름이 명확하고 작은 함수들로 계층화하는 것입니다. 변경 검토가 쉬워지고 테스트도 작성하기 쉬워집니다.

필드 수준 규칙부터 시작하세요: 단일 값이 자체적으로 통과/실패할 수 있는 검사(타입, 범위, 길이, 허용 값, 정규식). 단조롭고 예측 가능하게 유지하세요. 예: email은 기본 이메일 패턴과 일치, age는 0~120 사이 정수, status는 active|paused|deleted 중 하나.

교차 필드 규칙은 필요한 곳에만 추가하세요. 이러한 검사는 여러 필드에 의존하므로 버그가 숨기기 쉽습니다. 전형적인 예: startDate는 endDate보다 이전이어야 한다거나 total이 subtotal + tax - discount와 일치해야 하는 규칙입니다. 이러한 규칙은 단순히 “레코드가 유효하지 않음”이 아니라 특정 필드를 가리킬 수 있게 작성하세요.

레코드 수준 규칙과 파일 수준 규칙을 분리하세요. 레코드 수준 규칙은 한 행(CSV)이나 한 객체(JSON)를 검사합니다. 파일 수준 규칙은 전체 업로드를 검사합니다: 필수 헤더 존재 여부, 고유 키가 행 전체에서 반복되는지, 열 수가 기대와 일치하는지, 파일이 지원되는 버전을 선언하는지 등.

정규화는 “마법처럼” 처리하지 말고 명시적으로 하세요. 정규화 후에 검증을 할지 문서로 남기세요. 흔한 예: 공백 제거, 유니코드 정규화(시각적으로 동일한 문자가 동일하게 비교되도록), 전화번호를 일관된 저장 형식으로 포맷.

읽기 쉬운 구조 예시:

• 정규화: 원시 입력을 정규 형태로 변환
• 필드 검증: 필드별 작고 재사용 가능한 검사
• 관계 검증: 명확한 대상(field)을 가진 교차 필드 검사
• 파일 규칙 검증: 헤더, 중복, 버전 지원 등
• 각 계층별 테스트: 규칙별 단위 테스트와 몇 가지 엔드투엔드 픽스처

규칙에 버전 번호를 붙이세요. 파일이나 API 요청에 schemaVersion(또는 import “profile”)을 넣으세요. “유효”의 의미를 변경할 때도 이전 내보내기를 이전 버전으로 다시 가져올 수 있습니다. 이 한 가지 선택이 “어제는 작동했는데” 티켓을 많이 예방합니다.

사용자가 행동할 수 있는 오류 보고 형식 설계

좋은 임포터는 도움이 되는 방식으로 실패합니다. 애매한 오류는 무분별한 재시도와 피할 수 있는 지원 업무로 이어집니다. 명확한 오류 형식은 사용자가 파일을 빠르게 고치게 돕고, 검증을 개선해도 클라이언트를 깨뜨리지 않습니다.

CSV와 JSON 전반에 걸쳐 일관된 오류 객체 구조를 사용하세요. Claude Code를 이용해 스키마 제안과 현실적인 예시를 만든 다음, 이를 가져오기 계약의 일부로 고정하세요.

안정적인 오류 객체

각 오류를 변경되지 않는 작은 레코드로 다루세요. 메시지는 바뀔 수 있지만 code와 location은 안정적이어야 합니다.

• code: REQUIRED_MISSING 또는 INVALID_DATE 같은 짧고 안정적인 식별자
• message: UI용 사용자 친화 문장
• path: 문제 위치(예: /customer/email 같은 JSON 포인터 또는 email 같은 컬럼 이름)
• row 또는 line: CSV의 경우 1-based 행 번호(선택적으로 원본 라인 포함)
• severity: 최소 error와 warning

오류를 액션 가능하게 만드세요. 기대한 값과 실제로 본 값을 포함하고 가능한 경우 통과 예시를 보여주세요. 예: 기대값 YYYY-MM-DD, 실제값 03/12/24.

UI와 디버깅을 위한 그룹화

평평한 리스트를 반환하더라도 행과 필드별로 그룹화할 수 있는 충분한 데이터를 포함하세요. 많은 UI는 “행 12에 3개의 이슈가 있음”처럼 보여주고 각 컬럼을 강조합니다. 지원팀은 패턴(예: 모든 행에서 country가 누락) 파악에 그룹화를 선호합니다.

압축된 응답 예시:

{
  "importId": "imp_123",
  "status": "failed",
  "errors": [
    {
      "code": "INVALID_DATE",
      "message": "Signup date must be in YYYY-MM-DD.",
      "path": "signup_date",
      "row": 12,
      "severity": "error",
      "expected": "YYYY-MM-DD",
      "actual": "03/12/24"
    },
    {
      "code": "UNKNOWN_FIELD",
      "message": "Column 'fav_colour' is not recognized.",
      "path": "fav_colour",
      "row": 1,
      "severity": "warning"
    }
  ]
}

오류 코드는 지역화 없이 유지하세요. message는 번역 가능하도록 취급하고, 나중에 messageKey나 번역된 메시지를 추가하더라도 오래된 클라이언트는 동일한 코드로 필터링, 그룹화, 분석할 수 있게 하세요.

성공 및 실패 시 가져오기 API가 반환해야 할 것

“수상한 가져오기(mystery imports)”를 피하려면 API 응답이 두 가지 질문에 답해야 합니다: 무슨 일이 일어났는가, 사용자는 다음에 무엇을 해야 하는가.

항상 명확한 가져오기 요약 반환(항상)

오류가 있어도 UI와 지원 툴이 동일하게 처리할 수 있도록 일관된 요약을 반환하세요.

포함 항목:

• created, updated, skipped, failed 카운트
• totalRows(또는 JSON의 경우 totalRecords)
• mode(예: createOnly, upsert, updateOnly)
• startedAt, finishedAt 타임스탬프
• 지원에서 조회할 수 있는 correlationId

correlationId는 매우 유용합니다. “가져와지지 않았다”는 신고가 오면 정확한 실행과 오류 보고서를 찾아낼 수 있습니다.

액션 가능한 오류와 전체 리포트를 가져오는 방법 제공

10,000개의 행 오류를 응답에 모두 넣지 마세요. 패턴을 보여주는 작은 샘플(예: 20개)을 반환하고 전체 리포트를 별도로 조회하도록 하세요.

각 오류는 구체적이고 안정적이어야 합니다:

• 위치: 행 번호(CSV) 또는 JSON 포인터 같은 경로(JSON)
• 필드명
• 오류 코드(머신 리더블)
• 메시지(사람 친화적)
• 거부된 값(민감한 데이터는 주의)

완료됐지만 일부 행 실패가 있는 예시 응답 형태:

{
  "importId": "imp_01HZY...",
  "correlationId": "c_9f1f2c2a",
  "status": "completed_with_errors",
  "summary": {
    "totalRows": 1200,
    "created": 950,
    "updated": 200,
    "skipped": 10,
    "failed": 40
  },
  "errorsSample": [
    {
      "row": 17,
      "field": "email",
      "code": "invalid_format",
      "message": "Email must contain '@'.",
      "value": "maria.example.com"
    }
  ],
  "report": {
    "hasMore": true,
    "nextPageToken": "p_002"
  },
  "next": {
    "suggestedAction": "review_errors"
  }
}

next 필드를 제공하세요. 최소한의 성공 페이로드도 제품이 다음 단계로 나아가게 도와야 합니다: 검토 화면 표시, 재시도 제안, 또는 가져온 컬렉션 열기 등.

재시도 시 중복 생성이 없도록 idempotency 정의

사람은 재시도합니다. 네트워크는 실패합니다. 동일 파일을 두 번 가져오면 예측 가능한 결과가 필요합니다.

idempotency를 명확히 하세요: idempotencyKey를 받거나 파일 해시를 계산하고, 동일 요청이면 기존 importId를 반환하세요. 모드가 upsert라면 매칭 규칙(예: 이메일이 고유 키)을 정의하세요. create-only라면 중복은 created가 아닌 skipped로 처리하세요.

실패 시 올바른 상태 코드 사용, 그러나 형식은 안정적으로 유지

요청 자체가 잘못된 경우(인증 오류, 잘못된 컨텐츠 타입, 읽을 수 없는 파일)에는 빠르게 실패시키고 status: "rejected"와 간단한 오류 목록을 반환하세요. 파일은 유효하지만 행 수준 문제가 있다면 failed > 0인 완료된 작업으로 처리해 사용자가 요약을 잃지 않고 파일을 수정해 다시 업로드할 수 있게 하세요.

Claude Code를 사용해 규칙과 예시를 생성하는 방법

유용한 습관: 모델에게 서술형 문장 대신 구조화된 형식으로 계약을 작성하게 하세요. “도움이 되는 단락”은 공백 제거 규칙, 기본값, 빈 셀이 “누락”인지 “빈값”인지 같은 세부를 놓치기 쉽습니다.

사람이 빠르게 검토하고 개발자가 코드로 옮길 수 있는 표를 만들도록 프롬프트하세요. 각 필드의 규칙, 통과 예시와 실패 예시, 모호한 부분에 대한 명시적 메모를 요청하세요(예: 빈 문자열 vs null).

You are helping design an importer for CSV and JSON.
Output a Markdown table with columns:
Field | Type | Required? | Normalization | Validation rules | Default | Pass examples | Fail examples
Rules must be testable (no vague wording).
Then output:
1) A list of edge cases to test (CSV + JSON).
2) Proposed test names with expected result (pass/fail + error code).
Finally, list any contradictions you notice (required vs default, min/max vs examples).

첫 초안 후에는 각 규칙에 대해 긍정 예시와 부정 예시를 하나씩 더 요청하세요. 이렇게 하면 빈 문자열, 공백만 있는 값, 컬럼 누락, null vs "null", 매우 큰 정수, 지수 표기법, 중복 ID, 추가 JSON 필드 같은 까다로운 구석을 더 잘 커버할 수 있습니다.

예를 들어 CSV에서 “customers”를 가져오는 시나리오: email은 필수, phone은 선택, signup_date는 누락 시 오늘 날짜로 기본값을 주는 경우. 모델은 여러분이 동시에 "signup_date는 필수"라고 명시하면 모순을 지적해야 합니다. 또한 import_customers_missing_email_returns_row_error 같은 테스트 이름을 제안하고 반환할 오류 코드와 메시지 형태까지 지정하게 하세요.

구현 전에 한 번 더 검토하세요: 모델에게 규칙을 체크리스트 형태로 다시 작성하게 하고 기본값, 필수 필드, 정규화가 충돌할 수 있는 지점을 지적하게 하세요. 이 검토 단계가 많은 티켓성 동작을 잡아냅니다.

단계별: CSV 및 JSON 가져오기를 위한 퍼즈 테스트

퍼즈 테스트는 “이상한 파일”이 지원 티켓으로 이어지는 일을 막습니다. 소수의 정상 CSV/JSON 파일에서 시작해 수천 개의 약간씩 손상된 변형을 생성하고 임포터가 안전하고 명확하게 반응하는지 확인하세요.

시드 집합을 만들고 변형 생성

작고 현실적인 시드 코퍼스(valid examples)를 준비하세요: 가장 작은 유효 파일, 일반적인 파일, 큰 파일. JSON의 경우 단일 객체, 다수 객체, 중첩 구조(지원할 경우)를 포함하세요.

그다음 자동 변형기(mutator)를 추가해 한 번에 한 가지씩만 건드리세요. 무작위 시드(random seed)를 기록해 실패를 재현할 수 있게 하세요.

퍼즈의 주요 축:

• 인코딩 문제: BOM이 있는 UTF-8, 잘못된 바이트 시퀀스, 혼합된 유니코드 정규화
• 구조 문제: 헤더 누락, 추가 컬럼/필드, 잘못된 구분자, 후행 쉼표
• 인용과 개행: 닫히지 않은 따옴표, 내장 개행, CRLF vs LF, 일관성 없는 이스케이프
• 타입 엣지: 매우 큰 정수, NaN/Infinity(JSON), 빈 문자열 vs null, 공백 패딩
• 크기 및 한계: 매우 긴 필드, 많은 행, 반복 키, 깊게 중첩된 배열

문법적 문제에서 멈추지 말고 의미적 퍼즈도 추가하세요: 유사 필드 교환(email vs username), 극단적 날짜, 중복 ID, 음수 수량, 열거형을 위반하는 값 등.

“통과” 기준을 정의하고 고정

퍼즈 테스트는 통과 기준이 엄격해야 도움이 됩니다. 임포터는 절대 크래시나 멈춤(hang)을 일으키지 않아야 하고, 오류는 일관되고 액션 가능해야 합니다.

실용적인 통과 규칙:

• 크래시, 타임아웃, 허용 메모리 한계 초과 없음
• 행/필드 포인터(CSV) 또는 JSON 경로와 함께 명확한 오류 반환
• 동일 실패에 대해 실행 간에 안정적인 오류 코드
• 부분 성공을 명시적으로 지원하지 않으면 부분 쓰기 없음
• 공백 같은 무해한 포맷 차이(예: 공백)에는 동일한 결과

이 테스트들을 CI에서 모든 변경 시마다 실행하세요. 실패를 찾으면 정확한 파일을 픽스처로 저장하고 회귀 테스트로 추가하세요.

Claude Code를 사용한다면, 계약에 맞는 시드 픽스처, 변형 계획, 예상 오류 출력을 생성하게 하세요. 규칙은 여전히 여러분이 선택하지만, 특히 CSV 인용과 JSON 코너 케이스에서 넓은 테스트 표면을 빠르게 확보할 수 있습니다.

반복되는 지원 티켓을 유발하는 흔한 함정

대부분의 가져오기 티켓은 불분명한 규칙과 도움이 되지 않는 피드백에서 옵니다.

흔한 함정은 문서화되지 않은 “최선의 시도(best effort)” 파싱입니다. 임포터가 공백을 묵인하거나 쉼표와 세미콜론을 모두 허용하거나 날짜 형식을 추측하면 사용자는 그 추측에 기반해 워크플로를 만들게 됩니다. 그러다 작은 변경이나 다른 파일 생성기가 들어오면 모든 것이 깨집니다. 동작을 선택하고 문서화하고 테스트하세요.

또 다른 반복 문제는 일반적인 오류 메시지입니다. "Invalid CSV"나 "Bad request"는 사용자가 추측하게 만듭니다. 같은 파일을 다섯 번 올리고도 지원팀이 파일을 요청하게 됩니다. 오류는 행, 필드, 명확한 이유, 안정적인 코드까지 가리켜야 합니다.

하나의 잘못된 행 때문에 파일 전체를 실패시키는 것도 자주 문제를 만듭니다. 금융 관련 임포트처럼 부분이 위험한 경우가 있지만, 많은 비즈니스 임포트는 요약을 제공하고 계속할 수 있습니다. strict 모드 vs partial import 같은 명시적 선택지를 제공하세요.

텍스트 인코딩 문제는 끈질긴 티켓을 만듭니다. 기본은 UTF-8로 하되 실제 CSV는 BOM, 곱따옴표(curly quotes), 스프레드시트에서 복사된 비분리 공백 등을 포함합니다. 이런 것들을 일관되게 처리하고 감지한 내용을 보고해 사용자가 내보내기 설정을 고칠 수 있게 하세요.

마지막으로, 릴리스 간에 오류 코드가 변경되면 클라이언트와 자동화가 깨집니다. 문구는 개선하되 코드와 의미는 안정적으로 유지하세요. 정말 필요할 때만 버전 관리를 도입하세요.

방지해야 할 함정들:

• 시간이 지나면서 바뀌는 문서화되지 않은 “최선의 시도” 파싱
• 행/필드 포인터와 안정적인 오류 코드가 없는 오류
• strict vs partial 옵션 없는 전부 실패 방식
• UTF-8, BOM, 보이지 않는 문자 처리가 일관되지 않음
• 릴리스 간 오류 코드 변경으로 클라이언트 처리 깨짐

예: 고객이 Excel에서 CSV를 내보내면 BOM을 추가하고 날짜를 03/04/2026으로 포맷할 수 있습니다. 임포터가 MM/DD로 추측하지만 고객은 DD/MM을 기대했다면 문제가 생깁니다. 오류 리포트에 감지한 형식, 정확한 필드, 제안된 수정이 포함되어 있다면 사용자는 바로 고칠 수 있습니다.

임포터를 배포하기 전 빠른 체크리스트

대부분의 가져오기 문제는 사용자가 파일을 어떻게 해석하는지와 시스템이 그것을 어떻게 받아들이는지의 작은 불일치입니다. 이를 릴리스 게이트로 다루세요.

• 헤더와 필드 이름: 필수 컬럼이 있는지, 이름이 규칙에 맞는지, 중복이 거부되는지 확인하세요. 추가 컬럼에 대해서는 무시, 경고, 실패 중 일관된 정책을 정하세요.
• 데이터 타입과 포맷: 정수 vs 소수, 불리언(true/false, 0/1, yes/no), 날짜와 타임스탬프(타임존 규칙) 파싱 규칙을 고정하세요. 필드당 하나의 허용 형식을 선호하세요.
• 널과 누락 값: 빈 문자열이 필드마다 무엇을 의미하는지 정의하세요. 필드 누락, 명시적 null, 빈 텍스트를 구분하세요.
• 크기 및 안전 한계: 파일 크기, 최대 행 수, 필드 최대 길이 제한을 설정하세요. 조기에 실패시키고 명확한 메시지를 제공하세요.
• 결정적 오류: 동일한 잘못된 입력은 항상 동일한 오류 코드와 메시지 형태를 반환해야 합니다.

실용적 테스트: 의도적으로 지저분한 파일 하나를 사용하세요. 예: 헤더가 두 번 나타나는 CSV(두 개의 “email” 컬럼), 불리언 필드가 "Y"를 사용, 날짜가 "03/04/05"인 경우. 임포터는 추측하지 말고 문서화된 매핑 규칙을 적용하거나 구체적인 오류로 거부해야 합니다.

팀이 자주 놓치는 두 가지 검사:

첫째, 임포터가 소스 파일을 수정할 수 있을 정도의 위치 정보를 제공하는지 확인하세요. "Invalid date"는 도움되지 않습니다. "Row 42, column start_date: expected YYYY-MM-DD, got 03/04/05"는 행동을 유도합니다.

둘째, 동일한 잘못된 파일을 두 번 실행해 결과를 비교하세요. 오류 순서가 변경되거나 코드가 바뀌거나 행 번호가 흔들리면 사용자는 신뢰를 잃습니다. 결정적(deterministic) 동작이 지루해 보여도 그게 목적입니다.

현실적인 예시 시나리오와 다음 단계

현실적인 가져오기 예시는 오래된 시스템에서 내보낸 주문(order) 스프레드시트입니다. 누군가가 CSV를 내보내고 Excel에서 편집한 후 업로드합니다. 지원 티켓은 임포터가 데이터를 묵묵히 "수정"했거나 오류 메시지가 무엇을 바꿔야 하는지 말해주지 않을 때 주로 발생합니다.

파일 이름이 orders.csv이고 컬럼이 order_id,customer_email,order_date,currency,total_amount라고 가정합시다.

사용자가 보는 세 가지 현실적인 잘못된 행 예시:

order_id,customer_email,order_date,currency,total_amount
A-1001,[email protected],2026-01-05,USD,129.99
A-1002,not-an-email,01/06/2026,USD,49.00
,[email protected],2026-01-07,US, -10

2행은 이메일이 잘못됐고 날짜 형식이 애매합니다. 3행은 order_id가 비어있고, 지원되지 않는 통화 코드(US 대신 USD)가 있으며, 총액이 음수입니다.

API가 오류를 반환한다면 형태를 일관되게 유지하고 구체적으로 만드세요. 부분 성공을 지원하는 예시 응답:

{
  "correlation_id": "imp_20260109_7f3a9d",
  "import_id": "ord_01HZZ...",
  "status": "partial_success",
  "summary": {
    "total_rows": 3,
    "imported_rows": 1,
    "failed_rows": 2
  },
  "errors": [
    {
      "row_number": 2,
      "field": "customer_email",
      "code": "invalid_email",
      "message": "Email must contain a valid domain.",
      "value": "not-an-email"
    },
    {
      "row_number": 2,
      "field": "order_date",
      "code": "invalid_date_format",
      "message": "Use ISO-8601 (YYYY-MM-DD).",
      "value": "01/06/2026"
    },
    {
      "row_number": 3,
      "field": "order_id",
      "code": "required",
      "message": "order_id is required.",
      "value": ""
    },
    {
      "row_number": 3,
      "field": "currency",
      "code": "unsupported_currency",
      "message": "Allowed values: USD, EUR, GBP.",
      "value": "US"
    },
    {
      "row_number": 3,
      "field": "total_amount",
      "code": "must_be_positive",
      "message": "total_amount must be greater than 0.",
      "value": " -10"
    }
  ],
  "retry": {
    "mode": "upload_failed_only",
    "failed_row_numbers": [2, 3]
  }
}

부분 성공은 사용자가 전체 파일을 다시 업로드할 필요가 없게 합니다. 간단한 재시도 흐름: 실패한 행만 수정해 작은 CSV(행 2와 3만 포함)를 내보내 재업로드하세요. order_id가 있으면 임포터는 idempotent하게 동작해 재시도가 같은 레코드를 업데이트하도록 처리해야 중복 생성이 발생하지 않습니다.

지원에서 correlation_id는 진단의 가장 빠른 경로입니다. 지원 담당자는 이 값을 요청해 로그에서 정확한 실행을 찾아 파서가 추가 컬럼을 봤는지, 잘못된 구분자를 사용했는지, 예기치 않은 인코딩을 감지했는지 확인할 수 있습니다.

다음 단계로 반복 가능한 결과를 만들기:

• Claude Code를 사용해 검증 규칙, 잘못된 행 예시, 표준화할 오류 코드/메시지를 생성하세요.
• 그 예시들을 자동화된 테스트(퍼즈 테스트 포함)로 전환해 새로운 에지 케이스가 티켓이 아닌 실패하는 테스트가 되게 하세요.
• Koder.ai로 빌드한다면 플래닝 모드로 import contract를 설계하고, 검증기와 테스트를 생성한 뒤 오류 출력이 CSV와 JSON 전반에서 일관되도록 반복하세요.