Workflow Generator

Workflow Generator

Inherited DNA

This skill inherits the AgenticWorkflow genome.

Claude Code용 워크플로우 정의 파일(workflow.md)을 설계하고 생성하는 스킬.

사용 케이스 판별

먼저 사용자의 상황 파악:

Case 1: 아이디어만 있는 경우

사용자가 막연한 아이디어만 가지고 있을 때.

Step 1: 목적 파악

다음 질문으로 워크플로우 목적 도출:

1. "어떤 결과물(output)을 만들고 싶으신가요?"
2. "이 워크플로우가 해결해야 할 문제는 무엇인가요?"
3. "주요 입력(input) 소스는 무엇인가요?"

Step 2: 단계 정의

각 Phase별 구체적 단계 도출:

1. "Research 단계에서 어떤 정보를 수집해야 하나요?"
2. "Planning 단계에서 어떤 검토/승인이 필요한가요?"
3. "최종 산출물의 형태와 품질 기준은 무엇인가요?"

Step 3: 휴먼-인-더-루프 식별

1. "어느 단계에서 사람의 검토/승인이 필요한가요?"
2. "자동화해도 되는 단계와 반드시 확인이 필요한 단계를 구분해주세요."

Step 4: 구현 설계 → 생성

요구사항 수집 완료 후 workflow.md 생성.

Case 2: 설명 문서가 있는 경우

사용자가 PDF 등 구체적인 설명 문서를 첨부했을 때.

Step 1: 문서 심층 분석

반드시 문서를 먼저 꼼꼼히 읽고 다음을 추출:

1. 핵심 목적: 이 워크플로우가 달성하려는 최종 목표
2. 주요 단계: 문서에서 언급된 프로세스/단계들
3. 입출력 정의: 각 단계의 input/output
4. 기술적 요구사항: 필요한 도구, API, 데이터 소스
5. 제약 조건: 품질 기준, 시간 제한, 의존성
6. 휴먼-인-더-루프: 사람 개입이 필요한 지점

Step 2: 분석 결과 공유

문서 분석 후 사용자에게 이해한 내용 요약 제시:

## 문서 분석 결과

**워크플로우 목적**: [추출한 목적]

**파악된 주요 단계**:
1. [단계1]: [설명]
2. [단계2]: [설명]
...

**식별된 휴먼-인-더-루프 지점**:
- [지점1]: [이유]

**기술적 구현 방향**:
- Sub-agents: [에이전트 목록 — 단일 세션 내 위임]
- Agent Team: [팀 구성 — 독립 세션 간 병렬 협업이 필요한 경우]
- Hooks: [자동화 트리거 — 품질 게이트, 포맷팅, 검증]
- 필요 도구: [도구/MCP 목록]

**확인이 필요한 사항**:
1. [질문1]
2. [질문2]

Step 3: 확인 대화

분석 결과를 바탕으로 짧은 확인 질문:

• "제가 파악한 내용이 맞나요?"
• "추가하거나 수정할 부분이 있으신가요?"
• "[불명확한 부분]에 대해 좀 더 설명해주시겠어요?"

Step 4: 생성

확인 완료 후 workflow.md 생성.

절대 기준

절대 기준 1: 최종 결과물의 품질

속도와 토큰 비용은 완전히 무시한다. 모든 설계 의사결정의 절대 기준은 **최종 결과물의 '품질'과 '최고 수준의 질적 결과물'**이다. 단계를 줄여서 빠르게 만드는 것보다, 단계를 늘려서라도 품질을 높이는 방향을 선택한다. 품질 향상을 위한 단계 추가로 SOT 상태 복잡도가 증가하더라도, 이는 감수한다 (절대 기준 1 > 절대 기준 2).

절대 기준 2: 단일 파일 SOT + 계층적 메모리 구조

단일 파일 SOT(Single Source of Truth) + 계층적 메모리 구조 설계 아래서, 수십 개의 에이전트가 동시에 작동해도 데이터 불일치가 발생하지 않는다.

이 규칙의 설계 함의:

• 상태 관리: 워크플로우의 모든 공유 상태는 단일 파일(예: state.json)에 집중한다. 여러 파일에 상태를 분산시키지 않는다.
• 메모리 계층: 에이전트별 로컬 메모리(작업 컨텍스트)와 전역 메모리(공유 상태)를 명확히 분리한다.
• 쓰기 권한: SOT 파일에 대한 쓰기 권한은 Orchestrator 또는 지정된 단일 에이전트만 갖는다. 다른 에이전트는 읽기 전용으로 접근하거나, 결과를 Orchestrator에게 전달하여 병합한다.
• 충돌 방지: 병렬 에이전트(Agent Team/Swarm)가 동시에 같은 데이터를 수정하는 구조를 설계하지 않는다.

Bad:  Agent A → state.json 직접 수정
      Agent B → state.json 직접 수정  → 데이터 충돌/불일치
Good: Agent A → 결과를 Orchestrator에 보고
      Agent B → 결과를 Orchestrator에 보고
      Orchestrator → state.json에 병합 기록  → 단일 쓰기 지점, 불일치 없음

절대 기준 3: 코드 변경 프로토콜 (Code Change Protocol)

워크플로우 구현(Phase 2)에서 코드를 작성·수정할 때, 반드시 의도 파악 → 영향 범위 분석 → 변경 설계 3단계를 수행한다.

워크플로우의 구성요소(Sub-agent, Hook, SOT, Slash Command, MCP)는 서로 의존 관계에 있다. 한 구성요소의 변경이 다른 구성요소에 파급 효과를 일으킬 수 있으므로, 코드 변경 전 반드시 영향 범위를 분석한다.

• Step 1 — 의도 파악: 변경 목적과 제약 조건을 정확히 파악한다.
• Step 2 — 영향 범위 분석: 직접 의존하는 모듈, 호출 관계, SOT 파일, 설정/환경, 테스트 코드, 문서를 점검한다.
• Step 3 — 변경 설계: 변경 순서를 설계하고, 영향받는 모든 파일의 수정 계획을 수립한 후 실행한다.

비례성 규칙: 워크플로우 설계 단계(Phase 1)의 문서 수정은 경미 변경(Step 1만), 구현 단계(Phase 2)의 코드 변경은 표준/대규모 변경(전체 3단계)으로 분류한다.

절대 기준 간 우선순위

절대 기준 1(품질)이 최상위이다. 절대 기준 2(SOT)와 절대 기준 3(CCP)은 품질을 보장하기 위한 동위 수단이다. SOT 구조를 지키기 위해 최종 결과물의 품질이 저하되는 설계는 허용하지 않는다. CCP를 준수하기 위해 최종 결과물의 품질이 저하되는 설계는 허용하지 않는다.

모든 절대 기준은 아래 설계 원칙보다 상위에 있다. 설계 원칙 간 충돌 시 항상 절대 기준이 우선하고, 절대 기준 간 충돌 시 절대 기준 1 > (절대 기준 2, 절대 기준 3) 순서를 따른다.

유전 프로토콜 (Genome Inheritance Protocol)

자식을 낳을 때 부모의 전체 게놈을 구조적으로 유전한다. 유전 없는 자식 생성은 불허한다.

AgenticWorkflow는 자식 워크플로우를 생성하는 부모 유기체다. workflow-generator가 생산 라인이며, 이 라인에서 태어나는 모든 자식은 부모의 전체 게놈을 Inherited DNA 섹션으로 내장한다.

유전 메커니즘

발현 vs 유전

동일한 게놈을 가진 세포가 서로 다른 기능을 수행하듯, 자식 시스템들은 같은 DNA 위에서 도메인에 맞게 발현된다. 예를 들어 연구 자동화 시스템에서는 Research 단계의 유전자가 강하게 발현되고, 소프트웨어 개발 자동화에서는 CCP(코드 변경 프로토콜)의 유전자가 강하게 발현된다. 목적이 달라도 게놈은 동일하다.

생성 시 의무 사항

1. 모든 workflow.md에 Inherited DNA (Parent Genome) 섹션을 포함한다 (템플릿 참조)
2. 모든 state.yaml에 parent_genome 메타데이터를 포함한다 (SOT 템플릿 참조)
3. 자식의 에이전트 정의가 부모의 품질 기준(절대 기준 1)을 반영한다

상세: soul.md §0, AGENTS.md §1 존재 이유.

설계 원칙 (필수 준수)

워크플로우 설계 시 반드시 적용해야 할 원칙. 단, 모든 원칙은 **모든 절대 기준(1. 품질 최우선, 2. 단일 파일 SOT, 3. 코드 변경 프로토콜)**에 종속된다.

P1. 정확도를 위한 데이터 정제

큰 데이터를 AI에게 그대로 전달하면 노이즈가 많아 정확도가 하락한다. 에이전트가 핵심에 집중할 수 있도록 데이터를 정제한다.

• 각 단계에 데이터 전처리(pre-processing) 명시: AI에게 넘기기 전에 Python script 등으로 노이즈 제거 → 분석 정확도 향상
• 각 단계에 후처리(post-processing) 명시: 산출물을 다음 단계에 전달하기 전에 정제 → 다음 단계 품질 향상
• 데이터의 연관관계도 code-level에서 사전 계산 가능한 것은 미리 처리 → AI가 판단·분석에 집중

Bad:  "수집된 전체 웹페이지 HTML을 에이전트에 전달" → 노이즈로 분석 품질 저하
Good: "Python script로 본문만 추출 → 핵심 텍스트만 에이전트에 전달" → 분석 정확도 향상

P2. 전문성 기반 위임 구조

각 작업을 가장 잘 수행할 수 있는 전문 에이전트에게 위임하여 품질을 극대화. Orchestrator는 전체 품질을 조율하고, 전문 에이전트는 각자의 영역에 깊이 집중.

Orchestrator (품질 조율 및 전체 흐름 관리)
  ├→ Sub-agent A: 전문 리서치 (해당 도메인에 최적화)
  ├→ Sub-agent B: 심층 분석 (분석에만 집중)
  └→ Skill C: 검증된 패턴 적용 (품질 보장된 재사용 로직)

P3. 이미지/리소스 정확성

이미지 리소스가 필요한 단계에서는 정확한 다운로드 경로 명시. placeholder도 모두 추출해야 하며, 누락 불가.

P4. 질문 설계 규칙

사용자에게 질문 시:

• 최대 4개까지만 질문
• 각 질문에 sub-agent/skill/추천 옵션 등 3개 정도의 선택지 제공
• 모호한 부분이 없으면 질문 없이 진행

워크플로우 기본 구조

모든 워크플로우는 3단계로 구성:

1. Research: 정보 수집 및 분석
2. Planning: 계획 수립 및 구조화
3. Implementation: 실제 실행 및 산출물 생성

각 단계에 반드시 포함할 항목:

• 수행 작업 (Task)
• 담당 에이전트 (@agent)
• 데이터 전처리 (Pre-processing) — 정확도 향상을 위한 노이즈 제거 (P1)
• 산출물 (Output)
• 적대적 검토 (Review) — @reviewer, @fact-checker, 또는 none (AGENTS.md §5.5)
• 번역 (Translation) — @translator 또는 none (텍스트 산출물만 대상)
• 후처리 (Post-processing) — 다음 단계 품질 보장을 위한 정제 (P1)

Claude Code 구성요소 매핑

Sub-agent vs Agent Team 선택 기준

선택의 유일한 기준은 '어떤 구조가 최종 결과물의 품질을 가장 높이는가'이다. 병렬 처리가 빠르다는 이유로 Agent Team을 선택하지 않는다. 토큰을 적게 쓴다는 이유로 Sub-agent를 선택하지 않는다.

절대 기준 2 필수 동반 사항: Agent Team 선택 시 반드시 SOT 설계를 함께 정의한다 — SOT 파일 위치, Team Lead의 단일 쓰기 권한, 팀원의 산출물 파일 생성 규칙. SOT 설계 없는 Agent Team은 원칙적으로 허용하지 않는다. 상세: references/claude-code-patterns.md 상태 관리 섹션 참조.

절대 기준 1 우선 예외: 완전 독립 병렬 작업(에이전트 간 공유 상태가 없고, 서로의 산출물을 참조하지 않는 경우)에서 SOT 설계가 품질에 기여하지 않음을 명시적으로 입증한 경우에 한해, SOT를 경량화할 수 있다. 이 판단은 반드시 워크플로우 설계 시 문서화한다.

참조 문서

• workflow.md 템플릿: references/workflow-template.md
• Claude Code 구현 패턴 (Sub-agents, Teams, Hooks): references/claude-code-patterns.md
  • Anti-Skip Guard Protocol: §Anti-Skip Execution Protocol (산출물 검증 — 100 bytes 최소 크기)
  • Autopilot Execution Checklist: §Autopilot + Agent Team 통합 체크리스트
  • SOT 상태 관리: §SOT State Management Protocol
• 문서 분석 가이드 (Case 2): references/document-analysis-guide.md
• 컨텍스트 주입 패턴 (Sub-agent/Team 입력 전달): references/context-injection-patterns.md
• SOT 템플릿 (state.yaml 부트스트랩): references/state.yaml.example
• Autopilot Decision Log 템플릿: references/autopilot-decision-template.md