검증 우선 AI 코딩 에이전트 구축하기: 왜 나는 '생성 후 기도하기(Generate-and-Pray)' 방식을 버렸는가

궁극의 AI 코딩 어시스턴트를 만들기 위한 경쟁 속에서, 업계는 공유된, 매우 결함이 있는 패러다임에 안주해 왔습니다. 이를 **생성 후 기도하기 (Generate-and-Pray)**라고 부릅시다.

당신이 Cursor, GitHub Copilot, Cline 또는 커스텀 래퍼 스크립트(wrapper scripts)를 사용하든, 흐름은 동일합니다:

1. 당신이 LLM(대규모 언어 모델)에 프롬프트를 입력합니다.
2. LLM이 코드 패치(code patch)를 생성합니다.
3. 도구가 해당 패치를 당신의 파일 시스템(filesystem)에 직접 작성합니다.
4. 인간인 당신이 검증 계층 (verification layer) 역할을 강요받습니다. 당신은 diff를 검토하고, 컴파일러(compiler)를 실행하며, 환각(hallucination)된 패키지 임포트(package imports)를 잡아내고, 테스트 스위트(test suite)를 실행하며, 상황이 필연적으로 터졌을 때 롤백(rollback)을 수행해야 합니다.

이것은 혼란스럽고, 소모적이며, 안전하지 않습니다.

나는 시니어 엔지니어처럼 행동하는 어시스턴트를 원했습니다. 나에게 보여주기 전에 자신의 코드를 테스트하고 컴파일하는 사람 말입니다. 그래서 나는 Kode를 만들었습니다. 이는 기존 방식에 반하는, 검증 우선(verification-first) AI 코딩 에이전트입니다.

왜 우리가 생성(generation)에서 검증(verification)으로 전환해야 하는지, 그리고 Kode가 이를 어떻게 수행하는지에 대한 엔지니어링 세부 사항을 소개합니다.

핵심 논지: 검증 없는 생성은 없다

Kode는 단순한 규칙을 바탕으로 구축되었습니다: LLM은 생성 엔진(generative engine)이지만, 로컬 Go 오케스트레이터(orchestrator)는 보안 계층(security layer)입니다.

모델이 패치를 생성할 때마다, 해당 패치는 단 1바이트도 당신의 활성 파일 시스템에 닿기 전에 50밀리초(ms) 이내에 **9가지 결정론적 검증 게이트 (9 deterministic verification gates)**를 실행하는 정적, 사전 컴파일된 Go 바이너리(kode.exe)를 통과합니다. 만약 게이트가 실패하면 패치는 거부되며, 컴파일러 수준의 에러가 LLM에 다시 전달되어 스스로 수정(self-correct)하게 합니다.

                  ┌─────────────────────────┐
                  │      User Prompt        │
                  └────────────┬────────────┘
...

안전 점검(safety-checks)을 에디터 내부로 직접 왼쪽으로 이동(shift left)시킴으로써, 사용자는 결코 디버거(debugger)가 되지 않습니다.

내부 구조: 9가지 검증 게이트

쓰기 전 검증(pre-write verification)을 실행 가능하게 만들려면, 체크가 거의 즉각적으로 실행되어야 합니다. 컴파일된 Go 엔진이 안전을 강제하는 방식은 다음과 같습니다:

1. AST 구문 게이트 (AST Syntax Gate): 공식 Tree-sitter 바인딩(정밀한 AST 파서)을 사용하여 수정된 파일을 파싱하며, CGo를 사용할 수 없는 경우 정규 표현식 휴리스틱(regex heuristics)으로 대체합니다. 파싱 에러 발생 시 즉시 차단됩니다.
2. 임포트 게이트 (Imports Gate): 생성된 모든 임포트 경로(import path)를 로컬 의존성 그래프(dependency graph)와 교차 참조합니다. 더 이상 환각(hallucination)된 npm 또는 Go 패키지는 발생하지 않습니다.
3. 호출 게이트 (Calls Gate): 함수 및 메서드 호출 지점이 일치하는 시그니처(signature)를 가진 실제 존재하는 심볼(symbol)에 매핑되는지 검증합니다.
4. 폭발 반경 게이트 (Blast Radius Gate): 의존성 그래프를 역방향으로 탐색합니다. 패치(patch)가 허용된 임계값보다 더 많은 하위 파일에 영향을 미치는 경우 차단됩니다.
5. 아키텍처 게이트 (Architecture Gate): 모듈 경계(예: 데이터베이스 레이어가 라우트 핸들러를 임포트하는 것을 차단)를 강제합니다.
6. 보안 게이트 (SAST): AST 상에서 컴파일된 로컬 SAST 엔진을 실행하여 SQL 인젝션, XSS 및 하드코딩된 자격 증명을 차단합니다.
7. 샌드박스 리플레이 게이트 (Sandbox Replay Gate): CPU 사용량이 제한된 샌드박스에서 코드를 일시적으로 실행하여 무한 루프, 메모리 누수 및 비정상적인 소켓(rogue sockets)을 포착합니다.
8. QR 코드 터널 게이트 (QR Code Tunnel Gate): 로컬 웹 서버를 위한 보안 퍼블릭 개발 터널을 부팅하고 터미널에 QR 코드를 출력하여, 휴대폰에서 레이아웃 변경 사항을 즉시 미리 볼 수 있게 합니다.
9. 브라우저 E2E 게이트 (Browser E2E Gate): 개발 서버에서 헤드리스(headless) Playwright 스크립트를 생성 및 실행하여 UI 녹화본을 캡처하고, 콘솔 에러가 감지되면 롤백(rollback)합니다.

3가지 강력한 기능: 기존 업체들이 제공하지 못하는 것

검증 엔진을 구축함으로써, 일반적인 확장 프로그램 래퍼(extension wrappers)로는 구현할 수 없는 기능들을 구현할 수 있었습니다.

1. 고스트 브랜치 (Ghost Branches, 적자생존)

프롬프트를 하나만 실행할 수 있다면, 왜 세 개를 실행하지 않겠습니까? Kode는 병렬 git 워크트리(worktrees, 고스트 브랜치)를 생성하여 서로 다른 구현 경로를 탐색할 수 있습니다. 각 경로는 검증(Verification) 파이프라인과 테스트 스위트를 통과합니다. Kode는 결과를 평가하고 점수를 매긴 뒤, 가장 높은 점수를 받은 후보를 작업 공간(workspace)으로 자동 병합(merge)합니다.

2. 블라인드폴드 모드 (Blindfold Mode, 엔터프라이즈 프라이버시)

기업용 개발자들에게 독점적인 코드를 제3자 LLM(Large Language Model)으로 전송하는 것은 컴플라이언스(compliance) 측면에서 악몽과 같습니다. Blindfold Mode는 페이로드(payload)가 기기를 떠나기 전에 로컬에서 AST(Abstract Syntax Tree) 파싱을 수행하고 모든 식별자(변수명, 타입, 함수, 패키지)를 SHA-256 방식으로 난독화(obfuscate)합니다. 로컬 매핑 테이블이 응답 시 이를 다시 원래대로 번역합니다. 클라우드 모델은 코드의 로직은 볼 수 있지만, 지적 재산(intellectual property)은 절대 볼 수 없습니다.

3. 핸즈프리 음성 프로그래밍 (kode voice)

타이핑이 필요 없습니다. 그저 kode voice를 실행하고 작업을 말하면, 로컬 마이크가 Whisper를 사용하여 이를 캡처하고 전사(transcribe)합니다. 텍스트는 즉시 Plan-Generate-Verify 파이프라인으로 전달됩니다.

오픈 소스 라이선스: MIT + AGPLv3 하이브리드 모델

기업 친화적인 로컬 실행 기능을 유지하면서 SaaS 래퍼(wrapper)로부터 보호하기 위해, Kode는 이중 라이선스 모델을 채택합니다:

• MIT License: 핵심 개발 도구(CLI, TUI, 내부 모듈 및 웹 앱)는 완전히 허용적(permissive)입니다.
• AGPLv3 License: 클라우드용 LLM 게이트웨이 및 라우팅 프록시 서버(cmd/gateway/ 및 internal/gateway/)는 호스팅되는 모든 SaaS 래퍼가 자신들의 오케스트레이션(orchestration) 코드를 오픈 소스로 공개할 것을 요구합니다.

시작하기

Kode는 BYOK (Bring Your Own Key) 플랫폼입니다. 외부 런타임 의존성 없이 약 10MB 크기의 가벼운 Go 바이너리로 컴파일됩니다.

설치

• macOS / Linux:

  curl -fsSL https://raw.githubusercontent.com/sicario-labs/kode/master/script/install.sh | bash

• Windows (PowerShell):

  irm https://raw.githubusercontent.com/sicario-labs/kode/master/script/install.ps1 | iex

• Termux (Android): ARM64 Termux에서 빌드 및 컴파일:

  pkg install golang nodejs git clang make
  go build -o bin/kode ./cmd/kode
  cd third_party/opencode && npm install

설치가 완료되면 다음 명령어로 설정을 스캐폴딩(scaffold)하세요:

kode init

그리고 작업 루프를 시작하세요:

kode loop "add JWT validation to the login route"

전체 저장소(repository)를 확인하고 github.com/sicario-labs/kode에서 기여해 주세요. AI 코딩 패러다임을 생성(generation)에서 검증(verification)으로 전환하는 것에 대한 여러분의 의견을 듣고 싶습니다!