3단계 실행 흐름

CLI로 간편하게 구동하기

배경 실행 크론 데몬이나 클로드 네이티브 루틴에서 구동할 수 있는 CLI 트리거를 기본 내장하고 있습니다.

# BADA 루트 폴더로 이동 후 워크플로우 구동
NODE_PATH=./node_modules node scratch/trigger-bada-workflow.js [프로젝트 ID] [워크플로우 ID]

화면 구성 및 PTY 터미널 연계

• 메인 에이전트 터미널 (Xterm.js): 중앙 캔버스의 xterm.js는 백엔드의 node-pty와 실시간으로 바인딩되어 동작합니다. 사용자의 수동 개입(HITL) 입력과 에이전트 출력 스트림을 결합합니다.
• 상단 에디터 및 에이전트 표시바: 현재 기동 중인 서브 에이전트 스레드 상태와 작동 예산(Cost), 경과 시간 게이지를 실시간 추적합니다.
• 우측 에디터 슬라이드 패널 (Editor Panel): Ctrl+E 단축키로 토글 가능하며, 에이전트가 탐색하거나 가공한 코드의 Git Diff 이력과 물리 트리 구조를 고속 렌더링합니다.

BADA Terminal 레이아웃 Mockup (화면 가이드)

PTY 프로세스 백엔드 스펙 (node-pty)

BADA 코어는 플랫폼 비의존적인 PTY 세션을 생성하여 로컬 OS 쉘을 가상 래핑합니다. 백엔드의 생성 사양은 다음과 같습니다.

const pty = require('node-pty');
const ptyProcess = pty.spawn(shell, [], {
  name: 'xterm-color',
  cols: 80,
  rows: 24,
  cwd: projectPath, // 작업 타겟 디렉토리
  env: {
    ...process.env,
    FORCE_COLOR: '1',
    PAGER: 'cat' // Pager 대기 방지
  }
});

실시간 IPC 통신 프로토콜

Electron 메인 프로세스와 렌더러는 양방향 비동기 IPC 메시지로 통신합니다.

핵심 통제 및 프로세스 트리 수거

워크플로우 디자이너 (workflow-designer.html)

Cytoscape.js를 기반으로 구축된 캔버스 영역으로, 드래그 앤 드롭을 사용해 복잡한 조건문과 에이전트 루프백 관계를 그래픽 노드로 모델링합니다.

노드 유형 및 포트 결합 스펙

• Agent 노드 (Maker): input-port(이전 피드백/지침 주입) 및 output-port(작성된 코드 파일 및 커밋 객체 전송)가 결합됩니다. 일반 지침 프롬프트를 전송받아 코드를 생성/수정하는 작업을 수행합니다.
• Reviewer 노드 (Checker): code-port(Maker의 최종 산출물 전달) 및 decision-port를 가지며, {"approved": boolean, "feedback": string} 스키마의 JSON을 다음 엣지로 방출합니다.
• Harness 노드 (Verification): trigger-port로 들어오는 신호에 따라 빌드/테스트 파이프라인(예: npm run test)을 구동하고 결과 코드(0 또는 1)를 판정 엣지로 리턴합니다.

워크플로우 모니터 (workflow-monitor.html)

실시간으로 실행 상태(Idle, Running, Paused, Success, Failed)를 추적하며, 현재 활성화된 엣지와 노드를 밝은 네온 하이라이트로 보여줍니다.

사용자 피드백 대기(HITL) 혹은 예산 초과(Budget exceeded)로 대기 상태에 빠졌을 때 터미널 우측 제어판의 Pause / Resume / Restart / Kill 버튼이 즉각 활성화되어 조작할 수 있습니다.

워크플로우 데이터 영속화 스펙 (SQLite DB)

워크플로우 그래프의 노드 구조, 배치 순서, 엣지 결합 및 실시간 큐(Queue)는 다음 SQLite 스키마 테이블에 완전히 저장됩니다.

1) workflows 테이블 (디자인 명세 정의)

2) workflow_tasks 테이블 (실행 큐 상태 관리)

그래프 JSON 구조 명세

graph_json 컬럼에 기입되는 Cytoscape 호환 JSON 구조 예시입니다.

{
  "nodes": [
    { "data": { "id": "maker_node", "label": "Code Writer", "type": "pty_agent" } },
    { "data": { "id": "checker_node", "label": "PR Reviewer", "type": "reviewer" } }
  ],
  "edges": [
    { "data": { "id": "edge1", "source": "maker_node", "target": "checker_node", "type": "submit" } },
    { "data": { "id": "edge2", "source": "checker_node", "target": "maker_node", "type": "reject" } }
  ]
}

정적 검증 게이트 (Test-before-Schedule)

BADA 배치 스케줄러는 보안 및 오작동 안전을 위해 **"사전 구동 테스트(Test Run)"**를 의무 통제합니다.

비주얼 크론 생성기 & 표준 식 필드 규약

복잡한 크론 식(*/5 * * * *)을 직접 수작업으로 적지 않고, 대시보드 편집창에서 주기(시간/일/주/월)와 설정 조건을 선택하면 자동으로 크론 파서가 안전한 포맷 식을 주입해 줍니다.

크론 표현식 5필드 스펙

*    *    *    *    *
│    │    │    │    │
│    │    │    │    └─ 요일 (0 - 6) (0은 일요일)
│    │    │    └────── 월 (1 - 12)
│    │    └─────────── 일 (1 - 31)
│    └──────────────── 시 (0 - 23)
└───────────────────── 분 (0 - 59)

예를 들어, 매주 월요일 새벽 3시 30분에 기동하고자 하는 경우 30 3 * * 1 표현식을 적용합니다.

배치 스케줄러 데이터 영속화 스펙 (SQLite DB)

배치 작업의 설정과 이력은 다음 SQLite 스키마 테이블에 완전히 저장됩니다.

batch_tasks 테이블 상세 정의

하네스 매니저 UI (harness-manager.html)

모리스(Mories) MCP 도구 및 로컬 폴더 빌드 파이프라인의 핵심 검증 명령어들을 영속 데이터베이스로 통제합니다.

자동 검증 실행 프로토콜

BADA가 에이전트 결과물에 대해 하네스를 구동할 때, 다음 프로시저를 차례대로 밟습니다.

하네스 및 트리아지 영속화 스펙 (SQLite DB)

검증과 진단 정보는 아래 SQLite 스키마 컬럼에 저장되어 활용됩니다.

1) harnesses 테이블 (검증 규칙 정의)

2) harness_runs 테이블 (검사 실행 내역)

3) triage_items 테이블 (AI 진단 인박스)

지식 그래프 (knowledge-graph.html)

D3.js 힘지향(Force-directed) 네트워크 그래프를 도입해 프로젝트 내 클래스, 메소드, 파일 상호 참조 관계 및 위키 문서 노드 간의 복합 엔티티를 한 눈에 파악할 수 있도록 해 줍니다. 노드 검색 및 줌, 특정 노드 더블클릭 시 세부 설명 카드가 오픈됩니다.

RAGPresetManager & .clauderules 매핑

BADA가 로컬 폴더에 .clauderules 파일 및 AGENTS.md 가이드를 생성할 때, 지식베이스와 위키에서 추출한 가벼운 핵심 도메인 정보와 룰 프리셋들을 임포트(Import)하여 Claude 에이전트가 로컬 디렉토리의 아키텍처 규칙을 위배하지 않도록 도메인 고정 인덱싱을 지원합니다.

BADA Terminal은 지식의 중복(Duplication)과 모순을 예방하기 위해, 기계적 메타데이터인 지식 그래프와 인간 중심의 LLMWiki/Note, 그리고 에이전트가 상주하며 준수하는 Memory & Rules를 상호 격리하고 유기적으로 동적 바인딩합니다.

1. 4대 지식 영역 비교

2. 바다코드에서의 지식 연동 메커니즘

BADA는 정보가 파편화되는 것을 막기 위해 다음 3단계 파이프라인으로 지식을 수렴시킵니다.

3. 실전 사용자 가이드 & 활용 사례

지식 RAG & Headroom 이중 필터 메커니즘

BADA Suite는 에이전트의 상황 인지(Context) 주입 시 발생하는 두 가지 중대한 비용 및 보안 문제를 물리적 RAG 필터와 논리적 API 프록시 마스킹의 이중 파이프라인으로 해결합니다.

핵심 작동 구성 요소

1) 4-Signal Relevance Engine에 의한 물리적 1차 압축

에이전트가 코딩 중 참조할 파일이나 노트 맵이 백 개가 넘어가도, BADA의 Relevance Engine이 아래 공식에 의거하여 노드 간의 종합 가중치 점수를 실시간 계산합니다.

Relevance Signal 세부 명세

• Direct Link (직접 엣지 가중치): SQLite edges 테이블에 명시된 두 노드 간의 실시간 참조 연결 가중치입니다.
• Source Overlap (공통 소스 지수): 노드가 속한 패키지, 소스 파일의 공통 종속성 정도를 수치화한 값입니다.
• Adamic-Adar (그래프 구조 유사도): 그래프 내에서 두 노드가 공유하는 이웃 노드들의 차수(Degree) 역수를 합산하여 간접 유사도를 파악하는 휴리스틱 공식입니다.
• Type Affinity (노드 유형 선호도): 호출 대상(예: 클래스-메소드 간)에 매핑된 기본 적합도 상수 가중치입니다.

SQLite FTS (Full-Text Search) 및 nodes_fts 결합 검색

BADA는 자연어 쿼리나 에러 로그가 유입되었을 때, 텍스트 형태의 검색을 빠르게 보조하기 위해 SQLite FTS5 내장 검색 라이브러리를 결합하여 nodes_fts 가상 테이블을 구성하고 실시간 가중치 점수를 합산해 12개 노드로 축소시킵니다.

2) Headroom API 프록시에 의한 기밀 유출 방어 및 2차 정제

물리적으로 선별된 프롬프트 데이터가 외부 클라우드 LLM(OpenAI/Gemini/Anthropic 등)으로 발송되는 요청 바이트를 실시간으로 프록시 서버에서 가로챕니다. 프롬프트 본문 내부의 주민등록번호, 비밀번호, 시스템 계정, 보안 토큰키 및 DB 접속 정보와 같은 10대 기본 기밀 데이터를 안전한 대치 토큰([SECRET_...])으로 자동 마스킹 처리하여 기밀의 외부 유출을 원천 예방하고, 전송 데이터 중복을 없애 한 번 더 요금 절감을 이뤄냅니다.

BADA Headroom 10대 기본 기밀 마스킹 규칙 정의

관련 설정 및 사용 방법

⚙️ 설정 구성 (Headroom & RAG 연동)

1. 보안 및 마스킹 제어: 상단 메뉴바의 [Headroom 셋업] 메뉴를 선택하여 10대 기본 기밀 항목들의 개별 활성/비활성 여부를 지정하고, 기업 고유의 도메인 단어들을 위한 정규식을 수동 추가합니다.
2. 사내 내부망 LLM 우회(Bypass) 셋업: 만약 사내 내부에 배포된 Local Llama나 DeepSeek API를 사용하는 경우, 마스킹으로 인한 코드 품질 저하를 예방하기 위해 [Headroom 셋업] 내 프로바이더 목록에서 해당 Ollama/vLLM 프로바이더의 'Bypass Masking'을 활성화합니다.
3. RAG 참조 방식 변경: [환경설정] ➔ 지식 설정에서 RAG 컨텍스트 주입 방식을 contents(본문 주입) 혹은 path(경로만 주입)로 토큰 용량에 맞춰 조율합니다.

💡 실전 활용 시나리오

Allowed Folders (샌드박스 폴더 허용 목록)

원격 BADA 커넥터는 SFTP 파일 서버 역할을 겸하며, 허용 목록(Allowed Folders)에 등록되지 않은 임의의 디렉토리나 시스템 루트(`/`, `C:\` 등)로의 파일 탐색, 읽기, 쓰기 접근은 SFTP 프로토콜 레이어에서 원천적으로 차단 및 거부됩니다.

• 절대 경로 등록: 공유를 허용하고자 하는 디렉토리의 절대 경로(예: `/Users/jkb/Projects` 또는 `C:\workspace`)를 직접 입력하여 추가합니다.
• 보안 영역 구축: 에이전트 CLI(예: Claude)가 접근해야 하는 최상위 프로젝트 작업 폴더만 등록하여, 중요 시스템 설정 파일이 탈취되거나 파괴되는 것을 근본적으로 차단합니다.

IP 필터링 (화이트리스트 & 블랙리스트)

커넥터 데몬으로 원격 접속할 수 있는 클라이언트의 IP 주소를 강력하게 제어합니다.

• 화이트리스트 (허용 대역): 인증 키나 올바른 접속 요청이라 하더라도, 지정된 IP(예: `192.168.35.175`)에서 온 접속에만 연결을 수락하고 나머지는 드롭시킵니다. 만료 시간(Expire At)을 설정하여 한시적 원격 파트너십을 허가할 때 유용합니다.
• 블랙리스트 (차단 대역): 비정상 접속 시도나 공격이 포착된 IP 주소를 영구적 혹은 기간제로 즉시 차단합니다.

보안 실시간 감사 (Audit Logs)

샌드박스 폴더 내부의 모든 파일 변경 사항(생성, 수정, 삭제) 및 SFTP 세션 개시 정보, 비정상 IP 접속 시도 및 차단 내역을 실시간 감사 로그 뷰어를 통해 로깅 및 모니터링하여, 침해 위협 발생 시 즉각 대응할 수 있도록 지원합니다.

루프 엔지니어링이란?

BADA Terminal의 핵심 철학은 "에이전트에게 일을 맡긴 후 방치하지 않고, 검증(Verify)을 통과할 때까지 피드백 루프를 폐쇄형(Closed-Loop)으로 반복한다"는 것입니다. 이 방식은 에이전트의 초기 실수율을 획기적으로 낮추고 최종 작업 결과물의 완성도를 극대화합니다.

BADA의 루프 제어 엔진(Loop Controller)은 목표 수립(Goal) ➔ 격리 실행(Execute) ➔ 검증 평가(Verify) ➔ 회류 학습(Feedback)의 4단계 라이프사이클을 반복하며 목표를 자가 달성합니다.

Closed-Loop 4단계 실행 흐름

목표 설정 목표식(Goal Expression) 명세

BADA가 루프 성공/실패 여부를 판별하기 위해 해석하는 goal_expression JSON 속성 정의 구조입니다.

{
  "type": "test_command",           // 검증 타겟 유형: test_command | file_check | metric_limit
  "command": "npm run test:auth",   // 실행할 하네스 명령어
  "success_criteria": {
    "exit_code": 0,                 // 성공 종료 코드
    "regex_match": "Passed:"        // 로그에서 매칭되어야 할 필수 정규식 (선택)
  }
}

BADA Closed-Loop 안전 가드레일 제약 한도

루프 엔진이 무한 지출 및 프로세스 고아 방지를 위해 강제 준수하는 가드레일 제한 규칙입니다.

루프 관련 스키마 정보 (SQLite DB)

루프의 정의와 단계별 성공 및 토큰 소모 이력은 다음 테이블에 완전히 저장됩니다.

1) loop_goals 테이블 (루프 목표 등록)

2) loop_runs 및 loop_iterations 테이블 (순환 상태)

루프 엔지니어링 4대 고급 기능 (Phase 3 & 4)

BADA v3.12.0부터는 에이전트의 안정성과 다차원 검증을 위한 핵심 고급 가드레일들이 추가되었습니다.

상세 사용법 가이드 (Step-by-Step)

격리 작동 원리

에이전트 노드가 활성화되면 BADA 워크플로우 매니저는 isolation === 'worktree' 설정을 검사합니다.

git worktree add --checkout -b temp-branch-name wt-path hash

git worktree remove --force wt-path
git branch -D temp-branch-name

Squash Merge 및 Discard/Prune 생명주기

• 성공 ➔ Squash Merge: 에이전트가 격리된 공간에서 작성한 수십 번의 무수한 빌드 시도 커밋들을 하나의 깔끔한 기능 단위 커밋으로 압축(Squash)하여 메인 브랜치에 이식함으로써 메인 Git History의 안정성과 가시성을 확보합니다.
• 실패 ➔ Discard/Prune: 가드레일 예산 차단 등으로 인해 결국 최종 검증에 실패한 경우, 생성되었던 워크트리 디렉토리를 git worktree remove --force 명령어로 디스크에서 제거하고 생성한 브랜치도 흔적 없이 제거하여 원래 개발 상태로 자동 롤백시킵니다.

격리 워크트리 상태 추적 스키마 (SQLite DB)

BADA가 실시간으로 관리하는 워크트리의 마운트 상태와 디스크 수거 기록은 다음 SQLite 스키마에 완전히 동기화됩니다.

worktree_state 테이블 상세 정의

루프백 알고리즘 시각화

[Maker Node] ──(코드작성)──> [Checker Node] 
                                  │
                                판정 (Approved?)
                                ├──> [Yes] ──> (성공 완료)
                                └──> [No]  ──(Diff + 피드백 주입)──> [Maker Node (재시도)]
        

점진적 진화(Evolution) 콘텍스트 구조

반려 피드백이 Maker 노드에 다시 주입될 때, 아래와 같은 JSON 구조로 축적되어 Maker 에이전트의 프롬프트 전면에 강제 바인딩되어 동작합니다.

{
  "runId": "wf_run_1781552634074_db9c8",
  "retryCount": 2,
  "lastFeedback": "index.js 24라인에서 null 예외 처리가 누락되어 빌드가 실패했습니다.",
  "gitDiff": "--- index.js\n+++ index.js\n@@ -24,4 +24,2 @@\n-  return user.name;\n+  return user ? user.name : 'Unknown';"
}

VM 격리 실행

배치 스케줄러 워크플로우 진행 도중 JSON 파싱, 키 매핑, 데이터 형변환 등이 수행되는 JS 변환기 단계(Transform Step)를 실행할 때, Node.js 내장 vm 모듈을 사용하여 호스트 파일시스템(fs) 모듈 접근 등이 차단된 완전히 격리된 샌드박스 영역 내에서 보안 안전성을 담보하며 실행됩니다.

세이프티 가드레일

• 문법 IIFE 자동 포장: 사용자가 작성한 변환 코드가 비동기(Promise) 및 문법 오류 없이 구동되도록 내부적으로 즉시 실행 함수(IIFE) 블록((async function() { ... })())으로 자동 감싸 구동합니다.
• 강제 실행 시간 타임아웃 (2000ms): 스크립트 내에 무한 루프나 블로킹 연산이 포함되었을 경우, 2초가 경과되면 동기식 timeout 가드와 비동기 Promise.race 이중 가드가 개입하여 스레드 락을 해제하고 강제 종료합니다.

격리 아키텍처 개요

BADA Docker 샌드박스 커넥터 v2는 제어(Control), 실행(Execution), 자원(Resource)의 3중 격리 아키텍처를 제공합니다.

• 제어 Plane (BADA Terminal): 사용자 인터페이스 표시, 터미널 입출력, 세션 상태 및 Docker API 제어를 담당합니다.
• 실행 Plane (Host CLI): 로컬 또는 원격 SSH Host 상에서 AI 에이전트 CLI(Claude Code, OpenCode 등)가 실행되어 추론 및 도구 사용 결정 수행합니다.
• 자원 Plane (Docker Container): 에이전트가 코드를 빌드하고 실행하며 파일을 수정하는 작업 환경을 컨테이너 내부 /workspace로 완전 격리하여 Host 환경의 훼손을 차단합니다.

사용 및 설정 방법

1. 원격 서버 설정 등록: BADA Terminal 우측 상단 메뉴의 🖥️ 원격 서버 관리를 클릭하고 서버를 추가/편집합니다.
2. Docker 옵션 활성화: 🐳 Docker 개발 샌드박스 활성화 체크박스를 켭니다.
   • Docker 호스트 주소: Docker가 실행 중인 서버 IP (생략 시 SSH 접속 호스트 사용).
   • 컨테이너 이미지: 사용할 개발용 샌드박스 이미지명 (기본: bada-dev-sandbox:latest).
   • 리소스 한도: 컨테이너의 최대 가용 CPU 코어 수 및 Memory 크기를 제한합니다.
3. Docker 이미지 빌드 (최초 1회): Docker Host 상에서 bada-dev-sandbox:latest 이미지가 없는 경우, CLI 에이전트(예: INSTALL_CLAUDE_CODE=true)를 포함하는 Dockerfile 빌드가 자동으로 수행됩니다.
4. 격리 세션 개시: 원격 서버 리스트에서 ▶ 버튼을 클릭하여 원격 접속을 개시하면, SSH 터널을 경유해 도커 컨테이너가 가동되고, 터미널 화면에 컨테이너 내부 쉘 또는 내장된 에이전트 CLI가 투명하게 라우팅되어 가동됩니다.

포트 포워딩을 통한 개발 서버 접근

격리된 샌드박스 컨테이너 안에서 동작하는 웹 서버(예: 3000포트)는 자동으로 Host의 임의 포트와 매핑되며, BADA Terminal이 이를 감지하여 SSH 터널로 Local PC에 동적 매핑해 줍니다. 샌드박스 관리 도구 창에서 매핑된 로컬 포트를 확인하고 웹브라우저로 즉시 접근할 수 있습니다.

트리아지 흐름

워크플로우 노드가 실패 코드를 반환하면, BADA 코어 엔진은 즉시 백그라운드 AI 진단 프로시저(runAutoTriageDiagnostic)를 트리거합니다.

DB 락 결합 예외 방어

sqlite3 파일 락 경합(SQLITE_BUSY)이 일어나도 메인 서버 코어가 크래시되지 않도록 트리아지 데이터 트랜잭션 전체에 try-catch 결함 허용(Fault tolerance) 래퍼를 씌웠습니다.

CLI 스펙 개요

스크립트 위치: scratch/trigger-bada-workflow.js

본 유틸리티는 백엔드 이벤트 버스를 실시간 구독하여 워크플로우의 실행 상세와 비용, 노드 상태 전이를 콘솔 스트림에 렌더링하고 완료 시 성공(0) 또는 실패(1) 코드로 리턴합니다.

주요 CLI 옵션 및 아웃풋 통제

# 기본 실행 구문
NODE_PATH=./node_modules node scratch/trigger-bada-workflow.js [projectId] [workflowId]

# 상세 로그 전체 출력 (버퍼 트렁케이션 비활성화)
NODE_PATH=./node_modules node scratch/trigger-bada-workflow.js [projectId] [workflowId] --verbose

안전 연동 수거 설계

• 메모리/이벤트 리스너 누수 방지: CLI 종료 시 워크플로우 리스너(Named Handler)를 즉각 소멸시켜 다중 기동 시 리스너 누적 현상이 없습니다.
• HITL 승인 대기 차단: 백그라운드 크론 실행 중 인간 검토(HITL) 단계에 돌입하여 행(Hang)이 걸리는 현상을 방지하기 위해, CLI 구동 모드에서는 paused 진입 즉시 정상 종료 코드(exit 0)를 반환하고 물러갑니다.