microsoft/waza

AI 에이전트 (AI agent) 기술을 평가하기 위한 Go CLI — 평가 스위트 (eval suites) 스캐폴딩, 벤치마크 (benchmarks) 실행, 그리고 모델 간 결과 비교.

설치 스크립트를 사용하여 최신 사전 빌드된 바이너리 (pre-built binary)를 다운로드하고 설치하세요:

curl -fsSL https://raw.githubusercontent.com/microsoft/waza/main/install.sh | bash

이 스크립트는 OS 및 아키텍처 (linux/darwin/windows, amd64/arm64)를 자동으로 감지하여, 바이너리를 다운로드하고, 체크섬 (checksum)을 검증하며, /usr/local/bin (쓰기 권한이 없는 경우 ~/bin)에 설치합니다.

또는 최신 릴리스 (release)에서 바이너리를 직접 다운로드할 수 있습니다.

Go 1.26+ 버전이 필요합니다:

참고: LFS 아티팩트 (LFS artifacts) 사용으로 인해 go install을 사용하여 waza를 설치할 수 없습니다. 일반적인 릴리스 외의 방식으로 waza를 설치하려면 저장소 (repository)를 클론 (clone)해야 합니다:

git clone https://github.com/microsoft/waza.git
cd waza
# git LFS 기반 아티팩트가 사용 가능한지 확인 (내장된 copilot 바이너리용)
...

Waza는 azd 확장 기능 (extension)으로도 사용할 수 있습니다:

# waza 확장 기능 레지스트리 (extension registry) 추가
azd ext source add -n waza -t url -l https://raw.githubusercontent.com/microsoft/waza/main/registry.json
# 확장 기능 설치
...

설치가 완료되면 모든 waza 명령어를 azd waza 아래에서 사용할 수 있습니다. 예시:

azd waza init my-eval --interactive
azd waza run examples/code-explainer/eval.yaml -v

Waza는 백그라운드에서 자동으로 새 버전을 확인합니다. 업데이트가 가능한 경우, 명령어 출력 후 알림이 나타납니다:

A newer version of waza is available: v0.24.0 → v0.28.0. Run: curl -fsSL ... | bash

이 확인 작업은 비차단 방식 (non-blocking, 명령어를 느리게 만들지 않음)이며, 24시간 동안 캐시 (cached)되고, --no-update-check 또는 WAZA_NO_UPDATE_CHECK=1로 비활성화할 수 있습니다.

전체 과정을 확인하려면 Getting Started Guide를 참조하세요:

# 새 프로젝트 초기화
waza init my-project && cd my-project
# 새 기술 (skill) 생성
...

# 빌드 (Build)
make build
# 프로젝트 워크스페이스 (workspace) 초기화
...

skills/ 및 evals/ 디렉토리가 분리된 waza 프로젝트 워크스페이스를 초기화합니다. 멱등성 (Idempotent)을 보장하며 — 누락된 파일만 생성합니다.

플래그 (Flag)	설명 (Description)
`--no-skill`	첫 번째 스킬 (first-skill) 생성 프롬프트를 건너뜁니다.

생성 항목:

skills/

— 스킬 정의 (Skill definitions) 디렉토리
evals/

— 평가 스위트 (Evaluation suites) 디렉토리
.github/workflows/eval.yml

— PR에서 평가를 실행하기 위한 CI/CD 파이프라인
.gitignore

— Waza 전용 제외 항목
README.md

— 프로젝트 시작 가이드

예시 (Example):

waza init my-project
# 선택적으로 첫 번째 스킬을 대화형으로 생성합니다
waza init my-project --no-skill
...

스캐폴딩 (Scaffolded) 구조와 평가 스위트 (evaluation suite)를 갖춘 새로운 스킬을 생성합니다. 워크스페이스 컨텍스트를 감지하여 출력을 조정합니다.

플래그 (Flag)	단축형 (Short)	설명 (Description)
`--template`	`-t`	템플릿 팩 (Template pack) (출시 예정)

모드 (Modes):

프로젝트 모드 (Project mode) (skills/ 디렉토리를 감지함):

project/
├── skills/{skill-name}/SKILL.md
└── evals/{skill-name}/
...

단독 모드 (Standalone mode) (skills/가 감지되지 않음):

{skill-name}/
├── SKILL.md
├── evals/
...

예시 (Example):

# 프로젝트 모드에서 (위의 Modes 섹션 설명 참조): skills/code-explainer/SKILL.md + evals/code-explainer/ 생성
waza new skill code-explainer
# 단독 모드에서 (위의 Modes 섹션 설명 참조): code-explainer/ 독립형 디렉토리 생성
...

기존의 SKILL.md로부터 평가 스위트 (eval suite)를 스캐폴딩 (Scaffold) 합니다 (USE FOR 및 DO NOT USE FOR의 프론트매터 (frontmatter) 트리거 힌트를 읽음).

생성 항목:

evals/<skill-name>/eval.yaml

evals/<skill-name>/tasks/positive-trigger-1.yaml

evals/<skill-name>/tasks/positive-trigger-2.yaml

evals/<skill-name>/tasks/negative-trigger-1.yaml

플래그 (Flag)	설명 (Description)
`--output <path>`	`eval.yaml`을 위한 사용자 정의 경로 (태스크들은 형제 디렉토리인 `tasks/` 아래에 생성됨)

예시 (Example):

# 기본 출력 위치
waza new eval code-explainer
# 사용자 정의 평가 경로
...

Copilot을 통해 프롬프트를 실행하고, 관찰된 동작(응답 텍스트, 도구 사용, 호출된 스킬)을 기반으로 추론된 검증기 (validators)를 포함하는 태스크 YAML을 생성합니다.

플래그 (Flag)	설명
`--model <name>`	기록을 위해 실행할 Copilot 모델 (`claude-sonnet-4.5`가 기본값)
`--testname <name>`	생성된 태스크에 기록될 테스트 이름 및 ID (`auto-generated-test`가 기본값)
`--tags <a,b,...>`	생성된 태스크에 첨부할 쉼표로 구분된 태그
`--timeout <duration>`	프롬프트 실행 최대 시간 (`5m`이 기본값)
`--overwrite`	출력 태스크 파일이 이미 존재하는 경우 덮어쓰기
`--root <dir>`	스킬 발견 (skill discovery)에 사용되는 루트 디렉토리 (`.`이 기본값)

예시 (Example):

# 프롬프트를 기록하고 재사용 가능한 태스크 YAML 생성
waza new task from-prompt "Refactor this function for readability" evals/code-explainer/tasks/refactor-readability.yaml
# 메타데이터를 추가하고 기존 파일 덮어쓰기
...

스펙 (spec) 파일로부터 평가 벤치마크 (evaluation benchmark)를 실행합니다.

플래그 (Flag)	단축형 (Short)	설명
`--context-dir <dir>`		피스처 (Fixture) 디렉토리 (스펙 기준 `./fixtures`가 기본값)
`--output <file>`	`-o`	결과를 JSON으로 저장
`--output-dir <dir>`		구조화된 출력을 위한 디렉토리. 각 실행은 `<dir>` 내에 UTC 타임스탬프가 붙은 하위 디렉토리를 생성합니다. `--output`과 상호 배타적입니다.

결과 캐싱 (Result Caching)

--cache를 사용하여 캐싱을 활성화하면 테스트 결과를 저장하고 반복 실행 시 재실행을 건너뛸 수 있습니다:

# 첫 번째 실행은 모든 테스트를 수행하고 결과를 캐싱합니다
waza run eval.yaml --cache
# 두 번째 실행은 캐싱된 결과를 사용합니다 (훨씬 빠름)
...

캐싱된 결과는 다음의 경우 자동으로 무효화됩니다:

스펙 (Spec) 설정이 변경된 경우 (모델, 타임아웃, 채점자 등)
태스크 (Task) 정의가 변경된 경우
픽스처 (Fixture) 파일이 변경된 경우

참고: 비결정론적 채점자 (behavior, prompt)를 사용하는 평가의 경우 캐싱이 자동으로 비활성화됩니다.

종료 코드 (Exit Codes)

run 명령은 CI/CD 통합을 위해 종료 코드를 사용합니다:

종료 코드	조건	설명
`0`	성공	모든 테스트 통과
`1`	테스트 실패	하나 이상의 테스트가 검증에 실패함
`2`	설정 오류	잘못된 스펙, 파일 누락 또는 런타임 오류

CI 사용 예시:

# 테스트가 하나라도 실패하면 빌드를 실패 처리합니다
waza run eval.yaml || exit $?
# 특정 종료 코드를 캡처합니다
...

참고: waza generate는 waza new의 별칭 (alias)입니다. 두 명령 모두 사용자 정의 출력 위치를 지정하기 위한 --output-dir 플래그와 함께 동일한 기능을 지원합니다.

여러 평가 실행(evaluation runs)의 결과를 나란히 비교합니다 — 작업별 점수 차이(deltas), 통과율(pass rate) 차이 및 집계 통계(aggregate statistics)를 제공합니다.

플래그 (Flag)	단축형 (Short)	설명
`--format <fmt>`	`-f`	출력 형식: `table` 또는 `json` (기본값: `table` )

어떤 기술(skills)이 완전히 커버되었는지, 부분적으로 커버되었는지, 또는 평가(evals)가 누락되었는지를 보여주는 기술-평가 커버리지 그리드(skill-to-eval coverage grid)를 생성합니다.

참고: 완전한 커버리지(Full coverage)를 위해서는 작업(tasks) (tasks: 또는 tasks_from: 사용)과 2개 이상의 채점자(grader) 유형이 필요합니다. 커버리지 백분율은 완전히 커버된 기술만을 반영합니다.

플래그 (Flag)	단축형 (Short)	설명
`--format <fmt>`	`-f`	출력 형식: `text`, `markdown` 또는 `json` (기본값: `text` )
`--path <dir>`		기술/평가를 스캔할 추가 디렉토리 (중복 사용 가능)

Copilot SDK를 통해 평가 가능한 모델 목록을 나열합니다. waza run, waza quality 및 기타 명령의 --model 플래그와 함께 사용할 수 있는 모델 ID 및 메타데이터를 보여줍니다.

copilot login을 통한 인증이 필요합니다.

플래그 (Flag)	설명
`--json`	JSON으로 출력

예시:

# 테이블 형식으로 사용 가능한 모델 목록 표시
waza models
# 사용 가능한 모델을 JSON으로 출력
...

모든 캐시된 평가 결과(cached evaluation results)를 삭제하여 다음 실행 시 재실행을 강제합니다.

플래그 (Flag)	설명
`--cache-dir <dir>`	삭제할 캐시 디렉토리 (기본값: `.waza-cache` )

SKILL.md 파일 내의 기술 프런트매터(skill frontmatter)를 반복적으로 점수화하고 개선합니다.

비대화형(non-interactive) 단일 패스(single-pass) 마크다운 보고서를 위해 --copilot을 사용하며, 이 보고서는 다음을 수행합니다:

현재 기술 상세 정보 및 토큰 사용량 요약
trigger_tests.yaml이 존재하는 경우 트리거 테스트 프롬프트를 예시로 로드
기술 선택 개선을 위한 Copilot 제안 요청
어떠한 변경 사항도 적용하지 않고 보고서를 stdout에 출력

--copilot이 설정되면, 반복 모드 플래그(--target, --max-iterations, --auto)는 사용할 수 없습니다.

플래그 (Flag)	설명
`--target <level>`	반복 모드 (iterative mode)를 위한 목표 준수 수준: `low`, `medium`, `medium-high`, `high` (기본값: `medium-high`)
`--max-iterations <n>`	반복 모드를 위한 최대 개선 반복 횟수 (기본값: 5)
`--auto`	반복 모드에서 프롬프트 없이 개선 사항 적용
`--copilot`	Copilot 제안이 포함된 비대화형 마크다운 (markdown) 보고서 생성
`--model <id>`	`--copilot`과 함께 사용할 모델

포괄적인 준비 상태 보고서를 통해 스킬 (skill)이 제출 가능한 상태인지 확인합니다.

다음 다섯 가지 유형의 검사를 수행합니다:

준수 점수 (Compliance scoring)— 프론트매터 (frontmatter) 준수 여부 검증 (Low/Medium/Medium-High/High)
토큰 예산 (Token budget)— SKILL.md가 토큰 제한 내에 있는지 확인 (.waza.yaml의 tokens.limits에서 설정 가능)
평가 스위트 (Evaluation suite)— eval.yaml의 존재 여부 확인
사양 준수 (Spec compliance)— agentskills.io 사양에 따라 스킬 검증 (프론트매터 구조, 필수 필드, 명명 규칙, 디렉토리 일치, 설명 길이, 호환성, 라이선스 및 버전)
권고 검사 (Advisory checks)— 품질 및 유지보수성 문제 감지 (참조 모듈 수, 복잡도 분류, 부정적 델타 위험 패턴, 절차적 콘텐츠 및 과도한 구체성)

스킬을 개선하기 위한 평이한 언어의 요약과 실행 가능한 다음 단계(actionable next steps)를 제공합니다.

출력 예시:

🔍 Skill Readiness Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill: code-explainer
...

사용법:

# 현재 디렉토리 확인
waza check
# 특정 스킬 확인
...

LLM-as-Judge를 사용하여 명확성 (clarity), 완전성 (completeness), 트리거 정밀도 (trigger precision), 범위 커버리지 (scope coverage), 안티 패턴 (anti-patterns)의 다섯 가지 차원에서 스킬 콘텐츠 품질을 평가합니다.

플래그 (Flag)	설명
`--model <model>`	심판(judge)으로 사용할 모델 (기본값: 프로젝트 기본 모델)
`--format table	json`
`--rubric <path>`	사용자 정의 루브릭 (rubric) 파일 경로 (향후 사용을 위해 예약됨)

예시:

# 기술 품질 평가 (표 출력)
waza quality skills/code-explainer
# CI 통합을 위한 JSON 출력
...

LLM을 사용하여 SKILL.md를 분석하고

제안된 평가 아티팩트 (artifacts)를 생성합니다.

microsoft/waza

요약

핵심 포인트

댓글