하나의 워크플로에서 시스템으로

하나의 워크플로를 관리하는 것은 쉽습니다. 하지만 다섯 개가 되면 문제가 발생합니다:

• 사용자가 워크플로의 존재를 모르거나, 적절한 것을 찾지 못함
• 두 워크플로의 기능이 70% 중복됨; 유지보수 비용이 두 배로 증가
• 누군가 공유된 워크플로를 수정하여 모든 의존 관계에 있는 워크플로를 망가뜨림
• 운영 장애(production incident) 발생 시 어떤 워크플로 버전이 원인이 되었는지 흔적이 남지 않음

워크플로 레지스트리(Workflow Registry)는 발견(discovery) 문제를 해결합니다. 워크플로 컴포지션(Workflow composition)은 중복 문제를 해결합니다. 거버넌스(Governance) 메커니즘은 수정 권한과 책임 소재를 관리합니다.

워크플로 레지스트리 (Workflow Registry)

스킬 레지스트리(Skill Registry)가 스킬 발견을 관리하듯, 워크플로 레지스트리(Workflow Registry)는 워크플로 발견을 관리합니다.

# workflow-registry.yaml
workflows:
  - id: wf-bug-e2e
...

레지스트리의 세 가지 용도

용도 1: 워크플로 발견 (Workflow discovery)

사용자 입력: "이 버그를 수정해줘." 시스템은 trigger_keywords를 매칭하여 wf-bug-e2e를 찾아내고 자동으로 라우팅합니다. 찾아볼 목록이 필요 없습니다.

용도 2: 상태 모니터링 (Health monitoring)

metrics 필드를 최신 상태로 유지하고 워크플로 간 통합 상태 대시보드를 구축합니다:

Workflow                  Runs/mo   Success   Avg cost
──────────────────────────────────────────────────────
wf-bug-e2e                45        82%        $0.51
...

용도 3: 버전 의존성 추적 (Version dependency tracking)

wf-sprint-planning이 wf-bug-e2e를 호출할 때(다음 섹션 참조), 레지스트리는 해당 의존성을 기록합니다. wf-bug-e2e가 MAJOR 버전을 출시하기 전에, 시스템은 어떤 워크플로들이 이에 의존하고 있는지 확인하고 영향을 받는 소유자들에게 알림을 보냅니다.

워크플로 컴포지션 (Workflow Composition)

워크플로 컴포지션(Workflow composition)이란 하나의 워크플로가 파이프라인 단계로서 다른 워크플로를 호출하는 것을 의미합니다.

시나리오: wf-sprint-planning은 매주 월요일에 실행됩니다. 발견된 각 P0 버그에 대해 wf-bug-e2e를 트리거하고, 모든 결과가 나올 때까지 기다린 후, 주간 계획 보고서를 생성합니다.

# wf-sprint-planning/workflow.md

## Phase 2: Fix P0 Bugs
...

yaml  
phase_2_fix_p0:  
type: workflow_fanout  
child_workflow: wf-bug-e2e  
inputs:  
- source: phases.phase1.p0_bugs  
map_to: jira_key  
wait_strategy: collect-all  
timeout: 4h  
on_timeout: continue_with_available  

Phase 3: 주간 계획 생성 (Generate Weekly Plan)

Phase 2의 결과(각 버그에 대한 수정 상태)를 사용하여 주간 계획 보고서(weekly plan report)를 생성합니다.

yaml

자식 워크플로 인터페이스 설계 (Child workflow interface design):

서브 에이전트(subagents)와 마찬가지로, 자식 워크플로(child workflows)도 선언된 입력(input) 및 출력(output) 계약(contracts)이 필요합니다:

# wf-bug-e2e 인터페이스 선언 (SKILL.md 내)
interface:
  inputs:
...

부모 워크플로(parent workflow)는 자식의 내부 상태 파일(internal state files)이 아닌, 선언된 출력 필드(output fields)만을 읽습니다.

도구 간 이식성 (Cross-Tool Portability)

동일한 워크플로가 Claude Code 도구를 호출하는 OpenClaw 환경에서도 실행될 수 있고, 다른 도구 구현체를 호출하는 다른 환경에서도 실행될 수 있습니다. 즉, 워크플로 정의(workflow definition)는 변경되지 않습니다.

# config.yaml tool_bindings
tool_bindings:
  read_file:
...

# workflow.md는 도구 이름이 아닌 기능(capabilities)을 선언합니다
Phase 6 Step 6.1: 폴링 크론 잡 생성 (capability: create_cron)
Phase 7 Step 7.2: 종료 알림 전송 (capability: send_notification)

def resolve_tool(capability: str, runtime: str) -> str:
    return config["tool_bindings"][capability][runtime]

...

배포 환경을 전환할 때는 config.yaml만 변경하면 되며, 워크플로 로직(workflow logic)은 동일하게 유지됩니다.

세 가지 거버넌스 질문 (Three Governance Questions)

질문 1: 누가 워크플로를 수정할 수 있는가?

개인 워크플로 (단일 소유자):
  → 자유롭게 수정 가능, 리뷰 불필요

...

구현: Git의 CODEOWNERS가 리뷰 권한을 선언합니다:

# .github/CODEOWNERS
skills/wf-bug-e2e/**          @chendongqi @team-lead
skills/wf-sprint-planning/**  @team-lead

질문 2: 워크플로가 무엇을 수행했는가, 그리고 누가 책임을 지는가?

각 워크플로가 완료된 후 audit.json을 작성하며(W6에서 다룸), 책임 체인(accountability chain) 필드를 추가합니다:

{
  "workflow_id": "wf-bug-e2e-AE-33995-20260601",
  "workflow_version": "1.3.0",
...

책임 체인 (Accountability chain): triggerer → workflow version → phase → human approver. 모든 외부 쓰기(external write) 작업은 특정 개인과 워크플로 버전으로 추적됩니다.

질문 3: 어떻게 빠르게 롤백(Roll back)하나요?

버전 스냅샷 (Version snapshot):

# 새 버전을 출시하기 전에 이전 버전을 스냅샷으로 저장합니다
cp -r skills/wf-bug-e2e skills/wf-bug-e2e.v1.2.0.bak

...

더 체계적인 방법: git 태그 (git tags) 사용:

# 출시 시 태그 생성
git tag wf-bug-e2e-v1.3.0

...

진행 중인 인스턴스 (In-flight instances) 처리:

롤백 후에도 여전히 실행 중인 워크플로 인스턴스(status != done)는 롤백된 버전을 사용하고 있습니다. 해당 소유자들에게 알림을 보냅니다:

def handle_in_flight_on_rollback(state_dir: Path, rolled_back_version: str, previous_version: str):
    for state_file in state_dir.glob("**/workflow_state.json"):
        state = json.loads(state_file.read_text())
...

구현 로드맵 (Implementation Roadmap)

Level 1 — 개인 (지금 바로 수행):
  □ 모든 기존 워크플로를 나열하는 workflow-registry.yaml 생성
  □ 각 워크플로에 대해 domain, owner, status, trigger_keywords 작성
...

요약 (Summary)

1. 레지스트리 (Registry)는 발견(discovery)과 모니터링의 기반입니다: 레지스트리가 없으면 워크플로는 블랙박스 형태로 쌓이게 되지만, 레지스트리가 있으면 각 워크플로의 상태, 비용, 성공률을 확인할 수 있으며 trigger_keywords를 통해 자동 라우팅이 가능해집니다.
2. 컴포지션 (Composition)은 시스템에 계층 구조를 부여합니다: 부모 워크플로(스프린트 계획)가 자식 워크플로(버그 수정)를 호출하여 두 개의 계층을 형성합니다. 자식 워크플로는 서브에이전트 (subagent) 설계와 정확히 동일한 원칙을 사용하여 입출력 계약 (input/output contracts)을 선언합니다.
3. 세 가지 거버넌스 (Governance) 질문에 대한 세 가지 구체적인 답변: CODEOWNERS를 통한 수정 권한 + 리뷰 프로세스; triggerer, version, approver를 포함한 audit.json을 통한 책임 소재 (accountability); git 태그를 통한 롤백 및 진행 중인 인스턴스 알림.

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

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