aiagentflow/aiagentflow

소프트웨어 개발을 위한 멀티 에이전트 AI 워크플로우 (workflows)를 오케스트레이션하는 로컬 우선 (local-first) CLI입니다. 작업(task)을 부여하거나 사양서(specs), 제품 요구 사항 문서(PRDs), 가이드라인을 입력하면, 전문화된 에이전트(agents)들이 협력하여 설계, 코딩, 리뷰, 테스트 및 배포(ship)를 자동으로 수행합니다.

클라우드 의존성이 없습니다. 본인의 API 키를 사용하세요. 코드는 귀하의 머신에 그대로 유지됩니다.

작업 (Task) → 설계자 (Architect) → 코더 (Coder) → 리뷰어 (Reviewer) → 테스터 (Tester) → 수정자 (Fixer) → 배포 (Ship)

각 단계는 튜닝된 프롬프트 (prompts)와 파라미터 (parameters)를 가진 전문화된 AI 에이전트를 사용합니다. 이 루프는 품질 임계값 (quality thresholds)을 통과할 때까지 반복되며, 마치 귀하의 머신에서 실행되는 작은 AI 엔지니어링 팀처럼 작동합니다.

npm install -g @aiagentflow/cli

또는 pnpm을 사용하여:

pnpm add -g @aiagentflow/cli

# 1. 프로젝트에서 초기화
cd /path/to/your/project
aiagentflow init
...

init 마법사는 다음 과정을 안내합니다:

• 프로젝트 자동 감지 (언어, 프레임워크, 테스트 프레임워크, 패키지 매니저)
• LLM 제공업체 선택 (Anthropic, OpenAI, Groq, Gemini, OpenRouter, Ollama)
• API 키 입력
• 에이전트 역할별 모델 할당
• 워크플로우 모드 선택 (fast, balanced, strict)
• 자동 로딩을 위한 기존 문서 (사양서, 요구 사항, 가이드라인) 가져오기

설정은 .aiagentflow/config.json에 로컬로 저장됩니다.

멀티 에이전트 파이프라인 (Multi-agent pipeline)— 각각 고유한 역할을 가진 6개의 전문 에이전트
문맥 인식 (Context-aware)— 사양서, PRD (제품 요구 사항 문서), 아키텍처 문서 및 가이드라인을 모든 에이전트에 제공
문서 기반 계획 수립 (Plan from docs)— 기존 문서로부터 배치(batch) 처리가 가능한 작업 목록 생성
로컬 우선 (Local-first)— 완전히 로컬 머신에서 실행되며, 코드가 시스템 외부로 유출되지 않음
공급자 무관 (Provider-agnostic)— Anthropic, OpenAI, Groq, Google Gemini, OpenRouter (100개 이상의 모델), Ollama (로컬/무료) 지원
워크플로우 모드 (Workflow modes)— 반복(iteration), 승인 및 온도(temperature) 설정을 위한 fast, balanced, strict 프리셋 제공
스마트 탐지 (Smart detection)— 언어, 프레임워크, 테스트 러너(test runner) 및 패키지 매니저를 자동 탐지
설정 가능 (Configurable)— 에이전트별로 모델, 온도 및 반복 제한을 조정 가능
Git 네이티브 (Git-native)— 브랜치 자동 생성 및 QA 통과 시 자동 커밋(auto-commit)
인간 참여형 (Human-in-the-loop)— 모든 단계에서 승인 또는 재정의하거나, 완전 자동 모드로 실행 가능
QA 정책 (QA policies)— 구성 가능한 품질 게이트 (최대 심각한 이슈 수, 테스트 요구 사항 등)
배치 모드 (Batch mode)— 파일로부터 여러 작업을 처리
세션 지속성 (Session persistence)— 자동 세션 저장을 통한 충돌 복구
토큰 추적 (Token tracking)— 에이전트 및 실행별 LLM(대규모 언어 모델) 사용량 모니터링
커스텀 프롬프트 (Customizable prompts)— .aiagentflow/prompts/에서 에이전트 프롬프트 편집 가능

명령어	설명
aiagentflow init	대화형 설정 마법사
aiagentflow config	현재 설정 보기
aiagentflow doctor	상태 점검 — 공급자 및 설정 확인
aiagentflow run <task>	작업에 대한 워크플로우 실행
aiagentflow run <task> --auto	자율 모드 (승인 프롬프트 없음)
aiagentflow run <task> --dry-run	실행 없이 계획 미리보기
aiagentflow run <task> --context <files...>	참조 문서와 함께 실행
aiagentflow run --batch tasks.txt	파일로부터 여러 작업 처리
aiagentflow plan <docs...>	문서로부터 작업 목록 생성
aiagentflow plan <docs...> -o tasks.txt	작업 목록을 파일로 저장 (배치 준비 완료)
aiagentflow resume	마지막으로 중단된 세션 재개
aiagentflow sessions	저장된 모든 세션 목록 표시

에이전트 (Agent)	역할 (Role)	기능 (What it does)
🧠 Architect	계획 (Plan)	작업을 분석하고 구현 계획을 수립함
...
제공자 (Provider)	유형 (Type)	기본 모델 (Default Model)
---	---	---
Anthropic	Cloud API	claude-sonnet-4-20250514
OpenAI	Cloud API	gpt-4o-mini
Groq	Cloud API	llama-3.3-70b-versatile
Google Gemini	Cloud API	gemini-2.0-flash
OpenRouter	Cloud API	meta-llama/llama-3.1-8b-instruct:free
Ollama	Local	llama3.2:latest

제공자를 혼합하여 사용할 수 있습니다. 추론 에이전트(Architect, Reviewer, Judge)에는 클라우드 API (Cloud API)를 사용하고, 생성 에이전트(Coder, Tester, Fixer)에는 로컬 모델 (Local Model)을 사용하세요.

# Ollama 설치 및 시작
ollama serve
# 모델 가져오기 (Pull)
...

aiagentflow init 실행 후, 프로젝트에는 다음 항목들이 생성됩니다:

.aiagentflow/
├── config.json # 메인 설정 (Main configuration)
├── prompts/ # 사용자 정의 가능한 에이전트 프롬프트 (Customizable agent prompts)
...

프롬프트 파일을 편집하여 각 에이전트의 동작 방식을 사용자 정의할 수 있습니다. coding-standards.md를 편집하여 모든 에이전트가 따를 프로젝트 전용 규칙을 설정하세요. .md 또는 .txt 파일을 context/ 디렉토리에 넣으면 모든 에이전트의 참조 자료 (Reference material)로 자동 포함됩니다.

에이전트는 프로젝트의 요구 사항, API 계약 (API contracts), 그리고 표준을 이해할 때 가장 잘 작동합니다. 참조 문서를 제공하는 방법에는 세 가지가 있습니다:

1. 자동 로드 (권장) — 파일을 .aiagentflow/context/에 넣으세요:

cp docs/api-spec.md .aiagentflow/context/
cp docs/security-guidelines.md .aiagentflow/context/
aiagentflow run "Implement user registration"
...

2. 실행 시 --context 플래그 사용:

aiagentflow run "Add OAuth support" --context docs/oauth-spec.md docs/auth-arch.md

3. 초기화(init) 단계 중 — 설정 마법사(Setup wizard)가 기존 문서가 있는지 묻고 이를 자동으로 복사해 줍니다.

문서 유형 (Document type)	예시 (Example)	도움이 되는 이유 (Why it helps)
API 명세 (API specs)	api-spec.md	에이전트 (Agents)가 정확한 엔드포인트 (endpoints)와 계약 (contracts)을 생성함
요구사항 / PRD (Requirements / PRDs)	requirements.md	설계 계획 (Architect plans)이 실제 요구사항과 일치함
보안 가이드라인 (Security guidelines)	security.md	검토자 (Reviewer)가 정책 위반 사항을 포착함
아키텍처 문서 (Architecture docs)	architecture.md	코더 (Coder)가 사용자의 패턴과 컨벤션 (conventions)을 따름
개발 가이드라인 (Development guidelines)	dev-guidelines.md	모든 에이전트가 팀의 표준을 준수함

문서를 실행 가능한 작업 목록 (actionable task list)으로 변환한 다음, 일괄 실행 (batch-run) 하세요:

# PRD로부터 작업 생성
aiagentflow plan docs/prd.md -o tasks.txt
# 생성된 작업 검토
...

src/
├── cli/ # CLI 진입점 및 명령 (CLI entry point and commands)
├── core/ # 설정 시스템 (Config system), 워크플로우 엔진 (workflow engine), QA 정책 (QA policies)
...

# 클론 및 설치 (Clone and install)
git clone https://github.com/aiagentflow/aiagentflow.git
cd aiagentflow
...

기여 (Contributions)를 환영합니다! 시작하는 방법은 다음과 같습니다:

레포지토리 (repo)를 포크 (Fork)하고 자신의 포크를 클론 (clone)하세요.
기능을 위한 브랜치 (branch)를 생성하세요: git checkout -b feature/your-feature

코딩 표준 (coding standards)을 준수하세요:

• 함수 (Functions): camelCase

• 클래스 (Classes): PascalCase

• 파일 (Files): kebab-case

• 모든 공개 함수 (public functions)에는 JSDoc, 타입 (types), 그리고 에러 핸들링 (error handling)이 필요합니다.

• 커스텀 AppError 서브클래스 (subclasses)를 사용하세요 — 절대 가공되지 않은 throw new Error()를 사용하지 마세요.

• 함수 (Functions):
  작업 검토 (Check your work): pnpm typecheck && pnpm lint && pnpm test

main 브랜치에 무엇을 왜 했는지에 대한 설명과 함께 PR (Pull Request)을 오픈하세요.

• 의존성 방향 (Dependency direction)은 아래로 흐릅니다: cli → core → utils → types

• 설정 타입 (Config types)은 Zod 스키마 (schemas)로부터 추론되며, 수동으로 정의하지 마세요.

• 새로운 프로바이더 (providers)는 어댑터 (adapter) 파일 하나와 레지스트리 (registry) 항목만 필요합니다.

• 프로젝트 스캐폴딩 (Project scaffolding), 설정 시스템 (config system), LLM 프로바이더 레이어 (LLM provider layer)

• 워크플로우 엔진 (Workflow engine), 에이전트 구현 (agent implementations), Git 통합 (Git integration)

• QA 정책 (QA policies), 토큰 추적 (token tracking), 세션 지속성 (session persistence)

• 컨텍스트 문서 (Context documents) — 에이전트에 사양서 (specs), 제품 요구 사항 문서 (PRDs), 가이드라인을 제공

• Plan 커맨드 (Plan command) — 문서로부터 작업 목록 (task lists) 생성

• 다중 프로바이더 (Multiple providers) — Anthropic, OpenAI, Groq, Gemini, Ollama

• 프로젝트 자동 감지 (Project auto-detection) — 언어, 프레임워크, 테스트 러너 (test runner), 패키지 매니저 (package manager)

• QA 통과 시 자동 커밋 (Auto-commit on QA pass)

• 워크플로우 모드 프리셋 (Workflow mode presets) — fast, balanced, strict

• VSCode 확장 프로그램 (VSCode extension)

• 데스크톱 GUI (Desktop GUI)