가장 스트레스가 심한 게시(publish) 버그는 완전한 충돌(crash)이 아닙니다. 대부분 잘 작동하다가, 게시 직전에 중요한 세부 사항 하나를 변형시켜 버리는 스크립트입니다. 저는 콘텐츠 작업, 내부 문서 도구, 그리고 작은 릴리스 헬퍼(release helpers)에서 이런 일을 겪었습니다. 가장 도움이 되었던 패턴은 아주 작은 Preflight 파일을 추가하여, 게시 단계가 이미 결정된 사항들만 실행하도록 만드는 것이었습니다.

너무 단순하게 들릴 수도 있지만, 이는 자동화 스택의 느낌을 정말 빠르게 바꿔 놓습니다. 스크립트가 마지막 순간에 무엇을 추론할지 추측하는 대신, 파일 하나를 검사하여 입력을 확인하고 실행기(executor)가 지루한 부분을 처리하도록 맡길 수 있습니다.

게시 스크립트가 최악의 순간에 실패하는 이유

많은 게시 스크립트는 도움이 되려고 노력합니다. 기본값(defaults)을 선택하고, 누락된 필드를 복구하며, 메타데이터를 다시 쓰거나, 조용히 추가적인 상태(state)를 가져옵니다. 각각의 동작은 그 자체로 무해해 보이지만, 이들이 모이면 cron 작업이나 인수인계(handoff) 조건 하에서 신뢰하기 어려운 도구를 만들게 됩니다.

문제는 보통 세 가지 지점에서 나타납니다:

• 계획(planning)과 게시(publish) 사이의 제목(title) 또는 태그(tag) 드리프트(drift)
• 런타임 상태(runtime state)에 따라 변경되는 내부 링크
• 재시도(retries) 시 단순히 다시 게시(repost)만 해야 하는데 콘텐츠 생성(content generation)을 다시 실행하는 경우

마지막 경우가 팀들이 피해를 입는 지점입니다. 실패한 재시도는 기계적이어야 합니다. 만약 실행기가 다시 '생각'하기 시작한다면, 최종 결과가 승인된 계획에서 나온 것인지 아니면 스크립트의 마지막 순간에 갈라져 나온 것인지 더 이상 구분할 수 없게 됩니다.

Preflight 파일에 담는 내용

제 규칙은 간단합니다. 게시자(publisher)가 그것을 필요로 한다면, 계획자(planner)가 먼저 그것을 기록해야 합니다. 텍스트 전용 DEV 스타일 워크플로우의 경우, Preflight 파일은 매우 작게 유지될 수 있습니다:

{
  "title": "Preflight Files for Safer Publish Scripts",
  "description": "A simple pattern for making publish automation safer.",
...

이것은 전체 계획을 대체하기 위한 것이 아닙니다. 이것은 실행기가 게시 직전에 읽는 좁은 범위의 계약(contract)입니다. 저는 이것이 모든 계획 세부 사항을 끌어들이지 않으면서도, "우리가 정확히 무엇을 보내려고 하는가?"라는 질문에 답해주기 때문에 좋아합니다.

개발자 도구 작업의 경우, 그러한 좁은 계약(narrow contract)이 기발한 스크립트보다 더 유용할 때가 많습니다. 코드를 검토하거나(code review), 실패한 실행 폴더에서 확인하거나, 작은 셸 검사(shell check)로 이를 검증할 수 있습니다. 만약 누군가가 잘못된 계정이 잘못된 초안을 게시했다고 보고한다면, 프리플라이트 파일(preflight file)은 가장 먼저 살펴볼 명확한 장소를 제공합니다.

또한 저는 검사를 마법적이기보다는 명시적으로 유지합니다. 실행에 두 개의 내부 링크가 필요하다면 그렇게 명시하세요. 제목이 60자를 넘지 않아야 한다면 그렇게 명시하세요. 기사 경로(article path)가 누락되었다면, 초기에 크고 명확하게 실패하도록 만드세요. 조용한 자동화는 잘못된 일을 할 때까지 우아하게 느껴집니다.

한 번 검증하고, 놀라움 없이 게시하기

프리플라이트 파일의 가장 좋은 용도는 계획 단계의 검증(planning-time validation)과 게시 단계의 실행(publish-time execution)을 분리하는 것입니다. 플래너는 더 풍부한 작업을 수행할 수 있습니다: 주제를 선택하고, 개요를 구성하며, 포스팅이 자동화 테스트 설계에 접촉할 때 matrix-safe 이메일 검사와 같은 지원 링크를 선택하는 것입니다.

그런 다음 실행기(executor)는 훨씬 더 작은 작업을 수행합니다:

1. 프리플라이트 파일을 읽습니다.
2. 필요한 모든 필드가 존재하는지 확인합니다.
3. 참조된 기사 파일이 존재하는지 확인합니다.
4. 정확히 그 파일을 게시합니다.
5. 최종 결과를 작성합니다.

이 5단계 모델은 의도적으로 지루합니다. 좋은 자동화는 종종 약간 지루하며, 그것은 괜찮습니다. 제가 이 분리를 건너뛰면,

Preflight 검증을 하나의 거대한 정책 엔진 (policy engine)으로 만들고 싶은 유혹이 생길 수 있습니다. 하지만 정말로 필요한 경우가 아니라면 저는 이를 지양할 것입니다. 몇 가지 짧은 체크만으로도 대부분의 위험을 방지할 수 있습니다:

• 제목 길이 (title length)
• 설명 길이 (description length)
• 허용된 태그 개수 (allowed tag count)
• 필수 내부 링크 개수 (required internal link count)
• 선택된 계정 존재 여부 (selected account present)
• 기사 파일 존재 여부 (article file exists)

Planner가 이미 적절한 실행 디렉토리 (run directory)를 생성한 경우라면, 많은 워크플로 (workflows)에서 이 정도로 충분합니다. 만약 안전장치 (guardrail)를 하나 더 추가하고 싶다면, article.raw.md에 대한 콘텐츠 해시 (content hash)를 추가하여 게시자 (publisher)가 승인 후 초안이 변경되지 않았음을 확인할 수 있도록 하세요.

저는 또한 이를 검증 샌드박스 경계 (verification sandbox boundaries)와 연결하는 것을 좋아합니다. 아이디어는 비슷합니다. 위험한 경계를 좁게 유지하고, 데이터 이동을 가시화하며, 숨겨진 상태 (hidden state)를 피하는 것입니다. 경계가 샌드박스 편지함이든 게시자 쉘 스크립트 (publisher shell script)이든, 신뢰는 무엇이 그 경계를 넘는지 정확히 아는 데서 옵니다.

빠른 Q&A

Preflight 파일은 plan.json과 다른가요?

보통 그렇습니다. Plan은 계획을 위한 컨텍스트 (context)를 위한 것입니다. Preflight 파일은 실행 전 마지막 안전 확인을 위한 것입니다. 때로는 같은 파일일 수도 있지만, 저는 종종 더 작은 단위의 핸드오프 (handoff)를 선호합니다.

게시자가 잘못된 값을 수정(repair)해야 하나요?

아니요, 혹은 거의 그럴 일이 없어야 합니다. 필수 값이 잘못되었다면, 실패 처리하고 이를 보고하세요. 조용한 수정 (silent repair)은 듣기에는 좋지만, 나중에 자동화 과정을 추론하기 어렵게 만듭니다.

이것은 콘텐츠 워크플로에만 도움이 되나요?

전혀 그렇지 않습니다. 저는 릴리스 노트 (release notes), 변경 로그 작업 (changelog jobs), 문서 푸시 (docs pushes), 그리고 일회성 크론 작업 (cron tasks)에도 동일한 형태를 사용합니다. 스크립트가 게시하거나 알림을 보낼 수 있는 곳이라면 어디든, Preflight 계약 (contract)은 전체 시스템을 더 차분하고 디버깅 가능하게 (debuggable) 만들어 주는 경향이 있습니다.

좋은 점은 이 작업에 필요한 코드가 매우 적다는 것입니다. 검증된 파일 하나, 최종 기사 하나, 실행기 (executor) 하나. 화려하지는 않지만, 일정이 바빠지고 사람이 오프라인 상태일 때 매우 신뢰할 수 있습니다.