AACWorkflow Docs

아키텍처 다이어그램

AACWorkflow 시스템 아키텍처, 업무 생명 주기, 보안 경계 및 에이전트 협업 흐름의 시각적 가이드입니다.

AACWorkflow 아키텍처, 업무 디스패치, 보안 모델 및 에이전트 협업 패턴에 대한 참고 다이어그램입니다.

시스템 아키텍처

AACWorkflow Cloud는 웹 UI, 데몬을 통해 사용자 머신에서 실행되는 에이전트 및 중앙 백엔드를 연결합니다.

graph TB
    subgraph cloud ["AACWorkflow Cloud"]
        api["API Server<br/>(Go + PostgreSQL)"]
        ws["WebSocket<br/>Real-time Updates"]
        auth["Auth Service<br/>(OAuth, PAT)"]
    end

    subgraph local ["User Machine (Local Runtime)"]
        daemon["Daemon<br/>(Long-running)"]
        ai["AI Coding Tool<br/>(Claude Code, Cursor, etc.)"]
        cwd["Code Directory<br/>(Git repo)"]
    end

    subgraph ui ["Web UI"]
        board["Issue Board"]
        settings["Settings &<br/>Member List"]
        comments["Comments"]
    end

    board -->|assign issue| api
    api -->|dispatch task| ws
    ws -->|task event| daemon
    daemon -->|poll every 30s| api
    daemon -->|invoke| ai
    ai -->|read/write| cwd
    ai -->|report result| daemon
    daemon -->|upload result| api
    api -->|update| ws
    ws -->|refresh| board
    settings -->|create agent| api
    comments -->|post comment| api
    auth -.->|verify PAT| daemon
    auth -.->|verify session| ui

핵심 흐름:

  • 업무 디스패치: 이슈 할당 → API → WebSocket → 데몬 (30초 이내)
  • 실행: 데몬이 로컬에서 AI 도구 호출; 도구가 코드 읽기, 명령 실행, 파일 편집
  • 결과 업로드: 에이전트가 API에 완료 보고; WebSocket이 실시간으로 웹 UI 알림
  • 인증 경계: PAT(개인 액세스 토큰)은 데몬용; 세션 쿠키는 웹 UI용

업무 생명 주기

업무는 생성부터 완료까지 다양한 상태를 통과하며, 진행 중 재시도와 웹훅이 있습니다.

graph LR
    queued["📋 Queued<br/>(Issue created)"]
    dispatched["🚀 Dispatched<br/>(Daemon picked it up)"]
    running["⚙️ Running<br/>(AI tool executing)"]
    completed["✅ Completed<br/>(Result uploaded)"]
    failed["❌ Failed<br/>(Error or timeout)"]
    retry["🔄 Retrying<br/>(Automatic retry)"]

    queued -->|daemon polls| dispatched
    dispatched -->|daemon invokes AI| running
    running -->|success| completed
    running -->|error| failed
    failed -->|retry policy| retry
    retry -->|running| running
    retry -->|final failure| failed

    completed -->|webhook| slack["Slack Notification"]
    failed -->|webhook| slack

상태 타이밍:

  • Queued → Dispatched: ≤ 30초 (데몬 폴링 간격)
  • Dispatched → Running: ≤ 5초 (AI 도구 시작)
  • Running 지속 시간: 초~시간 (업무 복잡도에 따라)
  • Failed → Retry: 설정 가능한 백오프 (기본 지수)

보안 및 신뢰 경계

AACWorkflow는 클라우드, 데몬 및 로컬 실행 간 명확한 경계를 강제합니다.

graph TB
    subgraph cloud ["AACWorkflow Cloud<br/>(Fully Trusted)"]
        api["API<br/>(Manages auth, dispatch,<br/>webhooks)"]
        db["PostgreSQL<br/>(Stores issues, agents,<br/>audit logs)"]
    end

    subgraph untrusted ["User Machine<br/>(Partially Trusted)"]
        daemon["Daemon<br/>(Runs with user<br/>permissions)"]
        ai["AI Tool<br/>(Untrusted execution<br/>context)"]
        code["Code Directory<br/>(All code readable<br/>by AI tool)"]
    end

    subgraph external ["External Services<br/>(OAuth, Git, Webhooks)"]
        github["GitHub"]
        slack["Slack"]
    end

    api -->|PAT validation| daemon
    api -->|task dispatch| daemon
    daemon -->|result telemetry| api
    api -->|webhook| slack
    api -->|API| github
    ai -->|fork + exec| code
    daemon -->|invoke + stream| ai

    style cloud fill:#90EE90
    style untrusted fill:#FFB6C1
    style external fill:#ADD8E6

신뢰 가정:

  • 클라우드 API: 사용자 입력은 검증 없이 신뢰하지 않음; 모든 코드는 기본적으로 안전
  • 데몬: 사용자의 OS 권한 아래 로컬 실행; 클라우드 API로의 네트워크 접근만 가능
  • AI 도구: 데몬의 OS 사용자 아래 실행; 코드 디렉토리에 읽기/쓰기 접근; 임의 명령 실행 가능
  • 외부 서비스: GitHub/Slack 웹훅은 속도 제한 및 검증됨

에이전트 스킬 및 능력 모델

에이전트는 스킬로 강화될 수 있습니다 — 사전 패키징된 지침, 도구 및 컨텍스트로 특화된 업무를 처리합니다.

graph TB
    subgraph agent ["Agent"]
        name["Name & Provider<br/>(Claude Code, Cursor, etc.)"]
        model["Model Selection<br/>(gpt-4, claude-opus, etc.)"]
        instructions["Custom Instructions<br/>(System prompt)"]
    end

    subgraph skills ["Skills (Optional)"]
        skill1["Skill: Frontend<br/>React + Next.js<br/>guidelines"]
        skill2["Skill: Backend<br/>Go + sqlc<br/>patterns"]
        skill3["Skill: DevOps<br/>Terraform +<br/>Kubernetes"]
    end

    subgraph context ["Runtime Context"]
        files["Code Directory<br/>(Git repo)"]
        tools["Local Tools<br/>(git, npm, go,<br/>make, etc.)"]
        secrets["Env Vars & Secrets<br/>(API keys,<br/>credentials)"]
    end

    agent -->|attached to| skills
    agent -->|runs with| context
    skills -->|loaded before| instructions
    name -->|determines| model

    style skills fill:#FFE4B5

스킬 로딩:

  1. 데몬이 스킬 내용을 에이전트 시스템 프롬프트에 로드
  2. 스킬 컨텍스트(문서, 가이드라인, 예시)가 사용자 업무보다 먼저 옴
  3. 에이전트가 컨텍스트 사용해 더 좋은 결정 (명시적 도구 호출 필요 없음)
  4. 스킬이 쌓임 — 하나의 에이전트의 여러 스킬이 컨텍스트 결합

스쿼드 위임

스쿼드는 스쿼드 리드가 주도하는 에이전트 팀입니다. 들어오는 업무는 레이블, 컴포넌트 또는 키워드에 따라 올바른 에이전트로 자동 라우팅될 수 있습니다.

graph TB
    subgraph squad ["Squad: Backend"]
        lead["🏆 Squad Lead<br/>(Routes issues)"]
        agent1["Agent: Go Expert<br/>(sqlc, handlers)"]
        agent2["Agent: Testing<br/>(unit tests, mocks)"]
        agent3["Agent: DevOps<br/>(migrations, DB)"]
    end

    issue["Incoming Issue<br/>(label: 'backend')"]
    routing["Routing Rule<br/>(Squad + label)"]

    issue -->|matches| routing
    routing -->|dispatches to| squad
    lead -->|decides| agent1
    lead -->|or| agent2
    lead -->|or| agent3

    style squad fill:#E6E6FA
    style lead fill:#FFD700

스쿼드 사용 시기:

  • 다양한 전문성을 가진 여러 에이전트 (프론트엔드, 백엔드, QA, DevOps)
  • 자동 라우팅 규칙 (예: "all backend/* labels → Backend squad")
  • 명확한 소유권 및 책임
  • 에이전트 초점으로 컨텍스트 전환 감소

오토파일럿 트리거 흐름

오토파일럿은 이벤트(이슈 생성, PR 댓글 등)를 감시하고 매칭되는 업무를 자동 디스패치합니다 — 수동 할당 필요 없음.

graph TB
    subgraph event ["Events"]
        new_issue["New Issue Created"]
        pr_comment["PR Comment Posted"]
        schedule["Scheduled Time"]
    end

    subgraph rules ["Autopilot Rules"]
        rule1["Rule: New Issues<br/>with label 'bug'<br/>→ QA Agent"]
        rule2["Rule: PR Comment<br/>mentioning @bot<br/>→ Code Reviewer"]
        rule3["Rule: Daily 9am<br/>→ Digest Agent"]
    end

    subgraph dispatch ["Dispatch"]
        queue["Task Queue"]
        daemon["Daemon picks up<br/>(within 30s)"]
    end

    new_issue -->|event| rule1
    pr_comment -->|event| rule2
    schedule -->|event| rule3
    rule1 -->|matches| queue
    rule2 -->|matches| queue
    rule3 -->|matches| queue
    queue -->|poll| daemon

    style event fill:#E0FFFF
    style rules fill:#FFFACD
    style dispatch fill:#F0F8FF

오토파일럿 사용 사례:

  • 회귀 테스트를 위해 자동으로 QA 스쿼드에 버그 할당
  • 병합된 PR에서 자동으로 릴리스 노트 초안
  • 주기 업무 (일일 상태 체크, 주간 요약)
  • 모든 Terraform 차이를 DevOps 에이전트로 라우팅

데이터 흐름: Issue → Agent → PR → Resolution

엔드-투-엔드 흐름으로 이슈가 할당, 실행 및 PR 연결을 통해 어떻게 이동하는지 보여줍니다.

sequenceDiagram
    participant user as User
    participant web as Web UI
    participant api as API Server
    participant daemon as Daemon
    participant ai as AI Tool
    participant code as Code Dir
    participant github as GitHub

    user->>web: Create Issue
    web->>api: POST /issues
    api->>api: Store issue (status: queued)

    user->>web: Assign to Agent
    web->>api: PATCH /issues/:id (assignee)
    api->>api: Dispatch task (status: dispatched)
    api-->>daemon: WebSocket: New task

    daemon->>daemon: Wake up from poll
    daemon->>ai: Invoke AI tool
    ai->>code: Read codebase, run commands

    ai->>ai: Generate solution
    ai->>code: Edit files, commit to branch
    ai->>github: Push branch, create PR

    daemon->>api: POST /tasks/:id/complete (with PR URL)
    api->>api: Update issue status (completed)
    api-->>web: WebSocket: Task complete

    user->>web: Link PR in issue
    web->>api: PATCH /issues/:id (link_pr_url)
    api->>api: Store PR link, sync PR comments

    github->>api: PR merged webhook
    api->>api: Update issue status (resolved)
    api-->>web: WebSocket: Issue resolved

    web-->>user: Show resolved badge

업무 공간 다중 테넌시

각 업무 공간은 자체 멤버, 에이전트, 이슈 및 감사 로그가 있는 격리된 테넌트입니다.

graph TB
    subgraph ws1 ["Workspace: Acme Corp"]
        team1["Members: alice, bob,<br/>agent-backend"]
        issues1["Issues: AAC-1 to AAC-100"]
        agents1["Agents: 3"]
        board1["Board & Views"]
    end

    subgraph ws2 ["Workspace: StartupXYZ"]
        team2["Members: charlie, diana,<br/>agent-full-stack"]
        issues2["Issues: SXY-1 to SXY-50"]
        agents2["Agents: 2"]
        board2["Board & Views"]
    end

    subgraph ws3 ["Workspace: Open Source"]
        team3["Members: eve, frank,<br/>bot-ci, bot-release"]
        issues3["Issues: OS-1 to OS-200"]
        agents3["Agents: 5"]
        board3["Board & Views"]
    end

    db["PostgreSQL<br/>(Shared database<br/>with workspace_id<br/>partition key)"]

    ws1 -.->|workspace_id=1| db
    ws2 -.->|workspace_id=2| db
    ws3 -.->|workspace_id=3| db

다중 테넌시 보증:

  • 모든 쿼리는 데이터베이스 계층에서 workspace_id로 필터링
  • 업무 공간 간 데이터 유출은 설계상 불가능
  • 감사 로그가 어느 멤버가 어느 업무 공간에서 어떤 변경을 했는지 추적
  • 업무 공간은 독립적으로 아카이브, 이름 변경 또는 삭제 가능

제공자 환경

AACWorkflow는 16개 AI 코딩 도구와 통합되며, 각각 자신의 모델을 실행하고 다양한 API를 제공합니다.

graph TB
    aacw["AACWorkflow<br/>Platform"]

    subgraph claude_ecosystem ["Anthropic Ecosystem"]
        cc["Claude Code<br/>(macOS/Linux)"]
        opus["Model: Claude 3.5 Sonnet<br/>(via API)"]
    end

    subgraph cursor_eco ["Cursor Ecosystem"]
        cursor["Cursor IDE<br/>(macOS/Windows/Linux)"]
        gpt4["Model: GPT-4, Claude<br/>(configurable)"]
    end

    subgraph copilot_eco ["Microsoft Ecosystem"]
        copilot["GitHub Copilot<br/>(VS Code + Visual Studio)"]
        copilot_model["Model: GPT-4 Turbo<br/>(via GitHub)"]
    end

    subgraph others ["Other Providers"]
        hermes["Hermes"]
        antigravity["Antigravity"]
        kimi["Kimi"]
    end

    aacw -->|daemon invokes| cc
    aacw -->|daemon invokes| cursor
    aacw -->|daemon invokes| copilot
    aacw -->|daemon invokes| others
    cc -.->|uses| opus
    cursor -.->|uses| gpt4
    copilot -.->|uses| copilot_model

    style claude_ecosystem fill:#FFE4E1
    style cursor_eco fill:#E0F4FF
    style copilot_eco fill:#F0FFF0

모든 제공자는 AACWorkflow를 통해 동일한 할당, 실행 및 결과 보고 흐름을 공유합니다.

이 다이어그램은 명확성을 위해 단순화되었습니다. 상세 구현:

이 페이지에서

시스템 아키텍처업무 생명 주기보안 및 신뢰 경계에이전트 스킬 및 능력 모델스쿼드 위임오토파일럿 트리거 흐름데이터 흐름: Issue → Agent → PR → Resolution업무 공간 다중 테넌시제공자 환경