aiag-cli

AI 에이전트 하네스 CLI - Claude Agent SDK 기반 장기 실행 에이전트 개발 도구

개요

aiag-cli는 Anthropic의 "Long-Running Agent" 아키텍처와 Claude Agent SDK를 사용하여 AI 에이전트 개발 세션을 관리하는 커맨드라인 도구입니다.

주요 기능

• Claude Agent SDK 기반 (v2.0.0+): 안정적인 SDK 직접 호출 방식
• prd-taskmaster 통합 (v2.3.0): PRD 생성 스킬 내장 및 자동 설치
• 자동 검증 + AI 수정 (v2.11.0): Feature 생성 시 정적 검증 및 testCommand 검증 자동 실행, AI가 문제 자동 수정
• 상태 외부화: AI 메모리가 아닌 파일에 진행 상황 추적
• 자동 구현 모드: aiag auto로 다중 기능 자동 구현
• 점진적 진행: 테스트와 함께 한 번에 하나의 기능
• 세션 관리: 명확한 시작/종료 시퀀스
• PRD → Feature 파이프라인: aiag prd → aiag feature → aiag auto
• aiag-adp 통합: 웹 플랫폼과 양방향 동기화

설치

# npm
npm install -g aiag-cli

# 또는 npx로 직접 사용
npx aiag-cli init

필수 요구사항

• Node.js >= 18.0.0
• Claude Code OAuth 토큰 (SDK 사용을 위해)

# Claude Code CLI 설치 및 토큰 발급
npm install -g @anthropic-ai/claude-code-cli
claude login

빠른 시작

1. 프로젝트 초기화 및 PRD 생성

# 프로젝트 디렉토리 생성
mkdir my-project && cd my-project
git init

# AIAG 초기화 (prd-taskmaster 스킬 자동 설치)
aiag init

# PRD 생성 (대화형 - 12+ 질문 답변)
aiag prd

# 또는 기존 요구사항 문서에서 PRD 변환
aiag prd --from requirements.md

2. Feature 목록 생성

# PRD에서 feature_list.json 생성
aiag feature

# 상태 확인
aiag status

3. 자동 구현 모드 실행

# 기본 5개 기능 자동 구현
aiag auto

# 모든 기능 자동 구현 (무한 루프)
aiag auto --loop

# 상세 로그와 함께 실행
aiag auto --verbose

# 타임아웃 10분으로 설정
aiag auto --timeout 10

4. 결과 확인

# 진행 상황 확인
aiag status

# 웹페이지 열기 (macOS)
open index.html

명령어

핵심 명령어

| 명령어 | 설명 | | -------------------- | ------------------------------------- | | aiag init | 현재 디렉토리에 AIAG 초기화 | | aiag prd | PRD 생성 (prd-taskmaster 스킬 사용) | | aiag feature | PRD에서 feature_list.json 생성 | | aiag status | 프로젝트 진행 상황 표시 | | aiag next | 다음 기능 추천 받기 | | aiag work [id] | 단일 기능 작업 시작 | | aiag auto [count] | 자동 연속 구현 모드 | | aiag test [id] | 기능 테스트 실행 | | aiag complete <id> | 기능을 완료로 표시 | | aiag commit | 자동 메시지로 변경사항 커밋 | | aiag validate | Feature 목록 검증 + AI 자동 수정 |

세션 명령어

| 명령어 | 설명 | | -------------------- | -------------- | | aiag session start | 코딩 세션 시작 | | aiag session end | 현재 세션 종료 |

웹 플랫폼 연동 (aiag-adp)

| 명령어 | 설명 | | -------------------- | ----------------------- | | aiag login | 웹 플랫폼 로그인 | | aiag logout | 로그아웃 | | aiag connect <url> | 프로젝트 연결 | | aiag sync | 기능 목록 양방향 동기화 |

init 옵션

aiag init [options]

옵션:
  -f, --force          기존 프로젝트 재초기화
  --minimal            최소 구조만 생성
  --skip-skills        스킬 설치 생략

prd 옵션

aiag prd [options]

옵션:
  --from <path>        기존 요구사항 문서를 Taskmaster PRD로 변환
  -o, --output <path>  PRD 출력 경로 (기본: .taskmaster/docs/prd.md)
  -t, --template       템플릿: minimal | comprehensive (기본: comprehensive)
  --skip-validation    13개 품질 검증 생략
  --dry-run            시뮬레이션 모드
  -v, --verbose        상세 로그 출력

feature 옵션

aiag feature [options]

옵션:
  --from <path>        PRD 파일 경로 지정
  --format <type>      PRD 포맷 강제 지정: taskmaster | generic
  -o, --output <path>  출력 경로
  --dry-run            시뮬레이션 모드
  -v, --verbose        상세 로그 출력

# 기본 동작: 정적 검증 + testCommand 검증 + AI 자동 수정이 항상 실행됩니다

auto 옵션

aiag auto [count] [options]

옵션:
  --loop                   무한 루프 모드 (Ctrl+C로 중단)
  --until <featureId>      특정 기능에서 중단
  --features <ids>         특정 Feature만 구현 (쉼표 구분, 예: F-001,F-002)
  -c, --category <cat>     카테고리 필터
  --dry-run                시뮬레이션 (변경 없음)
  --cooldown <seconds>     기능 간 대기 시간 (기본: 5)
  --max-attempts <n>       최대 재시도 횟수 (기본: 3)
  -v, --verbose            상세 로그 출력
  --timeout <minutes>      타임아웃 (기본: 30분)

디렉토리 구조

.aiag/
├── feature_list.json    # 상태가 포함된 모든 기능
├── progress.md          # 세션 로그 (추가 전용)
├── init.sh              # 환경 설정 스크립트
├── session_context.md   # 현재 세션 정보
└── templates/           # 에이전트 프롬프트 템플릿
    ├── initializer.md
    └── coding.md

기능 형식

{
  "id": "FEAT-001",
  "category": "core",
  "priority": "critical",
  "description": "기능 설명",
  "acceptanceCriteria": ["기준 1", "기준 2"],
  "testCommand": "npm test",
  "passes": false,
  "lastTestedAt": null,
  "implementedBy": null,
  "dependsOn": []
}

카테고리

| 카테고리 | 설명 | | -------- | ----------------- | | core | 핵심 인프라 | | cli | CLI 명령어 | | api | API 엔드포인트 | | ui | 사용자 인터페이스 | | test | 테스트 인프라 | | data | 데이터 처리 | | docs | 문서화 | | devops | 빌드/배포 |

우선순위

1. critical - 다른 기능의 선행 조건
2. high - 핵심 사용자 가치
3. medium - 중요하지만 연기 가능
4. low - 있으면 좋은 것

핵심 원칙

Anthropic의 Long-Running Agent 아키텍처 기반:

1. 하나의 기능 규칙 - 한 번에 하나의 기능만 작업
2. 완료 전 테스트 - passes: true 표시 전 항상 테스트
3. 클린 상태 - 코드를 절대 깨진 상태로 두지 않음
4. 진행 상황 문서화 - 매 세션마다 progress.md 업데이트

문서

• 빠른 시작 가이드
• CLI 레퍼런스
• 워크플로우 가이드
• 실용 사용 가이드

변경 이력

v2.18.0 (2026-01-07)

• aiag test --fix 옵션: 실패한 테스트 자동 수정 워크플로우
  • testCommand 재생성: v2.17.0의 개선된 패턴 규칙으로 재생성
  • 테스트 실행 후 성공 시 passes: true 자동 업데이트
  • 사용법: aiag test --fix, aiag test --failed --fix

v2.17.0 (2026-01-07)

• testCommand 자동 생성 개선: acceptanceCriteria 기반 10가지 패턴 규칙
  • 한글/영어 패턴 모두 지원
  • 파일 존재, API 라우트, HTTP 핸들러, 컴포넌트 등 자동 검증

v2.14.0 (2026-01-03)

• 프로젝트 추가 문서 자동 통합: aiag feature 실행 시 프로젝트의 추가 문서를 자동 검색하여 CLAUDE.md에 포함
  • 검색 대상: ARCHITECTURE.md, CODING_RULES.md, DESIGN_TOKENS.md, SOURCE_TREE.md
  • 검색 위치: 프로젝트 루트, docs/, .docs/
  • 각 문서는 CLAUDE.md의 적절한 섹션에 자동 통합

v2.13.0 (2026-01-03)

• GitHub 중심 동기화: GitHub를 Single Source of Truth로 사용
• aiag sync 단순화: --status, --reset, --watch 3개 옵션으로 정리
  • 자동 동기화: Git 상태 감지 후 자동 pull/push
  • --reset: GitHub 상태로 로컬 강제 초기화
• GitHub Webhook 자동 등록: aiag connect 시 push 이벤트 Webhook 자동 설정
• aiag connect --update: 연결 정보 업데이트 및 Webhook 재등록

v2.12.0 (2026-01-02)

• aiag auto --features 옵션: 특정 Feature만 자동 구현 (쉼표 구분)
• aiag test --all 개선: 완료된 Feature도 포함하여 전체 테스트

v2.11.0 (2025-12-30)

• 자동 검증 + AI 수정: aiag feature와 aiag validate 실행 시 자동 검증 및 수정
  • 정적 검증: ID 형식, 필수 필드, 카테고리, 우선순위, 의존성 검사
  • testCommand 검증: bash 문법, 나쁜 패턴 감지 (로컬 bash -n 사용)
  • AI 자동 수정: Claude Agent가 문제를 자동으로 수정
• Breaking Change: --validate 옵션 제거 (이제 기본 동작으로 항상 실행)
• 새 템플릿 추가: validation-agent.md, testcommand-fix-agent.md

v2.3.0 (2024-12-25)

• 신규 명령어: aiag prd - PRD 생성 (prd-taskmaster 스킬 통합)
• 신규 명령어: aiag feature - PRD에서 feature_list.json 생성
• prd-taskmaster 스킬 번들링: aiag init 시 자동 설치
• PRD 변환 기능: aiag prd --from <path> 옵션 추가
• Breaking Change: aiag init --from-prd 옵션 제거 (→ aiag feature 사용)

v2.0.0 (2024-12-22)

• Breaking Change: Claude Agent SDK로 완전 전환
• --use-sdk 옵션 제거 (SDK가 기본값)
• 안정성 및 타임아웃 관리 개선
• 보안 훅 (Bash 명령어 검증) 추가
• 비용 추적 기능 추가

v1.9.0

• aiag-adp 웹 플랫폼 연동
• login, logout, connect, sync 명령어 추가
• SSE 실시간 스트리밍 지원

전체 변경 이력

Author

주식회사 기반 (Giban Co., Ltd.)

• Website: aiag.co.kr
• Email: [email protected]
• Maintainer: Yunchan Park

라이선스

MIT