AgentFlow
개요
AgentFlow는 기존의 Kanban 보드를 완전 자동화된 AI 개발 파이프라인으로 전환합니다. 커스텀 오케스트레이션 인프라를 구축하는 대신, 프로젝트 관리 도구(Asana, GitHub Projects, Linear)를 분산 상태 머신으로 활용합니다. 태스크는 단계를 거쳐 이동하고, AI 에이전트는 댓글을 통해 상태를 읽고 쓰며, 인간은 이미 사용 중인 동일한 UI를 통해 개입합니다.
결과적으로 핸드폰에서도 완전한 파이프라인 관찰이 가능하며, 무료 크래시 복구(상태가 메모리가 아닌 PM 도구에 저장됨), 그리고 카드를 드래그하기만 하면 언제든지 인간이 개입할 수 있습니다.
이 스킬을 사용해야 하는 경우
- 전체 개발 수명주기(빌드, 리뷰, 테스트, 통합)에 걸쳐 여러 Claude Code 워커를 조율해야 할 때
- AI가 생성한 코드에 대해 AI 리뷰 전에 결정론적 품질 게이트(tsc/eslint/tests)를 적용하고 싶을 때
- Kanban 보드나 핸드폰에서 파이프라인 전체를 관찰하고 싶을 때
- 비용 추적과 함께 자율적인 태스크 디스패치가 필요한 개인 또는 팀 프로젝트를 실행할 때
- 세션 재시작에도 살아남는 크래시 방지 오케스트레이션이 필요할 때
핵심 개념
7단계 Kanban 파이프라인
태스크는 Backlog, Research, Build, Review, Test, Integrate, Done 단계를 거쳐 흐릅니다. 각 단계에는 특정 게이트가 있습니다. Kanban 보드 자체가 오케스트레이션 계층입니다. 별도의 데이터베이스, 메시지 큐, 커스텀 인프라는 없습니다.
상태 없는 오케스트레이터
crontab 기반의 일회성 스윕이 15분마다 실행됩니다. 데몬이나 세션 종속성이 없습니다. 충돌이 발생해도 다음 스윕이 중단된 지점부터 계속됩니다. 모든 상태는 PM 도구에 저장되기 때문입니다.
결정론적 이후 확률론적
하드 게이트(tsc + eslint + tests)는 AI 리뷰 전에 먼저 실행되어 문제의 약 60%를 거의 비용 없이 잡아냅니다. AI 리뷰는 두 번째 계층으로 이후에 진행됩니다.
적대적 리뷰
서로 다른 AI 에이전트가 코드를 리뷰하고 통과를 결정하기 전에 반드시 3가지 문제점을 나열해야 합니다. 이는 형식적인 승인을 방지합니다.
전이적 우선순위 디스패치
가장 많은 다운스트림 작업을 차단 해제하는 태스크가 먼저 빌드되며, 임계 경로를 자동으로 계산합니다.
스킬 / 명령어
/spec-to-board
SPEC.md를 종속성이 매핑된 Kanban 보드의 원자적 태스크로 분해합니다.
/sdlc-orchestrate
전이적 우선순위와 충돌 탐지를 기반으로 워커에게 태스크를 디스패치합니다. crontab 스윕으로 실행됩니다.
/sdlc-worker --slot <N>
터미널 슬롯에서 워커를 실행하며, 태스크를 가져와 코드를 빌드하고 PR을 생성합니다. 3-4개의 워커를 병렬로 실행하세요.
/sdlc-health
각 태스크의 현재 단계, 할당된 에이전트, 재시도 횟수, 누적 비용을 보여주는 실시간 파이프라인 상태 대시보드입니다.
/sdlc-stop
정상 종료: 활성 워커는 현재 태스크를 마무리하고, 시작되지 않은 태스크는 Backlog로 돌아갑니다.
단계별 가이드
1. 스펙 작성
빌드할 내용을 설명하는 SPEC.md를 프로젝트에 생성하세요.
2. 태스크로 분해
claude -p "/spec-to-board"
이 명령은 SPEC.md를 읽고, 원자적 태스크로 분해하고, 종속성을 매핑하여 Kanban 보드에 생성합니다.
3. 워커 시작
3-4개의 터미널 창을 열고 각각을 워커 슬롯으로 사용하세요:
# 터미널 2 — 빌더
claude -p "/sdlc-worker --slot T2"
# 터미널 3 — 빌더
claude -p "/sdlc-worker --slot T3"
# 터미널 4 — 리뷰어
claude -p "/sdlc-worker --slot T4"
# 터미널 5 — 테스터
claude -p "/sdlc-worker --slot T5"
4. 오케스트레이터 시작
# crontab에 추가 (15분마다 실행)
crontab -e
# 추가: */15 * * * * ~/.claude/sdlc/agentflow-cron.sh >> /tmp/agentflow-orchestrate.log 2>&1
5. 모니터링 및 개입
핸드폰에서 Kanban 보드를 엽니다. 태스크가 파이프라인을 통해 흐르는 것을 지켜보세요. 개입이 필요하면 카드를 "Needs Human"으로 드래그하세요. 터미널 대시보드를 보려면 /sdlc-health를 실행하세요.
6. 파이프라인 중지
claude -p "/sdlc-stop"
품질 게이트
각 단계는 승격 전에 특정 게이트를 적용합니다:
- Build to Review:
tsc+eslint+npm test가 모두 통과해야 함 (결정론적) - Review to Test: 적대적 리뷰어가 통과 전에 3가지 문제점을 나열해야 함
- Test to Integrate: 새 파일의 80% 커버리지 임계값
- Integrate to Done: 병합 후 main에서 전체 테스트 스위트 실행; 실패 시 자동 되돌리기
비용 추적
단계별 상한선이 있는 태스크별 비용 추적 (Sonnet 기본값):
- Research: ~$0.10
- Build: ~$0.40
- Review: ~$0.10
- Test: ~$0.05
- Integrate: ~$0.03
자동 가드레일: $3/$8에서 경고, $10/$20 (Sonnet/Opus)에서 하드 스톱 및 인간 에스컬레이션.
안전 및 복구
- 자동 되돌리기: 통합 실패 시
git revert트리거 (새 커밋, 강제 푸시 금지) - 차단된 태스크: 2회 실패 후 인간 리뷰로 에스컬레이션
- 죽은 에이전트 감지: 5분마다 하트비트, 10분 타임아웃 후 재할당
- 정상 종료:
/sdlc-stop이 워커를 종료하고, 시작되지 않은 태스크를 백로그로 반환 - 스코프 크립 탐지: PR diff 파일을 예측된 파일 목록과 비교
- 스펙 드리프트 감지: SHA-256 해시 비교로 중간 스프린트 요구사항 변경 감지
설치
# 저장소 클론
git clone https://github.com/UrRhb/agentflow.git
# 스킬과 프롬프트를 Claude Code 설정에 복사
cp -r agentflow/skills/* ~/.claude/skills/
cp -r agentflow/prompts/* ~/.claude/sdlc/prompts/
cp agentflow/conventions.md ~/.claude/sdlc/conventions.md
또는 Claude Code 플러그인으로 설치:
/plugin marketplace add UrRhb/agentflow
/plugin install agentflow
모범 사례
- 권장:
/spec-to-board실행 전에 명확한 SPEC.md 작성 - 권장: 일반적인 프로젝트에서는 3-4개의 워커로 시작
- 권장: Kanban 보드에서 모니터링하고 필요 시 카드를 "Needs Human"으로 드래그
- 권장: 주기적으로 LEARNINGS.md 검토 — 일반적인 실패 패턴을 포착
- 금지: 결정론적 품질 게이트 건너뛰기 — 대부분의 문제를 저렴하게 잡아냄
- 금지: main에 강제 푸시 — AgentFlow는 안전을 위해
git revert사용 - 금지: 프로젝트의 병렬성 지원보다 더 많은 워커 실행
문제 해결
문제: 워커가 멈추거나 죽은 것처럼 보임
증상: 태스크 카드가 15분 이상 움직이지 않음, 새 댓글 없음
해결책: 오케스트레이터가 하트비트를 통해 죽은 에이전트를 감지하고 10분 후에 재할당합니다. 문제가 지속되면 /sdlc-health를 실행하여 상태를 확인하고 카드를 수동으로 Backlog로 드래그하세요.
문제: 비용 가드레일 트리거
증상: 태스크가 COST:CRITICAL 태그와 함께 "Needs Human"으로 이동됨 해결책: 태스크의 댓글 스레드에서 누적 컨텍스트를 검토하세요. 예산을 늘리거나, 태스크를 단순화하거나, 더 작은 조각으로 분할할지 결정하세요.
문제: 병합 후 통합 테스트 실패
증상: 태스크가 main에서 자동으로 되돌려짐 해결책: 자동 되돌리기는 main의 안정성을 유지합니다. 댓글에서 태스크의 재시도 컨텍스트를 확인하세요. 여기에는 시도한 내용과 실패한 내용이 포함됩니다. 다음에 할당되는 워커는 이 컨텍스트를 사용합니다.
관련 스킬
@brainstorming- AgentFlow 전에 SPEC.md 설계에 사용@writing-plans- 태스크 분해를 위한 스펙 작성 보완@test-driven-development- AgentFlow의 품질 게이트와 잘 작동@subagent-driven-development- 다중 에이전트 조정의 대안적 접근 방식
추가 자료
제한 사항
- 태스크가 위에서 설명한 범위와 명확히 일치하는 경우에만 이 스킬을 사용하세요.
- 출력물을 환경별 검증, 테스트 또는 전문가 리뷰의 대체물로 취급하지 마세요.
- 필수 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 중단하고 명확히 하세요.