튜토리얼: 첫 번째 실전 태스크
시작하기에서 5분 안에 설치하고 채팅하는 방법을 배웠습니다. 이 튜토리얼은 다음 단계입니다: ADHDev가 실제로 무엇을 위한 것인지 직접 체험하는 실습 과정 — 실제 코딩 에이전트 실행, 하는 일 제어, 그리고 (선택적으로) Repo Mesh를 통해 여러 머신에서 작업을 조율하고 Refinery가 main에 착지시키게 하기.
각 부분이 작동하는 것을 볼 수 있도록 직접 해봅니다. 끝에는 ADHDev가 제공하는 네 가지 — Refinery, 모든 에이전트, 당신의 머신, 원격 제어 — 를 불릿 포인트가 아니라 직접 구동해본 경험으로 이해하게 됩니다.
필요한 것
adhdevCLI 설치됨 (없으면 시작하기 참조).- 머신에 최소 하나의 CLI 에이전트가 설치되고 인증됨 — Claude Code, Codex CLI, Gemini CLI, 또는 다른 것. ADHDev는 에이전트 자체의 로그인을 관리하지 않습니다. 에이전트가 자체 인증을 유지합니다.
- 에이전트가 작은 변경을 하도록 허용할 git 레포지토리.
이 튜토리얼 전체는 Standalone 모드(계정 없음)에서 작동합니다. 끝의 Repo Mesh 섹션은 클라우드 전용입니다 — 명확히 표시되어 있으며, 그 이전의 모든 내용은 독립적입니다.
1단계 — Standalone 시작 및 대시보드 열기
adhdev standalone이 명령은 내장 데몬(localhost:3847)과 로컬 대시보드(localhost:3000)를 함께 시작합니다. http://localhost:3000을 여세요.
표시 내용: 로컬 머신이 온라인 상태로 나열된 대시보드. 로그인 화면 없음 — standalone은 완전히 로컬입니다.
📸 [스크린샷: standalone 대시보드, 한 대 머신 온라인, 빈 세션 목록]
왜 중요한가: 이것이 컨트롤 플레인입니다. 여기서 에이전트가 하는 모든 것 — 채팅, 도구 호출, 승인 — 이 브라우저와 데몬 사이에서 P2P로 흐릅니다. 대시보드는 모든 세션의 단일 뷰이며, 잠시 후 표시할 세션이 생깁니다.
정상 확인
대시보드가 비어 있거나 머신이 오프라인으로 표시되면 다른 터미널에서 adhdev doctor를 실행하세요. 데몬 프로세스, 로컬 연결, 프로바이더 레지스트리를 확인하고 특정 수정 방법을 알려줍니다.
2단계 — ADHDev가 구동할 수 있는 것 확인
실행하기 전에 이 머신에서 감지된 것을 확인하세요:
adhdev detect표시 내용: installed: yes/no가 있는 알려진 프로바이더 목록. yes인 것은 바로 실행할 수 있습니다.
왜 중요한가: 프로바이더는 ADHDev의 하나의 에이전트에 대한 어댑터이며, 네 종류가 있습니다 — 여기서는 첫 번째를 선택합니다:
| 카테고리 | 전송 | 예시 |
|---|---|---|
| cli | PTY (터미널) | Claude Code, Codex CLI, Gemini CLI, Hermes CLI |
| ide | Chrome DevTools Protocol | Cursor, VS Code, Windsurf, Kiro, PearAI, Trae |
| extension | CDP 웹뷰 | Antigravity |
| acp | stdio (Agent Client Protocol) | ACP 호환 에이전트 |
이 튜토리얼에서는 cli 프로바이더를 사용합니다 — 작동하는 세션을 가장 빠르게 얻을 수 있으며 에디터 재실행이 필요하지 않습니다.
3단계 — CLI 에이전트 세션 실행
installed: yes가 표시된 CLI 에이전트를 선택하세요. 예를 들어:
adhdev launch claude # Claude Code
# 또는: adhdev launch codex / adhdev launch gemini데몬이 PTY 아래에서 에이전트를 시작하고 터미널을 대시보드로 스트리밍합니다.
표시 내용: 대시보드에 새 세션 카드가 나타납니다. 클릭하면 하단에 입력창이 있는 라이브 터미널 뷰가 열립니다.
📸 [스크린샷: 세션 카드 + 입력창이 있는 열린 터미널 뷰]
왜 중요한가: 에이전트는 당신의 머신에서, 당신의 작업 디렉토리에서, 자체 인증으로 실행됩니다 — ADHDev는 그저 창을 제공합니다. 에이전트의 동작은 변하지 않았습니다. 위에 컨트롤 플레인을 추가했을 뿐입니다.
작업 디렉토리
세션은 실행한 디렉토리에서 실행됩니다. 에이전트가 작업할 git 레포지토리를 가리키세요 — adhdev launch 전에 cd로 이동하거나, 대시보드의 실행 흐름에서 레포를 여세요.
4단계 — 채팅하고 승인 제어 유지
세션 입력창에서 에이전트에게 작고 실제적인 일을 요청하세요. 예를 들어:
이 레포를 보고 README 맨 위에 이것이 무엇인지 설명하는 한 줄 설명을 추가해줘.
로컬 터미널에서 하듯이 입력하고 Enter를 누르세요.
표시 내용:
- 에이전트의 응답이 실시간으로 대시보드에 스트리밍됩니다 — 로컬 터미널에서 볼 수 있는 동일한 토큰.
- 에이전트가 도구를 실행하거나 파일을 편집하고 싶을 때 ACTION REQUIRED 배너가 Approve와 Reject 버튼과 함께 나타납니다.
📸 [스크린샷: Approve / Reject가 있는 ACTION REQUIRED 승인 배너]
Approve를 클릭하여 편집을 허용하거나(또는 Reject로 거부하세요). 결정이 P2P 채널을 통해 데몬으로 전달되고 에이전트가 계속됩니다.
왜 중요한가: 이것이 사람이 루프에 있는 제어입니다. 에이전트는 당신이 보지 못한 명령을 자동으로 실행하지 않습니다 — 모든 도구 호출과 파일 편집이 당신이 소유한 승인으로 표시됩니다. 같은 배너가 키보드에서 멀어져도 제어권을 유지할 수 있게 해주며, 이것이 정확히 다음 단계에서 구축하는 것입니다.
이미지 첨부
채팅 입력은 이미지 첨부(최대 5개, 각 10MB)를 허용합니다 — 버그 스크린샷이나 에이전트가 맞춰야 할 디자인을 붙여넣기 할 때 편리합니다.
5단계 — 휴대폰에서 승인 (클라우드)
클라우드 전용
이 단계는 클라우드 버전이 필요합니다. Standalone은 단일 머신과 로컬 전용이므로 원격에서 승인할 수 있는 표면이 없습니다. Standalone을 사용 중이라면 다음 단계로 건너뛰세요 — 이미 핵심 루프를 보았습니다.
4단계의 승인 배너는 에이전트가 실행되는 머신에 묶여 있지 않습니다. 클라우드 모드에서 휴대폰 브라우저로 adhf.dev에 로그인하면 동일한 Approve / Reject 배너가 나타납니다 — 반응형 레이아웃, 동일한 P2P 승인 흐름.
📸 [스크린샷: 모바일 승인 배너]
표시 내용: 에이전트가 책상에서 도구 호출로 일시 중지됨. 승인이 휴대폰에 표시됨. Approve 탭. 에이전트 계속.
왜 중요한가: 장기 실행 작업을 시작하고 자리를 떠날 수 있습니다. 에이전트는 당신이 어디 있든 모든 결정 지점에서 멈추고 당신을 기다립니다. (휴대폰은 승인을 받고 답변합니다. 새 태스크 디스패치는 데스크탑/CLI 작업으로 유지됩니다.)
6단계 — Repo Mesh로 여러 머신 조율 (클라우드)
클라우드 전용
Repo Mesh는 동일 계정의 여러 데몬을 조율하며 클라우드 버전에서만 사용 가능합니다. 단일 대시보드 위의 레이어 — 하나의 코디네이터가 여러 머신(또는 여러 격리된 워크트리)의 에이전트에 작업을 넘기고 결과를 수렴합니다. 개념은 전체 Repo Mesh 가이드를 참조하고, 여기서는 하나를 연결합니다.
지금까지는 하나의 세션에서 하나의 에이전트를 구동했습니다. Repo Mesh는 이것을 한 사람이 많은 에이전트를 조율하는 것으로 바꿉니다. 가장 작은 엔드-투-엔드 버전입니다.
1. 레포에 대한 메시를 만드세요. 레포 내부에서 (git 원격이 자동 감지되도록):
adhdev mesh create my-project --add-current--add-current는 현재 워크스페이스를 메시의 첫 번째 노드로 등록합니다. 명령이 메시 ID(예: mesh_abc123)를 출력합니다.
표시 내용: 메시 ID, 감지된 레포 identity, 브랜치가 있는 확인 메시지와 "다음 단계" 힌트.
2. 다른 노드를 추가하세요. 두 번째 머신(또는 격리된 워크트리)에서 같은 메시에 추가하세요. 워크트리는 병렬 에이전트들이 서로의 작업 트리를 방해하지 않게 합니다:
adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli--provider-priority는 태스크가 에이전트를 지정하지 않을 때 어떤 에이전트를 실행할지 노드에 알립니다 — 우선순위가 설정되지 않은 노드는 추측하는 대신 자동 실행을 거부합니다.
3. 메시의 형태를 확인하세요.
adhdev mesh show mesh_abc123 # 노드, 정책, 노드별 실행 준비 상태
adhdev mesh status mesh_abc123 # 라이브 노드별 git 상태 (브랜치, 클린/더티, 앞/뒤)📸 [스크린샷: adhdev mesh status 출력, 브랜치 + 클린/더티 상태의 노드들]
왜 중요한가: 이제 하나의 코디네이터 아래 두 개 이상의 워크스페이스가 등록되었습니다. 클라우드 대시보드의 Repo Mesh 페이지(/mesh)에서 미션에 대해 태스크를 큐에 넣으면, 유휴 노드가 자율적으로 작업을 가져갑니다 — 한 노드에서 Claude Code, 다른 노드에서 Codex. 특정 머신에 태스크를 push하고 감시할 필요가 없습니다. 빠른 유휴 노드가 큐를 소진하고, 코디네이터는 폴링 대신 완료 이벤트를 감시합니다. 각 태스크는 pending → assigned → completed(또는 failed) 순으로 이동합니다.
7단계 — Refinery가 작업을 착지시키게 두기 (클라우드)
클라우드 전용
Refinery는 Repo Mesh 수렴의 일부로 실행됩니다.
병렬 에이전트를 스폰하는 것은 쉬운 부분입니다. 생산한 것을 머지하는 것이 어렵습니다 — 그리고 이것이 ADHDev가 존재하는 이유입니다.
격리된 워크트리 브랜치에서 태스크가 완료되면, Refinery는 그 브랜치를 force-push 없이 베이스로 수렴합니다. 일련의 게이트를 실행합니다: 레포의 수렴 설정을 로드하고, 워크트리를 부트스트랩하고, 레포 자체의 검증(타입체크/테스트/린트)을 실행하고, no-op 가드와 패치 동등성 검사를 적용하고, 서브모듈 커밋을 게시하고, 베이스로 fast-forward-only 머지를 수행하고, 워크트리를 정리합니다.
모든 접촉된 브랜치는 정확히 하나의 최종 상태로 착지하므로 어떤 것도 조용히 방치된 브랜치에 남겨지지 않습니다:
| 최종 상태 | 의미 |
|---|---|
merged_to_main | 수렴되어 깔끔하게 머지됨. |
pushed_feature_branch_needs_merge | 푸시됨, 당신이 할 머지 대기 중. |
blocked_review | 사람 검토 대기 중 — 예: 서브모듈 커밋이 아직 서브모듈의 origin에서 도달 불가능. |
cleanup_candidate | 작업이 착지됨. 워크트리 제거 가능. |
not_mergeable | Fast-forward 불가. Refinery가 거부하고 당신에게 요청함 — 충돌을 맹목적으로 해결하는 대신. |
📸 [스크린샷: merged_to_main으로 끝나는 Refinery 수렴 로그]
왜 중요한가: 이것이 "열 개의 에이전트가 실행됨"과 "열 개의 브랜치가 안전하게 착지됨"의 차이입니다. Refinery는 git 네이티브이며 의도적으로 보수적입니다 — 당신의 게이트에 대해 검증하고 fast-forward만 합니다. 깔끔하게 착지할 수 없는 것(실제 충돌, 도달 불가능한 서브모듈 커밋)은 자동 머지 대신 not_mergeable 또는 blocked_review로 돌아옵니다. 머지 데이 숙취 없이 병렬성을 얻습니다.
방금 한 것
ADHDev를 통해 실제 에이전트를 실행하고 전 과정을 제어했습니다:
- 원격 제어 + HITL — 대시보드에서 라이브 세션을 구동하고 모든 도구 호출을 승인했습니다 (클라우드 모드에서 휴대폰으로).
- 모든 에이전트 — 프로바이더 어댑터를 통해 CLI 에이전트를 실행했습니다. 동일한 흐름이 Codex, Gemini, CDP를 통한 IDE, ACP 에이전트에도 적용됩니다.
- 당신의 머신 — 에이전트가 당신의 하드웨어에서, 자체 인증으로, 당신의 대시보드 아래에서 실행되었습니다.
- Refinery — (클라우드) 메시에 노드를 등록하고 완료된 작업이 검증 게이트를 통해
main으로 수렴하는 방법을, 모든 브랜치에 대한 명확한 최종 상태와 함께 보았습니다.