claude-devfleet

claude-devfleet 스킬 개요

claude-devfleet가 하는 일

claude-devfleet는 Claude DevFleet를 통해 멀티 에이전트 코딩 작업을 운영하는 조정용 스킬이며, 일반적인 코딩 프롬프트가 아닙니다. 이 스킬의 역할은 하나의 큰 엔지니어링 요청을 계획된 미션 세트로 바꾸고, 그 미션들을 분리된 git worktree로 배분한 뒤, 구조화된 진행 상황 및 완료 보고서를 반환하는 것입니다.

누가 설치하면 좋은가

이 claude-devfleet 스킬은 이미 로컬 또는 팀 단위 DevFleet 환경을 갖추고 있고, 의존성을 고려한 순차 실행과 병렬 실행을 함께 활용하고 싶은 사용자에게 가장 잘 맞습니다. 기능 개발, 리팩터링, 테스트 보강, 또는 자연스럽게 독립 작업이나 단계별 작업으로 쪼개지는 구현 계획에 특히 잘 어울립니다. 반대로 수정 한 번, 파일 하나 변경, 빠른 답변 정도만 필요하다면 적합도가 낮습니다.

일반 프롬프트 대신 이 스킬을 고르는 이유

핵심 차별점은 오케스트레이션입니다. 계획, 승인, 배포, 모니터링, 보고가 모두 명시적인 단계로 분리되어 있습니다. 한 에이전트에게 “전부 해줘”라고 맡기는 대신, Agent Orchestration용 claude-devfleet는 작업을 의존성이 있는 미션으로 분해하고, 각 미션을 별도 worktree에서 실행하게 해 동시 변경이 바로 충돌하지 않도록 돕습니다.

도입을 막는 가장 큰 장애물

가장 큰 장애물은 결국 환경 구성입니다. 이 스킬은 MCP를 통해 연결된 실행 중인 Claude DevFleet 인스턴스를 전제로 합니다. DevFleet가 설치되어 있지 않거나, 접속할 수 없거나, 예상한 MCP 엔드포인트로 노출되어 있지 않다면 이 스킬은 실질적으로 아무 역할도 하지 못합니다. 즉, 이것은 기존 인프라 위에서 동작하는 실행 워크플로우로 봐야지, 독립적으로 설치를 끝내주는 도구로 보면 안 됩니다.

claude-devfleet 스킬 사용 방법

설치 맥락과 필수 연결 조건

claude-devfleet 사용을 시도하기 전에, Claude Code가 MCP를 통해 DevFleet에 접근할 수 있는지 먼저 확인해야 합니다. 스킬 원문에서도 실행 중인 인스턴스를 전제로 하며, 다음과 같은 연결 패턴을 제시합니다.

claude mcp add devfleet --transport http http://localhost:18801/mcp

DevFleet 서버가 다른 호스트나 포트에서 돌고 있다면 해당 URL을 맞게 바꾸면 됩니다. 설치 여부를 판단할 때의 실무적인 기준은 단순합니다. 현재 환경에서 로컬 MCP 서비스를 허용하지 않는다면, 그 문제가 해결되기 전까지는 이 스킬을 보류하는 편이 맞습니다.

실무에서 claude-devfleet를 호출하는 방식

핵심 흐름은 다음과 같습니다.

1. plan_project(prompt)로 큰 요청을 프로젝트와 미션 DAG로 변환합니다.
2. 실행 전에 사용자와 함께 계획을 검토합니다.
3. dispatch_mission(mission_id, model?, max_turns?)로 작업을 시작합니다.
4. 설정된 경우 의존성이 연결된 미션은 자동으로 이어서 배포되게 합니다.
5. get_report(mission_id)로 files_changed, 완료된 작업, 오류, 다음 단계 요약을 확인합니다.

이미 작업 분해가 명확한 경우에는 create_project(...)와 create_mission(...)로 수동으로 계획을 구성할 수도 있습니다. 브레인스토밍보다 의존성 그래프의 정확성이 더 중요할 때는 수동 생성이 더 낫습니다.

막연한 목표를 강한 프롬프트로 바꾸는 법

약한 입력: “Build a REST API.”

claude-devfleet 스킬에 더 적합한 입력:

• repo 경로 또는 대상 코드베이스
• 원하는 엔드포인트와 인증 방식
• persistence layer
• 테스트 기대치
• 제외할 범위
• 순서 제약

예시:
“Plan a project for ./app: add a REST API for projects and tasks, JWT auth, PostgreSQL via existing DB layer, preserve current routes, add integration tests, and keep schema changes isolated from endpoint work. Prefer missions that can run in parallel where safe.”

이 입력이 잘 작동하는 이유는, plan_project가 경계, 인터페이스, 순서 제약을 알아야 더 좋은 미션 그래프를 만들 수 있기 때문입니다. 이런 정보가 없으면 계획이 지나치게 모호해지거나, 미션끼리 겹치는 범위가 커지는 경우가 많습니다.

권장 워크플로우와 먼저 읽어야 할 파일

먼저 SKILL.md부터 읽는 것이 좋습니다. 이 저장소에서 실제 운영 계약에 해당하는 내용이 거기에 담겨 있기 때문입니다. 특히 다음 항목에 집중하세요.

• 필수 MCP 의존성
• plan → approve → dispatch → report 워크플로우
• 사용 가능한 도구와 각 파라미터
• depends_on 및 auto_dispatch를 통한 의존성 처리

실무적으로는 다음 흐름을 권장합니다.

1. 우선 계획만 요청합니다.
2. 각 미션이 정말 분리 가능한지 확인합니다.
3. 그래프를 승인하거나 수정합니다.
4. 환경과 저장소 가정이 맞는지 검증하기 위해 작은 첫 미션 하나만 배포합니다.
5. 보고서 하나가 정상적으로 나온 뒤에야 병렬 배포를 확대합니다.

claude-devfleet 스킬 FAQ

claude-devfleet는 초보자에게도 좋은가?

초보자라도 이미 DevFleet를 실행 중인 상태라면 가능합니다. 오케스트레이션 모델 자체는 개념적으로 이해하기 어렵지 않지만, 실제 진입 장벽은 인프라와 작업 분해 능력에 있습니다. MCP나 worktree에 익숙하지 않은 초보자는 가치를 체감하기 전에 먼저 막힐 가능성이 큽니다.

일반 코딩 프롬프트 대신 언제 써야 하나?

claude-devfleet는 작업 규모가 충분히 커서 미션 계획, 격리된 실행, 구조화된 보고의 이점을 살릴 수 있을 때 쓰는 것이 좋습니다. 단일 파일 수정, 빠른 디버깅, 탐색성 질문에는 쓰지 않는 편이 낫습니다. 그런 경우에는 일반 프롬프트가 더 빠르고 운영 오버헤드도 적습니다.

이 스킬의 경계는 어디까지인가?

이 claude-devfleet 가이드는 오케스트레이션 동작을 다루는 문서이지, 전체 환경 프로비저닝을 책임지는 문서는 아닙니다. 이 스킬은 DevFleet가 이미 존재하고, plan_project, create_mission, dispatch_mission, cancel_mission, get_report 같은 도구 호출이 MCP를 통해 제공된다고 가정합니다. 이런 도구가 빠져 있다면 이 스킬은 사실상 사용할 수 없습니다.

팀 워크플로우에도 맞는가?

네. 특히 팀이 미션 그래프를 눈에 보이게 관리하고, 분리된 git worktree를 통해 더 안전하게 병렬 작업을 돌리고 싶을 때 잘 맞습니다. 반대로 아주 작은 저장소를 다루거나, auto-merge나 의존성 기반 자동화를 코딩 흐름에 넣고 싶지 않은 팀이라면 매력도가 떨어질 수 있습니다.

claude-devfleet 스킬을 더 잘 쓰는 방법

더 좋은 계획 입력을 주기

claude-devfleet 결과를 가장 빠르게 개선하는 방법은 아키텍처 제약과 작업 분할 힌트를 처음부터 구체적으로 주는 것입니다. 다음 내용을 포함하세요.

• 대상 repo/path
• acceptance criteria
• 충돌을 일으킬 가능성이 큰 shared file
• 반드시 먼저 끝나야 하는 작업
• 병렬로 돌려도 되는 작업

이렇게 하면 잘못된 미션 그래프를 줄일 수 있고, 두 에이전트가 같은 핵심 지점을 동시에 건드리는 상황도 피하기 쉬워집니다.

자주 생기는 실패 패턴을 주의하기

대표적인 실패 패턴은 비교적 예측 가능합니다.

• DevFleet로의 MCP 연결이 없음
• 미션 범위가 너무 큼
• 의존 작업이 너무 일찍 배포됨
• 병렬 worktree 사이에서 수정 범위가 겹침
• 복잡한 미션에 비해 max_turns가 부족함

미션이 계속 정체된다면, 모델을 바꾸거나 에이전트를 더 늘리기 전에 먼저 범위를 줄이세요.

첫 보고서 이후에 다시 다듬기

첫 계획을 최종안처럼 취급하지 마세요. get_report(...) 이후에는 다음 방식으로 프로젝트를 조정하는 것이 좋습니다.

• 끝나지 않은 작업을 더 좁은 후속 미션으로 분리하기
• 빠진 의존성 추가하기
• 중복 작업을 만든 미션 취소하기
• 정확한 파일, 인터페이스, 테스트 대상을 포함하도록 프롬프트 다시 쓰기

바로 이 지점에서 Agent Orchestration용 claude-devfleet가 긴 단일 프롬프트보다 더 가치 있어집니다. 이 워크플로우는 한 번에 완벽하게 끝내기보다, 반복 수정하며 정교화하는 방식에 맞춰 설계되어 있습니다.

더 촘촘한 미션 프롬프트로 결과 개선하기

좋은 미션 프롬프트는 코드 영역, 원하는 산출물, 완료 기준을 분명히 적습니다. 예를 들면 다음과 같습니다.
“Implement JWT auth middleware in server/auth, wire it into existing protected routes, add unit tests for token validation and expired tokens, do not change database schema.”

이 정도로 구체적이면 handoff 품질이 좋아지고, merge 위험은 낮아지며, 최종 보고서도 훨씬 실행 가능한 형태로 정리됩니다.