aiag-cli

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


개요

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

$3

- 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 통합: 웹 플랫폼과 양방향 동기화

설치

``bash


npm

npm install -g aiag-cli

또는 npx로 직접 사용

npx aiag-cli init
`

$3

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

`bash


Claude Code CLI 설치 및 토큰 발급


npm install -g @anthropic-ai/claude-code-cli
claude login
`

빠른 시작

$3

`bash


프로젝트 디렉토리 생성

mkdir my-project && cd my-project
git init

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

aiag init

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

aiag prd

또는 기존 요구사항 문서에서 PRD 변환

aiag prd --from requirements.md
`

$3

`bash


PRD에서 feature_list.json 생성

aiag feature

상태 확인

aiag status
`

$3

`bash


기본 5개 기능 자동 구현

aiag auto

모든 기능 자동 구현 (무한 루프)

aiag auto --loop

상세 로그와 함께 실행

aiag auto --verbose

타임아웃 10분으로 설정

aiag auto --timeout 10
`

$3

`bash


진행 상황 확인

aiag status

웹페이지 열기 (macOS)

open index.html
`

명령어

$3

| 명령어 | 설명 |
| -------------------- | ------------------------------------- |
| 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 | 기능을 완료로 표시 |
| aiag commit | 자동 메시지로 변경사항 커밋 |
| aiag validate | Feature 목록 검증 + AI 자동 수정 |

$3

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

$3

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

$3

`bash
aiag init [options]

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

$3

`bash
aiag prd [options]

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

$3

`bash
aiag feature [options]

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

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


`

$3

`bash
aiag auto [count] [options]

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

디렉토리 구조

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

기능 형식

`json
{
"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 레퍼런스
- 워크플로우 가이드
- 실용 사용 가이드

변경 이력

$3

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

$3

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

$3

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

$3

- 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 재등록

$3

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

$3

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

$3

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

$3

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

$3

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

전체 변경 이력

Author

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

- Website: aiag.co.kr
- Email: help.aiag@gmail.com
- Maintainer: Yunchan Park

라이선스

MIT