왜 워크플로에 CI가 필요한가

코드 변경: CI는 테스트를 실행하고 문제를 포착합니다. 워크플로의 "코드"는 Markdown + YAML입니다. 무엇이 그곳의 문제를 포착할까요?

런타임(runtime)에 감지되지 않은 채 도달하는 전형적인 세 가지 실패 사례:

• templates/analyze.md에 출력 필드(output field)를 추가했지만, workflow.md의 context_inputs에 선언하는 것을 잊어버림. 하위 단계(downstream phase)는 아무것도 받지 못하고 조용히 계속 진행됨.
• 라우팅 신뢰도 임계값(routing confidence threshold)을 0.95에서 0.9로 변경하면서 라우팅 테스트 업데이트를 누락함. 엣지 케이스(edge case) 동작이 변하며, 워크플로가 프로덕션(production)에서 실행될 때 이를 알게 됨.
• workflow.md에서 활발하게 참조되고 있는 템플릿 파일을 삭제함.

이 세 가지 모두 런타임이 아닌, 자동화된 체크를 통해 커밋(commit) 시점에 포착할 수 있습니다.

세 가지 CI 게이트 (CI Gates)

Gate 1: 정적 검증 (Static validation) (수 초 소요, 모든 커밋 시 실행)
  - 참조된 모든 템플릿 파일이 존재함
  - config.yaml의 스킬(Skills)이 레지스트리(registry)에 존재함
...

Gate 1: 정적 검증 스크립트 (Static Validation Script)

Gate 1은 LLM을 호출하지 않습니다. 순수 파일 시스템 체크이며, 수 초 내에 완료됩니다:

#!/usr/bin/env python3
# tools/validate_workflow.py

...

CI (GitHub Actions)에 연결됨:

# .github/workflows/workflow-ci.yml
name: Workflow CI

...

Gate 2: 데이터 계약 검증 (Data Contract Verification)

Gate 2는 모든 단계(Phase)의 선언된 context_inputs가 상위 단계(upstream phases)의 실제 출력 필드와 일치하는지 검증합니다.

# tests/integration/test_context_alignment.py

import yaml, json, re
...
```

json\n({.*?})\n

```", template, re.DOTALL)
    if schema_match:
        return set(json.loads(schema_match.group(1)).keys())
    return set()
...

버전 번호 규칙 (Version Number Rules)

워크플로 파일은 코드입니다. 모든 변경 사항은 버전을 가져야 합니다.

MAJOR.MINOR.PATCH

MAJOR: 단계(Phase) 구조 변경
...

버전 번호가 저장되는 위치:

# SKILL.md (워크플로 엔트리 파일)
---
name: wf-bug-e2e
...

// workflow_state.json (런타임에 바인딩되며, 재개 시 검증됨)
{
  "workflow_version": "1.3.0",
...

릴리스 프로세스 (Release Process)

1단계: 이유를 문서화하세요
CHANGELOG.md에 작성: 왜 이 변경이 필요한가? 무엇이 변경되었는가?
"일부 로직 최적화"라고 쓰지 마세요 — "Phase 3 신뢰도 임계값(confidence threshold) 변경"과 같이 작성하세요
...

CHANGELOG 템플릿 (CHANGELOG Template)

# CHANGELOG

## v1.3.0 (2026-06-01)
...

디자인 체크리스트 (Design Checklist)

파일 구조 (File structure)

• Policy / Workflow / TaskSpec / Tool 4계층 분리
• config.yaml에 가변 파라미터(타임아웃, 재시도 횟수, 모델 선택) 중앙 집중화
• SKILL.md에 버전 필드 포함

Gate 1 (정적 검증, static validation)

• 모든 템플릿 참조가 디스크에 존재함
• 모든 라우팅 대상(routing targets)이 알려진 단계(phases) 또는 예약된 키워드를 가리킴
• 모든 커밋 시 CI에서 자동으로 실행됨

Gate 2 (스키마 테스트, schema tests)

• context_inputs가 상위 단계(upstream Phase)의 출력 필드 테스트와 일치함
• 모든 라우팅 조건의 엣지 케이스(edge cases)에 대한 테스트 커버리지가 확보됨
• 모든 커밋 시 CI에서 자동으로 실행됨

Gate 3 (엔드 투 엔드 회귀 테스트, end-to-end regression)

• MAJOR 버전 변경 시 필수 사항
• 결과를 베이스라인(baseline)과 비교; 임계값 위반 시 릴리스 차단

버전 관리 (Version management)

• 모든 릴리스는 SKILL.md의 버전 번호를 업데이트함
• CHANGELOG는 단순히 무엇이 바뀌었는지가 아니라 변경 이유를 문서화함

요약 (Summary)

1. 3개의 게이트, 3가지 속도: 몇 초 만에 수행되는 정적 검증(static validation)은 파일 참조 오류를 잡아내고, 몇 분 만에 수행되는 스키마 테스트(schema tests)는 계약 불일치(contract misalignments)를 잡아내며, 몇 시간 만에 수행되는 엔드 투 엔드 회귀 테스트(end-to-end regression)는 동작 회귀(behavior regressions)를 잡아냅니다. 처음 두 단계가 낮은 비용으로 대부분의 오류를 처리합니다.
2. 버전 번호는 동작 변경과 안전한 업데이트를 구분합니다: MAJOR 버전은 라우팅이나 스키마를 변경하여 진행 중인 실행(in-progress runs)에 영향을 미치며, PATCH 버전은 문구를 변경하여 기존 상태 파일(state files)이 조용히 업그레이드되도록 합니다.
3. CHANGELOG는 작업이 아닌 이유를 문서화합니다: "임계값을 0.95에서 0.9로 변경함"은 작업(action)입니다. "Gate A가 목표치인 20%를 초과하여 18%의 빈도로 트리거됨"은 이유(reason)입니다. 6개월 후에는 이유만 있으면 됩니다.

PrimeSkills를 확인해 보세요 — 실제 기업급 워크플로 (workflows)에서 검증된 AI 에이전트 (agents) 및 기술 (skills)을 엄선하여 제공하는 마켓플레이스입니다. 불필요한 내용은 배제하고, 실제로 작동하는 것들만 제공합니다.

제 홈페이지에서 더 유용한 지식과 흥미로운 제품들을 찾아보세요.