Claude Code 블로그 자동화 파이프라인 오류 해결법

트러블슈팅

Claude Code로 블로그 글을 자동 생성하는 파이프라인을 구축하면서 실제로 부딪힌 오류들과 해결법을 단계별로 정리했습니다. 데이터 전달 구조부터 이미지 경로, 인코딩, 디버깅 전략까지 실전 경험을 담았습니다.

📌 3줄 요약

• 파이프라인 단계 간 JSON 키 불일치와 경로 오류가 가장 흔한 구조 문제이며, 입출력 스키마 문서화와 pathlib 사용으로 예방할 수 있습니다.
• 서브에이전트 호출 시 타임아웃 설정과 text=True 옵션 누락이 실패의 80% 이상을 차지합니다.
• 중간 산출물 파일 저장, 로그 기록, 글 단위 예외 처리로 파이프라인 전체 안정성을 확보할 수 있습니다.

📑 목차

• 파이프라인 설계 단계에서 먼저 부딪히는 구조 문제
• 초안 생성 중 서브에이전트 호출 오류 대처법
• 이미지 생성과 파일 저장에서 발생하는 경로 오류 잡기
• 파이프라인 전체 안정화를 위한 디버깅 전략

파이프라인 설계 단계에서 먼저 부딪히는 구조 문제

Claude Code로 블로그 글을 자동 생성하는 파이프라인을 만들 때, 가장 먼저 부딪히는 문제는 단계 간 데이터 전달 구조입니다. 글감 선정 → 초안 작성 → 품질 검증 → 저장이라는 흐름을 코드로 옮기려면, 각 단계의 입력과 출력 형식을 정확히 맞춰야 합니다.

예를 들어 글감 선정 결과를 JSON 파일로 저장하고, 다음 단계에서 그 파일을 읽어 초안을 작성하는 구조를 생각해 봅시다. 이때 JSON 파일의 키 이름이 단계마다 다르면 파이프라인 전체가 멈춥니다.

🔍 스키마(Schema)란?

실제로 step1_topic.json에 title 키로 제목을 저장했는데, 초안 작성 단계에서 topic_title이라는 키를 찾으려 해서 KeyError가 발생하는 경우가 흔합니다. 이 문제를 예방하려면 파이프라인 시작 전에 각 단계의 입출력 스키마(schema)를 문서로 정리해 두는 것이 좋습니다. 스키마 문서에는 각 JSON 파일의 키 이름, 데이터 타입, 필수 여부를 명시해 두면 나중에 단계를 추가하거나 수정할 때도 혼란이 줄어듭니다. 팀으로 작업하는 경우라면 이 스키마 문서가 곧 API 명세서 역할을 하기 때문에 더욱 중요합니다.

 

또 하나 자주 발생하는 문제는 작업 디렉토리 경로 불일치입니다. Windows 환경에서는 역슬래시(\)와 슬래시(/)가 섞여 경로 오류가 발생하기 쉽습니다.

⚠️ 주의

output/drafts/ 폴더가 존재하지 않는 상태에서 파일을 저장하려 하면 FileNotFoundError가 납니다. 파이프라인 시작 시점에 os.makedirs(output_dir, exist_ok=True)로 필요한 폴더를 미리 생성해 두면 이 문제를 피할 수 있습니다.

💡 팁

경로 관련 문제를 근본적으로 방지하려면 Python의 pathlib 모듈을 사용해 OS에 관계없이 일관된 경로 처리를 하는 것도 좋은 방법입니다. Path('output') / 'drafts'처럼 작성하면 Windows든 Mac이든 알아서 올바른 구분자를 사용해 줍니다.

💬 제가 직접 파이프라인을 설계해 보니, 처음부터 완벽한 구조를 잡으려 하기보다 2~3단계짜리 최소 파이프라인을 먼저 돌려보는 게 훨씬 효율적이었습니다. 전체 흐름을 한 번에 구현하면 어디서 문제가 생겼는지 찾기가 어렵기 때문입니다.

초안 생성 중 서브에이전트 호출 오류 대처법

파이프라인에서 Claude Code의 서브에이전트(subagent)를 호출해 초안을 작성시키는 구조를 쓸 때, 가장 빈번한 오류는 서브에이전트 응답 타임아웃입니다. 3,000자 이상의 긴 글을 생성하도록 요청하면, 기본 타임아웃 시간을 초과하는 경우가 발생합니다.

이 문제는 subprocess 모듈로 Claude CLI를 호출할 때 timeout 파라미터를 넉넉히 설정하면 해결됩니다. 보통 초안 생성에는 60~120초 정도를 잡아두는 것이 안전합니다. 타임아웃 값을 너무 짧게 잡으면 긴 글 생성 시 매번 실패하고, 너무 길게 잡으면 진짜 오류가 발생했을 때 불필요하게 오래 기다리게 됩니다. 상황에 따라 글 길이별로 타임아웃을 다르게 설정하는 것도 실용적인 방법입니다.

result = subprocess.run(
    ["claude", "--print", "-p", prompt],
    capture_output=True, text=True, timeout=120
)

⚠️ 반드시 주의

text=True 옵션을 빠뜨리면 출력이 바이트(bytes) 형식으로 돌아와서, 이후 문자열 처리 단계에서 TypeError가 발생합니다. 이 오류는 에러 메시지만 봐서는 원인을 파악하기 어렵기 때문에, 처음 코드를 작성할 때 반드시 text=True를 포함하는 습관을 들여야 합니다.

또 다른 흔한 문제는 서브에이전트가 마크다운 형식이 아닌 일반 텍스트로 응답하는 경우입니다. 프롬프트에 출력 형식을 명시하지 않으면 서브에이전트가 자유 형식으로 답변하기 때문입니다.

💡 팁

이를 방지하려면 프롬프트 맨 끝에 반드시 마크다운 형식으로만 출력하세요. 설명 없이 마크다운만 출력합니다.라는 지시를 추가합니다. CLAUDE.md 파일에 이 규칙을 적어두면 매번 프롬프트에 반복하지 않아도 됩니다. 서브에이전트가 코드 블록 바깥에 부가 설명을 붙이는 경우도 있으므로, 응답을 파싱할 때 마크다운 본문만 추출하는 후처리 로직을 추가해 두면 더 안정적입니다.

 

💬 제가 직접 써보니, 서브에이전트 호출 실패의 80% 이상이 타임아웃 아니면 출력 형식 불일치였습니다. 이 두 가지만 잡아도 파이프라인 안정성이 크게 올라갑니다.

이미지 생성과 파일 저장에서 발생하는 경로 오류 잡기

초안이 완성된 뒤, 캡처 포인트를 실제 이미지로 변환하는 단계에서도 오류가 자주 발생합니다. 대표적인 문제는 이미지 저장 경로와 마크다운 참조 경로의 불일치입니다.

이미지 생성 스크립트가 output/drafts/20260806_slug_images/ 폴더에 PNG 파일을 저장합니다. 그런데 마크다운 초안에서 ![alt](images/capture1.png)처럼 다른 경로를 참조하면, 티스토리 업로드 시 이미지가 누락됩니다. 이 문제가 까다로운 이유는 로컬에서 미리보기할 때는 정상적으로 보이는데, 실제 업로드 단계에서만 이미지가 빠지는 경우가 있기 때문입니다. 따라서 이미지 경로는 반드시 상대 경로가 아닌 스크립트가 생성하는 실제 경로와 일치하도록 관리해야 합니다.

이 문제를 해결하려면 이미지 생성 후 마크다운 파일 내 경로를 자동으로 업데이트하는 로직이 필요합니다. capture_generator.py가 이 작업을 자동 처리하지만, 스크립트를 직접 만들 때는 re.sub()으로 [캡처] 마커를 실제 이미지 경로로 치환하면 됩니다.

import re
content = re.sub(
    r'> \[캡처\] (.+)',
    lambda m: f'![{m.group(1)}]({image_dir}/{filename}.png)',
    content
)

 

파일 저장 단계에서는 인코딩 문제도 빈번합니다. 한글이 포함된 마크다운 파일을 저장할 때 encoding='utf-8'을 명시하지 않으면 Windows 환경에서 cp949 인코딩이 기본 적용되어 글자가 깨집니다.

with open(filepath, 'w', encoding='utf-8') as f:
    f.write(content)

⚠️ 주의

이 한 줄만 빠뜨려도 티스토리에 올린 글이 전부 깨진 문자로 보입니다. 사소해 보이지만 가장 당황스러운 오류 중 하나입니다. 파일을 읽을 때도 마찬가지로 encoding='utf-8'을 명시해야 하며, open() 함수를 사용하는 모든 곳에 일관되게 적용하는 것이 안전합니다.

 

💬 제가 직접 파이프라인을 운영해 보니, 이미지 관련 오류는 파이프라인 전체를 한 번 끝까지 돌려봐야 발견되는 경우가 많았습니다. 그래서 이미지 검증 스크립트(validate_images.py)를 별도로 만들어 PNG 누락 여부를 자동 감지하도록 구성했습니다.

파이프라인 전체 안정화를 위한 디버깅 전략

파이프라인의 개별 단계를 모두 수정해도, 전체를 이어 붙이면 새로운 문제가 생기기 마련입니다. 이때 가장 효과적인 디버깅 전략은 각 단계의 중간 산출물을 파일로 남기는 것입니다.

🔍 중간 산출물 파일 전략

step1_topic.json, step2_draft.md, step3_review.json처럼 각 단계가 끝날 때마다 결과를 파일로 저장합니다. 오류가 발생하면 어느 단계까지 정상 동작했는지 파일만 확인하면 바로 알 수 있습니다. 중간 산출물을 남기면 특정 단계만 독립적으로 테스트하기도 편해지기 때문에, 개발 속도가 눈에 띄게 빨라집니다. 다만 파이프라인이 정상 완료된 후에는 중간 파일을 정리하는 로직을 추가해서 디스크가 불필요하게 쌓이지 않도록 관리해야 합니다.

로그(log) 기록도 중요합니다. Python의 logging 모듈을 사용해 각 단계의 시작·종료·오류를 기록하면, 문제 원인을 빠르게 추적할 수 있습니다. 로그에는 단순히 "STEP 완료"만 적는 것이 아니라, 처리한 파일명이나 글자 수 같은 핵심 정보를 함께 남겨두면 나중에 문제를 재현할 때 큰 도움이 됩니다.

import logging
logging.basicConfig(filename='pipeline.log', level=logging.INFO)
logging.info(f'STEP 1 완료: {topic_title}')

 

재시도(retry) 로직도 반드시 넣어야 합니다. 네트워크 불안정이나 API 일시 오류는 한 번 더 시도하면 해결되는 경우가 많기 때문입니다.

⚠️ 주의

최대 재시도 횟수는 2회로 제한하는 것을 권장합니다. 무한 재시도는 API 비용만 올리고, 근본적인 오류는 잡지 못합니다. 재시도 사이에 짧은 대기 시간(sleep)을 두면 일시적인 서버 부하 문제가 해소되어 성공 확률이 높아집니다.

마지막으로, 파이프라인이 중간에 실패했을 때 이미 완료된 단계는 건너뛰는 로직이 있으면 편리합니다. 중간 산출물 파일이 존재하는지 확인해서, 있으면 해당 단계를 스킵하는 방식입니다.

if os.path.exists('output/step2_draft.md'):
    logging.info('STEP 6 스킵: 초안 이미 존재')
else:
    run_draft_writer()

💬 제가 6개 글을 연속 생성하는 파이프라인을 운영하면서 가장 큰 교훈은, 한 글이 실패해도 나머지 글 생성이 멈추지 않도록 글 단위로 try-except를 감싸야 한다는 점이었습니다. 하나의 오류가 전체 파이프라인을 중단시키면, 나머지 5개 글까지 못 쓰게 되니까요.

✍️ 마치며

Claude Code 블로그 자동화 파이프라인은 한 번에 완벽하게 만들기 어렵습니다. JSON 키 불일치, 경로 오류, 타임아웃, 인코딩 문제 등 각 단계에서 고유한 오류가 발생하기 때문입니다. 핵심은 중간 산출물 저장, 로그 기록, 글 단위 예외 처리라는 세 가지 안전장치를 갖추는 것입니다. 이 세 가지만 있으면 오류가 발생해도 원인을 빠르게 찾고, 나머지 글 생성에 영향을 주지 않는 안정적인 파이프라인을 운영할 수 있습니다.

#ClaudeCode #블로그자동화 #파이프라인 #트러블슈팅 #Python자동화 #AI블로그