duckbugio/flock

Flock – 채팅으로 조작 가능한 AI 기반 소프트웨어 개발 팀

무엇인가요 – Flock은 자체적으로 완전한 서비스로, 자신의 서버에서 Claude-Code 기반 개발 팀을 운영할 수 있게 해줍니다. Telegram, VK, 또는 단순한 텍스트 전용 "LO" 인터페이스를 통해 팀과 상호작용할 수 있습니다. 단일 메시지로 AI에게 새로운 기능의 계획, 코드 작성, 테스트, 리뷰, 그리고 풀 리퀘스트 개설을 요청할 수 있습니다. 각 채팅은 고유한 격리된 워크스페이스와 Git 브랜치를 가지므로, 여러 사용자가 동시에 독립된 프로젝트를 병렬로 실행할 수 있습니다.

왜 중요한가요 – 대부분의 AI 코드 보조 도구는 단일 프롬프트로 스니펫을 반환하는 수준입니다. Flock은 Docker 내에서 실행되는 완전한 개발 파이프라인 (플래너 → 코더 → 테스터 → 리뷰어 → 아비터)을 구축하며, Git 호스트와 통신하고, CI를 모니터링하고 성공 시 자동 머지까지 가능합니다. 모든 작업은 자체 하드웨어에서 실행되며, Claude Pro/Max 구독(또는 Anthropic API 키)만 필요하고, 토큰당 비용이 발생하지 않습니다.

주요 기능 (README에 설명됨)

기능	기능 설명
채팅 기반 사양	채팅에서 기능 설명을 작성하면 AI 팀이 구체적인 계획과 코드로 변환합니다.
완전한 CI 파이프라인	브랜치가 생성되고, 리포지토리의 테스트/체크 명령어가 실행되며, 풀 리퀘스트가 열리고, 녹색 빌드는 자동 머지 가능합니다.
자율 루프	선택적 루프를 통해 봇이 자신의 작업을 검증하고, 목표 재평가(`/goal`), 스케줄된 작업 실행(`/schedule`), CI 상태 모니터링(`ENABLE_CI_WATCH`)이 가능합니다.
다중 플랫폼 어댑터	Telegram과 VK용 즉시 실행 가능한 Docker 이미지; 어떤 텍스트 전용 채널에도 사용 가능한 가벼운 "LO" 어댑터.
채팅별 격리	각 채팅은 고유의 워크스페이스 디렉터리와 브랜치(`duck/<chatid>/<slug>`)를 가지며, 상호 간섭을 방지하고 병렬 실행을 가능하게 합니다.
Git 호스트 통합	GitHub, GitLab, Gitea와 PAT를 통해 연동 가능; 봇은 PR 리뷰 댓글을 페칭하여 원본 채팅으로 라우팅합니다.
옵션 음성 명령	음성 메시지는 (Mistral, OpenAI 또는 로컬) 음성 인식되어 채팅 명령어로 처리됩니다.
Docker만으로 배포	사전 빌드된 이미지(`ghcr.io/duckbugio/flock-telegram`, `flock-vk`)를 사용해 컴파일이나 Ansible 없이 빠르게 시작 가능합니다.
보안 제어	채팅당 비용 제한, 무한 루프를 중단하는 "아비터" 서브에이전트, 엄격한 사용자 허용 목록.

빠른 시작 (Telegram 예제)

# 리포지토리 클론 및 Telegram 어댑터로 이동
git clone https://github.com/duckbugio/flock
cd flock/adapters/telegram

# 예제 env 파일 복사 및 4개의 필수 값 설정
cp .env.example .env   # .env 편집 → BOT_TOKEN, BOT_USERNAME, ALLOWED_USERS, CLAUDE_CODE_OAUTH_TOKEN (또는 ANTHROPIC_API_KEY) 설정

# 컨테이너 시작 (Docker Compose가 사전 빌드된 이미지를 다운로드)
docker compose up -d

컨테이너가 실행된 후 Telegram에서 봇에 메시지를 보내어 브랜치 생성, 테스트 실행, 풀 리퀘스트 개설을 관찰하세요.

내부 동작 원리 (개요)

사용자 메시지 – 기능을 설명합니다.
리드 클로드 – 플래너 역할을 하며 범위를 확인합니다.
서브에이전트 – planner → coder → tester → reviewer → arbiter는 core/agents/에 정의된 Claude-Code 서브에이전트입니다.
브랜치 및 PR – 코드는 duck/<chatid>/<slug>라는 이름의 브랜치에 커밋되며, 설정된 Git 호스트에 풀 리퀘스트가 열립니다.
피드백 루프 – 리뷰어의 댓글은 채팅으로 페칭되며, 아비터는 승인, 수정 요청, 또는 중단을 수행할 수 있습니다.
자율 옵션 – 실행 후 검증, 목표 평가, 스케줄된 작업, CI 모니터링, 선택적 자동 머지 등은 환경 변수로 전환 가능합니다.

일반적인 사용 사례

기능 개발 – 프로덕트 매니저가 채팅에서 새로운 엔드포인트를 설명하면 완전히 테스트된 PR을 받을 수 있습니다.
버그 수정 – 버그 설명을 붙여넣기만 하면 AI 팀이 수정을 생성하고, 리포지토리의 테스트 스위트를 실행하며, PR을 열 수 있습니다.
손쉬운 CI 모니터링 – CI 모니터링을 활성화하면 빌드 실패 또는 성공 시 채팅에 알림을 보내며, 녹색 PR은 선택적으로 자동 머지 가능합니다.
스케줄된 유지보수 – /schedule을 사용해 정기적인 린트, 종속성 업그레이드, 기타 루틴 작업을 실행합니다.

설치 및 운영 노트

사전 조건 – Docker Compose, Claude Pro/Max 토큰(또는 Anthropic API 키), 쓰기 권한이 있는 Git 호스트의 PAT.
지원되는 전송 방식 – Telegram(사전 빌드 이미지), VK(사전 빌드 이미지), 로컬에서 빌드 가능한 일반적인 "LO" 어댑터.
환경 설정 – 대부분의 설정은 .env에 있으며, 필수 키는 README 테이블에 나와 있습니다. 옵션 기능은 ENABLE_* 플래그로 전환 가능합니다.
보안 – ALLOWED_USERS (또는 VK 동등 항목)에 등록된 사용자만 봇을 호출할 수 있으며, 에이전트는 컨테이너 내에서 비-root 사용자로 실행되며 워크스페이스 디렉터리에 샌드박스화됩니다.
확장성 – 새로운 채팅 플랫폼을 추가하려면 코어 에이전트를 재사용하는 얇은 어댑터만 만들면 됩니다. 리포지토리에는 설계 문서(docs/multi-transport-plan.md)가 포함되어 있습니다.

라이선스 및 기여

라이선스: MIT (see LICENSE).
기여: 표준 fork-branch-PR 워크플로우를 따르세요. 리포지토리는 Taskfile을 제공하여 린트, 테스트, 빌드 가능 (task lint, task tests, task build).
보안 공개: SECURITY.md를 통한 비공개 보고.

결론: Flock은 Claude-Code 구독을 완전히 자동화되고 채팅 기반의 개발 팀으로 전환하여, 자체 서버에서 기능의 계획, 코드 작성, 테스트, 리뷰, 머지까지 수행할 수 있으며, 강력한 격리와 선택적 자율 제어 기능을 갖추고 있습니다.