반복 작업 자동화와 공통 도구 계약: 무엇을 입력받고 어떻게 실패해야 하는가

30초 요약

반복 작업 자동화는 사람이 하던 명령을 긴 스크립트로 옮기는 일이 아니다. 호출자가 무엇을 주면, 도구가 어떤 변경을 계획하고, 무엇을 실제로 바꾸며, 성공·실패를 어떻게 판정할 수 있는지 고정하는 일이다.

반복해서 기억할 문장은 이것이다.

입력을 명시하고, 검증 뒤 계획하며, 부수 효과와 결과를 계약한다.

입력 수집 → 정규화 → 검증 → 계획 → 적용 → 확인 → 결과 보고
              실패: 변경 없음     실패: 부분 상태와 복구 방법을 결과에 포함

정규화는 ./config.json과 절대 경로처럼 모양이 다른 입력을 비교 가능한 한 형태로 바꾸는 일이다. 적용은 파일·원격 서비스 같은 외부 상태를 실제로 바꾸는 단계다. 부수 효과는 그처럼 도구 밖에 남는 변화다. 확인은 적용 뒤 실제 상태가 계획과 맞는지 다시 읽는 단계이고, 결과 보고는 사람과 다음 자동화가 판정할 상태·변경·복구 정보를 내보내는 단계다. 이 흐름을 지키면 로컬 명령, 지속적 통합 작업과 공통 패키지가 같은 핵심 규칙을 공유하면서도 환경별 입출력은 분리할 수 있다.

이 글의 대표 상황은 배포 도구가 Web 변경에는 성공했지만 모바일 단계의 응답을 받지 못한 부분 실패다. 같은 명령을 다시 실행해도 되는지 판단하려면 입력과 계획뿐 아니라 이미 남은 효과, 작업 식별자, 확인 결과와 종료 상태가 계약에 있어야 한다. 뒤의 각 절은 이 재시도 판단에 필요한 정보를 하나씩 채운다.

자동화할 반복 작업부터 정의한다

먼저 한 달 동안 반복된 작업에서 다음을 기록한다.

• 시작 조건과 필요한 판단은 무엇인가?
• 매번 같은 단계와 다른 단계는 무엇인가?
• 잘못 실행했을 때 피해와 되돌림 방법은 무엇인가?
• 실행 횟수, 사람의 대기 시간과 실패율은 얼마인가?

한 번뿐인 모호한 판단을 자동화하면 예외를 숨긴다. 반대로 규칙이 안정됐고 반복량이 늘며 잘못된 수동 실행의 피해가 큰 작업은 계약을 만들 가치가 높다. 자동화 전후에는 20편의 변경 한 건당 시간·실패와 복구 비용을 같은 분모로 비교한다.

“모든 것을 자동화”도 목표가 아니다. 시스템이 스스로 원하는 상태를 유지해 작업 자체가 사라질 수 있는지, 문서나 기본값 개선만으로 충분한지, 사람이 승인할 판단과 기계가 반복할 실행을 어디서 나눌지 먼저 정한다.

호출자가 관찰하는 입력과 출력을 그린다

도구의 함수 인자만 보고 계약을 다 적었다고 생각하기 쉽다. 실제 호출 경계는 더 넓다.

현재 폴더를 바꿨을 때 대상이 달라지면 현재 폴더도 입력이다. 현재 시각으로 이름을 만들면 시계가 입력이고, 정렬 순서가 언어·지역 설정(locale)에 따라 달라지면 그 설정도 입력이다. 7편의 재현 가능한 빌드와 같이 결과에 영향을 주는 숨은 입력을 찾아 명시하거나 통제한다.

비밀 값은 계약에서 없애는 것이 아니라 존재와 권한은 명시하되 값은 출력·로그·계획에서 가린다. 환경 변수 전체를 읽거나 저장소 전체를 쓰기 가능하게 주는 대신 필요한 이름과 경로만 허용한다.

입력을 정규화하고 변경 전에 모두 검증한다

명령줄, 환경 변수와 설정 파일에서 같은 값을 받을 수 있다면 우선순위를 문서화한다.

명시적 명령 옵션 > 지정한 설정 파일 > 문서화한 환경 변수 > 안전한 기본값

이 순서는 보편 표준이 아니라 한 예다. 중요한 점은 호출자가 최종 값을 설명할 수 있고 --explain이나 진단 출력으로 출처를 확인할 수 있다는 것이다. 비밀 값은 설명할 때도 가린다.

schema는 자료 모양을 선언한 문서, instance는 실제 검사할 입력, validator는 둘을 받아 유효 여부를 판정하는 검사기다. 구조화된 설정과 기계 출력에 schema를 두면 누락 필드, 잘못된 자료형과 범위를 부수 효과 전에 같은 규칙으로 막을 수 있다.

형식 검증만으로 의미가 맞아지는 것은 아니다.

형식: timeout은 0보다 큰 정수인가?
관계: minVersion은 maxVersion보다 작거나 같은가?
환경: 대상 경로가 허용 범위 안에 있는가?
권한: 호출자가 이 환경을 변경할 수 있는가?
현재 상태: 예상한 상태 개정 식별자(revision)와 실제 값이 같은가?

앞의 모든 검증이 끝나기 전에 첫 파일을 고치면 뒤 입력 오류가 부분 변경을 남긴다. 가능한 검증을 먼저 모으고, 사용자가 고칠 수 있는 오류는 입력 이름·받은 값의 안전한 표현·기대한 규칙·해결 방법을 함께 보여준다.

검증 뒤에 계획과 적용을 나눈다

계획 단계는 순수 계산에 가깝게 만든다. 정규화한 입력과 읽기 전용 현재 상태를 받아 생성·수정·삭제· 변경 없음 목록을 돌려준다. 적용 단계는 승인된 계획을 받아 실제 부수 효과를 수행한다.

collectInputs() → normalize() → validate() → buildPlan()
                                           ↓
                 applyPlan() → confirmAppliedState() → buildResult()

미리보기에서는 applyPlan()과 적용 확인을 수행하지 않았다고 결과에 표시하고 계획만 보고한다. 실제 적용에서는 일곱 단계를 모두 지나 같은 결과 자료형을 만든다.

--dry-run은 실제 쓰기를 하지 않고 계획을 보여주는 관례적 이름이다. 그러나 “아무 부수 효과도 없다”는 뜻은 도구가 직접 보장해야 한다. 원격 상태 조회, 인증 갱신, 캐시 쓰기와 telemetry 전송도 관찰 가능한 변화일 수 있기 때문이다.

따라서 미리보기와 실제 적용이 같은 함수를 공유해도 다음 중 어떤 보장을 주는지 적는다.

• 단순 미리보기: 현재 시점의 예상 변경만 보여 준다.
• 전제 조건 적용: revision·해시가 그대로일 때만 적용한다.
• 저장 계획 적용: 검토한 계획 식별자를 실제로 적용한다.
• 재계획 후 적용: 직전에 다시 계산하고 차이가 있으면 승인부터 다시 받는다.

재시도와 부분 실패를 부수 효과 계약에 넣는다

멱등한 목표: "설정 값을 enabled로 맞춘다"
멱등하지 않은 동작: "설정 파일 끝에 enabled를 추가한다"

모든 작업을 억지로 멱등하게 만들 수는 없다. 그때는 실행 ID·대상 revision·중복 키, 완료 기록과 보상 작업을 계약한다. 실행 ID로 중복을 막는다면 상태 변경과 중복 방지·완료 기록을 한 원자적 경계로 처리해야 한다. 보상은 이미 적용된 효과를 상쇄하는 새 작업이며, 이전 상태나 검증한 실행 대상으로 되돌리는 원상 복구(rollback)와 다르다. 원상 복구와 보상 모두 모든 외부 효과의 완전한 복구를 보장하지 않는다. 되돌릴 수 없는 외부 효과는 적용 전 승인과 적용 후 확인을 더 강하게 둔다.

여러 대상을 순서대로 바꾸는 도구는 “성공/실패” 두 값만 주지 않는다.

{
  "status": "partial",
  "operationId": "op-123",
  "applied": ["web"],
  "failed": [{ "target": "mobile", "code": "PERMISSION_DENIED" }],
  "retryable": false
}

동시에 두 실행이 같은 상태를 바꿀 수 있다면 잠금, revision 비교나 충돌 실패 중 하나를 정한다. 무조건 마지막 쓰기가 이기는 방식은 성공처럼 보이면서 다른 사용자의 변경을 잃을 수 있다.

사람용 설명과 기계용 결과를 분리한다

이를 모든 CLI의 유일한 규칙이라고 확대하지 않고, 조합 가능한 도구를 설계하는 출발 관례로 삼는다.

stdout: 다음 프로그램이 소비할 결과 또는 명시한 사람용 출력
stderr: 경고·오류·진행 진단
exit status: 성공, 차이 있음, 입력 오류, 외부 실패 같은 실행 요약
result file/artifact: 크거나 민감도·보존 규칙이 다른 결과

stdout은 표준 출력, stderr는 표준 오류다. 기계 모드의 stdout을 JSON으로 정했다면 진행 애니메이션 (spinner)·색상· 안내 문장을 섞지 않는다. JSON 한 필드씩 내보내는 형식인지 문서 하나인지, 문자열 정렬과 경로 표기, schema 버전도 정한다. 로그 문장을 기계 계약으로 쓰지 않는다.

실패를 잡아 메시지만 쓰고 0으로 끝내지 않는다. 반대로 결과를 모두 쓰기 전에 즉시 종료해 JSON을 중간에서 자르지도 않는다. main()이 결과를 만들고 맨 바깥 경계가 출력과 종료 상태를 한 번 결정하게 한다.

async function main(rawInput: RawInput): Promise<Result> {
  const input = validate(normalize(rawInput));
  const plan = await buildPlan(input);
 
  if (!input.apply) {
    return buildResult({ plan, confirmation: { status: "not-applied" } });
  }
 
  const applied = await applyPlan(plan);
  const confirmation = await confirmAppliedState(plan, applied);
  return buildResult({ plan, applied, confirmation });
}
 
main(readInput())
  .then((result) => writeResult(result))
  .catch((error) => {
    writeDiagnostic(toPublicError(error));
    process.exitCode = 1;
  });

예제의 toPublicError는 내부 호출 기록(stack)과 비밀 값을 그대로 노출하지 않고, 호출자가 고칠 수 있는 오류 코드·안전한 문맥·다음 행동으로 바꾸는 경계다.

호출자가 관찰하는 모든 표면을 버전으로 관리한다

같은 글에 나오는 “버전”과 “식별자”부터 나눈다.

revision은 대상 상태의 특정 개정, commit은 version control의 특정 기록, operation ID는 한 번의 작업을 추적하는 식별자다. 이 셋은 상태나 실행을 찾는 값이지 Semantic Versioning을 적용할 제품 버전이 아니다.

다음은 모두 호환성을 깰 수 있다.

• 기존 옵션 삭제·이름 변경 또는 기본 대상 변경
• 환경 변수와 설정 우선순위 변경
• stdout에 진행 문장을 추가해 JSON parser를 깨뜨림
• 성공 종료 상태의 의미 변경
• 출력 field 삭제·자료형 변경 또는 정렬 보장 제거
• 이전에는 읽기 전용이던 명령이 파일을 수정함
• 지원하던 Node·운영체제·저장소 구조 제거

새 필드를 추가하는 것이 언제나 안전한 것도 아니다. 호출자가 모르는 필드를 거부하는지, 순서를 고정해 비교하는지에 따라 깨질 수 있다. 소비자 fixture와 schema를 함께 실행해 실제 계약을 확인한다.

사용 중단 예정(deprecated)은 아직 동작하지만 제거될 예정임을 알리는 상태다. 대체 명령, 경고를 시작할 버전, 제거할 가장 이른 버전과 자동 이행 방법을 같이 제공한다. 한 번 공개한 같은 릴리스 버전의 내용을 조용히 바꾸지 않고 새 릴리스로 전달한다.

공통 도구는 복사가 아니라 호출 경계를 공유한다

공통화의 기준은 코드 줄 수가 아니라 여러 호출자가 같은 정책과 실패 규칙을 가져야 하는가다. 저장소 두 곳에 작은 명령이 있어도 플랫폼별 차이가 핵심이면 분리할 수 있다. 반대로 보안 검사·산출물 식별처럼 같아야 하는 규칙은 한 구현과 계약으로 모은다.

이 현재 구현은 공통 도구의 경계를 보여 주는 사례다. secrets: inherit처럼 비밀 값을 암묵적으로 모두 상속하기보다 필요한 값과 권한을 명시하고, 결과 이름·의미를 버전 계약으로 둔다. 외부 작업 흐름을 내용이 움직일 수 있는 브랜치(branch) 이름으로 참조하면 실행 내용도 달라질 수 있으므로, 재현성이 중요할 때는 검토한 commit 식별자를 사용한다.

공통 패키지의 핵심 로직, 명령줄 환경 연결층과 workflow 연결층을 나누면 같은 정책을 여러 환경에서 재사용할 수 있다. 연결층(adapter)은 환경의 입출력을 핵심 자료형으로 바꾸고, wrapper는 기존 실행 도구가 공통 로직을 호출하도록 감싸는 얇은 코드다.

핵심 로직(core): 입력 자료 → 검증·계획·결과 자료
명령줄 연결층: 명령 인자(argv)·환경 변수(env)·표준 입력(stdin)
             ↔ core ↔ 표준 출력·오류와 종료 상태
workflow 연결층: 자료형이 정해진 입력·비밀 값(secret)
               ↔ core ↔ 이름 있는 출력·보관 산출물(artifact)

핵심 로직이 process.env와 파일 시스템을 직접 읽지 않으면 같은 입력으로 단위 검증하기 쉽고, 환경별 권한·경로 처리는 연결층의 통합 테스트에 모을 수 있다.

계약을 실패 픽스처로 검증한다

성공 예제만 전체 결과 고정본(snapshot)으로 남기면 가장 중요한 계약이 비어 있다. 다음 층을 좁은 것부터 둔다.

1. 입력 해석기(parser)·정규화: 옵션 조합, 우선순위, 경로와 기본값을 표로 검증한다.
2. 출력 구조 규칙(schema)·의미 검증: 누락, 잘못된 자료형, 모순된 값과 경계값을 거부한다.
3. 계획: 고정한 현재 상태(current state)에서 생성·수정·삭제·변경 없음 결과를 검증한다.
4. 부수 효과 연결층: 임시 폴더·가짜 원격 경계에서 실제 읽기·쓰기와 정리를 검증한다.
5. 프로세스: CLI를 자식 프로세스로 실행해 stdout, stderr, 종료 상태와 생성 파일을 함께 본다.
6. 소비자 계약: 이전 도구 버전의 설정·호출·출력 해석기가 새 도구에서 유지되는지 확인한다.

실패 주입은 의도적으로 파일 쓰기, 두 번째 원격 요청, 출력 직전 같은 경계에서 실패시키는 테스트다. 이를 통해 부분 상태, 재시도와 정리 규칙을 실제로 확인한다.

전체 출력 고정본(golden file)은 검토한 출력 예시를 파일로 고정한 테스트 자료다. 읽기 쉽지만 작은 문구 변화에도 깨지므로 구조화된 필드(field) 의미는 별도 조건 확인(assertion)으로 검증한다. 비밀· 절대 임시 경로·현재 시각은 fixture에 그대로 기록하지 않는다.

Web, React와 React Native의 연결점

Web 도구는 주소 경로(route)별 산출물·source map·성능 예산을 검사할 수 있다. 입력 주소 경로와 배포 조건(production), 측정 단위가 명시되지 않으면 로컬과 CI에서 다른 예산을 판정한다. 기계 출력에는 경로별 결과와 결과 구조 버전을 두고 실패 상태가 병합 차단 여부와 일치하게 한다.

React 도구는 컴포넌트 틀(component template) 생성이나 codemod를 제공할 수 있다. codemod는 코드를 정해진 규칙으로 바꾸는 자동 변경 도구다. 파일을 바꾸기 전 대상 문법과 변경 계획을 보여 주고, 두 번 실행해도 같은 변경을 반복하지 않으며, 자동 판단할 수 없는 코드는 명시적으로 남겨야 한다.

React Native 도구는 Android·iOS·Metro 환경의 bundle, source map과 무선 업데이트 메타데이터(OTA metadata)를 함께 다룰 수 있다. 대상 플랫폼(platform)·빌드 방식(mode)·런타임 버전을 숨은 기본값으로 두지 않고, 한 플랫폼만 성공한 부분 상태를 전체 성공으로 보고하지 않는다. 네이티브 빌드 도구 묶음 (toolchain)을 실행하기 전 필요한 버전·권한·출력 경로를 검증한다.

세 환경에서 공통인 것은 입력 수집→정규화→검증→계획→적용→확인→결과 보고 계약이다. 브라우저 경로, React 코드 변경, 네이티브 도구 묶음처럼 실제 부수 효과와 실패 복구가 다른 부분은 연결층과 fixture로 분리한다.

자주 실패하는 자동화

성공 경로만 빠르게 만든다

입력 오류, 네트워크 단절과 부분 성공에서 상태를 설명하지 못한다. 실패 fixture부터 계약에 넣는다.

로그 문장을 API처럼 파싱한다

문구·색상·언어가 바뀌면 호출자가 깨진다. 기계 출력 schema와 종료 상태를 별도로 제공한다.

dry-run과 실제 적용이 다른 코드를 탄다

미리보기에서 누락된 효과가 실제 실행에서 나타난다. 한 계획 모델을 공유하고 effect adapter만 막는다.

모든 환경 변수를 암묵적으로 읽는다

같은 명령이 사람·CI·저장소마다 달라진다. 필요한 이름, 우선순위와 비밀 처리 규칙을 공개한다.

오류를 잡아 성공으로 끝낸다

다음 단계가 실패한 산출물을 사용한다. 결과 상태, 종료 상태와 실제 effect를 일치시킨다.

재시도를 복구 전략으로 착각한다

첫 적용 여부를 모른 채 같은 효과를 중복시킨다. 멱등성, operation ID와 확인 절차를 먼저 만든다.

공통화가 호출자를 숨긴다

누가 어떤 옵션·출력에 의존하는지 몰라 작은 변경도 전부 깨진다. 소비자 목록과 계약 fixture를 둔다.

공통 도구 설계 체크리스트

다음은 앞의 일곱 실행 단계를 바꾸는 또 다른 순서가 아니다. 도구를 설계·검토할 때 빠뜨린 계약이 없는지 확인하는 목록이다.

1. 반복량·실패·대기 비용과 자동화하지 않을 판단을 기록한다.
2. 호출자별 입력, 출력, 부수 효과와 권한을 한 표로 그린다.
3. 숨은 입력을 명시하고 정규화·형식·의미·환경 검증 순서를 정한다.
4. 읽기 전용 현재 상태에서 실행 계획을 만들고 적용 adapter와 분리한다.
5. 멱등성, 동시 실행, 부분 실패·재시도와 복구 결과를 설계한다.
6. 사람용 진단, 기계 출력 schema와 종료 상태 표를 문서화한다.
7. 성공·입력 오류·부분 실패·중복 실행 fixture로 process 경계를 검증한다.
8. 공개 표면과 소비자를 선언하고 version·deprecation·이행 규칙을 적용한다.
9. 실제 반복 시간·실패율·복구 비용을 관찰해 도구 자체의 toil을 다시 줄인다.

한 문장으로 다시 설명하기

반복 작업 자동화는 사람의 명령을 복사하는 일이 아니라 입력 수집→정규화→검증→계획→적용→확인→ 결과 보고를 따라, 재시도 가능한 부수 효과와 사람·기계가 판정할 결과를 버전이 있는 계약으로 공개하는 일이다.

스스로 확인하기

1. 입력 수집부터 결과 보고까지 일곱 단계를 순서대로 말하고, 각 경계의 실패를 설명할 수 있는가?
2. dry-run 뒤 실제 적용이 달라질 수 있는 이유와 부분 실패를 재시도할 멱등성 조건은 무엇인가?
3. stdout, stderr, 종료 상태와 결과 파일은 각각 어떤 소비자를 위한 경계인가?
4. 도구 릴리스·결과 구조·런타임 버전과 상태·실행 식별자는 어떻게 다른가?
5. Web·React·React Native 연결층이 공유할 핵심 로직과 따로 검증할 효과는 무엇인가?