워크플로우 전 대화: CodeMachine의 컨트롤러 패턴

Source: Dev.to

위에 제공된 링크만으로는 번역할 본문이 포함되어 있지 않습니다. 번역을 원하는 텍스트(기사 내용)를 그대로 복사해서 제공해 주시면, 요청하신 대로 마크다운 형식과 코드 블록, URL은 그대로 유지하면서 한국어로 번역해 드리겠습니다.

컨트롤러 단계가 있는 에이전시 워크플로

에이전시 워크플로를 구축할 때 흔히 나타나는 패턴: 자율 파이프라인이 실행되기 전에 누군가가 요구사항을 수집해야 한다.

CodeMachine v0.8.0은 컨트롤러 패턴을 도입하여 워크플로 실행 전에 AI 제품 소유자(PO)와 대화할 수 있는 일급 방법을 제공합니다.

이 walkthrough는 스펙 기반 개발 워크플로를 시연합니다. 여기서 PO 에이전트가 요구사항을 수집하고, 이후 분석, 아키텍처, 구현을 담당하는 전문 에이전트에게 넘깁니다.

왜 별도의 컨트롤러가 필요한가?

멀티 에이전트 워크플로는 보통 프롬프트로 시작해 자율적으로 실행됩니다.
하지만 실제 개발에서는 다음이 필요합니다:

시각적 개요

┌─────────────────────────────────────────────────────────────┐
│                    Controller Phase                         │
│              (Interactive PO conversation)                  │
│                                                             │
│   User ←→ spec-po agent (session persisted)                 │
│                                                             │
│   [Enter with empty input] → Confirmation Dialog            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ workflow:controller-continue
┌─────────────────────────────────────────────────────────────┐
│                   Execution Phase                           │
│              (Autonomous agent pipeline)                    │
│                                                             │
│   spec-analyst → spec-architect → spec‑api‑designer → …      │
│                                                             │
│   [Press C] → Return to Controller Dialog                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ workflow:return-to-controller
┌─────────────────────────────────────────────────────────────┐
│                 Return to Controller                        │
│          (Pause workflow, resume PO session)                │
│                                                             │
│   User ←→ spec-po agent (same session)                      │
│                                                             │
│   [Enter with empty input] → Resume Workflow                │
└─────────────────────────────────────────────────────────────┘

코드에서 컨트롤러 선언하기

export default {
    name: 'Spec-Driven Development',
    controller: controller('spec-po', {}),   // PO agent for pre‑workflow chat
    specification: false,

    steps: [
        separator("∴ Discovery Phase ∴"),
        resolveStep('spec-po', {}),               // PO step (auto‑skipped)
        resolveStep('spec-analyst', {}),

        separator("∴ Design Phase ∴"),
        resolveStep('spec-architect', {}),
        resolveStep('spec-api-designer', {}),

        separator("∴ Implementation Phase ∴"),
        resolveStep('spec-setup', {}),
        resolveStep('spec-impl-orchestrator', {}),

        separator("⟲ Review Loop ⟲"),
        resolveStep('spec-tester', { interactive: false }),
        resolveModule('spec-review', { interactive: false, loopSteps: 2 }),
    ],
};

핵심 포인트

• controller('spec-po', {}) – 사전 워크플로우 대화를 위한 PO 에이전트를 선언합니다.
• 동일한 PO 에이전트가 1단계에도 나타나며, 컨트롤러 단계가 실행될 때 이 단계는 자동으로 완료된 것으로 표시됩니다(중복 실행되지 않음).
• controller() 함수는 엔진/모델 오버라이드를 받을 수 있습니다:

controller('spec-po', {
    engine: 'claude',               // 엔진 오버라이드
    model:  'claude-4.5-sonnet'      // 모델 오버라이드
})

PO 대화가 이후 단계와 다른 기능이 필요할 때 유용합니다.

Interaction Flow

Starting the Workflow

┌──────────────────────────────────────────────────────────────┐
│  CodeMachine v0.8.0                                          │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ▸ spec-po (Running)                                         │
│                                                              │
│  What would you like to build today?                         │
│──────────────────────────────────────────────────────────────│
│                                                              │
│  > A todo list app with Next.js and SQLite                   │
│                                                              │
└──────────────────────────────────────────────────────────────┘

대화는 빈 줄에 Enter 키를 누를 때까지 계속됩니다. 그 후 확인 대화 상자가 나타납니다:

┌────────────────────────────────────────┐
│   Ready to start the workflow?         │
│                                        │
│   [Start]   [Continue Chat]            │
└────────────────────────────────────────┘

• Start 를 선택하면 workflow:controller-continue가 트리거되어 Execution Phase 로 전환됩니다.

Session Persistence

컨트롤러 세션은 디스크에 저장됩니다. 예:

{
  "controllerConfig": {
    "agentId": "spec-po",
    "sessionId": "ses_44785e25dffeDZqs8kVN7KbfIx",
    "monitoringId": 1
  },
  "autonomousMode": "true"
}

Benefits

• Resume on crash – CLI가 대화 중에 충돌하더라도 세션을 복구할 수 있습니다.
• Return to controller – 워크플로 중간에 일시 정지하고 같은 PO 세션으로 돌아갈 수 있습니다.
• Log viewing – 완료된 PO 단계를 클릭하면 전체 대화 기록을 확인할 수 있습니다.

Pausing Execution & Returning to the Controller

자동 파이프라인 실행 중에 C 키를 눌러 일시 정지합니다:

┌──────────────────────────────────────────────────────────────┐
│  Workflow Pipeline (8 items)                                 │
├──────────────────────────────────────────────────────────────┤
│  … (running steps)                                            │
│                                                              │
│  Press C to return to the PO conversation                     │
└──────────────────────────────────────────────────────────────┘

그러면 Return to Controller 화면으로 돌아가 PO와 채팅을 계속할 수 있습니다. 빈 입력으로 종료하면 워크플로가 중단된 지점부터 다시 시작됩니다.

요약

• Controller pattern은 요구 사항 수집과 자율 실행을 깔끔하게 분리합니다.
• 세션 지속성은 crash recovery, mid‑workflow returns, full conversation logs를 가능하게 합니다.
• 동일한 PO 에이전트가 컨트롤러와 일반 단계 역할을 모두 수행할 수 있으며, 중복을 방지하기 위해 자동 건너뛰기가 적용됩니다.
• 엔진/모델 오버라이드는 PO 대화 기능을 맞춤화할 수 있는 유연성을 제공합니다.

CodeMachine v0.8.0을 사용하면 견고하고 사양 기반의 다중 에이전트 개발 파이프라인을 구축하는 것이 간단하고 탄력적으로 됩니다.

워크플로 개요

                                                             │
│  ✓ Hady [PO] (completed)                                     │
│  ▸ Moaz [Analyst] (running)         ← Paused               │
│  ○ Atef [Architect]                                          │
│  ○ Essam [API]                                               │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│  [C] Controller  [Esc] Stop                                  │
└──────────────────────────────────────────────────────────────┘

컨트롤러 상호작용

• C 키를 눌렀을 때

  1. 현재 단계가 중단됩니다.
  2. 워크플로 상태 머신이 PAUSE 상태로 전환됩니다.
  3. 단계가 “onboarding.” 으로 전환됩니다.
  4. 컨트롤러 세션이 재개됩니다.

• 대화가 끝난 후

  • Enter 키를 눌러 일시 중지된 단계부터 워크플로를 재개합니다.

전체 사양‑주도 워크플로우 (컨트롤러 포함)

export default {
    name: 'Spec-Driven Development',
    controller: controller('spec-po', {}),
    specification: false,

    tracks: {
        question: 'What are we working on?',
        options: {
            new_project: { label: 'New Project' },
            existing_app: { label: 'Existing App' },
            refactor: { label: 'Refactor' },
        },
    },

    conditionGroups: [
        {
            id: 'features',
            question: 'What features does your project have?',
            multiSelect: true,
            conditions: {
                has_ui:   { label: 'Has UI' },
                has_auth: { label: 'Has Authentication' },
                has_db:   { label: 'Has Database' },
            },
        },
    ],

    steps: [
        separator("∴ Discovery Phase ∴"),
        resolveStep('spec-po', {}),
        resolveStep('spec-analyst', {}),

        separator("∴ Design Phase ∴"),
        resolveStep('spec-architect', {}),
        resolveStep('spec-api-designer', {}),

        separator("∴ Implementation Phase ∴"),
        resolveStep('spec-setup', {}),
        resolveStep('spec-impl-orchestrator', {}),

        separator("⟲ Review Loop ⟲"),
        resolveStep('spec-tester', { interactive: false }),
        resolveModule('spec-review', { interactive: false, loopSteps: 2 }),
    ],

    subAgentIds: [
        'spec-dev-data',
        'spec-dev-api',
        'spec-dev-ui',
        'spec-dev-tests',
    ],
};

요구 사항 및 솔루션

왜 컨트롤러 패턴인가?

컨트롤러 패턴은 에이전시 워크플로우에서 중요한 격차를 메워줍니다: 시스템이 자동으로 진행되기 전에 인간‑AI 대화가 필요합니다. 이 상호작용을 1급 원시 연산으로 승격함으로써 다음과 같은 이점을 얻습니다:

• 세션 지속성 – 작업을 나중에 재개해도 컨텍스트가 손실되지 않습니다.
• 명확한 핸드오프 UX – 사용자가 전환을 명시적으로 확인하여 실수로 인한 동작을 줄입니다.
• 워크플로우 중간 복귀 – 사용자가 일시 정지하고 논의한 뒤 정확히 중단한 지점부터 계속 진행할 수 있습니다.

이러한 기능을 통해 CodeMachine은 현실 세계 개발 프로세스를 보다 충실히 모델링할 수 있습니다.

리소스

• GitHub의 CodeMachine
• 워크플로우 예시
• 문서