tolimarchuk/goalbuddy

GoalBuddy – 장기적인 AI 지원 코딩 작업을 위한 가벼운 오케스트레이션 계층

무엇인가요

• GoalBuddy는 npm을 통해 배포되는 CLI 도구로, OpenAI Codex 또는 Anthropic Claude Code와 같은 LLM 기반 코딩 어시스턴트를 사용할 때 리포지토리 내에 작고 파일 기반의 "보드"를 생성하여 대규모 코딩 목표를 정리합니다.
• 보드는 채터 (goal.md), 상태 파일 (state.yaml), 노트, 하위 목표 폴더, 그리고 숨겨진 .goalbuddy-board 디렉터리를 포함합니다. 이 모든 내용은 일반 소스 코드 옆에 위치하므로, 작업을 일시 중단하거나 재개하거나 다른 에이전트 간에 원활하게 인수인계해도 컨텍스트를 잃지 않습니다.

작동 방식

1. 실행 시작 – npx goalbuddy를 실행하면 도구가 설치되고 /goal-prep 명령어가 출력됩니다.
2. 목표 준비 – $goal-prep (또는 Claude 내에서 /goal-prep)를 실행하면 보드가 생성되고, LLM 하드웨어가 다음에 실행해야 할 정확한 명령어가 표시됩니다.
3. 디스패치 – goalbuddy dispatch <board> --to codex|claude-code는 현재 작업의 프롬프트를 렌더링하고, 선택한 LLM CLI를 비디스플레이 모드로 호출하며, 반환된 수령증 (작업의 YAML 증거)를 캡처합니다. 또한 git을 사용해 파일 변경 사항이 작업에서 선언된 allowed_files 범위 내에 있는지 검증합니다.
4. 재개 / 인수인계 – npx goalbuddy resume은 모든 활성 보드를 목록으로 표시하고 각 하드웨어의 계속 실행 명령어를 보여주므로, Codex에서 Claude로(또는 그 반대) 전환할 때 계획을 다시 만들지 않아도 됩니다.
5. 검증 루프 – 작업자가 완료한 후, 판단자 에이전트가 수령증을 오라클(테스트 스위트, 데모, 벤치마크, 또는 인간 승인)과 비교하여 검증합니다. 보드의 state.yaml은 결과로 업데이트되어 "의도 → 오라클 → 표면 → 루프 → 증거" 사이클이 README에 설명된 대로 완료됩니다.

핵심 개념

• 보드 – 리포지토리 내에 영구적으로 존재하는 목표의 표현.
• 수령증 (v1) – 일반 YAML 형식으로, 하드웨어에 의존하지 않는 LLM이 수행한 작업의 기록. 자동 검증 가능.
• 스카우트 / 판단자 / 워커 – 리포지토리를 매핑하고, 안전한 작업 조각을 선택하며, 이를 실행하는 내장된 에이전트 역할.
• 오라클 – 목표가 진정으로 달성되었음을 알려주는 구체적인 신호(테스트, 데모, 벤치마크 등).
• 하위 목표 – 제한된 범위의 작업 분기용 깊이 1의 자식 보드. 부모 보드에서 링크됨.

왜 중요한가요

• 도구 간 연속성 – 보드가 단순한 파일이기 때문에 Codex로 시작한 목표는 내일 Claude Code에서 재개 가능하며, 동일한 보드에서 다중 벤더 실행도 가능합니다.
• 안전성 및 감사 가능성 – 수령증은 저장되고 git으로 검증되며, 나중에 판단자가 감사하여 LLM이 생성한 대규모 코드 변경의 명확한 기원 추적을 보장합니다.
• 최소한의 실행 시간 피트프린트 – 실행 시 생성되는 유일한 아티팩트는 goalbuddy npm 패키지뿐이며, 나머지는 모두 리포지토리 내에 있으므로 도구는 가볍고 버전 관리가 용이합니다.

일반적인 사용 사례

• 단계별 검증이 필요한 대규모 리팩터링.
• 여러 LLM 기반 작업(버그 수정, 문서 업데이트, 버전 증가)을 조율해야 하는 릴리스 준비.
• 증거(테스트 실패, 로그 등)를 수령증으로 캡처해야 하는 버그 조사.
• 별도의 LLM 호출 간에 컨텍스트를 잃는 위험이 있는 다중 프롬프트 프로젝트.

설치 및 기본 명령어

# 설치하고 새 보드 시작
npx goalbuddy

# 목표 준비 (보드 생성, 다음 명령어 출력)
$goal-prep   # 또는 Claude 내에서 /goal-prep

# 특정 하드웨어로 활성 작업 실행
npx goalbuddy dispatch docs/goals/my-feature --to codex

# 기존 보드 목록 및 재개
npx goalbuddy resume

# Codex 설치 검증
npx goalbuddy doctor --target codex --goal-ready

# 최신 버전으로 업데이트
npx goalbuddy update

더 알아보기

• 전체 문서는 리포지토리의 docs/ 폴더에 있습니다 (수령증 사양 및 릴리스 프로세스 포함).
• 실시간으로 작업, 수령증, 하위 목표가 업데이트되는 실시간 시각화 보드는 http://goalbuddy.localhost:<port>/<slug>/에서 열 수 있습니다.
• 프로젝트 웹사이트: https://goalbuddy.dev

라이선스 – MIT (오픈소스, 자유롭게 사용 및 수정 가능)