일본어 업무용 CSV 데이터의 오류를 검출하는 CLI를 만들었습니다

서론

Google Sheets나 Excel로 만든 CSV를 AI, Google Apps Script, 사내 도구, 자동화 스크립트에 전달하기 전에 체크하는 CLI를 만들었습니다.

이름은 sheetlint-jp입니다.

npx sheetlint-jp data.csv

GitHub:

npm:

만든 이유

AI에게 CSV 처리를 요청할 때, AI의 코드가 틀리기 이전에 입력 CSV 자체가 망가져 있는 경우가 있습니다.

예를 들어:

• 반각 스페이스(Half-width space)와 전각 스페이스(Full-width space)가 섞여 있음
• 제로 너비 공백(Zero-width space)이 포함되어 있음
• 헤더(Header)가 중복됨
• 행마다 열(Column) 수가 어긋남
• 우편번호나 전화번호 형식이 깨져 있음
• 금액 열에 確認中(확인 중)이나 三千円(3천 엔) 같은 값이 들어 있음
• 키(Key) 열이 중복됨

사람이 보면 대충 읽을 수 있어도, AI나 스크립트에 전달하면 별개의 데이터로 취급되거나 임포트(Import) 처리가 깨지게 됩니다.

sheetlint-jp로 할 수 있는 것

MVP(Minimum Viable Product)에서는 다음 체크에 대응합니다.

• 빈 셀 검출
• 헤더 중복 검출
• 행별 열 수 불일치 검출
• 전각·반각 스페이스 혼재 검출
• 불가시 문자(Invisible character) 검출
• 중복 행 검출
• 우편번호 형식 체크
• 전화번호 형식 체크
• 금액 열로 추정되는 열의 수치 체크
• 키 열의 중복 체크

사용법

npx sheetlint-jp examples/bad-sample.csv

Markdown 리포트로 만드는 경우:

npx sheetlint-jp examples/bad-sample.csv --format markdown --output report.md

키 열의 중복을 보고 싶은 경우:

npx sheetlint-jp data.csv --key 駐車場名,区画番号

Schema JSON도 사용할 수 있습니다.

npx sheetlint-jp data.csv --schema schema.json

AI에게 전달하기 전의 사용법

먼저 CSV를 체크합니다.

npx sheetlint-jp customer-import.csv --schema schema.json --format markdown --output report.md

그 후에, Codex나 Claude Code에 다음과 같이 의뢰합니다.

먼저 report.md를 읽어주세요.
CSV의 위험한 행을 확인한 뒤에, 임포트 처리를 작성해 주세요.

AI에게 직접 CSV 처리를 맡기는 것보다, 데이터가 깨져 있다는 전제를 먼저 공유할 수 있어 안전합니다.

로컬 퍼스트 (Local-first)

sheetlint-jp는 로컬에서 동작합니다.

CSV의 내용을 외부 서비스로 전송하지 않습니다.

업무용 CSV에는 고객 정보나 사내 정보가 포함되기 쉬우므로, 이 점을 중요하게 생각하고 있습니다.

향후 하고 싶은 것

• XLSX 읽기
• CSV 문자 코드 힌트
• 설정 파일
• 주소나 법인 번호 등 일본 맞춤형 체크
• GitHub Actions를 통한 CSV 품질 체크 예시

마치며

AI에게 일을 시키기 전에 입력 데이터가 깨져 있지 않은지 확인하는 것.

수수한 작업이지만, AI 시대의 업무 자동화에서는 중요한 전처리(Preprocessing)라고 생각합니다.

혹시 흥미로우시다면 Star나 Issue를 남겨주시면 감사하겠습니다.

Discussion