자동화 파이프라인 문서화하는 실제 순서

자동화 파이프라인 문서화 일러스트

작성자

카테고리:

자동화 파이프라인을 문서화해야 하는 순간은 따로 있다

크론이 서버에 70개, 노트북에 9개 돌아가는 시점에 도달하고 나서 알았다. 내가 왜 이 자동화를 이렇게 만들었는지 기억이 안 난다. “왜 이 트리거를 5분 간격으로 돌렸지?”, “이 예외 처리는 뭘 막으려고 넣은 거지?” 수준의 질문에 답을 못 하겠더라. 결국 하나는 통째로 해체해서 다시 만들었는데, 그때 문서화의 순서를 정리하게 됐다.

자동화를 여러 개 굴리다 보면 누구나 온다, 그 순간이. 만들 때는 전부 머릿속에 있는데 3주만 지나면 남이 만든 것처럼 보인다. 이 글은 거창한 문서화 이론 얘기가 아니다. 1인이 망하지 않고 유지할 수 있는 최소 기록 단위, 그걸 자동화에 붙이는 순서만 적는다.

문서화를 미루면 3주 뒤 벌어지는 일

미루면 두 가지가 온다. 고장 났을 때 원인을 못 찾는 것, 그리고 고쳐야 할 게 있는데 손을 못 대는 것. 후자가 더 아프다. 장애는 어쨌든 해결되는데, “이거 건드려도 되나?” 하는 확신 부족은 자동화를 방치로 이끈다. 방치된 자동화는 죽지 않고 계속 돌면서 이상한 데이터를 쌓는다.

이 글에서 다루지 않을 것

컨플루언스 운영법, 다이어그램 표기법, 팀용 문서화 프로세스. 나 혼자 굴리는 자동화에는 다 과하다. 필요한 건 미래의 내가 결정을 이해할 수 있는 줄 수다.

자동화마다 정확히 무엇을 어디까지 기록해야 하나

정의부터. 최소 기록 단위란 “6개월 뒤의 내가 이 자동화를 고칠 수 있는가”를 판단하게 해주는 정보다. 코드를 다 적는 게 아니다. 코드는 저장소에 있으니까. 적어야 할 건 코드에 안 보이는 것, 왜 그렇게 만들었는가다.

필수 5항목

  • 목적: 이 자동화가 없으면 무슨 일이 벌어지는가
  • 트리거: 언제, 무엇에 반응해 도는가 (크론 표현식 포함)
  • 입출력: 무엇을 먹고 무엇을 뱉는가, 저장 위치
  • 실패 시 행동: 에러 나면 멈추는가, 넘어가는가, 알림은 어디로 오는가
  • 소유자: 1인이면 “나” 한 줄이면 된다. 대신 “이상하면 누가(=나) 판단한다”는 표시

기록하지 않아도 되는 것들

의도적으로 버리는 정보가 더 중요할 수 있다. 내가 안 적는 것들이다.

  • 코드 내부 로직: 저장소와 코드 주석의 영역이다
  • 사용 라이브러리 버전 목록: lock 파일이 있다
  • 만든 날짜의 감상: “오늘 기분 좋게 만듦” 같은 건 3주 뒤에 읽으면 화만 난다

8줄짜리 자동화 카드 템플릿 (복붙용)

이름: blog-publisher
목적: 초안 글을 검사 통과시켜 자동 공개, 사고만 걸러냄
트리거: 매일 아침 크론 (0 7 * * *)
입력: 초안 폴더의 md 파일 / 출력: 공개 글, 로그
실패 시: 1회 재시도 후 슬랙 알림, 초안으로 강등
소유자: 나
비고: 문체 검사 기준 바꾸면 cards/review.yml도 고칠 것

이게 전부다. 여기에 한 줄도 더 쓰고 싶지 않게 만드는 게 나의 기준이다. 줄이 늘어난다는 건 자동화가 복잡하다는 신호니까, 그때는 문서를 늘리는 게 아니라 자동화를 쪼개는 걸 생각해본다.

문서는 어디에 어떤 형식으로 보관하는 게 좋은가

실패부터 고백하면, 한때 문서를 전부 노션에 옮긴 적이 있다. 정리된 화면 보기 좋아서. 근데 안 열어보게 된다. 자동화 고치러 터미널 들어갔는데 문서는 노션에 있으니, 결국 열어보는 사람은 없는 문서나 마찬가지가 됐다. 다시 자동화 저장소 안으로 돌아왔다.

저장 위치는 하나만: 자동화와 같은 저장소

지금은 각 자동화 폴더에 AUTOMATION.md 하나를 넣어둔다. git 저장소 26개에 각자 카드가 산 채로 들어 있다. 물리적 근접성이 전부다. 코드 옆에 있으면 git log 볼 겸 열어보게 된다. 위키는 사람이 찾아가야 하지만, 같은 폴더는 눈에 들어온다.

마크다운 한 파일 vs 노션 데이터베이스

트레이드오프를 솔직히 적으면 이렇다.

구분 마크다운 파일 노션 DB
코드와의 거리 같은 폴더, 바로 옆 앱 전환 필요
전체 목록 조회 약함, grep해야 함 필터·뷰 편함
이력 관리 git 커밋으로 남음 페이지 이력만
1인 유지 확률 내 경험상 높음 3주 후 방치됨

전체 목록이 보고 싶을 때는 Pipedeck로 파이프라인 현황을 따로 보고 있어서, 굳이 노션을 유지할 이유가 없어졌다.

이름 규칙

“나중에 찾는 사람”은 대부분 장애 난 시점의 나 자신이다. 그때 내 검색 행동은 폴더명 grep이다. 규칙은 단순하게 짰다.

  • 크론 잡 이름: 서비스-동작-주기 예: clip-video-daily
  • 커밋 메시지: [자동화이름] 무엇을 왜 바꿨는지 예: [blog-publisher] 재시도 2회로 늘림, 타임아웃 잦아서

커밋 메시지에 “왜”를 심어두면 카드가 낡았을 때 git log가 제2의 문서가 된다.

문서화 필요 시점 안내 일러스트

문서화를 자동화 안에 붙이는 방법

여기가 이 글에서 제일 공유하고 싶은 부분이다. 사람이 문서를 쓰는 구조는 1인에게 안 맞는다. 까먹으니까. 구조를 뒤집어서 파이프라인이 문서를 계속 갱신하게 만들었다.

실행 로그가 곧 문서가 되게 만들기

매번 카드 아래에 실행 요약 한 줄을 덧붙이게 해뒀다. 사람이 쓰는 게 아니라 스크립트 마지막에 append하는 것이다.

#!/bin/bash
STAMP=$(date '+%Y-%m-%d %H:%M')
COUNT=$(grep -c '^' "$OUT_FILE")
echo "- $STAMP 실행 완료, 처리 $COUNT건" >> AUTOMATION.md
git add AUTOMATION.md && git commit -m "[log] $STAMP" --quiet

이렇게 하면 카드가 살아있는 문서가 된다. 마지막 정상 실행이 언제인지 파일 열면 바로 보인다.

배포 시 메타 자동 생성

배포 스크립트가 날짜와 변경 사항을 카드 상단에 찍게 해뒀다. 버전 번호 같은 건 붙이지 않는다. “언제 뭘 고쳤는가”만 있으면 충분하다.

실패 알림 메시지에 ‘이 자동화가 뭔지’를 심기

무인 크론 자동화는 고장 나도 알림 한 줄로 끝나는 경우가 많다. 알림 첫 줄에 카드 요약을 넣었다.

[blog-publisher 실패] 아침 공개 자동화. 입력 초안 폴더, 재시도 1회 후 멈춤. 카드: repo/blog-publisher/AUTOMATION.md. 마지막 정상: 어제 07:00

이 포맷으로 바꾸고 나서 장애 시 문서를 안 열어도 된다. 알림만 보고 “아 그거, 초당 이럴 때 있지” 하고 기억이 돌아온다. 물론 카드가 최신일 때 얘기고, 안 그런 놈이 몇 개 있다. 그건 아직 못 고쳤다.

문서 보관 형식 정리 일러스트

기록 안 하면 실제로 이렇게 망한다

서두에 해체했다고 한 자동화가 있다. 이게 문서 없는 자동화의 전형이었다. 트리거가 되는 API가 정책을 바꾸면서 멈췄는데, 카드가 없으니 재빌드하러 들어갔다가 처음부터 다시 읽어야 했다. 내가 쓴 코드인데 왜 이렇게 짰는지 역추적하는 데만 시간이 꽤 들었고, 그 사이 다른 자동화 운영도 밀렸다. 재빌드 비용은 대부분 “다시 이해하는 비용”이다. 그걸 실감한 사례였다.

문서 있음 vs 없음의 차이

장애 대응 시간을 잰 적은 없지만 체감 차이는 명확하다. 카드 있는 자동화는 알림 보고 바로 판단한다. 목적이 적혀 있으니 “이거 지금 급한가, 아침까지 버텨도 되는가”가 즉시 결정된다. 카드 없는 자동화는 코드를 열어야 판단이 시작된다. 한밤중에 그 차이가 크다.

다만, 기록 안 해도 되는 경우도 있다

균형을 위해 적는다. 한 번 돌고 버리는 일회성 스크립트는 문서가 필요 없다. 만든 목적 자체가 “이번 한 번”이니까. 내 기준으로는 수명이 짧고, 실패해도 놓치는 게 작은 자동화는 카드 없이 폴더에 두고, 끝나면 지운다. 문서화는 유지할 가치가 있는 것에만 붙인다.

자동화 내부 문서화 방법 일러스트

1인이 유지하는 문서화 루틴: 언제까지 기록하면 되는가

검색의도에 정면으로 답하면, 기록 타이밍은 딱 두 번이다.

만들 때와 고칠 때

만들 때: 자동화가 처음 정상 도는 순간 카드를 쓴다. 그때가 목적이 머릿속에 제일 선명할 때다. 고칠 때: 커밋하면서 카드의 비고 한 줄을 바꾼다. 이 두 번 외에는 안 쓴다. 일요일마다 문서 정리하는 루틴은 해본 적 있는데, 3주 못 갔다. 주기적 의식은 1인에게 안 맞는다.

배포 직전 30초 체크리스트

  • 카드가 있는가
  • 트리거가 카드와 같은가
  • 실패 시 알림이 카드 요약을 포함하는가
  • 커밋 메시지에 이유가 들어갔는가
  • 이거 일회성인가, 유지할 건가 (일회성이면 카드 생략)

분기마다 죽은 자동화 지우기

분기에 한 번 크론 목록을 훑는다. 최근 실행 로그가 카드에 안 찍힌 놈, 서비스가 끝나서 무의미해진 놈을 지운다. 문서화의 반대말은 미기록이 아니라 방치다. 안 쓰는 자동화는 문서를 잘 쓴들 쓰레기가 잘 정리된 것일 뿐이다.

정리: 오늘 30분이면 되는 시작

지금 당장 할 수 있는 건 이 정도다.

  1. 돌아가는 자동화 중 제일 불안한 하나를 골라 8줄 카드를 써서 같은 폴더에 넣는다
  2. 실패 알림 메시지에 카드 첫 줄을 복사해 넣는다
  3. 배포 스크립트 끝에 실행 로그 한 줄 append를 추가한다

첫 카드 하나만 적어보면 감이 온다. 8줄이 은근히 까다롭다. 특히 “목적” 한 줄을 못 쓰겠으면 그 자동화는 애초에 필요 없는 걸 수도 있다. 그 발견만으로도 문서화는 값을 한다. 내가 이런 식으로 굴리는 자동화와 서비스는 포트폴리오(wallenstein.dev)에 공개돼 있으니 궁금하면 들어보셔라.


글쓴이 정보

춘천에서 AI 자동화로 서비스를 만들어 운영합니다. 릴스·쇼츠는 직접 만든 ClipSquare 로 만듭니다.

자주 나오는 질문

자동화 파이프라인 문서화에 꼭 필요한 최소 항목은 무엇인가요?

목적, 트리거(크론 표현식 포함), 입출력과 저장 위치, 실패 시 행동(재시도·알림), 소유자 다섯 개면 충분하다. 코드 자체는 저장소에 있으니 문서에는 코드에 안 보이는 ‘왜 그렇게 만들었는지’만 적으면 된다.

자동화 문서를 노션에 두면 안 되나요?

글쓴이도 노션에 옮겼다가 3주 만에 방치했다. 코드 고치러 터미널에 들어갔는데 문서는 다른 앱에 있으면 아무도 안 열어보게 된다. 자동화와 같은 저장소에 AUTOMATION.md 하나로 두는 게 1인 유지 확률이 훨씬 높다.

문서화를 미루면 실제로 어떤 문제가 생기나요?

고장 났을 때 원인을 못 찾는 것보다 ‘이거 건드려도 되나?’라는 확신 부족이 더 아프다. 방치된 자동화는 죽지 않고 계속 돌면서 이상한 데이터를 쌓는다.

자동화마다 몇 줄 정도 적는 게 적당한가요?

8줄짜리 카드 하나면 충분하다. 이름, 목적, 트리거, 입출력, 실패 시 행동, 소유자, 비고 순이다. 줄이 늘어난다는 건 문서가 부족해서가 아니라 자동화가 복잡하다는 신호니까 자동화를 쪼개는 게 맞다.

문서에 적지 말아야 할 것도 있나요?

코드 내부 로직, 라이브러리 버전 목록, 만든 날의 감상은 안 적는다. 코드와 lock 파일이 이미 그 역할을 하고, 감상은 3주 뒤 읽으면 기록에 도움이 안 된다.

커밋 메시지도 문서화의 일부인가요?

그렇다. [자동화이름] 무엇을 왜 바꿨는지 형식으로 커밋을 남기면 카드가 낡았을 때 git log가 제2의 문서 역할을 한다. 장애 난 시점의 나는 폴더명을 grep하니 이름 규칙도 ‘서비스-동작-주기’로 단순하게 유지한다.