kungfu-systems/kungfu

Kungfu – LLM 에이전트를 위한 내구성 있는 작업 레이어

무엇인가요

• Kungfu는 GitHub Copilot Codex, Anthropic Claude, OpenCode, Amp 또는 자체 호스팅 모델과 같은 어떤 LLM 기반의 코딩 또는 추론 에이전트와 함께 작동하는 명령줄 도구(선택적 TUI/GUI 포함)입니다. 작업의 목적, 증거, 결정, 상태를 채팅 세션 외부에 기록함으로써 동일한 작업이 에이전트 간 인수인계, 충돌, 연결 끊김에도 견딜 수 있도록 합니다.

핵심 개념

개념	의미
Project	관련된 작업 항목을 그룹화하는 폴더입니다. Kungfu는 여기에 상태를 저장하기 위해 숨겨진 .kungfu/ 디렉터리를 생성합니다.
Work	단일 내구성 작업(예: "릴리스 노트 준비"). 현재 진실, 진행 상황, 필요 증거를 보유합니다.
Attempt	에이전트가 Work를 실행하는 한 번의 시도입니다. 실패하더라도 Work를 덮어쓰지 않고 로그에 기록됩니다.

작동 방식

1. Kungfu를 통해 에이전트 시작 – kungfu run codex "Prepare the release notes". Kungfu는 선택한 에이전트를 시작하고 프롬프트를 전달하며, 에이전트가 수행한 모든 작업을 Attempt로 기록합니다.
2. 에이전트 자유롭게 전환 – Work가 .kungfu/에 저장되어 있으므로, 나중에 kungfu run claude를 실행하여 문맥을 다시 설명하지 않고도 동일한 작업을 계속할 수 있습니다.
3. 장애 이후 복구 – 에이전트가 충돌하거나 연결이 끊어져도, 다음 Attempt는 동일한 Work를 이어받아 이전 증거와 결정을 유지합니다.
4. 독립적 완료 – 에이전트가 결과를 제안할 수 있지만, Kungfu는 Work를 완료로 표시하기 전에 별도의 검토/결정 단계를 요구하여 에이전트가 자가 승인하는 것을 방지합니다.

주요 기능

• 에이전트 독립적: 로컬 명령을 실행할 수 있는 CLI 호환 LLM 에이전트와 함께 작동합니다.
• 결정론적 모크 에이전트: KUNGFU_MOCK_AGENT_SCENARIO라는 내장 에이전트를 통해 API 키 없이 지속성과 장애 복구를 데모할 수 있습니다.
• 사이드카 UI: 선택적 터미널 UI(kungfu)와 그래픽 UI를 통해 Projects, Work, Attempts를 시각화할 수 있습니다.
• 감사 가능한 증거: 각 Attempt는 프롬프트, 응답, 생성된 아티팩트를 저장하여 검토 및 준수를 가능하게 합니다.
• 안전 장치: 두 개의 에이전트가 동시에 동일한 Work를 쓰는 것을 방지합니다.
• 오픈소스 표준: KFD 엔지니어링 표준과 검증 가능한 릴리스 패스포트를 생성하는 Buildchain을 함께 제공합니다.

설치 (macOS / Linux / Windows)

# 단일 명령어 설치 (sudo 없음, 쉘 프로파일 변경 없음)
curl -fsSL https://kungfu.tech/install.sh | sh

스크립트가 PATH 추가를 출력한 후, 쉘에 추가하거나 Windows 가이드를 따르세요. 설치 프로그램은 최신 알파 릴리스를 다운로드합니다.

빠른 시작

# 어떤 프로젝트 폴더 내에서
KUNGFU_MOCK_AGENT_SCENARIO=recovery-story kungfu   # 결정론적 3단계 데모 실행
# 또는 실제 에이전트 실행
kungfu run codex "Write the changelog for v2.3"

숨겨진 .kungfu/ 디렉터리가 생성됩니다. 버전 관리에서 제외하세요.

일반적인 사용 사례

• 장시간 실행 개발 작업: 저렴한 LLM과 고성능 LLM 간 전환 필요 시.
• 팀 환경: 여러 엔지니어(또는 봇)가 동일한 AI 생성 작업을 컨텍스트 손실 없이 협업해야 할 때.
• 준수/감사: 모델이 무엇을 생성했고 왜 그렇게 했는지에 대한 완전하고 불변의 로그가 필요할 때.

성숙도

• 프로젝트는 알파(v4) 단계입니다. macOS, Linux, Windows에서 작동하지만 API와 UI는 여전히 변경될 수 있습니다. README는 릴리스가 프리릴리스 채널임을 경고하며, "알파 상태"와 "알려진 제한" 문서로 안내합니다.

라이선스

• Apache-2.0 (see LICENSE).

더 배우기

• 시스템 개요: docs/concepts/system-overview.md
• 에이전트-작업 랩 튜토리얼: docs/guides/agent-work-lab.md
• 전체 문서 맵: docs/MAP.md
• 릴리스 아티팩트: https://github.com/kungfu-systems/kungfu/releases/latest

---

Kungfu는 LLM 기반 에이전트의 지속성 레이어로, AI 생성 작업을 일반 소프트웨어 아티팩트처럼 다루어 충돌, 에이전트 간 인수인계, 모델 변경에도 견딜 수 있도록 합니다.