Ducklab

기본적으로 다중 LLM을 사용하고, 구조적으로 정직한 풀사이클 소프트웨어 개발 하네스입니다.

한 줄 요약: 자체 호스팅 개발 하네스(Go 엔진 + CLI + 데스크톱, Linux 우선) · 브리프 → 요구사항 → 스펙 → 계획 → 빌드 → 리뷰 → 릴리즈 · 판정은 종료 코드이지 모델 의견이 아님 · 로컬 모델 우선(llama.cpp, vLLM)과 함께 모든 OpenAI 호환 또는 Anthropic 엔드포인트 · 사람이나 다른 에이전트가 MCP를 통해 기록되고 출처가 명시된 결정으로 운영 가능 · Apache-2.0 · 스스로 개발함(.ducklab/의 실행 기록이 영수증). 에이전트: AGENTS.md와 llms.txt에서 시작하세요.

브리프를 주면 요구사항, 스펙, 계획을 작성하고; 하나 또는 여러 모델이 논쟁하며 태스크를 빌드하고; 프로젝트의 실제 테스트 게이트를 실행하고; 커밋 전에 멈춰서 당신의 확인을 받습니다. 모든 모델 호출은 기록됩니다. 어떤 모델도 판정을 내리지 않습니다.

로컬 모델 우선으로 만들어졌습니다 — 대부분을 만든 두 모델은 LAN의 vLLM 박스와 localhost의 llama.cpp 서버로, 둘 다 가격이 0이며 — 호스팅 모델은 같은 명단에서 나란히 자리하며, 같은 증거로 측정됩니다.

왜 이런 것이 존재하는가

대부분의 에이전트 코딩 도구는 하나의 강력한 모델을 가정하고 그것을 신뢰합니다. Ducklab은 여러 저렴한 모델을 가정하고 그 어느 것도 신뢰하지 않습니다:

• 게이트가 결정하지, 모델이 결정하지 않습니다. 판정은 명령의 종료 코드입니다. 테스트 우선 실행은 테스트가 작성되기 전에 녹색 베이스라인을 측정하고, 그 후 새 테스트 위에서 빨간색을 측정하며, 모든 수락은 커밋된 sha의 클린 체크아웃에서 게이트를 재현합니다 — 재현되지 않은 것은 아무것도 들어오지 않으며, 재현에 실패한 수락은 자신의 커밋을 되돌립니다.

• 모든 곳에서 비상관화. 다른 모델이 리뷰합니다; 리뷰어는 누가 코드를 썼는지 알 수 없습니다(페이로드에 없고, UI에 숨겨진 것도 아님); 토너먼트 심사위원은 블라인드로 선택합니다; 카운슬 비평가들은 초안을 읽지, 서로를 읽지 않습니다.

• 작업은 계약입니다. 태스크의 산출물은 구현자의 번호가 매겨진 체크리스트입니다; 각 번호로 보고하고, 리뷰어는 diff와 대조하여 각 항목을 확인하며, 전달되지 않은 항목은 러버 덕을 소환합니다 — 측정된 고통(브레이크 거부, 실패 연속, 빨간 게이트)에서만 깨어나는 조언자 좌석으로, none(구현자를 즉시 작업으로 돌려보내는 메모), 또는 stop으로 답합니다.

• 좌석은 증거에 따라 선택됩니다. 모든 덕링은 스코어카드를 지닙니다 — 자신의 실행에서의 좌석 내 통과율, 실행당 비용, 코딩 지수 — 그리고 로스터 보드는 그것에서 좌석을 제안하며, 순위 기준은 당신이 재정렬할 수 있습니다. 제안은 드물고 정당합니다: 통과율은 Wilson 하한으로 순위를 매기고, 최소 3회 실행, 로컬 모델은 $0 가격으로 이길 수 없습니다.

• 무한한 것은 없습니다. 턴, 토큰, 비용, 벽시계, 도구 출력, 셸 명령 — 모든 상한이 보이고 실행 중에 기록에 남겨 올릴 수 있습니다.

• 문서는 모델의 창에 제한되지 않습니다. 스테이지에 위키를 첨부하면 큰 좌석이 전체를 읽습니다; 작은 좌석은 각 문서를 맞게 요약해 받고, 전체 텍스트는 ref_read 호출 한 번으로 접근 가능하며, 게이트는 아무도 열지 않은 문서를 지목합니다. 32k 로컬 모델도 25만 자의 참조 자료로 브리핑받을 수 있습니다 — 하네스가 작업 기억을 담당합니다.

그리고 존재 증명: ducklab은 ducklab 내부에서 개발됩니다. 계획, 버그, 릴리즈, 그리고 지난 90개 이상의 수락된 태스크는 자체 루프를 거쳤으며, 그것이 측정하는 동일한 로컬 및 호스팅 모델에 의해 구동되었습니다 — 가장 최근 기능(멀티모달 채팅, 컨설턴트 좌석, 가이드 레일의 실행 기록)은 덕이 만들고 사람이 게이트했습니다.

Related MCP server: Loki Mode

상태

v0.6.1+, 빠르게 진행 중. 7개 스테이지, 5개 모드, 증거와 제안이 있는 로스터 보드, 자동 요약이 있는 참조 문서, 데스크톱에서 관리되는 스킬, 채팅할 수 있는 앉아 있는 컨설턴트(이미지 포함, 전송 전에 비전 검증), 스크린샷 증거가 있는 버그, 릴리즈, 오토파일럿, CLI, 데스크톱 앱, 그리고 MCP 서버 — 다른 모델이 기록되고 출처가 명시된 결정으로 전체 루프를 운영할 수 있게 합니다.

docs/status.md는 모든 수용 기준을 추적하고 반올림하지 않습니다. 코드와 스펙이 다를 때, 그 차이는 docs/decisions/에 기록됩니다.

설치

Go 1.25+, 데스크톱용 Node 22+, 그리고 git이 필요합니다.

Linux

CLI와 엔진은 순수 Go입니다. 데스크톱은 Wails v3 앱이며 GTK/WebKit 개발 패키지가 필요합니다:

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev   # Debian/Ubuntu names
make desktop && make install

Ubuntu 24.04+에서 데스크톱은 AppArmor 프로필도 필요합니다 — 결정 0003과 packaging/apparmor/를 참조하세요.

macOS

xcode-select --install    # the desktop build links against WebKit
brew install go node
make desktop && make install

정직성 메모: ducklab은 Linux에서 매일 개발되고 실행됩니다. CLI와 엔진은 모든 make cross에서 darwin/arm64 컴파일 검사를 하지만, Mac에서 검증된 데스크톱 빌드는 아직 없습니다 — 처음 시도하는 사람이 테스트이며, make install은 어느 쪽이든 CLI와 엔진을 제공합니다. 깨지는 것이 있으면 보고해 주세요.

둘 다

make install은 ~/.local/bin에 설치합니다 — PATH에 있는지 확인하세요. 데스크톱 바이너리가 frontend/src보다 오래된 경우 경고합니다, 오래된 것을 기꺼이 설치할 수 있기 때문입니다.

세 개의 바이너리

공급자 키는 호출 시점에 엔진의 환경에서 옵니다 — 시작하기 전에 내보내거나, 키링에서 로드하는 래퍼를 통해 데스크톱을 실행하세요. 앱은 채택한 엔진에 이 앱이 가진 키가 없는 경우 알려주고, 그 옆에 재시작 버튼이 있습니다.

처음부터 끝까지의 사이클

데스크톱에서: 프로젝트 → 새 프로젝트, 그 다음 사이클 → 초안 작성. 터미널에서:

cd ~/dev/myproject
git init                                    # ducklab needs a git repo
ducklab project init --name MyProject       # auto-starts the engine if none is running

ducklab intake --from brief.txt             # brief        → requirements
ducklab spec                                # requirements → spec
ducklab plan                                # spec         → milestones and tasks

ducklab run T-001                           # build it
ducklab run accept r-20260729-...           # commit it

ducklab review T-001                        # read the commit
ducklab release plan --bump minor           # what shipped

각 스테이지는 먼저 .proposed 파일을 쓰고 당신을 기다립니다. accept는 승격합니다; reject는 실행이 쓴 것만 정확히 복원하고 그 외에는 아무것도 하지 않습니다; "변경 요청"은 스펙, 계획, 릴리즈 노트 등 모든 초안을 당신의 메모와 함께 돌려보냅니다. 당신(또는 당신이 명시적으로 부여한 자율 수준) 없이는 아무것도 커밋되지 않습니다.

참조 문서는 모든 스테이지에 실릴 수 있습니다: --ref ~/wiki/product/(또는 데스크톱의 첨부 문)는 파일이나 전체 디렉토리를 아키텍트의 배경으로 로드합니다 — 프롬프트가 명시하는 두 가지 규칙에 근거합니다: 승인된 요구사항이 범위를 소유하고, 참조와 코드가 다를 때 코드가 진실입니다. 말뭉치가 좌석의 컨텍스트를 초과하면 각 문서는 한 번 요약되고(콘텐츠 해시로 캐시), 전체 텍스트는 ref_read 도구를 통해 계속 접근 가능하며, 제안 카드는 어떤 좌석도 열지 않은 문서를 나열합니다.

기존 코드베이스 채택도 같은 방식으로 작동합니다: 인테이크가 코드를 읽고 as-built 요구사항을 쓰고, 스펙은 섹션을 as-built로 표시하며, 계획은 의도적으로 비워 둡니다 — 새 작업은 버그 보고서와 계획 수정을 통해 들어오며, 이것이 ducklab 자체가 개발되는 방식입니다.

프로젝트는 .ducklab/project.toml에서 자신의 진실을 선언합니다: 게이트([verify] — 클린 체크아웃에 필요한 link_deps와 setup 포함), 앱이 어떻게 시작되는지([run]과 사전 점검), 그리고 프로젝트 자체 바이너리가 어떻게 재빌드되는지([install]) — 그래서 전체 루프가 ducklab을 떠나지 않고 실행됩니다.

모델 추가

ducklab provider set openrouter --url https://openrouter.ai/api/v1 \
                                --key-env OPENROUTER_API_KEY
ducklab duckling set pato-sonnet --provider openrouter \
                                 --model anthropic/claude-sonnet-4.5 \
                                 --roles reviewer,judge --context 200000 \
                                 --cost-in 3.0 --cost-out 15.0
ducklab duckling test pato-sonnet --prompt "say OK"

--key-env는 환경 변수의 이름이지, 키가 아닙니다. 어떤 키도 설정에 기록되지 않고, API로 전송되지 않으며, 셸 히스토리에 남지 않습니다.

데스크톱의 로스터 보기는 좌석이 할당되는 곳입니다: 무리에서 모드의 좌석으로 드래그하고, 전역 또는 프로젝트별로, 각 덕링의 증거가 카드에 있고 엔진의 제안이 좌석 옆에 있습니다. 코딩 / 지능 / 에이전트 지수는 덕링이 OpenRouter에 있을 때 OpenRouter의 벤치마크 엔드포인트에서 옵니다; 나머지는 자신의 실행이 제공합니다.

다섯 가지 모드

ducklab run T-001 --mode <모드>

하지 않을 것

이것들은 선호가 아니라 하중을 지탱하는 것입니다.

• 모델은 절대 판정을 내리지 않습니다. 게이트는 명령의 종료 코드입니다.

• 녹색 후보는 바이트 단위로 적용됩니다. 통과한 후에 다시 생성되지 않습니다.

• 리뷰어는 누가 코드를 썼는지 절대 알 수 없습니다.

• 클린 체크아웃에서 재현되지 않은 것은 아무것도 들어오지 않습니다.

• 거부는 실행이 쓴 것을 되돌리고, 다른 사람의 작업은 건드리지 않습니다.

• 무한한 것은 없습니다.

• 비밀은 프로젝트 상태에 닿지 않습니다.

• 엔진은 루프백 전용입니다. 원격 모드가 없습니다.

스킬

스킬은 SKILL.md가 있는 디렉토리입니다 — 한 프로젝트의 .ducklab/skills/ 아래, 또는 모든 프로젝트에 제공하는 머신 전체 스킬 디렉토리(이름 충돌 시 프로젝트가 전역을 가림). 문서 전용 형식은 스크립트가 없고 기본값입니다: 모델이 읽고 따르는 레시피. 아키텍트는 채택 전에 조사 가이드를 읽습니다(skill_list가 프롬프트에 있음), 컨설턴트는 채팅에서 읽고, 실행 가능한 스킬은 구현자만 skill_run할 수 있습니다.

스킬은 데스크톱(기어 → 스킬)에서 관리됩니다: 범위 배지와 검증 문제가 있는 목록, 읽기, 전체 SKILL.md 편집, 인수로 실행, 삭제. 실행 중에 덕링이 쓴 스킬은 실행이 수락될 때까지 회색 보류 중인 수락으로 표시됩니다 — 스킬 제안은 코드 제안과 같은 게이트를 거칩니다.

ducklab skill new house-style
ducklab skill run changelog-entry --arg summary="..."

컨설턴트

모든 프로젝트는 로스터 보드의 컨설턴트(Common 좌석)를 둡니다: "이것에 대해 채팅하기" 문 뒤와 가이드 레일의 자유 형식 채팅 뒤에 있는 모델입니다. 코드, 실행, 보드, 스킬을 읽기만 하고 — 절대 쓰지 않으며 — 이미지를 받습니다: 깨진 화면의 스크린샷을 붙여넣고 질문하세요. 비전은 가정되는 것이 아니라 검증됩니다: 비전이 선언된 좌석은 실제 이미지 요청으로 한 번 시험되고, 텍스트 전용 좌석은 답을 지어내는 대신 말로 붙여넣기를 거부합니다.

다른 모델에서 ducklab 운영하기

ducklab mcp serve는 전체 루프를 stdio를 통해 MCP 서버로 노출합니다: 외부 모델이 각 결과를 읽고, 게이트를 결정하며(필수적이고 기록되는 이유와 함께 — 결정은 "human"이 아닌 approved_by: mcp:<client>로 기록됩니다), 질문에 답하고, 버그를 등록하고, 계획을 수정하고 작업을 시작합니다. 엔진의 next 목록이 법입니다: 운영자는 사람이 할 수 없는 조치를 취할 수 없습니다.

기여하기

CONTRIBUTING.md를 참조하세요 — 빌드 방법, 테스트가 아키텍처를 보호하는 방법, 작업이 ducklab 자체 루프를 통해 흐르는 방법, 그리고 어디서 시작할지가 나와 있습니다. 간단히 말하면:

make            # vet, test, build the frontend
go test ./...   # 38 packages
cd frontend && npx vitest run

라이선스: Apache-2.0. 기여는 동일한 조건으로 수락됩니다 (라이선스 §5 — CLA 없음). Ducklab 이름과 오리는 유지보수자의 소유입니다(§6).

명세

코드는 이 저장소에 있는 문서화된 명세를 구현합니다: docs/spec/ (00-VISION부터 08-DESKTOP-UI까지)은 규범적 계층입니다 — 비전, 불변식, 프로토콜 계약, 승인 기준. 시스템이 오늘날 무엇인지는 .ducklab/docs/에 있습니다 — 루프 자체가 유지 관리하는 실제 구축(as-built) 요구사항, 명세 및 계획으로, 각 버전은 인간 게이트에서 서명됩니다. 둘이 의도적으로 다를 때 그 차이는 docs/decisions/에 기록됩니다; 둘 사이의 차이는 로드맵이며, 정렬 단계가 이를 계산합니다.