CLI 자동화가 실패할 때 먼저 확인할 것들

CLI 자동화를 만들다 보면 처음에는 잘 되다가 어느 순간 멈춥니다. 파일 하나가 예상과 다르거나, 권한이 없거나, 경로가 바뀌었거나, 조건을 너무 넓게 잡아서 엉뚱한 대상까지 처리하기도 합니다.

이때 가장 안 좋은 대응은 전체를 처음부터 다시 만드는 것입니다. 자동화 실패는 대부분 한 지점에서 시작됩니다. 먼저 해야 할 일은 그 지점을 찾는 것입니다.

전체가 아니라 멈춘 단계를 본다

자동화는 보통 여러 단계로 나뉩니다.

1. 입력 파일을 찾는다
2. 내용을 읽거나 변환한다
3. 조건에 맞는지 판단한다
4. 결과를 저장하거나 전송한다
5. 필요하면 다음 작업을 실행한다

실패했을 때는 “자동화가 안 된다”가 아니라 “몇 번째 단계에서 멈췄는가”로 봐야 합니다.

예를 들어 PDF를 텍스트로 뽑고 AI에게 요약을 맡기는 흐름이라면, 문제는 AI 요약이 아닐 수 있습니다. PDF에서 텍스트가 제대로 안 뽑혔거나, 파일 경로가 틀렸거나, 빈 파일을 AI에게 넘겼을 수도 있습니다.

로그를 먼저 남긴다

입문자가 만든 스크립트는 실패했을 때 조용히 끝나는 경우가 많습니다. 그러면 어디서 멈췄는지 알 수 없습니다.

처음에는 멋진 로깅 도구가 없어도 됩니다. 단계마다 현재 무엇을 하는지 출력해도 충분합니다.

echo "1. 입력 파일 확인"
echo "2. 텍스트 추출 시작"
echo "3. 결과 파일 저장"

이런 단순한 출력만 있어도 어느 지점까지 갔는지 알 수 있습니다. 나중에 익숙해지면 로그 파일로 남기거나, 실패한 명령의 종료 코드를 확인하면 됩니다.

입력 데이터가 예상과 다른지 확인한다

자동화는 입력이 늘 같은 모양일 거라고 가정하기 쉽습니다. 하지만 실제 파일과 데이터는 자주 예외를 만듭니다.

• 파일명이 다르다
• 확장자가 대문자다
• 빈 파일이 섞여 있다
• 줄바꿈 방식이 다르다
• 한글 인코딩이 깨진다
• CSV 열 개수가 예상과 다르다
• PDF가 텍스트가 아니라 스캔 이미지다

특정 파일에서만 멈춘다면 그 파일 하나를 따로 열어 보세요. 전체 흐름이 아니라 그 입력이 다른 점을 찾는 것이 빠릅니다.

권한과 경로를 확인한다

리눅스와 WSL에서는 권한과 경로 문제도 흔합니다.

스크립트가 파일을 못 읽거나 못 쓰면 먼저 아래를 봅니다.

pwd
ls -l

현재 어느 폴더에서 실행 중인지, 파일 권한이 어떤지 확인합니다. 상대경로를 썼다면 실행 위치가 바뀌는 순간 다른 파일을 보게 됩니다.

특히 cron이나 백그라운드 작업으로 돌릴 때는 평소 터미널에서 실행할 때와 환경이 다를 수 있습니다. PATH, 작업 디렉터리, 환경변수가 다르면 같은 명령도 실패할 수 있습니다.

조건이 너무 넓거나 좁은지 본다

자동화 조건도 자주 문제를 만듭니다.

예를 들어 파일명을 기준으로 처리한다면 조건이 너무 넓어서 원치 않는 파일까지 잡을 수 있습니다. 반대로 너무 좁으면 처리해야 할 파일을 놓칩니다.

• *.pdf만 처리한다고 했는데 대문자 .PDF는 빠진다
• report가 들어간 파일만 찾다가 old_report_backup.pdf까지 처리한다
• 날짜 조건이 현지 시간과 UTC 차이 때문에 어긋난다
• “완료”라는 단어를 기준으로 잡았는데 다른 문맥에도 등장한다

조건은 처음부터 실제 적용하지 말고, 먼저 대상 목록만 출력해 보는 편이 안전합니다.

find . -name "*.pdf" -print

삭제나 이동 전에 “무엇이 대상이 되는지”를 눈으로 확인하면 사고를 줄일 수 있습니다.

되돌리기 어려운 동작은 마지막에 붙인다

자동화에서 가장 위험한 동작은 되돌리기 어려운 동작입니다.

• 파일 삭제
• 원본 덮어쓰기
• 메일 자동 발송
• 외부 API에 실제 데이터 전송
• 데이터베이스 업데이트

처음부터 이런 동작을 켜두면 실패했을 때 피해 범위가 커집니다. 가능하면 처음에는 dry-run 방식으로 “무엇을 할 예정인지”만 출력하게 만드세요.

echo "삭제 예정: $file"
# rm "$file"  # 검증 전에는 주석 처리

확신이 생긴 뒤에 실제 동작을 켜도 늦지 않습니다.

AI 워크플로우도 중간 결과를 남긴다

AI 도구를 연결한 자동화도 결국 입력과 출력의 흐름입니다.

예를 들어 이런 구조라면:

1. PDF에서 텍스트 추출
2. 추출 텍스트 정리
3. AI에게 요약 요청
4. 요약 결과를 마크다운으로 저장

각 단계의 중간 결과를 남기는 것이 좋습니다. 그래야 요약이 이상할 때 원인을 나눠 볼 수 있습니다.

• PDF 추출이 문제인지
• 전처리에서 내용이 사라졌는지
• AI 프롬프트가 모호한지
• 저장 단계에서 깨졌는지

AI가 들어가면 결과가 그럴듯해 보여서 오히려 원인을 놓치기 쉽습니다. 그래서 더더욱 중간 파일과 로그가 필요합니다.

정리

CLI 자동화가 실패했을 때는 전체를 다시 만들기보다 실패한 단계를 좁혀야 합니다. 입력 데이터, 권한과 경로, 조건, 환경 차이, 되돌리기 어려운 동작을 차례로 보면 대부분 원인이 드러납니다.

자동화는 한 번에 완성되는 일이 아닙니다. 처음에는 로그를 남기고, dry-run으로 확인하고, 중간 결과를 보존하는 식으로 안전하게 키워 가는 편이 좋습니다. 특히 AI 워크플로우는 결과가 그럴듯해 보일 수 있으니, AI가 무엇을 입력으로 받았는지부터 확인하는 습관이 중요합니다.