Artifactize
Evaluation-driven development for people and AI agents.
artifactize는 여러분과 팀원이 프로젝트의 각 부분을 리뷰하되, 바뀌지 않은 작업은 다시 검사하지 않도록 도와줍니다. Artifact는 리뷰할 수 있는 작업 단위입니다. 파일이나 폴더뿐 아니라, 구성 요소 사이의 연결로 이루어진 Artifact Graph도 Artifact로 선언할 수 있습니다. eval은 Artifact에 대한 검사입니다. eval에는 Runtime 명령 실행, Agent 리뷰, Human 승인 중 한 가지 방식을 지정합니다.
- 각자 맡은 부분을 편한 방식으로 작업하세요. 각 eval이 입력으로 사용하는 Artifact를 선언해 두면, 입력이 바뀔 때 영향을 받는 리뷰만 다시 실행됩니다.
- 입력이 바뀌지 않았다면 이전 리뷰 결과를 재사용하세요. fingerprint가 그 입력을 식별하며,
artifactize status는 무엇을 다시 리뷰해야 하는지 보여 줍니다. - 팀 리뷰 저장소를 통해 팀원과 CI에 결과를 공유하세요. Monitor에서 진행 상황을 확인하고, Review에서 승인 대기 중인 요청을 차례로 처리할 수 있습니다.
Linux, macOS, Windows에서 실행됩니다. 설치부터 시작한 뒤 가이드를 따라 첫 GREEN 결과를 얻고, 모델이나 API 키 없이 그 결과를 재사용해 보세요.
다음으로 볼 곳
- 기능: Artifact와 eval을 선언하고, 무엇을 재사용할지 정하고, 검증을 실행하고 진행 상황을 확인하며, 리뷰어가 사용할 도구를 제공하고, 팀과 결과를 공유합니다. CLI, 데스크톱 앱, 에이전트 플러그인에서 똑같이 동작합니다.
- 데스크톱: 창에서 Run을 살펴보고 Human 리뷰를 처리합니다.
- 에이전트 플러그인: 여러 코딩 어시스턴트에서 쓸 수 있는 Arti 스킬을 추가하고 MCP로 코딩 호스트를 연결합니다.
- CLI: 명령 문법, 출력, 종료 코드.
- TUI: 터미널에서 쓰는 Monitor와 Review.
- 소스: Apache 2.0으로 공개된 오픈 소스.
artifactize 설치
Artifactize는 Linux(x86_64 또는 aarch64), macOS(Apple 실리콘 또는 Intel), Windows(x64)에서
실행되며, WSL 2에서는 Linux 빌드가 실행됩니다. 한 가지 방법으로 설치한 다음 새 터미널을 열고
artifactize --version을 실행하세요. artifactize 0.15.0처럼 설치된 버전이 출력됩니다.
Artifactize는 Apache License 2.0으로
공개된 오픈 소스입니다.
앱 내려받기
사용하는 운영체제에 맞는 앱을 내려받으세요. 앱에 artifactize 명령이 함께 들어 있으므로
Rust 빌드 도구는 필요 없습니다.
- macOS: Artifactize.dmg. 디스크 이미지 하나로 Apple 실리콘 Mac과 Intel Mac에 모두 설치할 수 있습니다. Artifactize를 응용 프로그램 폴더로 끌어다 놓고 한 번 열면 터미널에서 artifactize 명령을 쓸 수 있습니다.
- Windows: Microsoft Store의 Artifactize (x64). 설치한 뒤 새 터미널을 여세요.
- Linux: x86_64 Ubuntu 22.04, Debian 12 이상용
Artifactize-amd64.deb.
소프트웨어 설치 프로그램으로 열거나
sudo apt install ./Artifactize-amd64.deb를 실행하세요.
명령줄에서 설치
Linux (x86_64와 aarch64, WSL 2 포함). x86_64에서는 데스크톱 앱도 함께 설치됩니다.
curl -fsSL https://artifactize.dev/install.sh | sh
macOS, Homebrew 사용. 명령과 함께 데스크톱 앱도 설치하려면 --cask를 붙이세요.
brew install lhj6102/tap/artifactize
Windows, Microsoft Store에서 설치:
winget install 9PB6W4LL165D --source msstore
다른 설치 방법에서 이 방법들을 자세히 설명하고, PowerShell 설치 스크립트, AppImage, Cargo, 소스에서 빌드하는 방법도 다룹니다.
플러그인으로 빠르게 시작하기
Arti와 대화하며 시작해 보세요. Arti는 코딩 어시스턴트에서 현재 작업 중인 프로젝트를 예로 들어 Artifactize 사용법을 설명하고, 기존 테스트와 리뷰를 옮기거나 새 프로젝트를 준비하도록 돕습니다. 플러그인 하나만 설치하면 Claude Code와 Codex에서 Hey Arti의 안내를 받으며 Artifactize 도구를 쓸 수 있습니다.
/plugin marketplace add lhj6102/artifactize # Claude Code, 세션 안에서
/plugin install artifactize@artifactize
codex plugin marketplace add lhj6102/artifactize # Codex, 터미널에서
codex plugin add artifactize@artifactize
코딩 에이전트에게 이렇게 말을 걸어 보세요(Codex에서는 $artifactize:hey-arti로
쓰세요).
/artifactize:hey-arti Artifactize에 대해 설명해 주고 이 프로젝트에 어떻게 적용하면 좋을지 이야기해 줘
/artifactize:hey-arti 지금 있는 테스트와 리뷰를 Artifactize로 옮기도록 도와줘
/artifactize:hey-arti 이 프로젝트를 Artifactize로 처음부터 시작하도록 도와줘
다음 단계
- 가이드: 모델 없이 예제 프로젝트를 실행해 보는 5분짜리 실습입니다.
- 백엔드와 로그인: Agent eval을 모델 서비스에 연결합니다.
- 업데이트와 제거: 업데이트, 업그레이드 안내, 상태가 저장되는 곳, 제거 방법을 다룹니다.
다른 설치 방법
OS별 기본 설치 방법은 설치에 있습니다. 이 페이지에서는 각 설치 방법의 세부 절차와
대안을 설명합니다. 한 가지 방법으로만 설치하세요. 어떤 방법으로 설치하든 artifactize가
설치되며, 그 내장 도구는
artifactize tools로 쓸 수 있습니다. Store 이외의 방법으로 설치하면 이 도구가
artifactize-tools 명령으로도 함께 설치됩니다. 사용 중인 시스템에 맞는 설치 파일이 릴리스에
아직 없다면 Cargo로 설치하거나
소스에서 빌드하세요.
| OS | 기본: 앱 | 명령줄 | 기타 |
|---|---|---|---|
| macOS | 디스크 이미지 | Homebrew 또는 설치 스크립트 | Cargo, 소스에서 빌드 |
| Windows | Microsoft Store | winget 또는 PowerShell 설치 스크립트 | Cargo, 소스에서 빌드 |
| Linux | .deb (x86_64) | 설치 스크립트 | AppImage, Cargo 바이너리, 소스에서 빌드 |
앱
앱에는 artifactize 명령이 함께 들어 있습니다. 설치 스크립트와 Homebrew
cask도 앱을 함께 설치합니다. Homebrew formula, Cargo, 소스 빌드는
명령만 설치합니다.
macOS. 앱을 한 번 연 뒤에도 명령을 찾을 수 없다면 관리자 권한 요청을 승인하세요. 그러면
새 터미널에서 artifactize를 쓸 수 있습니다(자세히). Apple의 공증을 받은
디스크 이미지 하나로 macOS 11 이상의 Apple 실리콘 Mac과 Intel Mac을 모두 지원합니다.
Windows. Microsoft가 Store 패키지에 서명하므로 스마트 앱 컨트롤이 실행을 허용하고, Store가 패키지를 최신 상태로 유지합니다. 시작 메뉴에서 Artifactize를 선택하면 데스크톱 앱이 열립니다. Store 버전의 시작 메뉴 항목과 Store 버전만 따로 쓰는 상태 저장 위치는 Windows에서 다르게 동작하는 부분과 함께 설명합니다.
Linux. .deb는 세 명령을 모두 /usr/bin에 설치하며, apt가 함께 설치하는
WebKitGTK 4.1과 GTK 3가 필요합니다. aarch64나 다른 배포판에서는 설치 스크립트를 쓰세요.
명령줄
Linux
curl -fsSL https://artifactize.dev/install.sh | sh
artifactize --version
이 스크립트는 OS와 CPU에 맞는 최신 안정 릴리스를
~/.local/bin에 설치합니다. 내려받은 파일의 체크섬이 일치하지 않거나 바이너리를 실행할 수 없으면 스크립트는 기존 파일을 교체하지 않고 종료하므로, 이미 설치한 프로그램은 계속 사용할 수 있습니다. curl이나 wget을 쓰며, sudo를 쓰지 않고
셸 시작 파일도 고치지 않습니다. ~/.local/bin이 PATH에 없다면
추가할 줄을 출력합니다. 대신 실행될 수 있는 다른 artifactize나 artifactize-tools가
PATH에 있으면 경고도 합니다. 대부분의 x86_64 Linux 배포판(Ubuntu, Debian, Fedora 등)에서는 같은
릴리스의 데스크톱 앱도 같은 방식으로 확인해
~/.local/share/artifactize/desktop에 설치하고, artifactize 명령과 같은 디렉터리에 artifactize-desktop 실행 파일을
추가하며, 애플리케이션 메뉴에 Artifactize 항목을 만듭니다. ARM Linux와 Alpine에서는 명령만 설치합니다. 두
환경 변수로 동작을 바꿀 수 있습니다.
사전 릴리스는 ARTIFACTIZE_VERSION으로 그 버전을 지정했을 때만 설치됩니다.
curl -fsSL https://artifactize.dev/install.sh | ARTIFACTIZE_VERSION=0.5.2 sh # this release
curl -fsSL https://artifactize.dev/install.sh | ARTIFACTIZE_INSTALL_DIR="$HOME/bin" sh # this directory
macOS
Homebrew는 macOS 패키지 관리자로, 명령줄 도구를
대신 설치하고 업데이트해 줍니다. 터미널에서 brew를 쓸 수 없다면 먼저
Homebrew 설치 안내를 따르세요. 그다음 아래 명령을 실행하세요.
brew install lhj6102/tap/artifactize
artifactize --version
이 명령을 실행하면 프로젝트의 Homebrew 패키지 저장소(tap)인 lhj6102/tap에서 Mac의 CPU에 맞는 두 명령이
설치되며, 이후에는 안정 릴리스로만 업데이트됩니다. Homebrew는 이런 명령줄 패키지를 formula, 앱 패키지를
cask라고 부릅니다. 데스크톱 앱은 같은 tap의 cask로 제공됩니다. cask는
앱에 들어 있는 artifactize와 artifactize-tools를 Homebrew의 PATH에 연결하므로, 이 명령 하나로 앱과 두 CLI 명령을 모두 설치할 수 있습니다. cask가 formula를 대신하므로, formula가 설치되어 있다면 먼저 제거하세요.
brew install --cask lhj6102/tap/artifactize
macOS에서도 설치 스크립트는 Linux와 같은 확인 과정을 거치고 같은 환경
변수를 씁니다. 명령은 ~/.local/bin에 설치되는데, 새 Mac에서는 이 디렉터리가
PATH에 없습니다. 스크립트가 ~/.zshrc 같은 셸 시작 파일에 추가할 줄을
출력합니다. 데스크톱 앱도 ~/Applications/Artifactize.app으로 설치합니다.
curl -fsSL https://artifactize.dev/install.sh | sh
Windows
터미널에서 Microsoft Store로 설치(기본). 같은 Store 패키지를 winget으로 설치합니다.
winget install 9PB6W4LL165D --source msstore
artifactize --version # in a new terminal
PowerShell 설치 스크립트. Windows PowerShell 5.1 또는 PowerShell 7에서 관리자 권한 없이 실행합니다.
irm https://artifactize.dev/install.ps1 | iex
artifactize --version # in a new terminal
이 스크립트는 zip의 SHA-256을 확인하고 새
바이너리 두 개를 실행해 본 다음, artifactize.exe, artifactize-tools.exe, 데스크톱
앱의 artifactize-desktop.exe를 %LOCALAPPDATA%\Programs\artifactize에 설치합니다. 그리고 그
디렉터리를 사용자 Path에 추가하고 앱의 Artifactize 시작 메뉴 바로 가기를 추가합니다.
설치 후에는 새 터미널을 여세요. 쓸 수 있는 환경 변수는 install.sh와 같습니다.
스마트 앱 컨트롤. 설치 스크립트가 쓰는 릴리스 zip은 코드 서명이 되어 있지 않습니다.
스마트 앱 컨트롤이 켜진 머신에서는 이전 릴리스가 실행되었더라도 Windows가 새 릴리스를
차단할 수 있습니다. Windows가 새 바이너리를 차단하면 스크립트는 기존 파일을 하나도
교체하지 않고 멈춥니다. 이전 artifactize와 artifactize-tools는 설치된 채로
실행할 수 있고, Path도 바뀌지 않습니다. 애플리케이션 제어
정책을 우회하지 말고 Microsoft Store에서 설치하세요.
WSL. WSL 2 안에서는 artifactize의 Linux 빌드를 씁니다. 배포판 안에
Linux 안내대로 설치하세요. Windows 설치와는 별개이며
상태도 따로 저장합니다. 내장 open과 login codex는 Windows 프로그램이 아니라
배포판의 xdg-open을 씁니다.
파일과 브라우저 열기를 보세요.
Cargo (모든 플랫폼)
cargo-binstall로 앞의 설치 방법과
같은 사전 빌드 바이너리를 ~/.cargo/bin에 내려받습니다.
cargo binstall artifactize artifactize-tools
또는 crates.io에서 최신 안정 릴리스를 빌드합니다. 빌드하려면 rustup으로 받은 Rust 최신 안정 버전과 C 컴파일러가 필요합니다(SQLite를 소스에서 빌드합니다).
cargo install artifactize artifactize-tools --locked
cargo install artifactize@<version> artifactize-tools@<version> --locked # a particular release
--locked는 릴리스를 테스트할 때 쓴 의존성 버전으로 빌드합니다.
바이너리는 ~/.cargo/bin에 설치되며, 이 디렉터리가 PATH에 있어야 합니다. --root DIR을 쓰면 대신
DIR/bin에 설치합니다. 두 cargo 명령 모두 macOS와 Windows에서도 동작합니다.
소스에서 빌드 (모든 플랫폼)
소스에서 빌드하려면 저장소를 복제한 뒤 그 디렉터리에서 다음 명령으로 설치하세요. 복제한 저장소의 rust-toolchain.toml에 따라
Rust 안정 버전이 쓰입니다. 예제 프로젝트와 빠른 시작을
따라 하려면 복제한 저장소가 필요합니다.
git clone https://github.com/lhj6102/artifactize
cd artifactize
cargo install --path crates/artifactize --locked
cargo install --path crates/artifactize-tools --locked
릴리스 빌드는 태그에서 버전을 가져오며, 복제한 저장소에서 빌드하면 임시 버전 0.0.0-dev가
출력됩니다.
데스크톱 앱
데스크톱 앱은 현재 브랜치 목록과 브랜치별 Run, 지금 verify를 실행하면 처리할 작업, 대기 중인 Human 리뷰를 한 창에서 확인할 수 있습니다. 디스크 이미지나 AppImage로
실행하면 앱이 첫 실행 때 artifactize 명령을 설정합니다(아래 참고).
내려받기에서 설치하세요. 각 릴리스에는 AppImage
artifactize-desktop-vVERSION-x86_64-unknown-linux-gnu.AppImage도 첨부됩니다. VERSION은 릴리스 버전이며,
내려받은 파일 이름에 들어 있습니다. Linux의 시스템 C 라이브러리인 glibc 2.35 이상이 필요하며,
ldd --version을 실행하면 첫 줄에 설치된 버전이 나옵니다. 파일을 내려받은 폴더에서 아래 명령의 파일 이름을 실제 파일 이름으로 바꾼 뒤, 그 파일에 실행 권한을 주고 실행하세요.
chmod +x artifactize-desktop-vVERSION-x86_64-unknown-linux-gnu.AppImage
./artifactize-desktop-vVERSION-x86_64-unknown-linux-gnu.AppImage
각 파일 옆에는 .sha256 체크섬이 있습니다. artifactize-desktop 명령으로 앱을 실행하거나
응용 프로그램 메뉴 또는 시작 메뉴에서 Artifactize를 여세요.
앱은 첫 실행 때 터미널이 이미 artifactize를 찾을 수 있는지 확인합니다. Homebrew, 설치
스크립트, .deb, Store로 설치했다면 아무것도 바꾸지 않습니다. 그렇지 않으면 명령을 설정하며,
그다음 새 터미널을 열고 artifactize --version을 실행하면 됩니다.
- macOS: 터미널이 앱의 명령을 찾을 수 있도록 관리자 권한 확인 창에서 승인하세요. 명령은 설치된 앱에서 실행되므로 앱을 업데이트하면 명령도 업데이트됩니다. 앱을 다른 위치로 옮겼다면 한 번 더 실행해 명령을 다시 설정하세요. 권한 요청을 취소하면 실행할 때마다 다시 묻지 않습니다.
- Linux AppImage: 앱이 명령을
~/.local/bin에 설치합니다. AppImage를 닫은 뒤에도 명령은 계속 동작하며, 더 새 AppImage를 실행하면 명령도 업데이트됩니다. 앱이 만들지 않은 파일은 그곳에서 교체하지 않습니다. 셸이~/.local/bin을 검색하지 않는다면 셸 시작 파일에export PATH="$HOME/.local/bin:$PATH"를 추가하고 새 터미널을 여세요.
설정에 오류가 있어도 오류만 기록하고 앱은 계속 실행됩니다. Windows 설치 프로그램, .deb,
install.sh가 풀어 놓은 Linux 앱은 이미 명령을 제공하므로 설정이 필요 없습니다.
소스에서 데스크톱 앱 빌드
위에서 설명한 소스 빌드에 필요한 Rust 도구 외에 Node.js 24,
crates/artifactize-desktop/ui/package.json에 적힌 버전의 pnpm, 그리고
OS별로 Tauri 빌드에 필요한 도구와 라이브러리를 설치하세요.
Linux에는 WebKitGTK 4.1, GTK 3, librsvg 개발 패키지가 필요하고, macOS에는
Xcode 명령줄 도구가, Windows에는 C++ 빌드 도구와 WebView2가 필요합니다.
저장소 루트에서 실행하세요.
pnpm -C crates/artifactize-desktop/ui install --frozen-lockfile
pnpm -C crates/artifactize-desktop/ui build
cargo install --path crates/artifactize-desktop --locked --bin artifactize-desktop
artifactize-desktop
이 순서대로, Cargo로 설치하기 전에 프런트엔드를 빌드하세요.
앞에서처럼 같은 저장소에서 CLI도 설치하세요. 앱은
artifactize verify가 시작한 Run을 보여 줍니다. 앱은 Store 앱의 전용 상태가 아니라
패키지되지 않은 CLI와 같은 상태 디렉터리와 자격 증명을 씁니다.
업데이트와 제거
업데이트
| 설치 방법 | 업데이트 |
|---|---|
install.sh 또는 install.ps1 | 같은 명령을 다시 실행하세요. 데스크톱 앱도 함께 업데이트됩니다 |
| Homebrew | brew upgrade artifactize를 실행하세요. 데스크톱 앱은 brew upgrade --cask artifactize로 업데이트합니다 |
| Microsoft Store | 자동으로 업데이트됩니다. Store 앱의 라이브러리 → 업데이트 받기로 직접 받을 수도 있습니다 |
디스크 이미지, .deb 또는 AppImage | 최신 릴리스의 설치 파일을 같은 방법으로 설치하세요 |
cargo binstall | cargo binstall artifactize artifactize-tools를 실행하세요 |
cargo install | cargo install artifactize artifactize-tools --locked를 실행하세요. 체크아웃에서는 git pull 후 cargo install --path를 반복하세요 |
설치 스크립트나 Cargo를 쓰면 릴리스가 게시되는 즉시 그 버전을 설치할 수 있습니다. Homebrew와 Microsoft Store는 안정 릴리스만 제공하며, Microsoft가 검토하는 동안 Store 업데이트가 늦어질 수 있습니다. 업데이트해도 상태는 유지됩니다.
플러그인 업데이트 방법은 플러그인 페이지에 있습니다.
새 릴리스 알림
artifactize는 업데이트를 직접 내려받거나 설치하지 않습니다. 새 안정 릴리스가 나오면
데스크톱 앱은 헤더에 이를 표시하고,
artifactize doctor는 release 검사에서 경고합니다. 앱과 doctor는 현재 설치 방식에 맞는
위 표의 업데이트 방법을 안내하고, 설치 방식을 확인할 수 없으면 릴리스 페이지를 안내합니다.
Microsoft Store로 설치했다면 Store가 업데이트하므로 아무것도 표시하지 않습니다.
GitHub에서 최신 릴리스를 조회합니다. 요청에는 artifactize 버전 말고는
아무것도 담기지 않습니다. 확인을 끄려면 ARTIFACTIZE_NO_UPDATE_CHECK=1을 설정하세요.
0.16으로 업그레이드
처음 열면 스키마 6~9의 상태 데이터가 현재 스키마 10으로 자동 업그레이드됩니다. 기존 Run, 캐시 기록,
Human 승인은 유지되며, SIGNOFFS_PENDING으로 끝난 Run은 YELLOW로 처리됩니다. 이전 버전의 artifactize는 업그레이드된 상태를 열 수 없으니, 버전을 바꾸기 전에 백업해 두세요.
이제 이번 Run의 실행 대상으로 선택한 승인 요청은 다른 eval의 실행을 막지 않으므로 verify --defer-human, MCP defer_human, eval 필드
gate = "blocking"은 제거되었습니다. 스크립트에서는 플래그를, 선언에서는 필드를 지우세요. 이 플래그나 필드를
사용하면 삭제하라는 오류 메시지가 표시됩니다. Run은 진행 중에 제출되지 않은 승인이 있는 동안 WAITING_HUMAN이며, 제출되지 않은 승인만
남으면 YELLOW(종료 코드 5, 이전의 SIGNOFFS_PENDING)로 끝납니다. 담당자가 맡은 승인이 제출될 때까지는 Run을
종료하지 않고, 아무도 맡지 않은 승인만 남으면 2분의 승인 유예 시간이
지난 뒤 종료합니다.
종료 코드 5가 즉시 반환된다고 가정한 스크립트는 artifactize limits --signoff-idle-grace 0으로 이 시간을 0으로
설정할 수 있습니다. --reuse-only agent,human을 쓰는 CI는 바뀌지 않습니다.
승인과 Run 종료를 보세요.
0.11에서 업그레이드
상태는 0.16과 같은 방식으로 업그레이드됩니다.
이제 artifactize verify는 터미널을 닫아도 계속 실행되는 Run을 제출하고, Run ID를 출력한 뒤 접수되면 종료합니다.
검증 종료 코드가 필요한 스크립트와 CI에는 --wait를 추가하세요. 터미널을 닫거나
지켜보는 명령을 중단해도 Run은 계속 실행됩니다. Run을 취소하려면
artifactize run cancel RUN_ID를 실행하세요. 포그라운드 Human 제한 시간과
verify --timeout-ms는 제거되었습니다. --request-key를 쓰면 재시도해도 같은 Run이 반환됩니다.
게이트 우회(review_policy.dependency_gates를 포함한 --ignore-gates와 review_policy)는
제거되었습니다. 빈 review_policy 테이블도 설정 검사에 실패하니 지우세요. 의존하는 eval의 판정이 나오기
전에 eval을 실행하려면 verify 요청에 --speculate를 붙이세요. 이 옵션도 최종 승인을 면제하지 않습니다. 승인은 이제 다른
eval을 막지 않습니다(0.16으로 업그레이드 참고). Run과 status를 보세요.
인자 없이 실행한 artifactize monitor는 ALL에서 시작합니다. monitor ., 위치 인자 경로, 또는 --repo는
처음에 그 저장소를 선택합니다.
0.9로 업그레이드
선언을 폴더에는 TOML index.artf로, 파일에는 <file>.artf로 다시 작성하세요. 키는
snake_case이고 eval은 [evals.<id>] 테이블입니다. .artfignore가 예전 무시 파일을
대신합니다. 변환기는 없습니다. 에이전트에게 파일을 다시 작성해 커밋하게 하고,
기존 선언 형식의 흔적을 제거한 뒤 artifactize config check를 실행하세요. Family는 제거되었습니다. 템플릿이
필요하다면 직접 만든 생성기를 쓰고 그 .artf 출력을 커밋하세요. 선언 (.artf)을 보세요.
0.9 이전의 상태(스키마 1~5)는 거부합니다. ARTIFACTIZE_STATE_HOME이나 --state-dir을 새
디렉터리로 설정하거나, 이전 디렉터리를 다른 곳으로 옮기세요. 그 뒤의 상태는 자동으로
업그레이드됩니다(상태).
재사용 키 v2는 0.9 이전의 어떤 결과와도 일치하지 않습니다.
팀 리뷰 저장소에 있거나 스크립트 fingerprint를 쓰는 경우도 마찬가지입니다. 업그레이드 후 처음으로 전체 verify를
실행하면 Human 승인을 포함해 실행 가능한 eval을 모두 한 번씩 리뷰하고, 그 뒤 Run부터는 평소처럼 재사용합니다.
이제 Monitor는 eval의 Detail을 모달이 아니라 전용 패널에서 엽니다. 독립 실행형 Review도 같은 Human Detail을 씁니다. 요청은 직접 맡아야 하며, 도구를 실행하거나 결과를 제출해도 요청을 맡은 것으로 처리되지 않습니다. 판정 양식, 제출 키, 편집기 단축키가 바뀌었습니다. 현재 조작 방법은 Human 리뷰와 Monitor를 보세요.
0.5.0부터는 chatgpt와 claude Agent 백엔드가 login chatgpt,
logout chatgpt, 내부 mcp 명령과 함께 제거되었으며, ChatGPT 요금제
사용자를 위한 codex 백엔드가 추가되었습니다. config check는 제거된 백엔드를 아직 쓰는
eval이나 프로필 변형을 찾아 대신 쓸 백엔드를 안내합니다. artifactize는 이전 릴리스가 저장한 ChatGPT
토큰을 더 이상 쓰지 않습니다. ChatGPT 설정에서 artifactize 연결을 끊은 다음
상태 디렉터리에서 auth/chatgpt.json, auth/chatgpt-registration.json, auth/chatgpt.lock을
삭제하세요.
상태
Run, 저장된 Agent 대화, 로그인 정보는 모두 한 디렉터리에 저장됩니다. 기본값은 ~/.local/state/artifactize(Windows에서는 %LOCALAPPDATA%\artifactize)입니다.
상태에 그 내용,
상태 위치를 옮기는 환경 변수, Store 버전의 전용 사본이 정리되어 있습니다.
--state-dir PATH는 그 명령 하나에서만 상태 위치 전체를 바꿉니다. login, verify, request, run,
monitor에 같은 값을 쓰세요. 상태는 리뷰 대상 저장소 밖에 있어야 합니다.
auth/ 아래의 토큰도 git 워크트리나
artifactize 프로젝트 안에는 둘 수 없습니다. $HOME에 있는 dotfiles 저장소나 체크아웃 안의 gitignore된 폴더가 그런 예입니다.
ARTIFACTIZE_CODEX_AUTH_FILE을 쓰면 토큰을 따로 저장할 곳이 필요 없습니다
(상태).
정리와 제거
artifactize prune --dry-run # list removable scratch output of finished Runs
artifactize prune --older-than 7d # remove it; saved results stay readable
artifactize logout codex # if you signed in with Codex
artifactize remote logout # if you signed in to a review store
그다음 설치한 방법대로 명령을 제거하세요.
rm ~/.local/bin/artifactize ~/.local/bin/artifactize-tools # install.sh (or your ARTIFACTIZE_INSTALL_DIR)
brew uninstall artifactize # Homebrew
cargo uninstall artifactize artifactize-tools # cargo install or cargo binstall
데스크톱 앱도 제거합니다.
rm -rf ~/Applications/Artifactize.app # install.sh on macOS
rm -rf ~/.local/share/artifactize/desktop ~/.local/bin/artifactize-desktop \
~/.local/share/applications/artifactize.desktop # install.sh on Linux
brew uninstall --cask artifactize # Homebrew cask, with its commands
sudo apt remove artifactize # .deb
디스크 이미지로 설치했다면 응용 프로그램 폴더의 Artifactize를 휴지통으로 끌어다 놓으세요. 첫 실행 때 명령 설정을 승인했다면 그 터미널 경로 항목도 제거하세요.
sudo rm -f /etc/paths.d/artifactize
AppImage를 단독으로 실행했다면 AppImage를 삭제하세요. 앱의 고정 복사본을 가리키는 명령 링크만 제거한 다음, 그 복사본을 제거하세요.
bin="${XDG_DATA_HOME:-$HOME/.local/share}/artifactize/bin"
for command in artifactize artifactize-tools; do
link="$HOME/.local/bin/$command"
[ "$(readlink "$link")" != "$bin/$command" ] || rm "$link"
done
rm -rf "$bin"
명령의 경로 항목을 제거한 뒤에는 새 터미널을 여세요.
Windows에서는:
Remove-Item -Recurse "$env:LOCALAPPDATA\Programs\artifactize" # install.ps1
Remove-Item "$([Environment]::GetFolderPath('Programs'))\Artifactize.lnk" # its Start menu shortcut
Store 버전은 설정 → 앱 → 설치된 앱에서 제거하거나, 시작 메뉴에서
Artifactize를 마우스 오른쪽 버튼으로 클릭해 제거하세요. install.ps1 설치를 제거한 뒤에는
그 디렉터리를 사용자 Path에서도 제거하세요(시작 메뉴에서 “계정의 환경 변수 편집“을
검색하세요).
Store 앱을 제거하면 Run, 저장된 결과, 로그인, 캐시를 포함한
패키지 전용 상태가 제거됩니다. 다른 방법으로 설치했다면 앱을 제거해도 상태 디렉터리가 남으므로,
나중에 Store 이외의 방법으로 다시 설치하면 기존 Run과 결과를 다시 볼 수 있습니다. prune은 활성 Run,
데이터베이스 행, 저장소를 건드리지 않습니다. 패키지되지 않은 버전이 남긴 상태를 지우려면
artifactize doctor가 첫 줄에 출력하는 상태 디렉터리를 삭제하세요.
제거해도 프로젝트 파일, 내보낸 파일, --state-dir이나 환경 변수로 경로를 지정해 AppData 밖에 명시적으로 둔 상태는 지워지지 않습니다. eval의 명령이 만든 파일은 AppData 안에 있더라도 남으니,
더 이상 필요하지 않으면 따로 지우세요. Store 앱을 설치하기 전부터 AppData에
있던 파일(예: 이전에 패키지되지 않은 버전이 남긴 상태)도 남습니다. Store 앱이 AppData를 어떻게 함께 쓰는지는
상태를 보세요.
백엔드와 로그인
Agent eval은 백엔드를 통해 모델 서비스에 리뷰를 요청하며, Runtime eval과 Human eval에는 백엔드가 필요하지 않습니다. Agent eval이 쓰는 백엔드만 사용할 서비스에 맞춰 준비하세요. OpenAI·Anthropic·Gemini는 API 키를, Codex는 Codex를 쓸 수 있는 ChatGPT 요금제를, Claude Agent는 Claude Code에 로그인한 계정(Claude Pro·Max 구독 등)을 사용합니다.
Agent eval에는 백엔드 하나와 사용할 모델의 정확한 ID를 지정하세요. artifactize는 모델 목록을 따로 제공하지 않으며, 지정한 백엔드나 모델을 다른 것으로 바꾸지도 않습니다. 아래 기본 백엔드 말고도 직접 이름을 붙인 커스텀 provider를 백엔드로 쓸 수 있습니다. 기본 백엔드의 별칭이나, OpenAI·Anthropic·Gemini와 호환되는 엔드포인트를 등록하면 됩니다.
백엔드는 artifactize가 Agent 리뷰를 모델 서비스로 보낼 때 쓰는
연결입니다. API 키는 그 서비스에서 계정을 인증할 때 쓰는 비공개 인증 정보입니다.
API 키 백엔드를 쓰려면 OpenAI 계정,
Anthropic Console,
Google AI Studio에서 키를 만든 다음 artifactize login으로
저장하세요. 키를 묻는 프롬프트에 붙여 넣으면 artifactize가 stdin에서 키를 읽습니다. 데스크톱 앱의
Settings → Providers에 붙여 넣어 저장해도 됩니다. 키를 커밋하거나 Artifact 선언에 넣지 마세요.
Codex는 대신 아래의 별도 브라우저 로그인을, Claude Agent는 Claude Code 자체 로그인을 씁니다.
| 백엔드 | 설정 | 모델 목록 |
|---|---|---|
openai | artifactize login openai | artifactize models openai |
anthropic | artifactize login anthropic | artifactize models anthropic |
gemini | artifactize login gemini | artifactize models gemini |
codex | artifactize login codex | artifactize models codex |
claude-agent | artifactize login claude-agent(Claude Code 자체 명령 claude auth login 실행) | artifactize models claude-agent |
OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY에 키가 있으면 저장한 키보다 먼저 씁니다.
예를 들어 export OPENAI_API_KEY=...처럼 설정하세요(PowerShell에서는
$env:OPENAI_API_KEY = "..."). 저장한 키는 logout openai|anthropic|gemini로 지웁니다.
login codex는 Codex CLI와 같은 방식으로 ChatGPT 계정에 로그인합니다.
로그인 URL을 출력하고 기본 브라우저로 엽니다(Linux와 WSL에서는 xdg-open, macOS에서는 open,
Windows에서는 기본 브라우저). 로그인은 같은 머신의 브라우저에서 마치세요.
로그인이 끝나면 브라우저가 localhost:1455로 이동합니다. WSL 2에서는 Windows 브라우저도 쓸 수 있습니다. 아무것도 열리지 않으면
출력된 URL을 브라우저에 복사하세요. Codex CLI나 다른 앱의 로그인 기능이 포트 1455를
사용 중이면, artifactize가 주소를 붙여 넣으라고 안내합니다. 다른 머신에서 로그인할 때도 URL을 붙여 넣는 방법을 쓰세요.
http://localhost:1455/auth/callback?code=로 시작하는 전체 URL을
터미널에 붙여 넣거나 데스크톱 앱의 로그인 창에 있는 URL 입력란에 붙여 넣으세요. 로그인은 5분 안에 마쳐야 하며, 그 뒤에는
login codex를 다시 실행하세요. 페이지 로드에 실패했다면 브라우저 주소 표시줄에서,
페이지가 계속 로딩 중이라면 개발자 도구 → Network에서 이 URL을 찾을 수 있습니다.
logout codex는 artifactize의 토큰을 삭제하고
서버에 토큰 폐기를 요청합니다. 폐기가 확인되지 않으면 경고합니다. 대신 기존 Codex 로그인의 토큰을 쓰려면
ARTIFACTIZE_CODEX_AUTH_FILE=~/.codex/auth.json을 설정하세요. artifactize는 그 파일을 읽기만 합니다.
Codex를 보세요.
claude-agent는 설치된 Claude Code(PATH에 있는 2.1.248 이상의 claude)를 이미 로그인된
계정 그대로 실행합니다. login claude-agent는 Claude Code 자체 명령인 claude auth login을
실행합니다. Claude Code가 브라우저를 열고, 열리지 않았을 때 열 URL을 출력합니다. 페이지에 코드가
나오면 터미널에 붙여 넣으세요. logout claude-agent는 claude auth logout을 실행합니다. 로그인
정보는 Claude Code가 보관하며, artifactize는 이를 읽거나 복사하거나 저장하지 않습니다. 직접
claude auth login으로 로그인해도 똑같이 쓸 수 있습니다.
Claude Agent를 보세요.
artifactize doctor # state and its schema, API-key presence, Codex sign-in, Claude Code on PATH, review store, desktop app, newer release
artifactize doctor --repo PROJECT # also validates PROJECT's declarations
doctor는 어떤 provider도 호출하지 않고 Run도 만들지 않습니다. 모든 백엔드가 선택 사항이므로
키나 로그인이 없으면 경고로 처리합니다. 데스크톱 앱이 없을 때도 설치 링크와 함께 경고만 하고, 새 릴리스가 나온 경우도 경고입니다. 쓸 수 없는 상태나 잘못된 설정 같은
심각한 오류가 있을 때만 1로 종료합니다.
가이드 (모델 불필요)
이 가이드에서는 저장소에 포함된 예제 프로젝트로 실습합니다. 저장소를 아직 로컬에 복제하지 않았다면, 먼저 버전 관리 프로그램인 Git으로 내려받으세요
(git --version이 응답하지 않으면 Git 받기).
git clone으로 저장소를 새 artifactize 폴더에 내려받은 다음, cd로 그 폴더에 들어가세요.
git clone https://github.com/lhj6102/artifactize
cd artifactize
예제는 Python으로 된 eval을 실행하는 데 python3를, 텍스트를 검색하는 데 grep을 쓰므로 두 명령
모두 터미널에서 쓸 수 있어야 합니다. PATH는 터미널이 명령을 찾는 디렉터리 목록입니다.
터미널이 두 명령을 찾는지 확인하세요.
python3 --version
grep --help
Python 버전과 grep 도움말이 출력되어야 합니다. 둘 중 하나라도 명령을 찾을 수 없다는 오류가
나오면, 그 도구를 설치하거나 도구가 설치된 디렉터리를 PATH에 추가한 뒤 계속하세요.
artifactize는 모든 OS에서 프로젝트에 선언된 명령을 적힌 그대로 실행합니다.
운영체제를 보세요.
리뷰할 작업 단위마다 Artifact를 선언합니다. Artifact의 index.artf는 텍스트 설정 파일이며, 여기에 eval이라는 리뷰 항목을 나열합니다. 이 파일은 읽기 쉬운 key = value 형식의 TOML로 작성합니다. fingerprint는 리뷰된 입력을 식별합니다. 내장 artifactsum은 파일 내용을 해시해 변경 여부를 감지합니다.
Run과 결과는 상태 디렉터리에 저장되며, 이 데이터를 통틀어 상태(state)라고 합니다.
이 실습의 리뷰 기록은 평소 쓰는 상태 디렉터리와 분리된 임시 디렉터리에 저장하세요. POSIX 셸(예를 들어
Bash나 zsh)에서 아래 첫 줄은 mktemp -d로 새 임시 디렉터리를 만들고
artifactize가 그곳에 상태를 저장하도록 합니다. export로 설정한 변수는 이 터미널에서
이후 실행하는 명령에 전달됩니다. 그다음 예제 디렉터리로 이동해 선언을 확인하세요.
export ARTIFACTIZE_STATE_HOME=$(mktemp -d)
cd examples/runtime-relations
artifactize config check
artifactize status
artifactize config graph
PowerShell에서는 첫 줄을
$env:ARTIFACTIZE_STATE_HOME = (New-Item -ItemType Directory (Join-Path $env:TEMP (New-Guid))).FullName으로 바꾸세요.
이 명령은 Windows 임시 디렉터리 아래에 고유한 이름의 디렉터리를 만들고
그 경로를 위와 같은 환경 변수에 저장합니다. artifactize 명령은 그대로입니다.
config check는 프로젝트 프로그램을 실행하지 않고 선언을 검증합니다.
status에서는 eval 두 개를 실행 대상으로, 나머지 하나를 선행 eval의 결과가 나온 뒤 실행할 대상으로 표시합니다.
프로젝트에 필요한 eval이 아직 모두 통과하지 않았으므로 종료 코드는 1입니다. config graph는
Artifact들과 그 입력 관계를 보여 줍니다. 이제 세 eval을 모두 실행하고
결과를 기다리세요.
artifactize verify --all --wait
세 결과 모두 GREEN이고 종료 코드는 0(성공)이어야 합니다. 출력에는
저장된 Run의 Run ID가 run-Abc123 같은 형태로 나옵니다. 다음 명령에서는 RUN_ID를
그대로 입력하지 말고 화면에 출력된 Run ID를 넣으세요.
artifactize run show RUN_ID
이 명령은 저장된 Run을 JSON 형식의 구조화된 텍스트로 출력합니다. argv는
프로그램에 전달된 인자 목록이고, stdout은 그 프로그램이 출력한 텍스트입니다.
기록에는 리뷰된 입력을 식별하는 fingerprint도 들어 있습니다.
같은 eval을 다시 실행하세요.
artifactize verify --all --wait
artifactize status
이번에는 아무것도 실행되지 않습니다. 세 결과가 모두 재사용됩니다. 두 명령 모두 0으로 종료하고, status는 재사용할 수 있는 결과를 알려 줍니다. 이후 단계에서도 같은 임시 상태 디렉터리를 쓰도록 이 터미널을 열어 두세요.
runtime-relations README는 eval이 RED가 되는 상황을 만드는 방법도 보여 줍니다. 각 폴더는
그 안의 index.artf 파일에서 Artifact로 선언됩니다. fingerprint를 생략하면 파일 변경 여부를 확인하는 내장 artifactsum이 쓰입니다. 재사용을 끄려면 fingerprint = false로 설정하세요. snake_case 키와 JSON/출력 이름의
구분은 선언 (.artf)을 보세요.
파일과 eval 의존성
hero.png.artf 같은 사이드카는 옆에 있는 파일을 독립된
Artifact로 선언합니다. 사이드카에는 name이 필요하고, 폴더와 같은 TOML 스키마를 쓰며, 기본적으로
그 파일만 해시합니다. 내장 도구는 대상 파일과 eval에 명시적으로 제공한 입력에만
접근할 수 있으며, 같은 폴더의 다른 파일에는 접근할 수 없습니다. 공용 검사기처럼 다른 Artifact를 쓰는 eval은
그 Artifact를 {house-style}처럼 이름으로 가리킵니다.
eval 의존성을 보세요. posts 예제는
Markdown 사이드카 세 개와 공용 스타일 검사기 하나를 씁니다. 이전
예제의 디렉터리에서 다음을 실행하세요.
cd ../posts
artifactize config check # four Artifacts, three evals
artifactize verify --all --wait # three GREEN results
artifactize verify tip/style --wait # qualified file eval; reused
artifactize status # all three post reviews are reused
cd ../runtime-relations # continue the tour below
파일 Artifact의 기본 fingerprint는 그 파일 하나만 해시해 계산합니다. 참조된 house-style Artifact가
검사기와 금지어를 담고 있으므로, 공용 부분이 바뀌면 세 글 모두 기존 리뷰의
재사용 키가 무효가 됩니다. 재사용 키는
검사 기준과 리뷰한 입력을 구분하는 값이며, 이 값을 기준으로 이전 결과를 계속 쓸 수 있는지 판단합니다.
이 예제의 README는 글 하나를 RED로 만들고 나머지 두 개는 재사용하는 방법을 보여 줍니다.
Runtime eval은 지시문이나 인자에서 입력을 직접 참조합니다. 예를 들어
애플리케이션의 eval은 {e2e-tests}를 입력으로 삼아, 실제로 동작하는 애플리케이션을 검사하는 종단 간(E2E) 테스트 모음을 실행합니다. 테스트 코드
Artifact의 eval은 코드 스타일을 리뷰하고, 테스트가 각 기능을 충분히 검증하는지도 확인합니다. 그 애플리케이션 eval만
테스트 코드 리뷰가 끝난 뒤에 실행되고, 관련 없는 애플리케이션 eval은 그동안에도 실행할 수 있습니다.
eval 의존성을 보세요.
선택 실습: Agent 도구와 Human 리뷰 절차
앞선 실습에는 모델이 필요 없지만, 이 선택 실습을 진행하려면 모델이 필요합니다. 먼저
agent-tools README에 설명된 대로
examples/agent-tools/spec/index.artf에서 쓰는 프로필에 정확한 모델 ID를 넣고 자격 증명을 설정하세요.
다른 백엔드를 쓰려면 verify에 --profile anthropic 또는 --profile codex를 덧붙입니다.
자격 증명이 없으면 리뷰는 ERROR로 기록되고 대기 명령은 2로 종료합니다.
같은 Artifact에 선언된 나머지 자동 eval이 모두 GREEN이 된 뒤에야
Human eval을 요청하므로 spec/review가 먼저 실행됩니다. 두 터미널은 같은 임시 상태 디렉터리를 써야 합니다. 아래의
대기 명령을 시작하기 전에 첫 번째 터미널의 값을
echo "$ARTIFACTIZE_STATE_HOME"(PowerShell: $env:ARTIFACTIZE_STATE_HOME)으로 출력하세요.
두 번째 터미널에서는 아래 STATE_DIRECTORY를 출력된 그 경로로 바꾸세요.
RUN_ID에는 대기 명령이 출력한 새 Run ID를 쓰고, REQUEST_ID는
request list가 출력한 대기 중인 요청 식별자로 바꾸세요.
PowerShell에서는 export 대신 $env:ARTIFACTIZE_STATE_HOME = "STATE_DIRECTORY"를
쓰세요. 그다음 같은 예제 디렉터리를 여세요.
cd ../agent-tools
artifactize tools check # static: schemas, executables and scoped paths
artifactize tools check --execute --eval spec/review --tool coverage_spec --args '{}'
artifactize verify --eval spec/review --wait # the machine review comes first
artifactize verify --eval spec/signoff --wait # records a sign-off request and waits
# In a second terminal, in the same directory:
export ARTIFACTIZE_STATE_HOME="STATE_DIRECTORY" # copy the first terminal's path
artifactize request list --run RUN_ID # shows REQUEST_ID
artifactize request claim REQUEST_ID
artifactize request tool REQUEST_ID notes_spec
artifactize request submit REQUEST_ID --verdict GREEN --fields '{"approved":true,"comment":"Both questions are answered."}'
artifactize run show RUN_ID
claim, tool, submit은 --reviewer NAME을 넘기지 않으면 내 사용자 이름($USER)을 리뷰어로
씁니다. request unclaim REQUEST_ID는 담당을 해제합니다. artifactize review는 같은 일을 터미널 UI에서 합니다. 대기 중인 요청을 나열하고
지시문을 미리 보여 줍니다. Enter를 누르면 Detail이 열립니다. c를 눌러 요청을 직접 맡고, Tab으로 도구에 초점을 옮긴 뒤 Enter를 누르거나 클릭하면 도구 하나가 바로 실행됩니다. g/r을 누르면 GREEN/RED 입력 칸이 열리고, Ctrl-S를 누르면 제출됩니다. Esc는 목록으로 돌아가기 전에 편집을 멈추며 초안은 유지됩니다.
옵션 없는 verify는 Run을 제출하고 바로 끝납니다. verify --wait는 Run이 끝날 때까지 포그라운드에서 진행 상황을 표시합니다. 승인만
남은 상태에서 담당자가 2분 안에 요청을 맡으면, 담당자가 요청을 맡고 있는 동안 Run은 진행 중으로 유지됩니다. 앞선
자동 리뷰가 여전히 유효하면 GREEN 승인이 제출되는 즉시 verify --wait가 종료 코드 0으로 끝납니다. Run이
이미 YELLOW(종료 코드 5)로 끝난 뒤에 요청을 맡더라도, 승인을 제출하면 다음 verify에서 그 승인을 재사용합니다.
Monitor
artifactize monitor . # Initially select this repository
artifactize monitor # Initially select ALL repositories in this state
Run이 실행되는 동안 두 번째 터미널에서 시작하세요. Enter나 →로
Scope에서 Run과 트리를 거쳐 eval의 Detail까지 이동하고, Esc로 한 단계 돌아갑니다. j/k로 항목을 고르고, ?로 도움말을 확인하고, q로 종료하세요. Detail은 Agent 대화, Runtime
로그, 또는 eval을 실행하기 전에 충족해야 할 조건을 보여 줍니다. 화면을 살펴보기만 해서는 프로젝트에 선언된 명령이 실행되지 않습니다.
Human 요청 담당 지정, 도구, 판정 양식은 Human 리뷰와 Monitor를 보세요.
팀 리뷰 저장소 (선택)
팀 리뷰 저장소는 재사용할 수 있는 판정을 여러 머신과 CI가 공유하게 해 줍니다. 각 머신은 토큰으로 로그인합니다. 토큰은 어떤 동작이 허용되는지 정하는 비밀 값입니다. CI가 승인을 만들 수 없도록 CI에는 읽기 권한만 주세요. 팀 가이드와 워크스루에서 서버 설정, 토큰, 그리고 두 번째 머신에서 같은 리뷰를 시도하는 방법을 다룹니다.
다음 단계
예제는 각 기능을 작은 프로젝트로 보여 주고, Artifact와 eval은 방금 실행한 선언을 설명합니다.
예제
설치에 나온 대로 바이너리를 설치한 뒤 예제 프로젝트를 실행해 보세요. 각 README에 정확한 명령이 적혀 있습니다.
- Runtime relations: Artifact와 그
부분에서 명령을 실행하는 eval, 지시문과 명령 인자 안의
{artifact}참조, 입력만 제공하는 Artifact, 일부러 실패시켜 볼 수 있는 eval, 파일이 바뀔 때까지 결과를 재사용하는 모습을 보여 주며,status가 무엇이 바뀌었는지 설명합니다. - Agent tools: 내장
read,grep,view_image,section도구와 선언한json도구를 쓰는 Agent eval, 통과/실패 스키마, 백엔드와 모델 선택, 그리고 내장open,read도구를 쓰는 Human 승인을 보여 줍니다. - Posts: Markdown 파일 Artifact 세 개, 글마다 하나씩 둔 사이드카 선언, 참조된 basis Artifact 안의 공용 스타일 검사기, 글별 단어 수 제한, artifactsum으로 글마다 결과를 따로 재사용하는 방식을 보여 줍니다. 글 하나를 바꾸면 해당 글의 eval만 다시 실행되고, 공용 검사기나 규칙을 바꾸면 세 글의 eval이 모두 다시 실행됩니다.
- eval 의존성: eval마다 입력을 지정하는 방법과, 의존하는 eval을 먼저 실행하는 순서를 설명합니다.
- 팀 워크스루: 두 머신과 CI가 하나의
artifactize server를 통해 서로의 판정을 재사용합니다.
Artifact
리뷰할 대상이라면 무엇이든 Artifact로 선언할 수 있습니다. 코드, 문서, 디자인, 이미지 모두
Artifact입니다. 폴더에 index.artf를 추가하면(파일이라면 옆에 notes.md.artf를 두면)
Artifact를 선언할 수 있습니다.
name = "docs"
[evals.links]
title = "Links resolve"
profile = { kind = "runtime", command = "python3", args = ["check_links.py"] }
payload.instruction = "Check that every link in the docs resolves."
그다음 artifactize config check를 실행하면 Folder configuration is valid.가 나오거나,
오류가 나옵니다. 선언 내용이 잘못되었으면 파일 이름과 줄·열 번호가 나오고, 대상 파일이 없는 등의 문제라면 해당 경로가 나옵니다. artifactize는 이 선언들을 읽어 의존성 그래프 하나로
만듭니다.
Artifact Graph
Artifact Graph는 입력과 그 입력을 쓰는 eval을 연결합니다. eval에 {spec} 같은 참조를
쓰면 그 eval이 spec을 읽을 수 있습니다. spec이 바뀌면 이를 참조한 eval과 spec을 부분으로
포함하는 전체의 eval을 다시 리뷰하고, 관계없는 결과는 재사용합니다. 같은 저장소나 같은 폴더에 있다는 이유만으로 한 Artifact가
다른 Artifact의 eval 입력이 되지는 않습니다.
부분 관계는 입력 관계와 별개이며, 이를 구성이라고 합니다. combat이
game의 부분이면 combat이 실패하는 동안 game은 통과하지 못합니다. 그렇다고 game의
eval이 combat을 읽지는 않으며, 읽으려면 참조해야 합니다.
각 eval은 참조한 입력 Artifact를 평가하는 eval이 끝난 뒤 실행됩니다. eval 의존성을 보세요.
Artifact Graph 자체도 리뷰할 수 있습니다. 저장소 루트의 이름 없는 .artf가 그래프 Artifact를
선언합니다. 그 fingerprint는 소스 내용이나 실행 설정이 아니라, 추출한 기준과 이름이 붙은
관계를 포함합니다. 프로젝트의 리뷰 구조를 사람이 리뷰할 때 쓰세요. 문법은
선언에 있고, graph 도구는
Agent에게는 현재 프로젝트 구조를 텍스트로 보여 주고, 사람에게는 데스크톱 그래프 뷰어를 엽니다.
폴더 설정
index.artf가 있는 폴더는 Artifact입니다. name은 필수이고(이름
참고), basis, views, fingerprint, tags, parts는 선택입니다. 다른 Artifact의 폴더 안에
선언한 Artifact는 그 Artifact의 부분입니다. 예전 선언은
예전 정책 업그레이드 안내를 보세요.
eval은 로컬 ID를 키로 쓰는 테이블입니다. usage Artifact의 [evals.heading]은 eval ID
usage/heading이 됩니다. id 필드는 선언하지 마세요. eval마다 title과, kind가 runtime,
agent, human 중 하나인 profile이 있습니다. 모든 eval에는 payload.instruction이 필요하며,
pass_schema, fail_schema, profile_variants를 둘 수 있습니다.
Runtime eval은 프로그램의 종료 코드로 통과 여부를 판정하며, 0이면 GREEN입니다. Agent eval과 Human eval은 추가 결과 필드를 포함한 GREEN 또는 RED 판정을 돌려줍니다.
다음은 runtime-relations 예제의
guide Artifact이며, 그 README에서 부분, {artifact} 참조, basis Artifact를 설명합니다.
name = "guide"
[evals.terms]
title = "Every bold term is defined in the glossary"
profile = { kind = "runtime", command = "python3", args = ["check_terms.py", "{glossary}/terms.txt", "{intro}/page.md", "{usage}/page.md"], timeout_ms = 10000 }
payload.instruction = "Check that every bold term in {intro} and {usage} is defined in {glossary}."
선언 키는 snake_case입니다. minLength, additionalProperties 같은 JSON Schema 키워드는 표준
이름을 그대로 쓰고, eval 작성자가 정한 payload 필드는 정한 이름을 그대로 씁니다. 다만 --json 출력과
저장된 상태에는 지금도 passSchema, timeoutMs, agentTools 같은 필드가 쓰입니다. 정확한 문법은
선언(.artf)을 보세요.
파일 Artifact
일반 파일 hero.png 옆에 사이드카 hero.png.artf를 두면 그 파일을 Artifact로 선언합니다.
폴더 Artifact와 같은 스키마를 쓰며, 프로젝트 전체에서 겹치지 않는 name을 지정해야 합니다.
# hero.png.artf
name = "hero-art"
tags = ["type:image", "scope:player"]
[evals.approved]
title = "The hero sprite matches the style guide"
profile = { kind = "human" }
payload.instruction = "Check {hero-art} against {style-guide}."
파일 Artifact는 기본으로 대상 파일 하나만 해시합니다. 작업 디렉터리는 그 파일이 들어 있는
폴더이지만, 내장 도구로는 대상 파일과 허용 범위에 포함된 파일에만 접근할 수 있습니다. 폴더
Artifact의 폴더 안에 있으면 그 Artifact의 부분이 됩니다. 폴더는 자체 artifactsum에서
그 대상 파일을 제외하고, 대신 eval 재사용 키에 부분의 fingerprint를 넣습니다.
다른 Artifact의 폴더 안에 있는 하위 폴더에 index.artf를 두어도 그
Artifact의 부분이 되고, 그 폴더의 파일은 바깥 Artifact의 파일 범위에서 제외됩니다.
이름 짓기, fingerprint 형식, 가상 경로, 잘못된 대상과 재확인 규칙은
파일 Artifact 레퍼런스에 있습니다.
eval 의존성
의존성은 Artifact의 모든 eval에 일괄 적용되지 않고, 해당 입력을 쓰는 eval에만 적용됩니다. payload.instruction이나
Runtime args 인자에 있는 {name} 참조가 입력 Artifact를 가리키며, 그 eval은 입력을 판단하는
eval에 의존합니다. 한 Artifact가 다른 Artifact를 쓴다면, 그 부분을 검사하는 eval에서 그 Artifact를 {name}으로
참조하세요. 그 밖의 방식으로는 의존성이 추가되지 않습니다.
부분은 입력이 아닙니다. 게임 전체를 실행하느라 combat도 쓰는
game의 eval은 다른 입력과 마찬가지로 {combat}을 참조합니다.
예를 들어 애플리케이션의 E2E 테스트를 실행하는 eval은 애플리케이션 Artifact에 선언합니다.
name = "app"
[evals.e2e]
title = "The application passes its end-to-end suite"
profile = { kind = "runtime", command = "node", args = ["{e2e-tests}/run.mjs", "{app}"] }
payload.instruction = "Run {e2e-tests} against {app}."
e2e-tests Artifact의 eval은 테스트 코드 자체를 평가합니다. 테스트 코드의 스타일과, 기능 문서를
얼마나 충실히 따르는지를 봅니다. 테스트 코드 자체를 리뷰할 때는 애플리케이션 테스트를 실행하지 않습니다. 테스트 코드와
상관없는 app의 스타일 eval은 지시문에서 테스트 코드를 참조하지 않는 한, 테스트 코드 리뷰가 끝나지 않아도
실행할 수 있습니다.
모든 eval은 입력의 판정과 상관없이 그 대상을 판단할 수 있습니다. 옵션 없는 verify는
효율을 위해 의존성을 먼저 실행합니다. 입력 리뷰가 끝나지 않았으면 그 입력을 쓰는 eval은 실행을 미루고, 입력 리뷰가 RED면 실행이 막힙니다. --speculate를 쓰면 입력 게이트가 확정되기 전에 작업을 시작할 수 있지만, 최종 통과에 필요한 요건은 그대로 모두 충족해야 합니다. 최종 결과가 GREEN이 되려면 상위 리뷰를
포함해 필요한 증거를 모두 확보해야 합니다.
게이트는 eval마다 적용됩니다. eval 중 하나라도 ERROR나 RED이면 Artifact에도 그 상태를
표시합니다. 그런 eval이 없어도 막힌 eval이 하나라도 있으면 BLOCKED로 표시합니다. 위의 app/e2e는 e2e-tests를 참조합니다.
e2e-tests의 eval이 RED나 BLOCKED이면app/e2e가 막히고,app을 참조하는 eval도 차례로 막힙니다.- 부분이 RED여도 아무것도 막히지 않습니다.
combat이game의 부분이고combat/tests가 RED여도game의 eval은 실행되지만,game은 통과하지 못합니다(구성 참고). - eval이 없는 Artifact는 아무것도 막지 않습니다.
app/e2e가 eval이 없는bundleArtifact를 참조한다면,app/e2e는bundle의 부분 결과가 나오기 전에도 실행됩니다. 다만 Run에는 그 결과도 필요하므로, 그중 하나라도 RED면 Run은 GREEN으로 끝나지 못합니다.
한 Artifact의 eval이 다른 Artifact를 참조하고, 그 참조가 직접 또는 여러 단계를 거쳐 처음 Artifact로 돌아오면 이 Artifact들은 순환을 이룹니다. 순환은 참조로만 생기며, 부분 관계는 Artifact 선택자가 함께 실행하는 순환을 정할 때만 셉니다. 순환 안의 eval은 서로의 게이트가 되지 않지만, 순환 밖에서 들어오는 입력의 eval은 여전히 먼저 끝나야 합니다.
예를 들어 docs/matches-cli가 cli를 참조하고, cli/tests가 docs와 core를 참조한다고 해 봅시다.
| 결과 | 일어나는 일 |
|---|---|
cli/tests가 RED | docs/matches-cli는 그대로 실행되고 판정도 바뀌지 않습니다. |
core/tests가 RED | cli/tests가 막히고, cli를 참조하는 docs/matches-cli도 막힙니다. |
docs나 cli의 eval이 서로도 core도 참조하지 않음 | 그 eval은 이들의 결과가 나오기 전에도 실행됩니다. 다만 Run이 GREEN으로 끝나려면 모든 결과가 필요합니다. |
다른 곳의 eval이 docs를 참조함 | docs와 cli의 모든 eval 결과가 나와야 실행됩니다. |
eval은 대상 Artifact 자체를 게이트로 삼지 않습니다. 예외는 Human 형제 선행 조건 하나입니다. 어떤 eval을 대기 상태로 두고 어떤 추측 실행 작업을 취소할지도 이 게이트에 따라 정해집니다.
BLOCKED인 eval의 사유에는 Dependency verdict RED: core/tests처럼 실행을 막은 근본 원인인 RED eval만
표시하고, 단순히 실행 중인 eval은 표시하지 않습니다. 추측 실행하는 Run에서는 상위 eval의 ERROR도
그에 의존하는 작업을 막으며, 사유는 Dependency ERROR: …로 나옵니다. blockedBy에도 같은 eval이 나오고, 확정된 Run에는
그 eval이 모두 나옵니다.
Human 승인
Human eval은 의존성 게이트를 통과하고, 같은 Artifact에 선언된 나머지 자동 eval도 모두 GREEN이어야
시작합니다. 사람은 자동 eval을 이미 통과한 것만 승인하며, 그전까지 Human eval은 대기 상태로 남습니다.
자동 eval의 판정이 GREEN이면, 그 eval이 의존하는 승인이 아직 남아 있어 PROVISIONAL로 보이더라도
통과한 것으로 칩니다. 그
자동 eval 중 하나라도 RED나 ERROR면 Human eval은 시작하지 않고 BLOCKED가 되며, 사유에
Sibling machine eval RED: spec/review처럼 그 eval이 나옵니다. 같은 Artifact의 다른 Human
eval에는 이 조건을 적용하지 않으므로, 두 승인 요청은 서로의 완료를 선행 조건으로 삼지 않습니다. 옵션 없는 verify와
--speculate 모두 규칙이 같습니다. 추측 실행하는 Run도 그 자동 eval이
GREEN이 되기 전에는 사람에게 요청하지 않습니다.
구성
Artifact는 다른 Artifact, 곧 부분(part)으로 이루어질 수 있습니다. 폴더 Artifact의 폴더 안에
선언한 Artifact는 가장 가까운 상위 폴더 Artifact의 부분입니다. 자기 index.artf가 있는
하위 폴더, 그 옆에 선언한 파일, aspect가 모두 그렇습니다. 다른 곳에 있는 Artifact는 parts에
적어 부분으로 더할 수 있습니다.
# game/index.artf
name = "game"
parts = ["physics"]
game/combat/index.artf가 있으면 따로 적지 않아도 combat은 game의 부분이고,
game/combat/skills/fireball/index.artf가 있으면 fireball은 combat의 부분입니다. 다른 폴더에
선언한 physics는 parts에 적혀 있으므로 game의 부분입니다. 한 Artifact가 여러 Artifact의
부분일 수도 있습니다. 두 애플리케이션이 함께 쓰는 모듈은 두 애플리케이션의 parts에 모두 적으며,
그 모듈의 폴더는 둘 중 한쪽 안에 있어도 됩니다. 부분 관계가 이어져도 Artifact는 자기 자신을
부분으로 삼을 수 없습니다. 그래프 Artifact는 부분을 갖지 않으며 어떤 Artifact의 부분도 아닙니다.
각 부분도 독립된 Artifact입니다. Artifact는 eval 없이 부분을 모으기만 할 수도 있고, 부분들이 함께 동작하는지 보는 검사처럼 자기 내용과 eval을 가질 수도 있습니다. 부분이 자기 몫을 검사하므로 그 부분으로 이루어진 Artifact가 같은 검사를 되풀이할 필요는 없습니다.
| Artifact | 자기 eval |
|---|---|
game | 게임 전체가 시작되고 부분들이 함께 동작함 |
combat | 전투 구성 요소끼리 함께 동작함 |
fireball | 피해량, 재사용 대기시간, 효과 |
부분 관계는 판정, 선택 범위, 재사용에 영향을 줍니다.
- 부분이 실패하면 그 부분으로 이루어진 Artifact도 실패합니다.
fireball이 RED인 동안game도 RED로 보이며, 부분의 부분까지 모든 부분과 자기 eval이 통과해야game이 통과합니다. 자기 eval이 없는 Artifact에는 기다려야 할 리뷰가 따로 없습니다. UNREVIEWED를 포함해 부분의 상태를 그대로 보여 주고, 부분이 모두 통과하면 통과합니다. - Artifact를 선택하면 그 부분도 선택됩니다.
verify game은game,combat,fireball,physics의 eval을 실행하거나 재사용합니다. - Artifact가 필요하면 그 부분도 필요합니다.
{game}을 참조하는 eval이 GREEN으로 끝나려면game이 통과해야 하므로, Run에는 부분의 결과도 필요합니다. 다만 실행 게이트는 여전히game에 선언된 eval뿐입니다. - 부분이 바뀌면 전체도 다시 리뷰합니다. 각 Artifact의 artifactsum에서는 부분의 파일을 제외합니다.
파일, 폴더, aspect가 고른 경로 모두 해당합니다. 전체의 eval 재사용 키에는 자체 fingerprint와
모든 부분의 fingerprint를 넣으며, 부분의 부분까지 포함합니다. fireball이 바뀌면
fireball,combat,game의 eval과{fireball}을 참조하는 eval을 다시 리뷰하고, 관계없는 eval은 재사용합니다.game의 파일만 바뀌면 fireball은 다시 리뷰하지 않습니다. 재사용 키에 포함된다고 접근 권한이 생기지는 않습니다. fireball을 읽는game의 eval은 여전히{fireball}을 참조해야 합니다.
부분에 자기 폴더가 꼭 있어야 하지는 않습니다. 파일 Artifact는 파일 하나이고, aspect는 fireball의 코드, 테스트, 스프라이트처럼 큰 폴더에서 한 부분의 파일만 골라, 그 부분을 따로 리뷰하고 재사용할 수 있게 합니다.
fingerprint 필드
fingerprint를 생략하면 내장 방식인 artifactsum으로 그 Artifact에 속한 파일을 해시합니다.
fingerprint = false는 재사용을 끄고, 스크립트로 다른 값을 정할 수도 있습니다. 형식, 포함하는
입력, GREEN/RED 결과 재사용은 Fingerprint에서 설명합니다.
태그와 검사
tags = ["type:code", "scope:player"]는 화면에 보여 주기만 하는 메타데이터를 더합니다. 태그는
ASCII 제어 문자가 없고 비어 있지 않은 고유한 문자열이며 64개까지입니다. status,
config graph, monitor와 그 JSON의 Artifact 출력에 나옵니다. 태그를 바꿔도 fingerprint, eval 정의
해시, 재사용 키, 의존 관계, verify와 status로 선택하는 대상은 바뀌지 않습니다. 이런 명령에는 태그로
거르는 기능이 없고, 태그로 관계를 정하는 규칙도 없습니다. artifactize review에서 tag: 검색어를 쓸 때만 태그로 결과를 걸러 볼 수 있습니다.
프로젝트에 템플릿이 필요하면 .artf 파일을 직접 생성해서 커밋하세요. 선언 찾기와 검사 규칙은
선언 검사에 있습니다.
선언(.artf)
폴더를 리뷰하려면 그 안에 index.artf를, 파일을 리뷰하려면 그 옆에 NAME.artf를 만든 다음 아래 명령으로 확인하세요.
artifactize config check
선언이 유효하면 Folder configuration is valid.를 출력하고, 오류가 있으면 오류를 출력한 뒤 종료 코드 2로 끝납니다. 선언 내용에
오류가 있으면 파일 이름과 줄·열 번호가 나오고, 대상 파일이 없는 등 파일 시스템에 문제가 있으면 그 경로만 나옵니다. 이 페이지에는 선언, 폴더와 파일 Artifact, fingerprint, 참조, 명령 실행 방식의
정확한 규칙이 있습니다. 개념 소개는 Artifact와 eval에 있습니다.
기존 의존성 선언을 새 방식으로 바꾸기
kind = "dependency"와 depends_on은 없어졌습니다. 의존성만 선언하던 eval은 삭제하세요. 필요한 Artifact는 해당 Artifact를 입력으로 쓰는 eval의 payload.instruction(또는 Runtime args)에서 {name}으로 참조하세요.
예를 들어 spec과 assets를 나열하는 ready eval을 따로 만들지 말고, 실제 리뷰 지시문을
"Review {app} against {spec} and {assets}."처럼 쓰세요. 입력 Artifact를 참조하는 eval은 그 Artifact에 필요한 eval이 끝난 뒤 실행됩니다. 같은 Artifact에 선언됐더라도 그 입력을 참조하지 않는 eval은 먼저 실행할 수 있습니다.
다른 Artifact의 리뷰가 먼저 끝나야 한다면, eval의 지시문이나 argv에서 그 Artifact를 직접 참조하세요. 안에 선언된 폴더도, 그 밖의 부분도 참조가 아닙니다.
예전 프로필을 쓰면 설정을 해석하는 단계에서
unknown variant dependency, expected one of agent, human, runtime`` 오류가 납니다.
지원하는 프로필이라도 depends_on 필드를 쓰면 알 수 없는 필드라는 오류가 납니다. 이는 리뷰 판정이
아니라 설정 오류이므로, verify하기 전에 선언을 옮기세요.
선언 검사
index.artf는 그 파일이 있는 폴더를 Artifact로 선언합니다. <filename>.artf는 같은 폴더에서 이름(확장자 포함)이 <filename>과 정확히 일치하는 파일을 선언하고, 그런 파일이 없을 때 select가 있으면 aspect를 선언합니다. 모두 표준 TOML을 쓰며 name이 필요합니다.
저장소 루트의 이름 없는 .artf는 소스 파일 없이 그래프 Artifact를
선언합니다.
선언을 찾을 때는 저장소 루트부터 내려가며, .git, node_modules, 그리고 루트에 둘 수 있는
.artfignore(gitignore 문법)에 적은 하위 디렉터리와 사이드카 경로는 건너뜁니다. 탐색하는
디렉터리의 index.artf는 그 파일 이름만 가리키는 ignore 패턴이 있어도 읽습니다. 하위
프로젝트의 폴더 선언을 빼려면 그 폴더 자체를 탐색에서 빼세요. ignore된 사이드카는 해석하지도
대상을 확인하지도 않으며, 다른 선언이 포함하지 않는 한 그 대상은 일반 파일로 남습니다. 별도
프로젝트, 픽스처, 예제가 든 폴더를 적어 두세요.
crates/app/tests/
examples/
이름, eval ID, 도구·세션 이름, 프로필 변형 이름은 영문자나 숫자로 시작하고, 영문자, 숫자, 밑줄, 하이픈으로만 이루어져야 하며, 길이는 64자 이하입니다([A-Za-z0-9][A-Za-z0-9_-]{0,63}). Artifact가 어느 Artifact의 부분인지는 이름이 아니라 폴더
구조와 parts로 결정합니다(구성 참고). Artifact 이름은
프로젝트 전체에서 중복되지 않아야 합니다. eval은 배열이 아니라 ID를 키로 쓰는 테이블이며, app의
[evals.check]는 app/check가 됩니다. eval에 id 필드를 직접 쓰면 거부합니다. 선언 안의
eval은 TOML에 적힌 위치가 아니라 ID 순서로 정렬합니다.
| 필드 | 규칙 |
|---|---|
name | 필수입니다. Artifact 이름입니다 |
select | aspect가 고른 경로입니다. aspect 선언에만 씁니다 |
parts | 선택입니다. 폴더가 담은 것 말고도 이 Artifact의 부분인 Artifact 이름 1–64개를 중복 없이 적습니다. 자기 자신은 적을 수 없고, 루트 .artf에는 쓸 수 없습니다 |
tags | 선택 사항입니다. 비어 있지 않고 ASCII 제어 문자가 없는 고유한 문자열을 최대 64개 담은 목록입니다 |
basis | 선택 사항이며 불리언입니다. true면 eval 없는 입력으로 선언하며, 그 Artifact의 리뷰 요건은 없애지만 의존성의 리뷰 요건은 없애지 않습니다 |
fingerprint | 생략하면 artifactsum을 씁니다. false면 재사용하지 않습니다. 그 밖에는 artifactsum이나 스크립트 테이블을 지정합니다 |
views.agent_tools, views.human_tools | 선택 사항입니다. 선언한 도구의 맵입니다 |
views.agent_sessions.<name>.start, .stop | 도구 세션 명령입니다. command와 args는 필수이고 execution_paths는 선택 사항입니다. 다른 필드는 없습니다 |
views.agent_tools.<name>.session | 선택 사항입니다. 같은 Artifact에 선언한 도구 세션 이름입니다. 명령을 실행하는 Agent 도구에만 씁니다 |
evals.<id>.title | 필수입니다. 비어 있지 않은 제목입니다 |
evals.<id>.mutex | 선택 사항입니다. 고유한 계층형 mutex 태그를 최대 64개 담은 목록입니다. Runtime과 Agent eval에만 씁니다. 기본값은 없습니다 |
evals.<id>.profile | 필수입니다. runtime, agent, human 프로필입니다 |
evals.<id>.payload.instruction | Runtime, Agent, Human eval에 필수입니다. 비어 있지 않은 지시문입니다 |
evals.<id>.pass_schema, fail_schema | 선택 사항입니다. 실행 가능한 eval의 추가 결과 필드 JSON Schema입니다. Human eval은 양식으로 입력할 수 있는 형태만 받습니다 |
evals.<id>.profile_variants | 기본 프로필과 종류가 같은 프로필을 이름별로 최대 64개 선언합니다. 각 항목에는 프로필 전체를 씁니다 |
도구 세션을 쓰면 리뷰 하나가 진행되는 동안 테스트 하네스를 계속 실행해 둘 수 있습니다. 시작, 종료, 정리는 artifactize가 관리하며, 세션을 얼마나 오래 실행하고 언제 시작하거나 끝낼지 선언하는 옵션은 없습니다.
선언 키는 모두 snake_case입니다: timeout_ms, max_tool_calls, max_tokens,
input_schema, execution_paths, pass_schema, fail_schema, profile_variants,
mutex. 그 밖의 키와 timeout_ms 대신 쓴 timeoutMs 같은 camelCase 표기는 거부합니다.
additionalProperties, minLength, maxItems 같은 JSON Schema 키워드는 표준 이름을 그대로
씁니다. eval 작성자가 정한 payload 필드는 정한 이름을 그대로 씁니다. 이 필드는 eval에 저장되고 재사용 키에도
들어가지만, Agent는 payload.instruction만 보므로 리뷰어에게 필요한 내용은 모두 거기에 쓰세요. --json, 도구 프로토콜, 저장된
상태는 timeoutMs, passSchema, agentTools, blockedBy처럼 기존 camelCase 필드를 계속
쓰며, 이는 선언 문법이 아닙니다.
인라인 테이블, 점으로 이은 키, 여러 줄 문자열 같은 표준 TOML 문법을 쓸 수 있습니다.
name = "app"
tags = ["type:code"]
[evals.review]
title = "The implementation matches the spec"
profile = { kind = "agent", backend = "codex", model = "YOUR_EXACT_MODEL_ID", reasoning = "high", timeout_ms = 240000 }
[evals.review.payload]
instruction = """
Read {spec}, then review {app}.
Return GREEN when the implementation matches the spec.
"""
[evals.review.pass_schema]
type = "object"
required = ["summary"]
additionalProperties = false
properties.summary = { type = "string", minLength = 1 }
TOML에는 null 값이 없습니다. 선택 필드는 생략하고 null을 쓰지 마세요. 스키마에
type = "null"은 쓸 수 있지만, null const 같은 null 값 자체는 쓸 수 없습니다. 따옴표 없는
TOML 날짜·시각과 유한하지 않은 숫자(inf, nan)는 JSON으로 나타낼 수 없으므로 payload와
스키마를 포함해 어디서든 거부합니다. 날짜를 문자열로 쓰려면 따옴표로 감싸세요. 선언 오류는 TOML 해석 오류든 값의 타입, 필드, 참조 오류든 오류가 난 .artf 파일과 줄, 열을 알려 줍니다. 값이 잘못됐으면 evals.check.profile.args처럼 그 키도 알려 줍니다.
config check는 fingerprint 스크립트를 실행하거나 파일을 해시하지 않고 검사합니다. 선언을
고친 뒤에 실행하세요. 예전 선언 파일과 ignore 파일은 읽지 않습니다. ignore되지 않은 예전 선언
파일이 있으면 선언 찾기가 실패합니다. 예전 선언 파일과 이름이 같은 디렉터리도 디렉터리 ignore
패턴에 해당하지 않는 한 다른 디렉터리와 마찬가지로 탐색합니다. .artfignore로 예전 파일 하나만 ignore하거나 그
폴더 전체를 건너뛸 수 있습니다. 저장소 루트에 예전 ignore 파일이 있으면 항상 실패합니다. 진단
메시지는 다음과 같습니다.
artifactize.json is no longer read; declare this Artifact in index.artf (TOML).
.artifactizeignore was renamed to .artfignore.
옮기는 방법은 0.9로 업그레이드를 보세요.
staleKey, stale, critics, envRequirements, resultCheck,
reviewPolicy.maxConcurrentExecutors, 도구 메타데이터 observation 같은 예전 필드는
거부하며, 새 필드의 별칭이 아닙니다. artifactsum 형식의 예전 dependencies 옵션도
거부합니다.
결과 필드 스키마
Agent와 Human 결과에는 verdict와, eval 작성자가 정한 추가 결과 필드가 들어 있습니다. pass_schema(GREEN)와
fail_schema(RED)에는 이 추가 결과 필드만 선언하세요. verdict는 artifactize가 넣습니다. 예를 들어
위의 summary 스키마라면 Agent는 {"verdict":"GREEN","summary":"All requirements are covered."}를 돌려줍니다. Human은 GREEN을 따로 고르고, 양식 필드로
{"summary":"All requirements are covered."}만 입력합니다.
이 스키마는 JSON Schema입니다. 결과에 어떤 필드가 있을 수 있고 어떤 값을 허용하는지 정하는
규칙입니다. 결과 객체 전체에 적용되는 스키마(결과 형식)에는 일반 JSON Schema의 일부 기능만
쓸 수 있으며, 참조(다른 스키마를 가리키는 $ref)와 조합(여러 스키마를 합치는 allOf, anyOf,
oneOf, not)도 제한됩니다.
type이 있으면"object"여야 합니다.additionalProperties가 있으면false여야 합니다. 생략해도 artifactize가 최종 스키마에 객체 타입과 추가 속성 금지 조건을 적용합니다.- 허용하는 최상위 추가 결과 필드는 모두
properties에 직접 적어야 합니다.patternProperties나$ref로 선언하지 않은 최상위 필드를 허용할 수 없습니다. - 최상위의
allOf,anyOf,oneOf,not은 거부합니다. 조합은 추가 결과 필드 안에서 하세요. 중첩 객체, 배열, 로컬 참조는 스키마 검사기가 지원합니다. - 다음 이름은 예약되어 있으므로 필드로 선언하거나 필수 항목으로 지정할 수 없습니다:
verdict,reference,reusedFrom,executionProvenance,attemptId,provider,model,stdout,stderr,durationMs,exitCode. 감사·실행 데이터는 추가 결과 필드 밖에 있습니다. - 한 판정의 스키마를 생략하면 그 판정에서는 추가 결과 필드를 하나도 허용하지 않습니다.
Agent는
{"verdict":"GREEN"}이나{"verdict":"RED"}만 돌려주고, Human 양식 필드는{}입니다. 빈 객체 스키마도 마찬가지로 추가 결과 필드를 허용하지 않습니다.
Human 결과 스키마
Human 결과는 사람이 양식으로 입력하므로, Human eval의 pass_schema와 fail_schema에는 양식으로
입력할 수 있는 형태만 쓸 수 있습니다. 그 밖의 형태는 .artf를 읽을 때 선언 오류가 되며, 키
경로와 대신 쓸 수 있는 형태를 알려 줍니다.
| 추가 결과 필드 스키마 | 리뷰에서 보이는 모습 |
|---|---|
{ type = "string" }. minLength, maxLength를 붙일 수 있습니다 | 텍스트 상자 |
{ type = "integer" }나 "number". minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf를 붙일 수 있습니다 | 숫자 상자 |
{ type = "boolean" } | true / false(선택 항목이면 – 도) |
{ enum = ["a", "b"] }. 문자열만 받으며, type = "string"은 써도 되고 안 써도 됩니다 | 선택지 |
{ const = … } | 표시하지 않고 값을 자동으로 채웁니다 |
{ type = "array", items = { type = "string" } }. 항목에 minLength, maxLength를 붙일 수 있습니다 | 텍스트 상자 목록 |
{ type = "array", items = { type = "object", properties = … } }. 속성은 위의 단일 값 형태만 쓸 수 있습니다 | 그 필드들의 반복 그룹 |
배열에는 minItems와 maxItems를 쓸 수 있습니다. 결과 객체와 각 그룹의 객체에는
type = "object", properties, required, additionalProperties를 씁니다. required에
적은 이름은 모두 선언한 속성이어야 합니다. 어느 스키마에나 title, description,
$comment를 붙일 수 있으며, 속성의 description은 도움말로 나옵니다. 필수 필드에는 *가
붙습니다. 비어 있는 선택 필드에는 Optional이 표시되며, 해당 필드는 결과에 포함되지 않습니다. 빈 목록 항목과 아무것도 입력하지 않은 그룹도 결과에 포함되지 않습니다. 데스크톱 앱에서는 + Add와 ✕ 버튼으로 항목과 그룹을 추가하고
지우며, 터미널 UI에서는 Review 양식에서 설명하는 키를 씁니다. 패턴, 형식,
중첩 객체, 그룹 안의 목록, $ref, anyOf 같은 조합은 사람이 입력할 수 없으므로 거부합니다.
Agent 스키마에는 검사기가 지원하는 기능을 모두 쓸 수 있습니다.
스키마는 8 MiB까지입니다. Agent의 최종 응답은 다 받은 뒤에 검사하며, 1 MiB를 넘으면 잘못된 응답입니다. 그 응답에서 artifactize가 보관하는 결과는 256000자까지입니다. 이모지처럼 기본 다국어 평면 밖의 문자는 2자로 셉니다. 최종 응답이 잘못되면 한 번만 수정을 요청하며, 이때도 정해진 제한을 적용합니다. 알리지 않고 필드를 지우지는 않습니다. Human 제출 인터페이스는 따로 입력 크기를 제한하며, 검사 오류를 알릴 뿐 요청을 확정하지 않습니다.
그래프 Artifact
저장소 루트에 파일명이 .artf인 선언 파일을 두면 프로젝트 전체의 Artifact Graph를 선언할 수 있습니다.
이때도 index.artf는 루트 폴더를, <filename>.artf는 같은 폴더의 그 파일을 선언합니다. 다른
디렉터리에 이름 없는 .artf가 있으면 선언 오류입니다. 루트 .artf는 index.artf처럼
.artfignore 패턴이 그 파일 이름을 가리켜도 읽습니다. 그래프 Artifact는 하나만 둘 수
있습니다.
# .artf at the repository root
name = "project-graph"
[views.agent_tools.structure]
builtin = "graph"
args = []
[views.human_tools.viewer]
builtin = "graph"
kind = "launch"
args = []
[evals.review]
title = "The Artifact boundaries and evaluation criteria fit the project"
profile = { kind = "human" }
payload = { instruction = "Use the graph viewer to review the current structure." }
이름 있는 일반 Artifact이므로 Runtime, Agent, Human eval과 도구를 무엇이든 선언할 수 있고,
verify, status, CI, --reuse-only에서 이름으로 고를 수 있습니다. 기본 eval이나 부분은 없고, 이름이나 참조로 만들지 않는 한 다른 Artifact와의 관계도 생기지 않습니다. 지시문이나 argv의 Artifact 참조에는 일반 Artifact와 같은 규칙을 적용합니다.
명령은 저장소 루트에서 실행되지만, 그래프를 선언해도 그 폴더가 그래프 Artifact에 속하지는 않습니다. 범위 항목의
kind는 "graph"이고 선언 경로는 .artf입니다.
fingerprint는 false나 빈 테이블이라도 선언하지 마세요. fingerprint는 항상 현재 추출한
그래프입니다. 그 밖에는 일반 Artifact 규칙을 따릅니다. basis = true로 선언한 Artifact에는 eval을 둘 수 없고 그 Artifact의 리뷰도 필요 없지만, 의존하는 Artifact에 필요한 리뷰까지 면제되지는 않습니다.
basis = true가 없고 eval도 없는 그래프는 그런 다른 Artifact처럼 UNREVIEWED로 남습니다.
그래프는 부분을 갖지 않고 어떤 Artifact의 부분도 아닙니다.
소스 파일을 만들지 않으며, 소스 파일이 없어도 됩니다. 일반 Artifact의 순환도 허용하며, 그래프
Artifact를 선언한 내용도 그래프 fingerprint에 들어갑니다.
그래프 fingerprint는 소스 파일 내용이나 eval 실행 옵션이 아니라 구조에 관한 정의가 바뀔 때 바뀝니다. 차이 비교, 이력, 자동 리뷰 정책은 없습니다. 현재 그래프를 리뷰해 결과를 만들거나, 현재 그래프에 맞는 기존 결과를 재사용합니다.
파일 Artifact
hero.png.artf는 같은 폴더의 일반 파일 hero.png를 선언합니다. name은 필수이며, 파일이 들어 있는 폴더의 Artifact 이름과 별개로 정합니다. 없는 대상, 디렉터리, 심볼릭 링크, 특수 파일은 대상이 될 수
없습니다. 범위가 정해진 도구 경로로 나타낼 수 없으므로 이름에 :가 든 대상 파일은 선언을 찾을
때 거부합니다. .artf 선언 자체도 일반 파일이어야 합니다. 선언 위치에 심볼릭 링크, 특수 파일,
bundle.artf 같은 디렉터리가 있으면 선언 찾기가 실패합니다. index.artf는 항상 폴더를 선언하므로
이름이 index인 파일에는 사이드카를 둘 수 없습니다. .artf 파일은 선언이며 대상이 되지
않습니다.
파일 Artifact는 가장 가까운 상위 폴더 Artifact의 부분입니다.
그 폴더 Artifact를 선택하면 파일 Artifact도 함께 선택되고, 파일 Artifact가 통과해야 폴더 Artifact도
통과합니다. 폴더 Artifact의 eval 키에는 참조가 없어도 파일 부분의 fingerprint가 들어갑니다.
부분에 선언된 도구로 읽으려면 여전히 그 부분을 참조해야 합니다. 폴더의 artifactsum에서는
옆에 있는 파일 Artifact의 대상, 자체 index.artf가 있는 하위 폴더를 비롯해 모든 부분의 파일과
모든 *.artf 선언을 제외합니다. 각 부분의 파일은 그 부분의 fingerprint로 반영합니다.
파일 Artifact가 있는 폴더에서 Runtime 명령, 도구, fingerprint 스크립트를 실행하므로, 같은 폴더의
실행 파일을 상대 경로로 지정할 수 있습니다. 그렇다고 같은 폴더의 다른 파일에 접근할 수 있는 것은 아닙니다.
내장 도구와 범위가 정해진 argv 참조로는 대상 파일과 참조한 Artifact에만 접근할 수 있습니다. {name}은 폴더가
아니라 대상 파일 경로가 되며, 파일 참조에는 /path를 붙일 수 없습니다. list .는 파일
Artifact의 가상 루트를 가리키며 대상 파일 이름을 보여 줍니다. 가상 루트 안의 경로는 대상 파일이
있는 폴더를 기준으로 지정합니다. 기본 artifactsum은 대상 파일만 포함합니다. 작업 공간에 파일
Artifact만 있어도 되며, 폴더 선언이 없어도 됩니다.
파일을 해시하려면 fingerprint를 생략하세요. 파일 Artifact의
artifactsum 설정에는 대상 파일만 적으며, 스크립트나
fingerprint = false를 선택할 수도 있습니다.
JSON 명령 도구의 context.artifactPath는 파일을 가리키고, 프로세스의 작업 디렉터리는 그
파일이 들어 있는 폴더입니다. 범위 항목에는 kind = "file", "folder", "aspect", "graph"가
있습니다. aspect의 경로는 선언이 있는 폴더이며, 그 안에서 select에 적은 경로에만 접근할 수 있습니다.
execution_paths에는 어떤 버전의 도구가 실행됐는지 해시로 기록할 파일을 프로젝트 기준 경로로 적으며, 이 필드는 모든 종류에서 똑같이 동작합니다.
대상은 리뷰하는 동안 내내 심볼릭 링크가 아닌 일반 파일이어야 하며, fingerprint = false여도
마찬가지입니다.
- eval이 시작되기 전에 없거나 잘못된 경우: eval이 ERROR/PREPARATION_FAILED로 끝납니다.
- Runtime이나 Agent 리뷰가 끝날 때 없거나 잘못된 경우: 판정 대신 ERROR/INPUT_CHANGED로 끝납니다.
- Human 리뷰 중에 없거나 잘못된 경우: 도구와 제출이 실패하고 요청은 계속 남아 있으니, 파일을 되돌려 놓고 다시 시도하세요.
- 내용이 바뀐 경우: eval에 온전한 재사용 키가 있고 그 변경이 eval이 포함하는 fingerprint를 바꿀 때만
감지합니다. 이 파일이나 eval이 포함하는 다른 Artifact에
fingerprint = false가 있어 재사용 키가 없거나, 파일을 바꿔도 스크립트로 계산한 fingerprint가 그대로이면 변경을 감지하지 못합니다. 그 밖에는 Runtime이나 Agent 리뷰, 또는 승인이 ERROR/INPUT_CHANGED로 끝납니다. 일반 파일인지, 심볼릭 링크가 아닌지에 대한 위의 검사는 어느 경우든 적용합니다. - 없거나 잘못된 대상에 대한 도구 호출은 도구를 실행하지 않고 오류를 돌려줍니다.
파일을 되돌려 놓은 뒤 다시 verify하세요.
어떤 예전 정책 필드가 없어졌고 무엇으로 대체해야 하는지는 업그레이드 안내에서 확인하세요.
Aspect
aspect는 별도 폴더 없이 더 큰 파일 묶음 안에서 한 부분을 이루는 파일들입니다. 게임 트리 곳곳에 흩어진
스킬 하나의 코드, 테스트, 스프라이트가 그런 예입니다. 같은 이름의 파일이 없는 <label>.artf에 선언하고, select에
선언 파일이 있는 폴더를 기준으로 한 경로를 적습니다.
# game/fireball.artf
name = "fireball"
select = ["src/skills/fireball.rs", "tests/fireball.rs", "assets/fireball"]
[evals.behaves]
title = "Damage, cooldown and effects match the skill spec"
profile = { kind = "agent", backend = "codex", model = "YOUR_EXACT_MODEL_ID" }
payload.instruction = "Review {fireball} against {skill-spec}."
select에는 파일이나 디렉터리 경로를 중복 없이 1–64개 적으며, 각 경로는 1024자까지입니다(이모지처럼 기본 다국어 평면 밖의 문자는 2자로 셉니다). 경로는 심볼릭 링크를 거치지 않고 존재해야 하며 선언 파일이 있는 폴더 아래에 있어야 합니다. aspect는 다른 Artifact의 일부를 나타내므로, 안에 선언된 폴더 Artifact를 포함해 다른 Artifact의 파일을 골라도 됩니다.*.artf선언은 고르지 않습니다.- label은 선언에 붙이는 이름일 뿐이므로 자유롭게 정하면 됩니다. label과 같은 이름의 파일이 있는
선언에
select를 쓰면 오류이고,index.artf와 루트.artf에 써도 오류입니다. fingerprint를 생략하면 고른 경로를 artifactsum으로 해시하므로, 폴더의 다른 곳이 바뀌어도 aspect의 결과를 재사용합니다. artifactsum 형식을 직접 쓰면files를 고른 범위 안으로 좁히고ignore를 더할 수 있습니다. 스크립트나fingerprint = false는 다른 Artifact와 같습니다.- 도구에는 선언 파일이 있는 폴더가 보이지만, 고른 경로와 그 경로로 가는 폴더만 보입니다. aspect
참조
{name}은 그 폴더를 가리키고,{name}/path는 고른 범위 안에 있어야 합니다. 명령은 그 폴더에서 실행됩니다. - scope 항목과 저장된 정의에는
kind = "aspect"가 들어갑니다.
범위가 겹쳐도 괜찮습니다. 여러 aspect가 겹치는 파일을 다룰 수 있다는 점이 aspect의 장점입니다. game의 다른 파일이 바뀌어도
fireball의 결과는 재사용되고, src/를 담은 폴더 Artifact는 여전히 그 안을 모두
리뷰합니다. aspect는 선언이 있는 폴더를 둘러싼 폴더 Artifact의 부분입니다.
eval mutex 태그
Runtime이나 Agent eval은 profile과 함께 mutex도 선언할 수 있습니다.
[evals.suite-passes]
title = "The end-to-end suite passes"
mutex = ["use-computer:display", "use-computer:callback"]
profile = { kind = "runtime", command = "pnpm", args = ["e2e"], timeout_ms = 1800000 }
payload.instruction = "Run the end-to-end suite."
태그는 use-computer이거나 use-computer:display처럼 콜론으로 이은 하위 태그입니다. 하위
태그의 각 부분은 [A-Za-z0-9][A-Za-z0-9_-]{0,63}에 맞아야 합니다. 다른 최상위 이름, 빈 부분,
잘못된 부분, 중복 태그, Human eval에 선언한 태그는 오류입니다. mutex를 생략하거나
mutex = []로 선언하면 아무 제약도 없습니다.
두 eval의 태그 중 하나라도 같거나 한쪽이 다른 쪽의 상위 태그면 두 eval은 충돌합니다.
use-computer는 모든 하위 태그와 충돌하고, use-computer:db는 use-computer:db:users와
충돌하지만 use-computer:browser나 use-computer:database와는 충돌하지 않습니다. 같은 화면을
조작하는 두 eval처럼 함께 실행하면 안 되는 eval에는 같은 태그나 상위·하위 관계의 태그를 주세요.
다른 eval이 충돌하는 태그를 쓰고 있으면, 실행할 eval은 태그를 쓰고 있는 eval의 이름과 함께 QUEUED로
표시되고(아래 참고), 태그가 풀리면 시작합니다. 태그로 우선순위나 실행 순서를 정할 수는 없으며, eval들이 서로 점유한 태그 때문에
교착 상태에 빠지는 일도 없습니다.
태그는 한 Run 안에서만이 아니라 같은 상태를 쓰는 모든 Run, 워크트리, verify에 적용됩니다.
--state-dir이 다르면 태그도 따로 적용됩니다. 대기 중인 요청은 QUEUED로 남고, blockedReason에
태그를 잡고 있는 eval과 Run이 나옵니다. 실행이 보류된 동안에는 실행 예산을 쓰지 않고, 백엔드 자리나
--jobs 자리도 차지하지 않으며, timeout_ms는 eval이 시작할 때부터 셉니다. 태그는 eval이 끝나거나 취소되면
풀리고, 프로세스가 죽거나 Run이 끝날 때도 풀립니다.
태그는 Artifact가 아니라 그 eval에서 실행하는 명령이나 도구를 나타냅니다. 다른 eval이 테스트를 실행하는 동안에도, 테스트 코드를 읽기만 하는 Agent eval은 실행을 미룰 필요가 없습니다. 암묵적인 태그는 없습니다. mutex 태그는 평가 기준이 아니라 실행 옵션이므로, 바꿔도 fingerprint나 재사용 키가 바뀌지 않고, 충돌하는 eval이 실행 중일 때도 캐시 결과는 재사용할 수 있습니다.
eval 의존성
Artifact 참조는 payload.instruction과 Runtime profile.args에 {input}이나
{input}/path로 씁니다. 최종 검증 요건, 순환, 스케줄링, Human 선행 조건은
eval 의존성에, 부분은 구성에 있습니다.
Artifactsum
fingerprint를 생략하면 artifactsum을 씁니다. 폴더라면 fingerprint = {}도 같습니다.
fingerprint = false는 재사용을 끄고, fingerprint = true는 거부합니다. 무엇을 포함하는지,
files, ignore, 파일 Artifact 형식은 Fingerprint와 재사용에
있습니다. 태그는 해시하지 않습니다.
artifactsum은 범위가 정해진 경로 규칙에 따라 Artifact 아래의 파일을 읽습니다. 읽을 파일에 ignore되지 않은 심볼릭 링크나 특수 파일이 있으면 오류가 발생해 검증을 중단합니다. 적용되는 .gitignore는 해시 대상에서 빠지더라도 규칙을 적용하려고 모두 읽으므로,
심볼릭 링크가 아닌 1 MiB 이하의 일반 파일이어야 합니다. 해당 Artifact에 속하지 않은 파일은 해시하지
않습니다. 다만 무엇을 제외할지 알기 위해 저장소 루트까지 그 위 폴더들의 .gitignore도 읽습니다. 탐색 항목이 10,000개를 넘거나 전체 용량이 1 GiB를 초과하면 오류를 내고 중단합니다. 해시는 준비 단계와 리뷰가
끝날 때의 재확인에서 계산합니다. 그래서 리뷰 중에 Python의 __pycache__처럼 ignore된 경로에
파일이 생겨도 INPUT_CHANGED가 일어나지 않습니다. 결과마다 포함한 파일 목록을 저장하므로,
status가 그 뒤로 바뀐 파일(path, +path, -path)과 바뀐 의존성을 알려 줄 수 있습니다.
폴더가 아주 크면 status가 구체적인 변경 내역 대신 변경 여부만 알려 줄 수도 있습니다.
Fingerprint 스크립트
eval을 실행하기 전에 verify는 선택한 eval에 필요한 모든 Artifact의 fingerprint를 계산하며,
eval을 선택하지 않은 의존 Artifact도 포함합니다. 동시에 몇 개를 계산할지는
--fingerprint-jobs로 정합니다. 실패하면 이름 순서로 처음 실패한
Artifact를 알리고 나머지는 멈춥니다. 각 스크립트에는 별도의 출력 폴더를 줍니다.
스크립트 출력은 그대로 Artifact의 fingerprint가 되며, 그 Artifact의 모든 eval에 같은 값이 쓰이고 요청마다 저장됩니다. 이 값을 평가 기준 및 의존성과 어떻게 조합하는지는 재사용 키에 있습니다. artifactsum이 실패해도 똑같이 준비를 멈춥니다.
명령은 그 Artifact의 작업 디렉터리에서 stdin으로 JSON {"version":1,"artifactId":"example"}을
받아 실행됩니다. 경로 없는 명령은 PATH에서 찾고, 절대 경로 실행 파일은 그대로 실행합니다.
./fingerprint.sh처럼 /가 든 상대 경로 실행 파일은 폴더 Artifact의 허용된 범위 안에서
찾습니다. 파일 Artifact라면 대상 파일이 있는 폴더 아래에서 찾으며, 같은 폴더의 다른 파일을
가리킬 수도 있습니다. 어느 쪽이든 상위 경로로 올라가거나 심볼릭 링크를 거치는 경로는 거부합니다. 인자는 범위가 정해진
Artifact 참조만 빼고 적은 그대로 전달합니다. {name}은 전역 Artifact 이름입니다. 스크립트에서는
참조한 Artifact에 접근할 수 있지만, 이 참조로 그래프에 관계가 추가되지는 않습니다.
config check는 모르는 참조와 형식이 잘못된 참조를 거부하며, 존재 여부와 심볼릭 링크는 명령을
준비할 때 확인합니다. 인터프리터별 플래그, 래퍼, 진입 파일 규칙은 없습니다.
fingerprint.script.files는 Artifact 기준의 고유한 파일·디렉터리 경로를 64개까지 받으며, 각
경로는 1024자까지입니다(이모지처럼 기본 다국어 평면 밖의 문자는 2자로 셉니다). 호출할 때마다 각 경로가 존재하고 심볼릭 링크를 거치지 않는지
확인하며, 내용은 해시하지 않습니다. 실행 환경, 취소 처리, 스트림마다 128 KiB인 원본 출력 크기 제한은 Runtime 명령과 같으며, 기본 시간 제한은 30,000ms입니다(timeout_ms는 1–2,147,483,647). 별도의 출력·임시
디렉터리는 실행이 끝나면 지웁니다. stdout은 [A-Za-z0-9._:-]로 이뤄진 1–128자의 ASCII여야
하며, 그 뒤에 LF 하나(Windows에서는 CRLF 하나)만 올 수 있습니다. 그 밖의 공백은 허용하지 않고
앞뒤 공백을 지워 주지도 않습니다. 다음 중 하나라도 해당하면 동작 오류로 처리하고 준비 단계를 중단합니다. 종료 코드가 0이 아닐 때, 출력 형식이 잘못됐을 때, stdout이나 stderr가 128 KiB를 넘을 때(올바른 fingerprint를 출력했더라도), 시간이 초과됐을 때, 취소됐을 때, 파일이 없을 때, 정리에 실패했을 때입니다. eval을 시작하지 않으며, 캐시 없이 리뷰하는 방식으로 전환하지도 않습니다. stderr는 fingerprint 진단으로 전달하지 않습니다.
Runtime이나 Agent 리뷰가 끝나면 GREEN이나 RED 판정을 확정하기 전에 포함한 fingerprint를 다시
계산합니다. 값이 바뀌었으면 판정 없이 ERROR/INPUT_CHANGED를 기록하고, 재확인에 실패하면
ERROR를 기록합니다. force를 줘도 준비와 재확인은 건너뛰지 않습니다. fingerprint = false인
Artifact는 준비할 fingerprint가 없으며, 온전한 재사용 키가 없는 eval은 fingerprint 값 재확인을 건너뜁니다.
그래도 모든 eval에서 준비 단계와 eval 실행 전후, 도구 호출 때마다 파일 Artifact의 대상 파일을 확인합니다. 필요한 다른
Artifact의 fingerprint는 그래도 준비할 수 있습니다. 작업 공간의 변경을 계속 감시하지는 않습니다.
artifactsum은 준비와 재확인 때만 해시합니다.
명령 안의 Artifact 참조
Runtime 인자, fingerprint 스크립트, 도구 인자는 {name}, {name}/path,
--flag={name}/path로 다른 Artifact를 가리킵니다. 경로는 폴더 Artifact나 aspect의 폴더에서
시작합니다. Runtime 인자에서 폴더 Artifact의 경로는 그 안에 선언된 폴더 Artifact로 들어갈 수 없습니다.
그런 경로는 config check가 알려 주므로 그 Artifact를 대신 참조하세요. fingerprint 스크립트와 도구
인자에서는 안에 선언된 Artifact도 범위에 들어 있지 않으면 명령을 준비하거나 호출할 때 실패합니다. aspect의 경로는 고른 범위 안에 있어야
하며, 고른 범위는 안에 선언된 폴더 Artifact까지 닿을 수 있습니다. 파일 참조는 파일 자체이므로 경로를 붙이지 않습니다. 참조는 명령이 실행될 때 절대
경로로 바뀝니다. 지시문과 Runtime 인자에서 참조하면 eval이 그 Artifact에 의존하게 되고,
fingerprint 스크립트에서 참조하면 스크립트가 그 Artifact를 읽을 수 있게 될 뿐입니다. 도구
인자에는 그 eval이 이미 참조한 Artifact만 쓸 수 있습니다. 나머지는 적은 그대로 전달합니다.
이스케이프한 중괄호, 두 겹 중괄호, ${variables}, JSON, 짝이 맞지 않는 중괄호는 쓴 대로
남으며, artifactize는 문자열로 명령줄을 만들지 않습니다. eval은 그 대상과 참조한 Artifact를
읽을 수 있습니다. 허용된 폴더 안에 있는 파일 부분의 대상이나 aspect가 고른 파일은 폴더의 경로로
읽을 수 있지만, 허용 범위에 없는 중첩 폴더 Artifact는 읽을 수 없습니다. 부분 관계만으로 부분에
선언된 도구가 추가되지는 않습니다. 그 도구를 쓰려면 사용하는 eval의 지시문이나 Runtime 인자에서
부분을 참조하세요. 다른 Artifact를 참조하더라도 그 Artifact의 eval 지시문까지 현재 리뷰의 기준으로
적용하지는 않습니다. 프로젝트 전체의 기준은 graph 도구로 볼 수 있습니다.
참조의 경로는 절대 경로일 수 없고, ..로 올라가거나, 빈 부분, 백슬래시, 콜론, 제어 문자를
담거나, 4096자를 넘을 수 없습니다. 직접 선언하는 경로(fingerprint.files,
fingerprint.script.files, execution_paths)는 1024자까지입니다. config check는 eval마다
선언한 프로필의 이름과 문법을 확인합니다. 위의 문법과 경로 규칙은 모든 profile_variants 항목에도
적용되므로, 어느 변형에든 {app}/../outside처럼 잘못된 참조가 있으면 config check가 실패합니다.
변형에만 나오는 참조가 실제 Artifact를 가리키는지는 그 변형을 고를 때 확인하므로, 변형을 쓰기 전에
status SELECTOR --profile NAME을 실행하세요. 참조한 파일이
있는지와 심볼릭 링크를 따라가지 않는지는 명령을 준비할 때 확인합니다.
Runtime 실행
artifactize는 프로그램을 적은 인자 그대로, 셸 없이, Artifact 폴더(파일 Artifact면 들어 있는 폴더)에서 실행합니다.
명령은 작성자의 평소 터미널 환경에서 실행되므로, 프로젝트에 명령을 선언할 때도 터미널에 입력하듯 쓰면 됩니다. 실제 홈과 캐시 위치(HOME, XDG_*, Windows에서는 USERPROFILE, APPDATA,
LOCALAPPDATA와 시스템 변수)를 포함해 artifactize 프로세스의 환경을 모두 전달하므로, 버전
관리자로 설치한 cargo나 pnpm처럼 이 변수로 위치를 찾는 도구도 터미널에서처럼 동작합니다.
artifactize 전용 환경 변수는 전달하지 않습니다. 호출한 쪽의 ARTIFACTIZE_* 변수(ARTIFACTIZE_REMOTE_TOKEN
같은 자격 증명과 설정)는 모두 지웁니다. 명령은 ARTIFACTIZE_WORKSPACE_DIR,
ARTIFACTIZE_OUTPUT_DIR(출력용 별도 폴더로, Run이 끝나도 prune할 때까지 남음),
ARTIFACTIZE_TMP_DIR, 그리고 명령이 끝나면 지우는 별도 임시 폴더를 가리키는
TMPDIR/TMP/TEMP를 받습니다. 이 폴더는 현재 사용자만 읽을 수 있고, 리뷰하는 프로젝트 안에 두지
않습니다.
명령은 작성자의 환경에서 실행되므로, 다른 터미널 명령과 마찬가지로 실행 환경에 따라 결과가 달라질 수 있습니다. 환경은 재사용 키에 들어가지 않으므로 도구를 업그레이드해도 캐시 결과가 무효가 되지 않습니다. 도구 버전이 바뀔 때 fingerprint도 바뀌어야 한다면, fingerprint 계산에 도구 버전을 넣으세요.
Runtime의 제한 시간은 기본 30,000ms이며, 1~2,147,483,647ms로 설정할 수 있습니다. 결과에는 stdout과
stderr를 각각 앞에서부터 최대 128 KiB까지 저장하고, 출력이 잘렸는지 여부와 종료 상태, 실행 시간을 기록합니다. 텍스트는 UTF-8로
읽고(잘못된 바이트는 대체), 터미널 색상 코드와 탭, LF, CR을 뺀 ASCII 제어 문자를 지웁니다(DEL은
남깁니다). 전체 스트림은 Run 출력에 남으며, request logs와 MCP request_logs로 로그의 끝부분, 지정한 범위,
검색 조건에 맞는 줄을 읽을 수 있습니다. 캡처를 지우면 저장된 앞부분 128 KiB만 남습니다. artifactize prune은
Run의 output 폴더를 지우지만 이 스트림 캡처는 남깁니다. 캡처가 없거나 일부만 남았거나 이전 버전·원격 실행의 기록만 있으면 그 상태를 알려 줍니다.
명령이 정상으로 끝나든, 취소되거나 시간이 초과되든 그 명령이 시작한 프로그램도 함께 멈추므로, 백그라운드에서 시작한 프로그램이 명령보다 오래 남지 않습니다. 계속 실행되어야 하는 보조 프로그램에는 Agent 도구 세션이나 Human launch 도구를 쓰세요. 명령은 사용자가 신뢰하는 로컬 코드로 보고 샌드박스 없이 실행합니다. 명령은 현재 사용자 계정의 권한으로 실행되므로, 그 계정에 허용된 작업은 모두 수행할 수 있습니다. 명령은 리뷰 대상인 입력을 바꾸면 안 됩니다. 부모 프로세스에서 일부러 분리해 실행한 프로그램은 명령이 끝난 뒤에도 계속 실행될 수 있습니다.
Eval
eval은 Artifact를 검사하는 단위입니다. 바뀌지 않는 로컬 ID, 통과 조건을 나타내는 제목,
리뷰 주체를 정하는 프로필을 설정하세요. 예를 들어 library Artifact의
[evals.tests]는 전체 ID가 library/tests입니다.
세 종류의 eval은 실행부터 끝날 때까지의 처리 방식과 결과 재사용 규칙이 같습니다.
| 종류 | 리뷰어 | 판정 |
|---|---|---|
| Agent | 미리 선언된 읽기 전용 도구로 리뷰하는, 선택한 백엔드의 지정 모델 | 스키마로 검사한 추가 결과 필드와 함께 GREEN 또는 RED |
| Human | 대기 중인 요청을 맡아 승인을 제출하는 사람 | 스키마로 검사한 추가 결과 필드와 함께 GREEN 또는 RED |
| Runtime | 선언한 프로그램과 인자 목록 | 종료 코드 0이면 GREEN, 그 밖이면 RED |
실행에 실패했거나 모델 결과가 잘못되면 RED가 아니라 ERROR입니다. RED는 Artifact가 통과 조건을 충족하지 못했다는 eval의 판정을 뜻합니다. 어느 종류든 입력과 기준이 그대로인 동안은 재사용할 수 있습니다.
평가 기준은 payload.instruction에 쓰세요. Agent와 Human eval에서는 pass_schema와
fail_schema가 eval 작성자가 정한 추가 결과 필드를 정하고, 판정은 artifactize가 덧붙입니다. 추가 필드를 허용하지 않는 결과 형식,
예약된 이름, 스키마를 생략했을 때 판정만 돌려주는 기본 응답은 결과 필드 스키마를
보세요. Runtime eval은 결과 필드 스키마 대신 명령의 종료 상태를 씁니다. 이름을 붙인
profile_variants를 두면 호출하는 쪽이 다른 실행 프로필을 고를 수 있습니다. Agent 변형은 리뷰를 실행하는 방식만 바꾸지만, 명령이나 인자가 다른 Runtime 변형은 별도의 재사용 키와 입력을 쓰는 다른 eval입니다. 선언을 보세요.
의존성은 해당 입력을 쓰는 eval에만 적용됩니다. 입력 Artifact를 지시문이나 Runtime 인자에 {name}으로
적으세요. eval 의존성을 보세요.
실제 입력만 선언하세요. eval은 대상 Artifact와, 지시문이나 Runtime 인자가 가리키는 Artifact만 볼 수
있습니다. 예를 들어 지시문이 Check {app} against {spec}.인 app/review는 app과 spec을 읽고
그 도구를 쓸 수 있습니다. 하지만 app 폴더 안에 선언된 폴더 Artifact ui처럼 app의
부분인 Artifact나, spec의 eval이 참조하는 Artifact에는 접근할 수 없습니다.
ui도 읽으려면 Check {app} and {ui} against {spec}.처럼 이름을 적으세요. 도구 인자에
Artifact를 적는다고 입력이 늘어나지는 않습니다.
eval의 도구가 읽을 수 있는 Artifact는 곧 재사용 여부를 정하는 Artifact(재사용 키)이자 실행 전에 결과가 나와야 하는 Artifact(eval 의존성)입니다. Runtime 명령은 이렇게 제한되지 않으므로, 명령이 파일을 쓰는 Artifact는 모두 이름으로 적으세요.
artifactize verify library/tests --wait는 eval 하나로 Run을 시작합니다. 먼저
artifactize status library/tests로 무엇을 재사용할 수 있고 무엇을 리뷰해야 하는지 확인하세요.
status는 fingerprint를 계산하지만 eval을 실행하지는 않습니다.
Agent eval과 백엔드
Agent eval은 지정한 백엔드 하나와 모델 하나로 Artifact를 리뷰합니다. 모델은 선언한 읽기 전용 도구로 Artifact를 살펴보고, 엄격한 형식의 GREEN 또는 RED 판정을 돌려줍니다.
Agent 리뷰
artifactize는 모델 목록을 따로 제공하지 않으며, 여러 위치에서 자격 증명을 찾거나 지정한 모델을 다른 모델로 대체하지도 않습니다.
# Inside [evals.review]
profile = { kind = "agent", backend = "openai", model = "YOUR_EXACT_MODEL_ID", reasoning = "high", timeout_ms = 240000 }
backend에는 기본 provider(openai, anthropic, gemini, codex, claude-agent)나, eval을 실행하는
머신에 등록한 커스텀 provider의 이름을 씁니다. openai, anthropic,
gemini는 OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY에 든 키를 쓰고, 없으면
artifactize login openai|anthropic|gemini나 데스크톱 앱의 Settings에서 저장한 키를 씁니다.
그 밖의 자격 증명은 찾지 않습니다. 키는 공백 없는 출력 가능한 ASCII 문자 1–4096개이며, 앞뒤 공백은
지웁니다. 변수가 설정되어 있으면 그 키를 씁니다. 값이 잘못되었으면 저장한 키로 넘어가지 않고 오류가
납니다. 유효한 유니코드가 아닌 값은 설정되지 않은 것으로 보아 저장한 키를 씁니다. codex는 ChatGPT 로그인을, claude-agent는 내 Claude Code와 그 로그인을 씁니다(Codex, Claude Agent 참고).
provider와 effort는 설정에서 쓸 수 있는 별칭이 아닙니다. 0.5.0에서 chatgpt(Sign in with ChatGPT)와 claude(Claude CLI) 백엔드가
없어졌으며, 아직 이를 선언한 프로필이 있으면 config check가 대신 쓸 백엔드를 알려 줍니다.
artifactize models openai # model ID and display name, in provider order
artifactize models anthropic --json
artifactize models gemini
artifactize models codex
artifactize models claude-agent
모델 목록 조회에는 별도의 고정 제한 시간이 있습니다. API 키를 쓰는 백엔드와 커스텀 provider의
목록 조회, Codex 모델 요청은 30초, Claude Agent 초기화는 25초까지입니다. 시간이 초과되면 목록을
가져오지 못합니다(API 목록 조회에서는 Model listing timed out.). eval의 timeout_ms를 늘려도
이 제한 시간은 늘어나지 않습니다. 연결 상태를 확인하고, claude-agent라면 Claude Code가 정상적으로
시작되는지도 확인한 뒤 다시 시도하세요.
reasoning은 선택 항목입니다. OpenAI와 Codex는 none, minimal, low, medium, high,
xhigh, max를, Anthropic은 low, medium, high, max를, Claude Agent는 low, medium,
high, xhigh, max를, Gemini는 minimal, low,
medium, high를 받습니다. 그 밖의 값은 선언 오류이며, 다른 값으로 바꿔서 보내지 않습니다.
커스텀 provider에서는 해당 API가 지원하는 값을 쓸 수 있으며, 지원 여부는 리뷰를 시작할 때 확인합니다. 요청한 설정을 모델이 지원하지 않으면 provider에서 오류가 납니다. artifactize가 다른 모델로 바꾸거나 강도를 낮추지는 않습니다. 응답에 모델 ID가 나오면
정확히 일치해야 합니다.
Agent eval도 Runtime eval처럼 입력 eval이 끝날 때까지 실행을 미루고, 결과를 재사용하며, 리뷰가 끝난 뒤 입력을 다시 확인합니다. 백엔드, 모델, reasoning, 제한은 실행 옵션일 뿐 재사용 키에 들어가지 않습니다. eval, Artifact 종류, fingerprint가 같으면 모델이나 프로필이 달라도 결과를 재사용하며, 결과를 만들 때 쓴 모델과 프로필은 기록에 표시됩니다.
payload.instruction에는 무엇을 확인하고 무엇을 GREEN으로 볼지 쓰세요. 대상이 지켜야 할 기준을
적으면, 리뷰어가 그 기준에 비추어 GREEN 또는 RED와 지적 사항을 돌려줍니다. 리뷰어는 리뷰만
합니다. 구현이나 수정은 하지 않고, 선언된 Artifact 도구만 실행합니다. 테스트를 실행하거나 테스트
대상 코드를 불러오지 않고, 테스트 코드를 읽어 평가 기준에서 요구하는 사항을 충분히 검증하는지 판단합니다. 테스트 모음이
통과하는지 확인하려면 그것을 실행하는 Runtime eval을 선언하세요. 다른
Artifact는 {name}으로 참조하세요. 리뷰어는 대상과 참조된 Artifact, 그것을 읽는 도구를 이미 알고 있으므로
지시문에 도구 이름을 적을 필요는 없습니다.
Agent 리뷰는 스키마로 검사한 GREEN 또는 RED 판정을 돌려줍니다. 모델이 잘못된 결과를 돌려주면 artifactize가 한 번 고쳐 달라고 요청하고, 그래도 잘못되면 리뷰는 ERROR가 됩니다. Agent 응답에서 결과, 검사, 수정 요청 턴을 설명합니다.
재시도, 도구 결과, 사용량 수치는 Agent 백엔드에 있습니다.
Agent 프로필 제한
Agent 프로필에서 max_tokens와 max_tool_calls로 리뷰의 한도를 정할 수 있습니다.
profile = { kind = "agent", backend = "codex", model = "YOUR_EXACT_MODEL_ID", max_tokens = 100000, max_tool_calls = 100 }
모델 서비스는 입력과 출력 텍스트의 양을 토큰 단위로 셉니다. 토큰은 단어보다 작은 텍스트 조각일 수 있습니다. 로그인이나 리뷰
저장소의 토큰과는 상관없습니다. 두 예산 모두 선택 항목이며 1부터 9007199254740991까지의 정수를
받습니다. 생략하면 그 예산은
무제한입니다. 이는 provider의 생성 매개변수가 아니라 클라이언트 쪽 리뷰 예산입니다.
max_tokens로 제한하는 사용량은 모든 턴, 수정 요청 턴, 다시 보낸 턴의 모든 시도에서 응답에 보고된 total_tokens를 합산한 값입니다(보고된 캐시 읽기·쓰기 포함). 합계가 보고되지 않으면 0으로 셉니다. 사용량은 응답을 받은 뒤에
확인하고 합계가 한도를 넘을 때만 실패로 처리하므로, 실제 사용량은 한도를 넘을 수 있으며 이 설정이 생성량이나 비용의 엄격한
상한이 되지는 않습니다.
max_tool_calls는 도구를 실행하기 전에 호출 시도를 세며, 성공한 호출뿐 아니라 모르는 도구,
잘못된 호출, 실패한 호출도 포함합니다. 둘 중 하나라도 넘으면 PROVIDER_BUDGET_EXCEEDED로
작업을 멈춥니다. 수정 요청과 재시도에도 원래 리뷰의 제한 시간과 예산을 적용하며, 예산을 추가하지 않습니다.
Agent 도구
리뷰어에게 필요한 읽기 전용 도구를 선언하세요. 내장 도구, 사용자 정의 명령, 호출 사이에 테스트 하네스를 계속 실행해 두는 세션은 도구에서 설명합니다. 아래의 저장된 Agent 대화는 도구 세션과 별개입니다.
Agent 백엔드
Agent 프로필, 백엔드, reasoning은 위의 Agent 리뷰에 있습니다. models
출력의 JSON 형태는 로컬 진단과 유지보수에
있습니다.
Agent 리뷰에서는 모델이 답변을 생성하는 동안 그 내용을 스트리밍으로 받습니다. 리뷰 전체의 제한 시간은
기본 240초이며, 모든 턴, 재시도, 도구 실행에 걸린 시간을 합쳐 셉니다.
Anthropic 응답은 리뷰의 max_tokens와 별개로 턴마다 출력 토큰 16384개로도
제한됩니다.
재시도와 오류 코드
출력이나 토큰 사용이 생기기 전에 사용량 제한이나 일시적인 오류로 턴이 실패하면, provider가 안내한 만큼
기다렸다가 몇 차례 재시도합니다. claude-agent 리뷰는 Claude Code가 요청을 직접 재시도하므로 다시 보내지
않습니다(Claude Agent). 답변이 나오기 시작한 뒤에 실패한 턴(DEGENERATE_OUTPUT, 출력이
끝나지 않은 PROVIDER_ERROR, TRANSIENT)도 같은 횟수까지 재시도하며, 그 토큰은 max_tokens에 포함됩니다.
출력이나 사용량이 생긴 뒤의 다른 실패는 재시도하지 않습니다. 재시도로도 해결되지 않거나 provider가 요구한
대기 시간이 리뷰의 남은 시간보다 길면, 리뷰는 마지막 시도의 코드와 함께 ERROR로 끝납니다. 잠시 뒤
verify를 다시 실행하세요(완료된 결과는 재사용됩니다). 같은 식으로 계속 끝나면 다른 모델이나
reasoning을 써 보세요. 시도마다 수치, error, errorCode가 usage에 저장됩니다.
프롬프트 캐싱
provider는 매 턴 반복되는 대화 부분을 캐시하므로, 리뷰 후반에는 턴당 비용이 줄어듭니다. 얼마나
캐시되었는지는 usage에 있는 시도별 cacheReadTokens 수치로 확인하세요(verify --wait --json, run show, request show, session show --summary). 강제로 실행한 리뷰도 포함해 리뷰는 매번 새로 시작합니다. follow-up은 그 리뷰의 대화를 이어 가므로 캐시를
쓸 수 있습니다. 캐시 적중 여부는 provider가 정합니다. anthropic follow-up은 답이 판정이 아닌
일반 텍스트라서 대개 캐시가 적중하지 않습니다.
실패한 Agent 리뷰는 다음 errorCode 중 하나를 기록합니다.
errorCode | 원인 | 재시도 |
|---|---|---|
AUTHENTICATION | 자격 증명이 없거나 만료됐거나 거부된 경우입니다. HTTP 401/403, API 키나 Codex 로그인이 없는 경우, 만료된 인증 파일, PATH에 claude가 없거나 Claude Code가 로그아웃된 경우가 여기에 해당합니다 | 하지 않습니다. 백엔드를 멈춥니다 |
QUOTA | 결제, 크레딧, 요금제 사용량 한도(insufficient_quota, Codex 사용량 한도, Claude 구독 사용량 한도) | 하지 않습니다. 백엔드를 멈춥니다 |
RATE_LIMIT | 할당량 문제가 아닌 HTTP 429입니다. 재시도 뒤에도 실패했거나, Retry-After에 따른 대기 시간이 리뷰의 남은 시간 이상인 경우입니다 | 합니다 |
TRANSIENT | 연결 실패, HTTP 5xx나 과부하, 끊긴 스트림입니다. 요청한 재시도 대기가 너무 길어도 이 분류를 유지합니다 | 합니다. 출력 뒤에는 그 턴을 다시 보냅니다 |
TIMEOUT | 리뷰의 timeout_ms 제한 시간 | 하지 않습니다 |
CANCELLED | Run을 직접 취소했습니다(run cancel 또는 MCP verify_cancel) | 하지 않습니다 |
PROVIDER_BUDGET_EXCEEDED | max_tokens나 max_tool_calls를 넘었습니다 | 하지 않습니다 |
INVALID_RESULT | 형식 수정을 한 번 요청한 뒤에도 유효한 판정이 없습니다 | 하지 않습니다 |
DEGENERATE_OUTPUT | 모델 답변이 긴 공백으로만 계속되어 리뷰가 중단됐습니다 | 합니다. 그 턴을 다시 보냅니다 |
PROVIDER_ERROR | 그 밖의 provider 실패: 거부된 요청, 알 수 없거나 요청과 다른 모델, 끝나지 않은 응답, 잘못된 도구 호출 | 출력 한도에서 끊긴 답변(Length)만 그 턴을 다시 보냅니다 |
AGENT_ERROR | 그 밖의 모든 경우입니다. 예를 들어 잘못된 테스트 엔드포인트나 쓸 수 없는 도구가 해당합니다 | 하지 않습니다 |
BACKEND_STOPPED | 시작하지 않습니다. 그 Run에서는 그 백엔드로 새 리뷰를 보내지 않습니다 | — |
provider 오류 메시지에 artifactize가 보낸 자격 증명의 일부가 포함되어 있으면, 표시하거나 저장할 때
그 메시지를 [withheld: it contained part of the credential sent]로 대체합니다. 추가 결과 필드와
명령 출력은 이렇게 가리지 않습니다.
Ctrl-C로 verify --wait를 중단해도 진행 상황 표시만 멈추며, Agent 리뷰와 Run은
계속 실행됩니다. 직접 취소를 요청해야 Run의 작업이 멈춥니다.
백엔드 멈추기
AUTHENTICATION이나 QUOTA 실패는 같은 백엔드의 모든 리뷰에서 똑같이 반복되므로, 그 Run에서는 그 백엔드로 새 리뷰를 보내지 않습니다. 이후 그 Run에서 같은 백엔드로 실행하려던 리뷰는 시작하지 않고
BACKEND_STOPPED인 ERROR가 되며, 오류 메시지에 원래 실패가 나옵니다. 그 백엔드에 실행 자리가 없어 대기 중이던 요청(백엔드 수용량)도 대기열에서 빠져 같은 방식으로 BACKEND_STOPPED인 ERROR가 되며, 멈춘 백엔드는 자리를 차지하지 않습니다. 이미 실행 중이던 리뷰는 끝까지 실행되고,
재사용할 수 있는 결과는 계속 재사용하며, 다른 백엔드는 그대로 진행합니다. Run은 멈춘 백엔드를
stoppedBackends(verify --wait --json과 run show)에 남기고, verify는 이렇게 출력합니다.
Stopped backend openai after AUTHENTICATION in docs/review: 2 reviews not started.
다음 Run에서는 그 백엔드를 다시 쓸 수 있습니다.
eval의 범위에 있는 도구만 제공하며, 도구는 하나씩 차례로 실행됩니다. 각 도구가 무엇을 받고
돌려주는지는 Agent 도구에 있습니다. PNG/JPEG/WebP 결과는 모든 백엔드에
보내며, 이미지를 지원하지 않는 모델은 provider의 오류로 실패합니다. 요청의 시도별 usage는 성공했을 때와 ERROR일 때 모두 저장합니다. 캐시가 적중하면 해당 시도의 사용량을 reusedUsage에 기록하고, 이번 실행에서 발생한 사용량에는 포함하지 않습니다. 수치는 provider가 보고한 값(0으로 보고한 경우 포함)이며, 추정한 합계나
비용이 아닙니다. Anthropic의 inputTokens는 캐시하지 않은 입력만 센 값이고 캐시 읽기·쓰기
수치는 따로 있습니다. OpenAI의 입력에는 캐시 읽기가 이미 포함되어 있습니다. 모든 수치를 더하지
마세요. 보고되지 않은 필드는 빠집니다. 요청에는 판정, 결과, 사용량이 남고, 메시지, reasoning,
도구 호출과 그 인자, 결과는 리뷰의 저장된 대화에만 있습니다.
session show --summary가 이를 집계합니다.
백엔드를 본격적으로 쓰기 전에, 계정에서 쓸 수 있는 정확한 모델 ID와 선언한 도구 하나로 간단한 시험용 리뷰를
한 번 실행하고 run show로 결과를 확인하세요. 모델 없이 도구와 스키마를 시험하려면
가짜 provider를 쓰세요.
저장된 대화
artifactize는 Agent 리뷰 대화를 이 머신에 저장합니다. 그래서 저장된 대화에서 리뷰어가 무엇을 보고 어떤 답변을 했는지 확인하고, 채팅하듯 follow-up을 보낼 수 있습니다. 기록된 판정은 절대 바뀌지 않습니다.
저장되는 내용. 리뷰 세션은 내 계정만 읽을 수 있는 곳에 저장합니다 (저장소). 지시문, 모든 메시지, 도구 호출과 그 결과, 수정 요청 턴, 토큰 수, 리뷰에 쓴 설정이 들어 있습니다. 저장에 실패해도 리뷰는 실패하지 않습니다. 쓰기 오류는 stderr에 출력하고 리뷰는 저장 없이 계속됩니다.
참조. 대화가 저장된 요청을 verify --wait --json, run show, request show로 확인하면 session 필드가 나옵니다.
"session": {
"producer": "alice@laptop",
"state": "34bb3c3a-9480-4a54-9ab3-3bce54e043b8",
"runId": "run-FiVNCV",
"requestId": "run-FiVNCV-1",
"sessionId": "e83bf374-5136-484c-8d2f-2ce38ee4ca57",
"ref": "alice@laptop/34bb3c3a-9480-4a54-9ab3-3bce54e043b8/run-FiVNCV/run-FiVNCV-1/e83bf374-5136-484c-8d2f-2ce38ee4ca57"
}
producer는 리뷰를 실행한 user@host이고, state는 그 상태 데이터베이스의 고정 ID입니다.
결과를 재사용한 요청은 그 결과를 만든 리뷰를 가리킵니다. 팀 리뷰 저장소는
Agent 결과마다 대화가 아니라 이 참조만(producer.session으로) 함께 보내므로, 팀원의 판정을 보면
그 대화가 어느 팀원의 상태 디렉터리에 저장되어 있는지 알 수 있습니다.
저장된 대화는 session show로 읽고, session show --summary로 집계하고, session send로
follow-up을 보냅니다. Agent 세션을 보세요.
Codex
codex 백엔드는 사용 중인 ChatGPT 요금제에서 이용할 수 있는 Codex 모델(gpt-6-luna, gpt-6.1-sol 등)로 리뷰합니다.
artifactize login codex # sign in to ChatGPT in the browser
artifactize models codex # the account's Codex models
# Declare backend = "codex", model = "gpt-6-luna", reasoning = "max", then:
artifactize verify --all --wait
artifactize logout codex # delete artifactize's tokens; their revocation is attempted
-
로그인.
login codex는 Codex CLI처럼 브라우저에서 ChatGPT 로그인 페이지를 열고, 로그인하면 artifactize로 돌아옵니다. 브라우저 단계, 주소를 붙여 넣는 대체 방법, 5분 제한은 로그인 설정에 있습니다. 토큰과 ChatGPT 계정 ID는 나만 읽을 수 있는$STATE/auth/codex.json에 저장합니다.login,models,verify에는 같은--state-dir을 쓰세요. 토큰은 절대 저장소 안에 저장하지 않습니다.$STATE/auth가 git 워크트리, artifactize 작업 공간,--repo안에 있으면login codex는 그 폴더 경로를 알려 주며 로그인을 거부하고doctor는 경고합니다(상태). 저장소 바깥의 상태 디렉터리나ARTIFACTIZE_CODEX_AUTH_FILE을 쓰세요. artifactize는 액세스 토큰이 만료되기 전에 갱신합니다. 서버가 갱신 토큰을 더 이상 허용하지 않으면 artifactize는 저장된 토큰을 지우고, 리뷰는 다시 로그인하라는 오류로 끝납니다. -
기존 Codex 로그인 사용하기. 예를 들어
ARTIFACTIZE_CODEX_AUTH_FILE을~/.codex/auth.json으로 설정하면, artifactize에 저장된 토큰 대신 매 턴 그 파일의tokens.access_token(과tokens.account_id)을 읽습니다. 지정한 파일은 1 MiB 이하의 일반 파일이어야 하며, 그렇지 않으면 거부되어 로그인 정보로 쓰이지 않습니다. 그 파일을 쓰거나 복사하거나 갱신하지는 않습니다. 토큰 만료까지 남은 시간이 1분 이하이면 리뷰는codex login등으로 Codex에 다시 로그인하라는 메시지와 함께 실패합니다.logout codex는 그 파일을 건드리지 않습니다. -
요청. provider는 대화를 보관하지 않습니다. 선언한
reasoning은max를 포함해 그대로 보내며, reasoning 요약은 Monitor에 나옵니다. 재시도, 예산, 도구 결과, 프롬프트 캐싱, 사용량은openai와 같습니다. -
오류. 사용량 한도는
QUOTA이며, 요금제와 초기화 시각을 알려 주고 그 Run에서codex를 멈춥니다. 단순한 HTTP 429는RATE_LIMIT이며 재시도합니다. HTTP 401과 403은AUTHENTICATION이며 다시 로그인하는 방법을 알려 줍니다. 토큰을 갱신할 때 토큰 엔드포인트에 연결하지 못하거나 오류 응답을 받으면TRANSIENT로 분류합니다. -
모델.
models codex는 지금 계정으로 Codex 모델 선택기에서 고를 수 있는 모델을 서버가 보내 준 순서대로 나열합니다. 프로필에는 목록에 표시되지 않더라도 계정에서 사용할 수 있는 모델을 지정할 수 있습니다.
Claude Agent
claude-agent 백엔드는 사용자의 Claude Code를 통해 리뷰하며, Claude Code에
로그인한 계정을 그대로 사용합니다. Claude Pro·Max 구독이나 API 키, 클라우드 계정으로 로그인한 Claude Code를
사용할 수 있습니다.
artifactize login claude-agent # runs Claude Code's own claude auth login
artifactize models claude-agent # the models Claude Code offers
# Declare backend = "claude-agent", model = "claude-opus-5-5", reasoning = "high", then:
artifactize verify --all --wait
- 로그인. 로그인 정보는 Claude Code가 직접 보관합니다.
login claude-agent와 데스크톱 앱의 Settings → Providers → Claude Agent는 Claude Code 자체 명령인claude auth login을 실행합니다. Claude Code가 브라우저를 열고, 열리지 않았을 때 열 URL을 출력하며, 페이지에 나온 코드는 터미널이나 데스크톱 앱의 코드 입력란에 붙여 넣을 수 있습니다. 로그인은 Claude Code가 종료되면 끝나며(로그인 성공 또는 Claude Code의 오류), 10분이 지나면 멈춥니다.logout claude-agent는claude auth logout을 실행합니다. 데스크톱 앱은claude auth status가 알려 주는 대로 로그인 방식과 요금제를 보여 주며, 계정 정보는 보여 주지 않습니다. artifactize는 로그인 정보를 읽거나 복사하거나 저장하지 않으며, Claude Code와 서비스 사이에 끼어들지도 않습니다. 직접claude auth login으로 로그인해도 똑같이 쓸 수 있습니다.PATH에 2.1.248 이상의claude가 있어야 하며, 그보다 오래된 버전이면claude update를 실행하라는 메시지와 함께 거부합니다.doctor는claude를 실행하지 않고 위치만 보여 줍니다. - 리뷰. 리뷰어는 eval에 선언한 Artifact 도구만 쓸 수 있으며,
max_tool_calls,max_tokens, 마감 시간도 다른 백엔드와 같습니다. 그 밖의 Claude Code 설정은 리뷰에 쓰이지 않습니다. Claude Code 자체 도구, Claude Code 설정, 훅,CLAUDE.md, 메모리, 스킬, MCP 서버는 모두 빠지고, 리뷰 내용이 내 Claude Code 세션 목록에 남지도 않습니다. 선언한 모델과reasoning을 그대로 쓰며, Monitor에는 모델의 thinking 요약과 답변이 나오는 대로 표시됩니다. 판정과 형식 수정 요청 한 번은 다른 백엔드와 같습니다. - 오류. Claude Code가 실패한 요청을 직접 재시도하므로 artifactize는 다시 보내지 않습니다.
구독 사용량 한도에 걸리면
QUOTA이며, 어느 구간(5시간 또는 주간)인지와 초기화 시각을 알려 주고 그 Run에서claude-agent를 멈춥니다. Claude Code가 로그아웃된 상태면AUTHENTICATION이며claude auth login을 실행하라고 알려 줍니다. 결제 문제는QUOTA입니다. - 사용량. 응답 하나가
usage의 시도 하나이며, Claude Code가 알려 준 토큰 수를 기록합니다. 구독에서는 비용이 나오지 않습니다. - 모델.
models claude-agent는 모델을 호출하지 않고, Claude Code가 지금 로그인으로 제공하는 모델을model에 쓰는 모델 ID로 나열합니다. 프로필에는 목록에 없더라도 Claude Code가 받는 모델을 지정할 수 있습니다. - follow-up. 다른 백엔드와 마찬가지로
session send로 follow-up을 보낼 수 있습니다. 리뷰어는 리뷰 대화를 바탕으로 일반 텍스트로 답하며, 필요하면 Artifact를 다시 읽습니다. 기록된 판정은 바뀌지 않습니다.
커스텀 provider
프로젝트에는 provider 이름만 적습니다. 그 이름이 어디로 연결되는지는 eval을 실행하는 머신마다
따로 설정합니다. 커스텀 provider는 Agent 프로필의 backend에 쓸 수 있는 이름으로, 데스크톱 앱의
Settings → Providers에서 + Custom provider를 누르거나 artifactize provider로 추가합니다.
종류는 둘 중 하나입니다.
-
별칭(alias): 기본 provider를 다른 이름으로 쓰며, 그 provider의 로그인이나 키를 그대로 씁니다.
artifactize provider add work --alias codex -
엔드포인트: API, 루트 URL, 키(선택)를 지정합니다. API는
openai-responses,openai-chat(호환 서버 대부분이 지원하는 Chat Completions),anthropic,gemini중 하나입니다.--key를 주면 키를 명령줄이 아닌 stdin에서 읽습니다.artifactize provider add local --api openai-chat --url http://localhost:11434/v1 printf '%s\n' "$ROUTER_KEY" | artifactize provider add router --api openai-chat --url https://openrouter.ai/api/v1 --key
URL은 요청을 보낼 API 루트로, 기본 provider의 루트(https://api.openai.com/v1,
https://api.anthropic.com, https://generativelanguage.googleapis.com)와 같은 형태입니다. http://나
https://로 시작하고 호스트가 있어야 하며, 자격 증명(user:pass@), 쿼리(?…), 프래그먼트(#…)가 든 URL은
거부합니다. 키는 따로 입력하기 때문입니다. 끝의 /는 지웁니다. 이미 있는
이름으로 provider add를 실행하면 그 provider를 바꾸고, provider remove NAME은 삭제합니다.
provider list는 커스텀 provider 전체와 기본 provider의 키를 어디서 가져오는지 보여 주며, 키 값은
보여 주지 않습니다. 기본 provider의 이름은 커스텀 provider 이름으로 쓸 수 없습니다.
profile = { kind = "agent", backend = "local", model = "YOUR_EXACT_MODEL_ID" }
이 머신에 등록되지 않은 provider를 지정한 리뷰는 AUTHENTICATION ERROR로 끝나며,
오류 메시지에 그 provider 이름이 표시됩니다. 키와 커스텀 provider는 본인만 읽을 수 있는 $STATE/auth/providers.json에
저장되고, 저장소 안에는 저장되지 않습니다. 이 파일은 최대 1 MiB까지만 읽습니다. 이를 넘으면 provider를 읽거나 바꾸는
명령이 모두 Credential file is too large. 오류로 실패하며, logout과 provider remove도 마찬가지라
이 명령으로는 파일을 줄일 수 없습니다. 대신 providers.json을 $STATE/auth/ 밖으로 옮겨 백업으로 두고,
계속 쓸 키와 provider를 login과 provider add로 다시 저장하세요. provider도 모델, reasoning과 마찬가지로 실행 옵션이라 결과마다
기록되지만 재사용 키에는 들어가지 않습니다.
가짜 provider로 테스트하기
모델 없이 도구, 스키마, 결과 해석을 시험하려면 백엔드를 이 머신의 가짜 provider에 연결하세요. 아래 변수로 provider의 API 루트를 바꿀 수 있습니다.
| 백엔드 | 변수 | 예 | 가짜 provider가 응답할 요청 |
|---|---|---|---|
openai | ARTIFACTIZE_OPENAI_BASE_URL | http://127.0.0.1:8080/v1 | POST <root>/responses, GET <root>/models |
anthropic | ARTIFACTIZE_ANTHROPIC_BASE_URL | http://127.0.0.1:8080 | POST <root>/v1/messages, GET <root>/v1/models |
gemini | ARTIFACTIZE_GEMINI_BASE_URL | http://127.0.0.1:8080 | POST <root>/v1beta/models/<model>:streamGenerateContent, GET <root>/v1beta/models |
codex | ARTIFACTIZE_CODEX_BASE_URL | http://127.0.0.1:8080/backend-api/codex | POST <root>/responses, GET <root>/models |
| Codex 로그인 | ARTIFACTIZE_CODEX_AUTH_URL | http://127.0.0.1:8080 | POST <root>/oauth/token과 <root>/oauth/revoke입니다. login codex는 브라우저를 <root>/oauth/authorize로 보냅니다 |
- 루트는
localhost,127.0.0.0/8,[::1]의http://나https://여야 하며, 자격 증명, 쿼리, 프래그먼트가 없어야 합니다. 그 밖의 값이면 연결하기 전에 리뷰,models,doctor가 그 변수 이름을 알려 주며 실패합니다. 빈 값은 설정하지 않은 것으로 간주합니다.anthropic은 끝에/v1이 붙어도 됩니다. - 이때도 키(변수나 저장한 키)가 필요하고 가짜 provider에 그대로 전달되므로 아무 값이나 넣어 두세요.
커스텀 엔드포인트에는 변수가 필요 없으며, URL을 가짜 provider 주소로 지정하면 됩니다.
codex는ARTIFACTIZE_CODEX_AUTH_FILE을{"tokens":{"access_token":"dummy","account_id":"test"}}같은 파일로 지정하세요. - 그 밖에는 바뀌는 것이 없습니다. 요청 본문과 스트리밍, 재시도, 예산, 도구 호출, 수정 요청, 판정 검사가 모두 같습니다.
- 결과는 다른 결과처럼 기록되고 재사용되므로 버려도 되는 상태 디렉터리(
--state-dir나ARTIFACTIZE_STATE_HOME)를 쓰세요. 테스트 엔드포인트가 설정되어 있으면verify가 리뷰 저장소 사용을 거부하므로ARTIFACTIZE_REMOTE=off로 설정하세요. 가짜 결과가 든 상태는 절대remote push하지 마세요. - 테스트 엔드포인트가 설정되어 있는 동안
doctor는 경고하고 이를testEndpoint로 알립니다. claude-agent에는 테스트 엔드포인트가 없습니다. Claude Code가 서비스에 직접 연결하기 때문입니다.
가짜 provider는 요청에 지정된 모델의 응답을 해당 provider의 전송 형식에 맞춰 text/event-stream으로 스트리밍합니다.
openai라면 response.completed 이벤트 하나면 됩니다. GREEN 스키마가 {"verdict":"GREEN"}만으로 충족되는 리뷰는 이 가짜 provider로 통과시킬 수 있습니다. pass_schema에 다른 필드가 필요하면
가짜 provider의 text 응답에 그 필드의 유효한 값을 넣으세요. 그러지 않으면 응답이 스키마에 맞지
않아 artifactize가 한 번 수정을 요청하고, 수정한 응답도 맞지 않으면 INVALID_RESULT가 됩니다.
#!/usr/bin/env python3
"""A fake OpenAI Responses provider on loopback that returns a verdict-only GREEN response."""
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
class Fake(BaseHTTPRequestHandler):
def do_POST(self):
request = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
text = json.dumps({"verdict": "GREEN"})
response = {
"id": "resp_fake", "object": "response", "created_at": 0,
"model": request["model"], "status": "completed",
"output": [{"type": "message", "id": "msg_fake", "role": "assistant",
"status": "completed",
"content": [{"type": "output_text", "text": text, "annotations": []}]}],
"usage": {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
}
event = {"type": "response.completed", "sequence_number": 0, "response": response}
body = f"event: response.completed\ndata: {json.dumps(event)}\n\n".encode()
self.send_response(200)
self.send_header("Content-Type", "text/event-stream")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
HTTPServer(("127.0.0.1", 8080), Fake).serve_forever()
python3 fake_openai.py &
export ARTIFACTIZE_OPENAI_BASE_URL=http://127.0.0.1:8080/v1 OPENAI_API_KEY=dummy
ARTIFACTIZE_REMOTE=off artifactize --state-dir "$(mktemp -d)" verify --all --wait
명령 도구를 모델 없이 따로 시험하려면
tools check --execute를 쓰세요. 입력과 출력은
명령 도구 프로토콜을 따릅니다.
Agent 응답
GREEN이나 RED 결과에 무엇이 들어갈지는 pass_schema와 fail_schema로 선언합니다
(결과 필드 스키마). 이 페이지는 Agent가 무엇을 돌려줘야
하는지, artifactize가 이를 어떻게 확인하는지, 실패하면 run show에서 무엇을 보게 되는지
설명합니다. 설정 방법과 기본 사용법은 Agent eval과 백엔드를 보세요.
최종 출력과 검사
Agent는 먼저 도구를 호출할 수 있고, 그다음 provider의 구조화된 출력으로 최종 답을 냅니다. 이
출력은 결과 필드 스키마에 맞도록 제한됩니다. 저장되는
결과는 "verdict":"GREEN"이나 "verdict":"RED"와, 그 판정의 스키마가 허용하는 추가 결과 필드를
함께 담은 객체 하나입니다. session send의 follow-up 답변은 일반 텍스트입니다.
provider가 검증하지 못하는 키워드도 artifactize가 결과 필드 스키마로 직접 검사하므로, 선언한 JSON Schema 제약 조건이 모두 적용됩니다. 답이 스키마에 맞지 않으면 Agent에게 무엇이 잘못됐는지 알리고 도구를 쓰지 않은 채 한 번 더 답하게 합니다. Agent는 이미 모은 정보로 답해야 하며, 이때
도구를 요청해도 리뷰는 INVALID_RESULT로 끝납니다. 저장된 대화에 그 메시지가 나옵니다.
Your final response did not match the required schema: schema_mismatch: result must match the selected verdict's owner schema
- instancePath "/covered": "R1" is not of type "array"
Return only one JSON object matching the schema.
그 답도 잘못되면 리뷰는 INVALID_RESULT와 함께 ERROR로 끝납니다.
session show로 Agent가 무엇을 답했는지 읽고, 스키마와 지시문이 서로 맞도록 고친 다음 다시 verify하세요. 예를 들어 각 필드에 무엇이 들어가야 하는지 지시문에 적을 수 있습니다. artifactize는 max_tokens와 max_tool_calls에 따라 토큰 수와 도구 호출 수를 세며, 예산을 다 쓰면 더 이상 도구를 호출하지 못하게 합니다. 이 값들은 provider에게 보내지 않습니다.
Human 리뷰
Human eval은 사람에게 리뷰를 요청하고 GREEN이나 RED 판정을 받습니다. 리뷰어는 대기 중인 요청을 맡고,
선언한 Human 도구를 실행하고, artifactize request 명령이나 artifactize review 터미널 UI로
판정을 제출합니다.
사람은 Artifact의 자동 eval을 이미 통과한 것만 승인합니다. 상위 승인이 남아 있어
PROVISIONAL로 보이는 GREEN 판정도 통과한 것으로 칩니다. 자동 eval이 아직 실행 중이면
Human eval은 대기 상태(WAIT_DEPENDENCY)로 남고, 그중 하나가 RED나 ERROR면 BLOCKED가 되며 사유에 해당 eval이 표시됩니다. Human 승인을
보세요.
eval 준비가 끝나면 artifactize는 사람이 판정해야 하는 요청을 DEFERRED 상태로
기록합니다. 이 요청은 다른 작업을 막지 않습니다. 사람이 판정을 제출할 때까지는 Run의 --jobs 실행 자리도,
--max-executions 예산도 쓰지 않으며, 그 예산이 0이어도 마찬가지입니다. 그 승인에 의존하는 eval은 바로
실행하며, 그 eval의 GREEN 결과는 승인이 GREEN이 될 때까지 PROVISIONAL로 표시되고, eval 자체의 RED나 ERROR는
그대로 표시됩니다. 다른 작업이 아직 실행 중일 수 있으니, 최종 상태를
리뷰하려면 그 작업이 끝날 때까지 기다리세요. 모든 승인은 review, Monitor, 데스크톱, 요청 목록에 나오고, 담당
지정과 해제, 도구 실행, 판정 제출 때 Human 권한을 확인합니다. 막힌 승인은 사람에게 보여 주지 않습니다. 진행 상황을 지켜보거나 터미널을 닫아도 승인이나 거부가 제출되지는 않습니다. 제출, 지켜보기, 직접 취소는
Run 수명 주기에서 설명합니다.
요청을 맡은(claim) 리뷰어가 담당자가 됩니다. 이와 별개로, 승인이 필요한 다른 Run은
입력과 프로필이 같으면 체크아웃 위치와 관계없이 새 요청을 만들지 않고 이미 대기 중인 리뷰에
합류합니다. 이렇게 합류한 요청을 팔로워라고 합니다. 팔로워를 통해 Human 작업을 해도 결과는 원래 요청이 저장된 저장소의 해당 요청에 반영됩니다. --force는 합류하지 않고 새 승인을 요청하지만, 새 요청에서도 사람이 먼저
맡아야 도구를 실행하거나 판정을 제출할 수 있습니다.
리뷰한 입력이 그대로면 기존 승인 결과를 기본적으로 재사용합니다. 이후 verify는 제출된
결과를 재사용하고 그 결과를 쓰는 eval을 리뷰할 수 있습니다. 대상이나 포함한 의존성에
fingerprint = false가 있으면 승인은 현재 Run에만 적용되므로, 다음 Run에서는 사람이
다시 판정해야 합니다. Run의 검증 결과는 그 시점에 확보된 결과를 기준으로 확정되며, 나중에 승인을 제출해도 지난 Run의
판정은 바뀌지 않습니다.
아래 명령 표기에서 대괄호로 묶은 부분은 생략할 수 있으며, 입력할 때 대괄호는 빼세요. 대문자로 쓴
부분은 바꿔 넣을 값입니다. REQUEST_ID에는 request list가 출력한 실제 요청 ID를 넣고, NAME에는
리뷰어 이름을 넣으세요.
artifactize verify --all --wait
# In another terminal, using the same state directory:
artifactize request list [--run RUN_ID] [--json]
artifactize request show REQUEST_ID
artifactize request claim REQUEST_ID [--reviewer NAME]
artifactize request unclaim REQUEST_ID [--reviewer NAME] # release without a verdict
artifactize request tool REQUEST_ID inspect_child [--reviewer NAME]
artifactize request submit REQUEST_ID --verdict GREEN --fields '{"approved":true}'
# Alternatively: --fields-file /path/to/fields.json
# Or claim, run tools and submit in a terminal UI (see Review):
artifactize review [REQUEST_ID]
이 명령들의 옵션, 출력, 종료 코드는 모두 Human 요청에 있습니다.
Run의 종료 코드를 보면 지켜보기만 중단한 경우, Run을 직접 취소한 경우,
최종 검증 요건을 충족하지 못한 경우를 구분할 수 있습니다. verify --reuse-only human은 Human 요청을 기록하지 않으며 결과가 나올 때까지 대기하지도 않습니다. CI에서는
Human eval이 기존 승인을 재사용하고, 재사용할 승인이 없으면 실행되지 않습니다.
request list와 request show의 필드, Run 요약은 레퍼런스에
있습니다.
승인과 Run
진행 중인 Run은 제출되지 않은 승인이 하나라도 있는 동안 WAITING_HUMAN입니다. 남은 작업이 승인뿐이면
리뷰어가 그중 하나를 맡고 있는 동안, 그리고 승인 유예 시간(따로
바꾸지 않았다면 2분) 동안 Run은 종료되지 않습니다. 그 시간 안에 승인을 맡아 제출하면 Run은 그 결과에 따라 GREEN이나
RED로 끝납니다. 아무도 맡지 않으면 Run은 YELLOW(종료 코드 5)로 끝나며, 승인만 남았다는 뜻입니다. 그 뒤에도
승인을 제출할 수 있고, 다음 verify가 그 결과를 재사용합니다. 자세한 내용은
승인과 Run 종료에 있습니다. 이 재사용에는 fingerprint가 필요하므로
fingerprint = false면 재사용하지 않습니다.
같은 워크트리에서 같은 eval에 더 새로운 요청이 오면, 재사용 키가 다른 이전 DEFERRED 승인은 끝나고 Review에서 사라집니다. 이전 승인이 종료되는 조건과 리뷰 합류 방식, Run이 끝난 뒤 승인을 제출하는 방법은 Run 규칙을 보세요.
CI 설정은 대기 중인 승인을 병합 게이트에서 빼기를 보세요.
Human 도구
리뷰어가 쓸 도구는 views.human_tools 아래에 도구마다 이름을 붙여 적으세요. 도구는
리뷰어가 실행하며, 실행할 때 임의의 인자를 덧붙일 수는 없습니다. 내장 도구는 Linux, macOS, Windows에서
똑같이 동작합니다. open은 파일, 폴더, http(s) URL을 데스크톱의 기본 애플리케이션으로 열고,
graph는 현재 프로젝트 그래프 뷰어를 실행합니다. read, list, section, help는 터미널에
텍스트를 출력합니다.
[views.human_tools]
open = { description = "Open the review notes of {artifactName}.", builtin = "open", args = ["{artifactPath}/notes.md"] }
notes = { description = "Print the review notes of {artifactName}.", builtin = "read", args = ["{artifactPath}/notes.md"] }
내장 도구는 builtin과 args, 선택 항목인 description을 받습니다. 종류는 도구에 따라
정해집니다. open과 graph는 프로그램 실행용이고, 나머지는 출력 표시용입니다.
명령 도구는 고른 프로그램을 실행합니다. description, kind, command, args는
필수 항목이며, kind는 "launch"나 "output"입니다. timeout_ms(1–2147483647)는
선택 항목입니다. input_schema, 호출할 때 임의로 넘기는 인자, protocol, execution_paths,
metadata, script 래퍼는 받지 않습니다. 설명은 {artifactName}을 포함해 Agent 설명 규칙을
따릅니다.
[views.human_tools]
edit = { description = "Open {artifactName} in VS Code.", kind = "launch", command = "code", args = ["{artifactPath}"] }
도구가 출력하는 내용은 리뷰가 열려 있는 동안 리뷰어의 Tool log에 실시간으로 나오며, 리뷰어가 결과에 복사해 넣을 수 있습니다.
자리 표시자, 실행 파일 찾기, launch와 output 종류는 레퍼런스에
있습니다.
결과 양식
리뷰어는 eval의 pass_schema(GREEN)나 fail_schema(RED)로 만든 양식에 결과를 입력합니다.
텍스트, 숫자, true/false, 선택지, 텍스트 목록, 반복해서 추가할 수 있는 필드 그룹이 있으며, 상수는 미리 채워집니다. Human eval의 스키마에는 이런 형태만 쓸 수 있습니다.
선언 레퍼런스에 지원하는 형태의 목록과 화면 표시 방식이
정리되어 있습니다.
Runtime
테스트, 린터, 렌더러처럼 종료 상태로 통과 여부를 판정할 수 있는 일반 프로그램을 실행하려면 Runtime eval을
선언하세요. 모델이나 API 키는 필요 없습니다. library 폴더라면 다음과 같습니다.
name = "library"
[evals.tests]
title = "The library tests pass"
profile = { kind = "runtime", command = "cargo", args = ["test", "--locked"], timeout_ms = 240000 }
payload.instruction = "Run the tests of {library}."
artifactize verify library/tests --wait는 거기서 cargo test --locked를 실행하고, 종료 코드가
0이면 library/tests [run-…]: GREEN을, 그렇지 않으면 RED를 출력합니다.
command와 args는 따로 씁니다. args의 항목은 하나씩 그대로 프로그램의 인자가 되며, 셸이
따옴표, 파이프, *를 해석하지 않습니다. 작업 디렉터리는 Artifact 폴더이고, 파일 Artifact라면
그 파일이 들어 있는 폴더입니다. 프로그램은 작성자가 평소 쓰는 도구 환경에서 실행되지만,
호출한 쪽의 artifactize 변수는 전달되지 않습니다. 출력과 임시 파일을 둘 공간은 저장소 밖에 따로 마련됩니다. 표준 입력은 비어 있어서 터미널 입력도
payload.instruction도 프로그램에 전달되지 않으므로, 필요한 값은 인자나 파일로 넘기세요. 실행 파일 찾기와 어느
OS에서나 동작하는 명령은 운영체제를 보세요.
시작에 실패하거나, 시간이 초과되거나, 실행이 중단되거나, 입력이 잘못되면 판정 대신 실행 오류로 처리합니다. 종료 코드가 0이어도 artifactize가 출력을 끝까지 받지 못하면 마찬가지입니다. stdout이나 stderr를 읽거나 저장할 수 없을 때, 또는 명령이 남겨 둔 보조 프로세스가 출력을 계속 열어 둘 때가 그렇습니다. 출력이나 저장 공간 문제를 고친 뒤 다시 verify하세요. Runtime 명령은 Agent나
Human의 추가 결과 필드를 돌려주지 않습니다. 실행이 끝나면 종료 코드와 stdout/stderr를 결과에 저장하며, 저장할 출력의 크기에는 제한이 있습니다. 프로그램이 실행 중일 때는
artifactize request logs REQUEST_ID로 지금까지 출력된 로그를 정해진 크기까지 읽을 수 있으며,
수집이 끝나지 않은 로그는 일부만 있다고 표시됩니다. 이 명령은 그 시점의 로그를 읽을 뿐이며, 로그를 실시간으로 계속
보내 주지는 않습니다. 로그의 끝부분이나 특정 범위를 읽는 방법, 로그를 검색하는 방법, 수집 상태는
Runtime 로그 CLI 레퍼런스에서 설명합니다. 로그
보관 기간과, 현재 정리 기능이 지우지 않고 남겨 두는 원본 로그는 공통
Runtime 실행 레퍼런스에서 설명합니다. CLI,
TUI, 데스크톱은 저장된 증거를 공통으로 읽습니다.
선언한 인자에 {spec}/requirements.json 같은 참조를 쓰면 그 Artifact가 입력이 됩니다. 명령이 실행되는
동안 fingerprint가 포함하는 파일이 바뀌면 판정 대신 ERROR(INPUT_CHANGED)가 됩니다.
fingerprint 밖의 파일은 확인하지 않으며, 재사용하지 않는 eval(fingerprint = false)은 다시
확인하지 않습니다. 이후 Run은 입력이 바뀌지 않았으면 RED 결과도 그대로 재사용하며, 명령을 다시
실행하지 않습니다. 정확한 한도, 환경, 치환, 프로세스 정리는 Fingerprint와
Runtime 실행 레퍼런스를 보세요.
Fingerprint와 재사용
artifactize verify --all --wait를 두 번 실행해 보세요. 두 번째에는 모든 eval이
GREEN (reused …)으로 나오고 아무것도 다시 실행되지 않습니다. 파일 하나를 바꾸고 다시
verify하면 그 파일에 의존하는 eval만 실행됩니다. fingerprint는 Artifact의 리뷰 결과에 영향을
주는 입력을 나타내는 값입니다. eval과 그 eval이 의존하는 Artifact의 fingerprint가 바뀌지 않았으면 이전 결과를 재사용하므로, 바뀐 부분의 리뷰만 다시 실행합니다.
Fingerprint
폴더, 파일, aspect Artifact는 기본으로 artifactsum을 씁니다. fingerprint를 생략하면 그 Artifact의 파일을
해시하고, 스크립트를 고를 수도 있습니다. 루트 그래프 Artifact는 항상
구조 기반 그래프 fingerprint를 쓰며, fingerprint를 선언해 그 값을
바꾸거나 끌 수 없습니다. 아래 방식으로 계산한 폴더·파일 Artifact의 fingerprint에는 도구 선언이나 다른 Artifact의
값이 들어가지 않습니다. 의존하는 Artifact의 fingerprint는 재사용 키에 반영됩니다.
- 생략하면 artifactsum을 씁니다. 그 Artifact의 입력 경로와 내용을 SHA-256으로 해시한 값에
artifactsum:을 붙입니다. 폴더라면fingerprint = {}도 됩니다. 폴더는 그 안의 파일을, 파일 Artifact는 대상 파일 하나를, aspect는 고른 경로를 해시합니다. fingerprint = { script = { command = "hash", args = [] } }는 명령의 출력을 fingerprint로 씁니다. artifactize가 따로 해시를 계산하지 않으므로, 입력이나 스크립트가 바뀌어 다시 리뷰해야 한다면 그 변경을 모두 명령의 출력에 반영해야 합니다.fingerprint = false는 재사용을 끕니다.fingerprint = true는 거부합니다.
Artifactsum
Artifact의 파일이 바뀌거나, eval이 의존하는 Artifact의 fingerprint가 바뀌면 그 Artifact를 다시 리뷰합니다. 폴더 Artifact에서 해시할 파일 범위를 제한하려면 다음처럼 설정하세요.
fingerprint = { files = ["src"], ignore = ["*.log"] }
files: 그 Artifact의 폴더를 기준으로 한 중복 없는 경로 1–64개이며, 각 경로는 1024자까지입니다(이모지처럼 기본 다국어 평면 밖의 문자는 2자로 셉니다). 기본값은["."]이며, 그 Artifact에 속한 파일을 가리킵니다. 경로는 존재해야 하고 Artifact 안에 있어야 하며, 안에 선언된 폴더 Artifact를 가리키는 경로는 거부합니다. 디렉터리를 훑을 때 안에 선언된 폴더 Artifact와*.artf선언은 모두 건너뜁니다..artf파일을 직접 입력으로 적으면 알림 없이 건너뛰지 않고config check가 실패합니다. 이름이.artf로 끝나는 디렉터리가 있으면 잘못된 선언으로 처리하며 선언 찾기가 실패합니다. 전체의 해시에서는 모든 부분의 파일을 제외합니다. 옆에 있는 파일 Artifact의 대상, 안에 선언된 폴더의 내용, aspect가 고른 경로 모두 해당하며,files에 직접 적어도 제외합니다. 각 부분의 파일은 그 부분에서 한 번만 해시하고, 전체의 eval 키에는 부분의 fingerprint를 넣습니다.ignore: 그 Artifact의 폴더를 기준으로 한.gitignore형식의 glob 패턴을 최대 64개 지정할 수 있으며, 패턴은 중복될 수 없고 부정 패턴은 쓸 수 없습니다. 비어 있거나,#로 시작하거나, 제어 문자가 든 패턴은 안 됩니다. 이 패턴에 맞는 파일은.git,__pycache__/,*.pyc,target/,node_modules/같은 내장 ignore처럼 항상 제외합니다..gitignore에 적힌 패턴과 일치하는 파일도 git과 같은 규칙에 따라 제외합니다. 저장소 루트(--repo)에서 Artifact까지의 경로와 탐색 중인 하위 디렉터리에 있는.gitignore를 모두 적용합니다. 패턴은 그 파일이 있는 폴더를 기준으로 하고, 부정 패턴도 쓸 수 있으며, 하위 디렉터리의.gitignore규칙이 상위 디렉터리의 규칙보다 우선합니다.files에 직접 적은 파일은 선언 파일이 아니라면 어떤 패턴으로도 제외되지 않습니다.
파일 Artifact는 대상 파일만 해시합니다. artifactsum 형식을 직접 쓸 때는
fingerprint = { files = ["hero.png"] }처럼 그 파일만 적어야 합니다. 파일 Artifact에서는
fingerprint = {}, files = ["."], ignore([]라도)를 거부합니다. 기본값을 쓰려면 필드를
생략하고, 대상 파일 외의 입력까지 fingerprint에 반영하려면 스크립트를 쓰세요.
예전 dependencies fingerprint 옵션은 거부합니다. fingerprint는 그 Artifact만 포함합니다.
탐색 제한은 레퍼런스에, 스크립트 형식은
fingerprint 스크립트에 있습니다.
재사용 키
eval의 키에는 대상 Artifact, 대상의 모든 부분(그 부분의 부분까지),
지시문이나 Runtime 인자에서 이름으로 가리킨 Artifact의 fingerprint가 들어갑니다. 포함된 Artifact마다
이름, 종류, 자체 fingerprint를 한 번씩 넣습니다. 파일 부분이나 안에 선언된 폴더 부분이 바뀌면 전체의 파일이 바뀔 때와
마찬가지로 전체의 eval을 다시 리뷰합니다. status에서는 전체의 파일 변경과 구분해 어느 부분이
바뀌었는지 알 수 있습니다. 한 부분만 검사하는 eval은 그 부분에 선언하세요.
참조 관계는 여전히 한 단계만 반영합니다. 다른 Artifact를 참조해도 그 Artifact의 부분이나 그 eval이
참조한 Artifact까지 키에 넣지는 않습니다. fingerprint 스크립트는 인자에서 이름으로 가리킨 Artifact의
파일을 읽을 수 있습니다. eval의 기준이 바뀌거나, 키에 포함된 Artifact의 이름, 종류, fingerprint가
바뀌면 그 eval을 다시 리뷰합니다. 부분 관계로 키에 입력이 추가되어도 도구의 접근 범위가 늘어나지는
않습니다. 부분의 도구를 쓰거나 {part}로 파일을 가리키려면 eval에서 그 부분을 참조해야 합니다.
부분을 반영하는 키로 업그레이드하면 첫 verify에서 부분이 있는 대상의 eval을 한 번 다시 리뷰합니다.
Human 승인도 해당하며, 스크립트 출력이 그대로이거나 eval이 이미 그 부분을 참조했어도 다시 리뷰합니다.
그다음 Run부터는 평소처럼 재사용합니다. 저장된 Run과 결과는 계속 읽을 수 있으며 상태를 초기화할 필요는 없습니다.
키에는 대상 Artifact와 포함된 모든 의존성의 이름과 종류(folder, file, aspect, graph)가
들어갑니다. 폴더가 파일로 바뀌면 스크립트가 같은 fingerprint를 내더라도 이전 결과를 재사용하지
않습니다. 실제 경로는 키에 들어가지 않으므로, 복사본의 이름, 종류, fingerprint가 원본과 같으면
기존 리뷰 결과를 재사용합니다. 포함한 Artifact의 이름을 바꾸면 키가 바뀝니다. 이름이 다른 두 Artifact도 결과를 함께 쓸 수 있습니다.
예를 들어 두 Artifact에 상대를 읽는 같은 eval을 선언하면, 두 eval은 같은 평가 기준으로 같은 Artifact들을
포함하므로 결과 하나를 재사용합니다. eval 정의 해시는 eval의 평가 기준 중 하나가 바뀔 때마다
바뀝니다.
- eval 종류(Runtime, Agent, Human)
- 지시문을 포함한
payload pass_schema와fail_schema- Runtime eval이라면 명령과 인자
평가 실행 옵션은 키에 들어가지 않습니다. Agent의 백엔드, 모델, reasoning, timeout_ms,
max_tool_calls, max_tokens, Runtime의 timeout_ms, 고른 프로필 변형이 그렇습니다. eval
ID와 제목, 태그, 저장소 경로, 쓰지 않은 프로필 변형, 도구 선언(views)도 들어가지 않습니다.
도구는 Artifact를 보는 방법일 뿐이므로, 도구의 설명이나 스키마만 바꿔서는 다시 리뷰하지
않습니다. 도구 변경도 반영하려면 관련 파일을 fingerprint에 포함하세요.
실행 가능한 eval은 대상과 의존하는 모든 Artifact에 fingerprint가 있을 때만 재사용 키가 만들어집니다.
생략하면 폴더와 파일 Artifact(그 종류의 basis Artifact 포함)는 artifactsum을 쓰고, 그래프
Artifact는 항상 구조 기반 그래프 fingerprint를 씁니다. 폴더나 파일 Artifact가
fingerprint = false를 선언하면 그 eval은 재사용하지 않아서, verify할 때마다 다시
리뷰합니다. status는 eval마다 상태와 동작의 이유를 알려 줍니다.
status 상태를 보세요.
완료된 결과 재사용
리뷰가 끝났을 때 입력이 그대로면 GREEN이나 RED 결과를 해당 키로 보관합니다
(캐시 살펴보기). 오류와 취소는 보관하지 않습니다. 한
키에 기록이 여러 개 있으면 GREEN이든 RED이든 완료 시각이 가장 늦은 것을 재사용합니다. 그래서
평가 기준과 입력이 같으면 프로필이 달라도 기존 결과를 재사용할 수 있습니다. 선언된 프로필로 요청한
리뷰에 --profile fast 같은 Agent 변형으로 만든 결과를 재사용할 수 있고, 그 반대도 됩니다.
명령이나 인자가 다른 Runtime 변형은 서로 다른 재사용 키로 구분되며, 다른 입력을 가리킬 수도 있습니다.
재사용한 결과에도 원래 결과를 만든 명령이나 모델, 결과 출처가 기록됩니다. run show에서
둘을 어디서 보는지는 verify와 Run에 있습니다.
결과를 재사용하기 전에 artifactize는 리뷰 범위에 포함된 대상 파일을 다시 확인합니다. 대상은 심볼릭 링크를 거치지
않는 일반 파일로 존재해야 합니다. fingerprint = false로 재사용을 꺼도 대상 파일이 안전한지
확인하는 절차는 그대로 진행됩니다. 대상은 fingerprint 준비와 재확인, eval 시작과 끝, 도구 호출 때마다
확인합니다.
캐시가 적중하면 eval을 실행하지 않고, 요청한 프로필이나 스키마로 다시 검사하지도 않고 원래 결과를 돌려줍니다. 결과를 만든 프로필과 요청한 프로필을 따로 기록하며, 결과를 재사용한 요청에서는 추가 사용량이 발생하지 않습니다. 재사용한 RED도 게이트와 최종 검증 요건에서는 RED로 취급됩니다. 이번에 실행하도록 선택하지 않은 의존성의 결과도 캐시에서 가져와 검증에 쓸 수 있습니다. 원래 저장소를 지워도 결과는 계속 읽을 수 있지만, 결과에 기록된 외부 경로를 새 환경에 맞게 자동으로 바꾸지는 않습니다.
팀 리뷰 저장소가 있으면 verify는 모든 키를 저장소에서도 조회하고, 로컬 기록과 저장소 기록 중 더 나중에 완료된 결과를 재사용합니다. 리뷰 저장소에 접속할 수 없으면 로컬에 저장된 최신 기록을 씁니다.
재사용 키가 없으면 캐시를 조회하지 않고 리뷰 결과도 게시하지 않습니다. --force를 쓰면 직접 선택한 실행 가능한 eval은 로컬
캐시나 리뷰 저장소의 결과를 재사용하거나 실행 중인 리뷰에 합류하지 않고 새로 실행합니다. 완료된 GREEN/RED 결과는
새 기록으로 추가하고, 리뷰 저장소가 설정되어 있으면 그곳에도 게시하며, 이후 Run에서 재사용합니다. 강제로
실행했거나 재사용 키 없이 실행한 결과도 그 Run의 검증에 반영되고 실행 기록으로 남습니다.
그래프 fingerprint
루트 .artf 그래프 Artifact는 graph:<sha256>을 씁니다. 이
값은 파일이 옮겨지거나 내용이 바뀔 때가 아니라, 프로젝트의 구조나 기준이 바뀔 때 바뀝니다. 다음을
포함합니다.
- Artifact 이름과 종류,
basis, aspect의select, fingerprint 범위: artifactsum의files와ignore, 스크립트의command,args,files, 또는fingerprint = false. - 관계: 폴더와
parts에 따른 구성(부분 → 그 부분으로 이루어진 Artifact), 지시문 참조, Runtime argv 참조(eval ID, argv 위치, 인자의 Artifact 참조 뒤에 붙인 하위 경로 포함)와 그 입력 대상. - eval ID, eval을 선언한 Artifact, 제목, 평가 기준: 기본 프로필 종류, 지시문과
eval 작성자가 제공한 추가 정보를 포함한
payload전체,pass_schema,fail_schema, Runtimecommand/args.
평가 실행 옵션은 빠집니다. 여기에는 백엔드, 모델, reasoning과 fingerprint 스크립트 시간 제한을 비롯한 모든 timeout_ms, max_tool_calls, max_tokens, profile_variants, eval mutex 태그가 포함됩니다. 모든 도구 뷰와 세션, Artifact 태그, 저장소 경로, 소스 파일 내용도 빠집니다. 선언한 범위 경로와, 범위가 정해진
인자의 Artifact 참조 뒤에 붙인 하위 경로는 fingerprint에 들어갑니다. 이런 논리적 선언과 Artifact 간의 포함 관계를 유지한 채 경로만 바꾸면 그래프 fingerprint는 달라지지 않습니다. 실행 옵션은 그래프 fingerprint에서 빠질 뿐, 일반 상태 기록에는 그대로 저장됩니다.
그래프 리뷰는 항상 이전 구조와의 차이가 아니라 현재 구조를 봅니다. 그래프 eval의 제목을 바꾸면 그래프를 다시 리뷰합니다. 다른 eval은 제목을 바꿔도 다시 리뷰하지 않습니다.
Run
verify는 선택한 eval을 리뷰하고 Run을 기록합니다. status는 eval을 실행하지 않고, 다음
verify에서 각 eval이 실행될지, 결과를 재사용할지, 대기하거나 차단될지를 예측합니다. status도 선언된
fingerprint 스크립트는 실행할 수 있습니다.
eval 실행 게이트
verify는 eval마다 그 eval의 실행 게이트에 따라 실행 시점을
정하며, 여기에는 Human 승인의 자동 eval 선행 조건도 포함됩니다.
status는 eval을 실행하지 않고 이 게이트를 보여 줍니다.
Verify와 Run
verify는 선택자를 정확히 하나 받습니다. Artifact,
eval(green/check), --all 중 하나입니다. Artifact 선택자는 그 Artifact와 그
부분의 eval을 실행해 달라는 뜻입니다. verify game은 combat도
함께 다룹니다. Artifact 사이의 참조나 부분 관계를 따라가다 처음 Artifact로 돌아오는 구조를 순환이라고 합니다. 순환에 속한
Artifact의 eval은 선택한 Artifact를 리뷰하므로, Artifact 선택자는 순환에 속한 Artifact의 eval도 함께
실행합니다. eval 선택자는 그 eval 하나만 실행해 달라는 뜻입니다. 그래도 Run이 GREEN으로 끝나려면 그 eval이 의존하는 모든 대상의 유효한 결과가 필요하며, 이를 확인하려고 의존 관계를 필요한 범위까지 따라갑니다. 이렇게 이어진 묶음이
의존성 범위이고, 여기서 반드시 확보해야 하는 결과가 최종 검증 요건입니다. 이번 Run에서 실행해 달라고 하지
않았더라도 마찬가지입니다.
--recursive는 선택한 Artifact의 다른 eval을 포함해 그 묶음의 모든 eval을 설정 순서대로
선택합니다. --all은
이미 모든 eval을 선택하며, eval이 없는 대상도 최종 검증 요건에 포함합니다. 파일 Artifact 선택자는 그 파일의 eval만
선택하며, 그 파일이 들어 있는 폴더의 eval은 선택하지 않습니다. 다만 그 폴더가 같은 순환에 들면 다릅니다.
파일의 eval이 자기를 담은 폴더를 참조하면, 그 폴더의 eval도 순환에 속한 Artifact의 eval로 함께 실행됩니다.
예를 들어 code/tests가 plan에 의존하고, plan에는 사람의 승인 plan/signoff가 필요하다고 가정합니다. verify --eval code/tests는 테스트를 선택하지만, 그 승인이 아직 유효하지 않으면 GREEN으로
끝날 수 없습니다. verify --eval code/tests --recursive는 code/style과 plan/signoff 같은
묶음의 다른 eval도 선택해서, 실행하거나 결과를 재사용할 수 있게 합니다. eval을 더 선택한다고
승인이 자동으로 생기지는 않습니다. --recursive가 없어도 code/style과 그 입력에 필요한
리뷰는 통과해야 하므로, 이전 Run이나 캐시에 유효한 결과가 있어야 Run이 GREEN으로 끝납니다.
READY인 eval은 준비되는 즉시 시작하며, 동시 실행 수에 기본 상한이 없습니다. 머신이 감당하기
어려울 만큼 프로세스가 많아지는 등 한꺼번에 실행하는 것이 문제를 일으킬 때만 --jobs N(최소
1)을 쓰세요. --jobs나 백엔드 한도 때문에 일부만 실행할 수 있으면 나머지는 이유와 함께 QUEUED로
표시되고, 앞선 작업이 끝나는 대로 시작합니다. --max-executions는 다릅니다. Run에서 시작할 수 있는 리뷰의 총수를 제한합니다. 한도에 도달하면 남은 요청은 BUDGET_EXHAUSTED가 되고 Run은 INCOMPLETE로 끝납니다(자세히). 다른 Run의 리뷰에 합류한 Runtime이나 Agent 요청은 직접 지정한
--jobs에 포함되지만, 승인에 합류한 Human 요청과 캐시 적중은 포함되지 않습니다. Agent 리뷰는
백엔드 자리도 필요합니다. QUEUED는 접수 대기 중이거나, 백엔드 자리가 나지 않았거나, 합류한 실행이 아직 끝나지 않았거나, 직접 정한 Run의 동시 실행 상한에 걸렸을 때 표시됩니다. 백엔드 자리가
빌 때까지 대기 중인 요청은 Run의 --jobs 동시 실행 수에 포함되지 않습니다.
실행 대기 중인 작업은 선택·선언 순서와 관계없이, Run을 빨리 끝낼 수 있도록 artifactize가 정한 순서로 시작합니다. --max-executions가 어떤 리뷰까지 실행할지도 이 순서로 정합니다.
제출, 지켜보기, 취소
누가 요청했든 Run은 artifactize가 관리합니다. 옵션 없는 verify는 Run을 제출하고 Run ID
(--json이면 {"run","state"})를 출력한 뒤, 승인 여부와 관계없이 Run이 접수되면 0으로 종료합니다.
verify --wait는 stderr에 Run ID를 출력한 뒤 결과가 확정될 때까지 대기하고, 저장된 결과를
보여 줍니다. 터미널을 닫거나 상태 확인 명령을 중단해도 Run은 계속 실행되고, 중단되는 것은 상태 확인뿐입니다. Run을 취소하는
방법은 run cancel RUN_ID뿐입니다. 요청이 기록되면 바로 0으로 종료하고, 그 뒤 Run은 새 작업을
시작하지 않고, 실행 중인 작업을 멈추고, 이미 저장된 결과는 남긴 채 ERROR/CANCELLED로 끝납니다.
작업이 정말 멈췄는지 확인하려면 run watch RUN_ID나 run show RUN_ID로 이어서 보세요. 이 Run이 다른 Run의 실행에 합류했다면 그 원래 실행은 멈추지 않습니다. 아직 대기 중이던 승인도
ERROR로 끝나고, 다른 Run에서 그 승인에 합류한 요청도 마찬가지이며, 다음 verify가 다시 요청합니다.
이는 Run이 아직 끝나지 않았을 때(RUNNING 또는 WAITING_HUMAN)만 해당합니다. 이미 YELLOW로 끝난 Run은
취소해도 바뀌는 것이 없고, 그 승인은 여전히 제출할 수 있습니다. 프로세스가 죽은 작업은
ERROR/OWNER_DIED로 끝나고 자동으로 다시 실행되지 않으니 다시 verify하세요.
Run에는 접수 시점의 선언을 그대로 적용합니다. 준비하는 동안 선언을 바꾸면 Run은 다른 기준이나 프로필로 실행하지 않고 ERROR/INPUT_CHANGED로 끝납니다. eval의 실행 일정이 잡힌 뒤에는 접수된 대로 실행합니다. 선언을 다 고친 다음 새 Run을 제출하세요(이전 Run이 아직 실행 중이면 취소하세요). 접수된 Run의 대상이 바뀌지는 않습니다.
승인은 다른 eval을 막지 않습니다. Run은 승인과 Run 종료에 설명한
조건을 충족하는 동안 종료되지 않습니다. Human 대기 제한 시간이나 verify --timeout-ms는 없으며, 모든 eval
종류가 같은 확정 규칙을 따릅니다. 선택 기능인 추측 실행은 실행 순서를 바꿀 뿐, Human의
결정 권한을 바꾸지 않습니다.
Run이 끝나면 지켜보는 명령도 그 Run의 결과에 맞는 종료 코드로 끝납니다. 종료 코드는 CLI 레퍼런스에 있습니다.
Run이 최종 검증을 통과하려면, 필요한 범위의 모든 대상에 실제 GREEN 증거가 있거나 그 Artifact를 직접 basis = true로 선언해야 합니다.
basis로 선언해도 그 Artifact가 의존하는 Artifact의 리뷰 요건은 면제되지 않습니다. RED이면 하위 작업이 막히고, 필요한 증거가 없거나 실행 오류가 나면 하위 작업이 대기합니다. 선택한 리뷰가 GREEN이어도 충족되지 않은 최종 검증 요건이 있으면 INCOMPLETE이며, 남은 요건을 텍스트와
JSON으로 보여 줍니다. 없어진 예전 게이트 우회 설정은
업그레이드 안내에 있습니다.
--reuse-only KINDS(CI에서는 예를 들어 agent,human)는 그 종류의 결과를 재사용만 합니다.
재사용할 증거가 없으면 실행하지 않고 INCOMPLETE로 남깁니다. CLI를
보세요.
--request-key는 요청하는 쪽이 각 제출 시도를 구분하려고 지정하는 키입니다. 같은 키로 다시 요청하면 같은 Run을 돌려주므로, 응답을 놓쳤을 때 다시 시도하려면 같은
키를 쓰고 무언가를 고친 뒤에는 새 키를 쓰세요. eval 결과 재사용은 이 키와 상관없습니다.
코멘트에는 요청하는 쪽이 지금 하는 일, 예를 들어
에이전트가 맡은 작업을 적습니다. Run에 저장되어 run list, run show, 터미널의 Monitor와 데스크톱
앱에서 사람에게 보입니다. 앞뒤 공백 없는 한 줄, 1–200자이며 Run의 동작은 바꾸지 않습니다.
같은 요청 키로 다시 시도하면 처음 Run과 그 코멘트를 그대로 돌려줍니다.
승인과 Run 종료
승인 요청은 Human 승인에서 설명하듯 그 Artifact의 자동 eval이
통과하면 보내며, 요청은 DEFERRED로 표시됩니다. 그 승인에 의존하는 eval은 바로 실행되고 PROVISIONAL로
표시되며, 자세한 내용은 Human 리뷰에 있습니다. 여기까지는 이번 Run에서
실행 대상으로 선택한 승인입니다. 선택하지 않은 승인도 최종 검증 요건에 포함되므로, 그 승인에 의존하는 eval은
재사용할 승인 결과가 있어야 실행되고, 그런 결과가 없으면 Run은 INCOMPLETE로 끝납니다. --recursive나 --all 등으로 그 승인도
선택하세요.
제출되지 않은 승인 요청이 하나라도 있는 동안 Run은 WAITING_HUMAN입니다. RUNNING과 마찬가지로 아직 끝나지 않은 상태입니다. 그런 요청이 없는 진행 중인 Run은 RUNNING이므로, 다른 작업이 아직 실행되는 동안 마지막 승인이 제출되면 Run은 다시 RUNNING으로 표시됩니다. 승인만 남으면 리뷰어가 그중 하나를 맡고 있는 동안에는 Run이 종료되지 않으며, 아무도 맡지 않은 채 승인 유예 시간이 지나면 종료됩니다. 승인 유예 시간은 따로 바꾸지 않았다면 2분입니다. 유예 시간은 다른 작업이 모두 끝난 시점과 승인 요청을 마지막으로 제출하거나 담당을 해제한 시점 중 더 늦은 시점부터 계산합니다. 새로 승인을 맡으면 멈춥니다. 그래서 승인을 요청한 사람은 다른 결과를 모두 재사용한 경우에도 승인을 맡을 시간이 있고, 한 리뷰어가 제출한 뒤에도 다음 리뷰어가 승인 요청을 맡을 시간이 있습니다. 그다음 Run은 이렇게 끝납니다.
- INCOMPLETE: 실행 예산을 다 썼거나
--reuse-onlyeval에 재사용할 결과가 없었습니다. 다른 결과가 RED여도 INCOMPLETE로 끝납니다. - 그렇지 않을 때 결과 하나라도 ERROR이면 ERROR로 끝납니다.
- GREEN: 승인을 포함해 모든 결과가 GREEN입니다.
- RED: 승인을 포함해 결과 하나라도 RED입니다.
- YELLOW(종료 코드 5): 다른 결과는 모두 GREEN이지만 제출되지 않은 승인이 있습니다. 승인만 남았다는 뜻이며 승인된 것은 아닙니다. 더 새로운 Run이 대신한 승인(아래)은 여기서 ERROR 결과가 아니라 제출되지 않은 승인으로 칩니다.
verify --wait, run show --wait, MCP의 대기 도구는 Run이 끝날 때까지 반환하지 않습니다. 승인 요청을 맡은 리뷰어가 있거나 승인 유예 시간이 남아 있으면 계속 대기합니다. YELLOW는 최종 상태입니다. 나중에 제출하면 요청이
바뀔 뿐, Run의 판정은 바뀌지 않습니다. Run의 최종 판정에 승인 결과를 반영하려면 승인 유예 시간이 지나기 전에 승인 요청을 맡으세요. 새 verify에서는 자동 eval의 잠정 결과가 바뀌지 않았으면 이를 재사용합니다. 승인이 GREEN이면
SATISFIED가 될 수 있고, RED면 그에 의존하는 eval을 막습니다. --reuse-only agent,human은 승인을 요청하지
않고 대기 중인 승인을 GREEN으로 간주하지 않으므로 CI에 그대로 쓸 수 있습니다.
같은 워크트리에서 더 새로운 Run이 같은 eval에 Human 요청을 보내면, 재사용 키가 다른 이전
DEFERRED 승인은 거기에 합류한 요청까지 포함해 ERROR/SUPERSEDED로 끝납니다. 누군가 맡은 승인도
마찬가지입니다. 이런 승인은 Review에서 사라지고 다시 맡을 수 없습니다. 이 승인이 남아 있던 Run은
승인이 제출되지 않은 상태로 끝나므로, 승인만 남았다면 YELLOW가 됩니다. 같은 키라면 기존
리뷰에 그대로 합류하며, 몇 개의 Run이 합류하든 Review에는 한 번만 나옵니다. 다른 워크트리의 원래 승인은 건드리지 않습니다. 이렇게 끝나기 전까지는 승인을
그 Run이 끝난 뒤에도 제출할 수 있습니다. 제출할 때 선언과 fingerprint를 다시 확인하며, 선언이나 파일이 바뀌었으면 요청은
판정 없이 ERROR(INPUT_CHANGED)로 끝나니 새 승인을 받으려면 다시 verify하세요.
워크트리를 지우는 등으로 Run의 저장소 폴더가 없어지면, 그 승인은 ERROR/REPOSITORY_REMOVED로 끝나고 Review에서 저절로 사라집니다. 누군가 맡고 있었다면 그것도 함께 풀립니다. 마찬가지로 폴더가 없어진 다른 Run에서 거기에 합류한 요청도 같이 끝납니다. 다른 워크트리에 같은 리뷰의 승인 요청이 아직 처리되지 않은 채 남아 있으면, 해당 워크트리에서 리뷰를 이어 갑니다. 해당 워크트리에서 가장 최근에 생성된 요청을 맡아 리뷰를 확인하고 제출하면 됩니다.
status는 지금 대기 중인 승인과 잠정 결과를 표시하고, 결과가 없는 승인에 의존하는 eval이 실행될 것으로 예측합니다. Run과 결과를 보여 주는 화면은 WAITING_HUMAN인 Run을 아직 끝나지 않은 상태로, YELLOW인 Run을
끝났지만 최종 검증 요건은 충족하지 못한 상태로 표시합니다.
추측 실행
--speculate는 요청별 verify 모드이며, 기본으로 꺼져 있고 Run의 modes에
저장됩니다. 같은 요청 키로 다시 제출하면 처음 선택을 그대로 씁니다.
추측 실행을 사용하면 게이트 조건의 충족 여부가 정해지기 전에도 요청한 Runtime, Agent eval을 시작합니다. 이때도 --jobs, 백엔드별 동시 실행 한도, --max-executions 한도를 지킵니다. 승인은 앞선 eval이 통과하기 전에 추측으로 미리 요청하지 않으며, --speculate Run에서도 앞선 eval이 통과하면 평소처럼 요청합니다. 준비된 작업이 먼저 실행됩니다. 준비된 작업을 실행할 자리를 추측 실행 리뷰가 차지하고 있으면 그 리뷰를 중단하고 나중에 다시 시작합니다. 리뷰를 시작할 때마다 --max-executions의 실행 횟수에 포함됩니다. 상위 eval이 RED나 ERROR가
되면 그 결과로 무효가 된 하위 작업만 바로 취소합니다. 취소 대상은 실패한 상위 eval에 의존하는 eval이며, 실패한 eval과 같은 Artifact에
속하거나 같은 순환에 드는 eval은 제외합니다. 취소한 eval은 재사용할 수 있는 결과를 남기지 않고 BLOCKED로 표시합니다. 상위 eval이 GREEN이면 같은 파일을 대상으로 이미 만든 결과를 그대로 씁니다. 결과는 스케줄링이 끝난 뒤에, 끝까지 유효한 것만
팀 리뷰 저장소에 공유합니다.
텍스트 형식에서는 요청별 결과를 한 줄씩 보여 줍니다. fingerprint가 일치해 재사용했거나 실행 중인 리뷰에 합류해 얻은 결과에는, 그 결과를 실제로 만든 Run이 표시됩니다. 팀 리뷰 저장소에서 가져온 결과에는 결과를 만든 사람이나 Human 리뷰어도 표시합니다.
web/tests [run-x05qFq-5]: GREEN
docs/review [run-x05qFq-3]: GREEN (reused from run-Ksl1Qr)
Summary: executed 1 (runtime 1, agent 0, human 0), reused 4 (runtime 2, agent 1, human 1)
Usage: spent none; saved inputTokens 10, outputTokens 5, totalTokens 20
executed는 ERROR 결과와 이 Run이 기록한 Human 요청을 포함해 이 Run이 직접 실행한 횟수이고,
reused는 캐시, 합류, 원격 결과를 셉니다. 모델, 제한 같은 설정은 재사용 키에
들어가지 않으므로, 설정이 다른 프로필로 얻은 결과도 재사용될 수 있습니다. 그런 결과의 줄에는
profile NAME이 붙습니다. 요약 끝에는 ; N produced by another profile(JSON에서는
summary.reused.otherProfile)이 붙습니다. 설정이
같은 변형의 결과에는 표시가 붙지 않으며, 저장된 options.variant에 변형 이름이 있습니다.
Usage(사용량이 보고됐을 때만 출력)는 이 Run의 실제 사용량과, 재사용한 실행들의 원래 사용량 합계인
saved를 나눠 보여 줍니다. verify의 JSON 출력과 run show에는 같은 수치가 summary.executed,
summary.reused, Run 단위의 usage: {spent, saved}로 들어 있고, summary.usage는
usage.spent와 같습니다.
JSON에서는 요청마다 source가 결과의 출처를 알려 줍니다. 그 요청에서 리뷰를 직접 실행했거나 아직 결과가
없으면 null이고, 캐시, 합류, 원격 재사용이면 결과를 만든 실행의 요청을 가리킵니다.
"source": {"runId": "run-Ksl1Qr", "requestId": "run-Ksl1Qr-3", "kind": "cache"}
kind는 해당 재사용 키로 저장된 완료 기록을 썼으면 cache, 같은 키로 실행 중인 작업(다른
verify나 같은 Run의 다른 eval)이 끝날 때까지 대기한 뒤 그 결과를 썼으면 joined,
팀 리뷰 저장소의 기록이면 remote입니다.
run show, request show, request list --json에도 source가 있습니다.
verify --wait --json과 run show RUN_ID는 저장된 Run 전체를 출력합니다. run show는 선언을
찾거나 코드를 실행하지 않습니다. Run이 시작될 때의 선택, 정책, 프로필 옵션, eval 정의를
보여 주므로, 나중에 선언을 고쳐도 보이는 내용은 바뀌지 않습니다.
일부 eval만 실행하는 Run에서는 선택 범위 밖의 상위 eval 등에 새 요청을 만들지 않고 저장된 증거를 쓸 수 있습니다. Run은 eval ID를 키로, 저장된 상태를 값으로 하는 evidence 맵에 그 판정을 기록합니다.
{"evidence": {"code-style/approved": "GREEN"}}
이는 이 Run이 쓴 증거이지 가장 최근 결과가 아닙니다. JSON 형태는 CLI 레퍼런스에 있습니다. 선언을 바꾼 뒤에도 Monitor에서 이전 Run을 열면 그때 저장한 정의와 실행 게이트를 기준으로 실행 내역을 보여 줍니다.
run list는 저장된 Run을 보여 줍니다. Run 목록을 보세요.
리뷰 정책, --force, --max-executions, 선택 파일, --profile 변형은
레퍼런스에 있으며, 명령 표와
상태 구성도 함께 보세요.
Status와 정적 그래프
artifactize --repo PROJECT status
artifactize --repo PROJECT status ARTIFACT --recursive --json
artifactize --repo PROJECT config graph ARTIFACT --json
artifactize --repo PROJECT config check --json
status는 verify와 같은 선택자 중 하나를 받으며 기본은 --all이고, 같은 --profile,
--recursive, --force 정책 옵션을 받습니다. 현재 Artifact와 eval의 상태, 아직 충족하지 못한 최종
검증 요건, execute / reuse / wait / blocked 동작을 알려 줍니다. 필요한 범위의 eval은 모두
나오며, selected와 included로 직접 선택한 것과 실행에 포함된 것(재귀로 들어온 의존성)을
구분합니다. JSON에서는 eval마다 재사용 키를 이루는 값도
보여 줍니다. evalDefHash, 대상의 fingerprint, fingerprints(eval이 의존하는 각
Artifact와 현재 fingerprint, 없으면 null), 이를 합친 key(fingerprint를 끈 경우 null)이며,
verify가 Run의 키로 쓸 값과 같습니다. 동작별 개수를 집계할 때는 실행에 포함된 eval만 셉니다. 종료 코드
0은 현재 검증 요건을 모두 충족했다는 뜻이고, 1은 아직 충족하지 못한 요건이 남았다는 뜻이며, 입력이나 상태가 잘못되면 2입니다.
status도 verify와 같은 격리와 검사 규칙을 적용하며, --fingerprint-jobs 한도 안에서
선택한 범위의 실행 가능한 eval에 필요한 fingerprint를 계산합니다. fingerprint 계산에 실패하면 2로 종료하며, 예전에 저장한
fingerprint로 대신하지 않습니다. 도구나 eval 명령을 실행하거나 Run을 만들지 않고, 실행할 작업을 예약하지도 않습니다. 없는 데이터베이스를 새로 만들지 않으며, 로컬 캐시의 사용 시각도 바꾸지 않습니다. 다만
팀 리뷰 저장소에서 찾은 결과는 그 저장소에서 사용한 것으로 기록되므로 더 오래 보관됩니다. fingerprint
스크립트는 상태 디렉터리 아래의 버려도 되는 출력 폴더를 쓰며, 데이터베이스가 없어도 이 폴더는
생길 수 있습니다. config graph와 config check는 완전히 정적이며 프로젝트 코드를 실행하지
않습니다.
eval마다 나오는 동작은 verify에서 그 eval이 실행되는지, 결과를 재사용하는지, 대기하는지, 막히는지를 나타냅니다.
| 동작 | 언제 | 사유 예 |
|---|---|---|
reuse | 현재 재사용 키의 GREEN이나 RED 결과가 있습니다. 의존성이 대기 중이거나 RED여도 마찬가지입니다(이때 상태는 WAIT_DEPENDENCY나 BLOCKED입니다) | The current eval and fingerprints have a completed cached result. |
execute | 결과가 없고, 의존성은 지금 있는 결과로 GREEN입니다 | The current eval and fingerprints have no completed cached result. |
blocked | 결과가 없고, 의존성이 RED입니다 | Dependency verdict RED: core/tests |
wait | 결과가 없고, 의존성의 결과는 verify가 실행해야 생깁니다 | Waiting for current GREEN dependency evidence: core/tests |
wait | 의존성이 준비됐고 같은 리뷰가 이미 실행 중입니다. 새 리뷰를 시작하지 않고 기존 리뷰가 끝날 때까지 대기합니다 | The current eval and fingerprints have a live execution. |
status는 wait인 eval이 실행될지는 알려 주지 못합니다. 텍스트 출력은 예를 들어
Verify actions: will execute 1, will reuse 4, wait 0, blocked 0으로 끝나므로, 병합한
체크아웃에서 status를 실행하면 verify를 돌리지 않고도 무엇을 다시 리뷰할지 알 수 있습니다.
--force도 verify와 마찬가지로 직접 선택한 실행 가능한 eval에만 적용됩니다. Human eval의 execute 동작은 대기 요청을
기록한다는 뜻입니다. 같은 키의 Human 실행이 진행 중이면 원래 verify가 종료한 뒤에도 DEFERRED와
wait 동작으로 보입니다. 저장된 실행 기록 중에서는 정규화한 현재 저장소 경로에 해당하는 기록만 읽습니다. eval마다 있을 수
있는 last: {runId, verdict, fingerprint?}는 지난 기록이지 현재 증거가 아닙니다. 누가 만든
결과인지 전부 보려면 run show RUN_ID를 쓰세요. 재사용 키가 없는 GREEN이나 RED는 그 결과를 만든 Run의
요건만 충족하므로, 이후 status에서는 재사용이 아니라 STALE로 나옵니다. basis Artifact만으로 이루어진 범위도 검증 요건을
충족할 수 있지만, basis Artifact가 의존하는 Artifact의 요건이 충족되지 않으면 INCOMPLETE입니다.
재사용 키가 있는 eval에 현재 캐시 결과가 없으면, status는 같은 기준으로 낸 마지막 GREEN이나
RED 결과 이후 무엇이 바뀌었는지 설명하고 changes: {sinceRunId, files?, dependencies?, summary}를 알려 줍니다. 텍스트로는 Fingerprint changed since Run RUN_ID: ... 줄이며, 예를
들어 changed: +docs/new.md, -old.md, src/a.py; dependency core changed입니다. files는
대상 Artifact에 속한 파일의 변경을 path(바뀜), +path(추가), -path(삭제)로 보여 주고, dependencies는
fingerprint가 바뀐, 이름으로 참조한 Artifact의 변경을 name, +name, -name으로 보여
줍니다. fingerprint를 스크립트로 계산했거나 파일 목록을 남기지 않은 이전 기록처럼 파일별 변경 내역을 알 수 없으면, 대상의 변경 내역은 fingerprint changed나 inputs changed로만 표시합니다. 그 eval 정의가 캐시된 적이 없거나
강제로 실행한 eval이면 설명이 나오지 않습니다. 강제로 실행하지 않은 READY Runtime/Agent eval에 키가 없으면,
실행 사유에 fingerprint = false를 선언한 대상이나 의존성이 나옵니다. READY인 Human eval은 키가
없어도 “Record a request awaiting a Human claim and submission“이라고 나옵니다. 막혔거나
대기 중인 eval에는 실행을 막는 게이트나 대기 사유가 표시됩니다.
대기 중인 eval의 blockedBy에는 결과가 아직 없는 eval의 ID가, BLOCKED인 eval의 blockedBy에는 사유와 마찬가지로 실행을 막은 RED eval의 ID가 나옵니다. Detail은 이 게이트를 입력 Artifact별로 Waits for
아래에 묶어 보여 주며, w를 누르면 대기 중인 eval이 나옵니다.
나중에 Human이 승인을 제출하면 대기 중이던 Run이 확정될 수 있습니다. run show는 저장된 검증과
요청을 그대로 보여 줍니다. Monitor는 저장된 정의와 증거에 지금의 요청 상태(나중에 제출한 Human
승인 포함)를 더해 트리를 만듭니다. 맨 위 줄은 Run이 끝났을 때의 SATISFIED / NOT
SATISFIED를 유지하며, 흐린 *는 그 뒤로 상태가 바뀐 행을 표시합니다. 파일이 바뀌었다는 뜻은
아닙니다. Monitor를 보세요.
config graph는 정적 그래프를 출력합니다. Config graph를 보세요.
현재 그래프 리뷰 도구
config graph는 설정을 확인하는 도구입니다. 리뷰에 쓰려면 아무 Artifact에나
내장 graph 도구를 선언하세요. Agent는 추출한 현재
그래프를 트리로 보고, Human은 저장된 Run 없이도 데스크톱 앱에서 그 브랜치의
Current를 엽니다. 루트에 선택적으로 두는
.artf 그래프 Artifact에도 일반 eval을 선언할 수 있으며, 다른 Artifact처럼
Run과 status에 나옵니다. 다른 점은 fingerprint 계산 방식뿐이며, 그래프 전용 검증 절차나 루트
폴더 Artifact와의 자동 관계는 없습니다.
도구
도구를 쓰면 리뷰어가 직접 빌드하지 않고도 Artifact를 살펴볼 수 있습니다. Agent 도구는 모델이 호출할 수 있는 읽기 전용 작업입니다. Human 도구는 사람이 리뷰를 맡은 뒤 실행하는 미리 정의된 명령입니다. 두 종류의 도구 모두 리뷰에 필요한 정보를 제공할 뿐, eval의 기준을 대신하거나 판정을 내리지는 않습니다.
내장 도구
래퍼를 직접 만들기 전에 내장 도구를 쓰세요. 내장 도구로 파일을 읽고 폴더를 나열하며
텍스트를 검색하고, 이미지나 Markdown 섹션과 프로그램 도움말,
현재 Artifact Graph를 확인할 수 있습니다. Human 도구는 파일이나 URL을 기본
애플리케이션으로 열 수도 있습니다. 파일을 읽고, 폴더를 나열하고, 텍스트를 검색하고,
이미지나 섹션을 보여 주는 Agent 내장 도구는 머신 전체가 아니라 eval의 범위에 들어간 Artifact만 봅니다.
graph는 eval 범위와 상관없이 프로젝트의 현재 선언을 모두 읽습니다.
help는 일반적인 실행 파일 검색으로 찾은 실제 프로그램을 실행하며,
직접 선언한 명령 도구도 사용자가 신뢰하는 프로그램으로 보고 실행합니다. 어느 쪽도 OS
샌드박스 안에서 실행되지 않습니다. 현재 사용자 권한으로 실행되므로 선언한 Artifact 바깥의 파일과
자격 증명에도 접근할 수 있습니다.
[views.agent_tools]
read = { builtin = "read" }
list = { builtin = "list" }
[views.human_tools]
notes = { builtin = "read", args = ["{artifactPath}/notes.md"] }
eval은 실제로 참조하는 Artifact에 선언된 도구를 쓸 수 있습니다. 도구 이름은
<operation>_<artifactName>이 되므로, spec에 선언한 read는 read_spec입니다.
직접 도구 Artifact 만들기
도구를 재사용하려면 구현 파일이 있는 폴더에 Artifact 선언을 추가하세요.
예를 들어 tools/checker/index.artf에서 Python 프로그램 inspect.py와 그 옆의 tests/ 폴더를 포함하는 checker Artifact를 선언할 수 있습니다.
name = "checker"
[evals.tests]
title = "The inspection tool handles the requirements and JSON protocol"
profile = { kind = "runtime", command = "python3", args = ["-m", "unittest", "discover", "-s", "tests"] }
payload.instruction = "Run the protocol and requirements tests of {checker}."
[views.agent_tools.inspect]
description = "Inspect the specification for {artifactName}."
protocol = "json"
command = "python3"
args = ["inspect.py", "{spec}/requirements.json"]
input_schema = { type = "object", properties = { section = { type = "string" } }, required = ["section"], additionalProperties = false }
[views.human_tools]
source = { builtin = "read", args = ["{artifactPath}/inspect.py"] }
도구를 쓸 eval의 기준에서 그 도구 Artifact를 참조하세요.
name = "app"
[evals.review]
title = "The app satisfies the specification"
profile = { kind = "agent", backend = "openai", model = "YOUR_EXACT_MODEL_ID" }
payload.instruction = "Review {app} against {spec}; use inspect_checker from {checker} to inspect the requirements."
[evals.approved]
title = "The implementation is approved"
profile = { kind = "human" }
payload.instruction = "Review {app} and the implementation of {checker}; run its source tool before deciding."
Agent는 inspect_checker를, 사람은 source_checker를 쓸 수 있습니다. 두 eval 모두
참조된 도구 Artifact가 eval 범위에 들어가므로, 그 fingerprint가 재사용 여부에
영향을 줍니다. 필요하면 도구 자체도 테스트하거나 리뷰하세요. 필요한 테스트나 리뷰를 건너뛰려는
목적으로 도구를 basis로 선언하지 마세요. execution_paths는 실제로 실행된 바이너리를 기록할 뿐이며, 도구가 바뀌었을 때 리뷰를 다시 실행할지는 fingerprint만으로 정합니다.
json 명령은 stdin에서 context와 args가 든 JSON 요청 하나를 읽고,
{"content":[{"type":"text","text":"The required headings are present."}]} 같은
JSON 콘텐츠 객체 하나를 출력합니다.
plain 명령은 선언된 스키마 속성을 별도의 argv 항목으로 치환하고, stdout을 정해진 크기까지만 텍스트로 돌려줍니다. Human 명령에는 실행할 때 임의의 인자를 추가로 넘길 수 없으므로,
출력을 수집하는 output 방식이나 애플리케이션을 실행하는 launch 방식 중 하나로 선언하세요. 전체 프로토콜, 범위, 제한은
Agent 도구와 Human 도구를 보세요.
게임이나 앱 하네스를 계속 실행해 두기
하네스는 리뷰하는 동안 애플리케이션을 실행하거나 조종하는 보조 프로그램입니다. 도구 세션을 쓰면 Agent 리뷰에서 도구를 여러 번 호출하는 동안 하네스 하나를 계속 실행해 둘 수 있습니다. 예를 들어 게임 도구 Artifact는 창을 띄우지 않는 헤드리스 모드로 게임을 실행하고, 게임 보드 상태를 조회하는 읽기 전용 작업을 제공할 수 있습니다.
[views.agent_sessions.game]
start = { command = "game-harness", args = ["start"] }
stop = { command = "game-harness", args = ["stop"] }
[views.agent_tools.board]
session = "game"
description = "Read the current game board."
protocol = "json"
command = "game-harness"
args = ["board"]
start 명령은 명령 도구와 같은 형식의 JSON 객체를 읽고, 공유 상태를 전용
ARTIFACTIZE_SESSION_DIR에 쓰고, 준비가 끝났다는 신호로 한 줄을 출력한 뒤 계속 실행됩니다. 세션에 묶인
도구 호출과 stop 명령은 같은 디렉터리를 쓰고, 세션은 리뷰마다 따로 만들어집니다.
Agent는 인스턴스를 시작하거나, 멈추거나, 이름을 정하지 않습니다. 오류가 나거나 취소된 경우에도 모든 세션을 멈추고 정리하는 일은 artifactize가 맡습니다. 리뷰 결과를 재사용할 때는 하네스를
시작하지 않습니다. 세션은 저장된 Agent 대화가 아닙니다. 하네스가
구현해야 할 규약은 도구 세션에서 확인하세요.
리뷰하기 전에 선언 확인하기
artifactize tools check는 프로젝트 명령을 실행하지 않고 도구를 쓸 수 있는지, 선언이 올바른지 확인합니다. 특정 도구를 시험하려면 명시적인
실행 형식을 쓰세요. 이 방식으로 도구를 실행해도 Run, 리뷰, 캐시
항목은 생기지 않습니다. 세션에 묶인 Agent 도구는 그 진단 호출에만 쓰는 하네스를 새로 실행합니다.
내장 도구
스크립트를 쓰거나 cat, xdg-open 같은 OS 프로그램을 실행하는 대신 builtin에 이름을 적어
리뷰어에게 내장 도구를 제공하세요. [views.agent_tools] 아래에 read = { builtin = "read" }를
적으면 Agent가 그 Artifact의 파일을 무엇이든 읽을 수 있고, args를 주면 정해진 파일이나 섹션
하나를 보여 줍니다. 다른 형태는 다음과 같습니다.
[views.agent_tools]
read = { builtin = "read" } # the model picks the path
grep = { builtin = "grep" }
style = { builtin = "read", args = ["DEV-CODING.md"] } # one fixed file
spec = { builtin = "section", args = ["spec.md"] } # the model passes only the heading
install = { builtin = "section", args = ["spec.md", "Install"] } # one fixed section
reqs = { builtin = "read", args = ["reqs/requirements.md"] } # in a subfolder
structure = { builtin = "graph", args = [] } # current project entity tree
cargo_help = { builtin = "help", args = ["cargo", "build"] } # cargo build --help
[views.human_tools]
open = { builtin = "open", args = ["{artifactPath}/notes.md"] } # kind = "launch"
viewer = { builtin = "graph", kind = "launch", args = [] } # existing desktop graph view
docs = { builtin = "open", args = ["https://artifactize.dev/docs/"] }
notes = { builtin = "read", args = ["notes.md"] } # kind = "output"
summary = { builtin = "section", args = ["{reqs}/requirements.md", "Summary"] }
내장 도구는 Linux, macOS, Windows에서 똑같이 동작합니다. 다른 점은 디스크에 있는 경로 표기를
확인하는 방식(경로 참고)과, Windows의 junction과 그 밖의 reparse
point를 심볼릭 링크처럼 거부한다는 점뿐입니다. 내장 도구는 대부분 따로 설치할 것이 없고, artifactize-tools 명령도 필요 없습니다. 예외는 세 가지입니다. open은 파일이나 URL을 기본 애플리케이션으로 여는 OS 명령(Linux에서는 xdg-open)을 쓰고, help는 요청한 프로그램을 실행합니다. Human graph는 데스크톱 앱을 열므로 artifactize-desktop이 설치되어 있지 않으면 실패합니다. Agent용 graph 도구는 별도 프로그램을 설치하지 않아도 사용할 수 있습니다. 그 명령과
artifactize tools는 스크립트와 Runtime eval에 파일 시스템과 프로그램 도구를 제공합니다. 현재
프로젝트의 구조를 보여 주는 graph 도구는 artifactize의 리뷰 도구로 선언해야 쓸 수 있으며, 독립
실행형 도구 CLI에는 없습니다.
내장 도구 선언은 builtin, args(모델 입력을 받는 Agent 도구에서는 선택), 선택 항목인
description을 받으며, 도구마다 기본 설명이 있습니다. Human 내장 도구는 kind도 적을 수
있지만 도구와 맞아야 합니다(open과 graph는 실행, 나머지는 출력). 맞지 않으면
config check가 거부합니다. 내장 도구는 timeout_ms, command, protocol, input_schema를
받지 않습니다. 리뷰어는 명령 도구처럼 각 도구를
<name>_<artifactId>라는 이름으로 씁니다.
도구
| 도구 | Agent, 모델 입력 | Agent, 고정 args | Human args | 출력 |
|---|---|---|---|---|
read | {path, offset?, limit?} | [file] | [file] | 파일 |
list | {path?, offset?, limit?} | [folder] | [folder] | 정렬된 항목(JSON) |
glob | {pattern, path?} | — | — | 일치하는 경로 |
grep | {pattern, path?, glob?, caseInsensitive?, maxResults?} | — | — | 일치하는 줄 |
view_image | {path} | — | — | 이미지 |
section | — | [file](모델이 heading을 넘깁니다) 또는 [file, heading] | [file, heading] | Markdown 섹션 하나 |
help | — | [program, subcommand...] | [program, subcommand...] | program subcommand... --help |
graph | — | [] | [](실행) | Agent: eval, 기준, 입력에서 사용처로 이어지는 관계를 담은 트리입니다. Human: 데스크톱 뷰어입니다 |
open | — | — | [file, folder 또는 URL](실행) | 출력은 없습니다. 기본 애플리케이션으로 엽니다 |
args가 없으면 Agent 도구는 모델의 입력을 받습니다. read, list, glob, grep,
view_image의 입력, 결과, 한도는 Agent 도구에 있습니다. args를 고정하면 인자를 하나만 지정한 section을 제외하고는 모델에서 인자를 받지 않습니다. 인자를 고정한 Agent 도구 중 list는 구조화된 JSON 내용 블록을 돌려주고, read, section, help는 텍스트 블록을 돌려줍니다.
- **
read**는 UTF-8 파일을 최대 64 KiB까지 출력하며, 더 긴 파일은[output truncated]로 끝납니다. 파일 앞부분에서 실제로 읽은 범위만 검사하므로, 그 안에 NUL이나 잘못된 UTF-8이 있으면 거부하지만 출력에서 잘린 뒷부분에 있으면 감지하지 못할 수 있습니다. CLI의 고정 read도 한도가 같습니다. - **
list**는 모델 입력을 받는list처럼 폴더 항목을 정렬한 목록의 첫 페이지를 JSON으로 출력하지만, offset이나 limit을 받지 않아 다음 페이지를 가져올 수 없습니다. 항목이 더 많은 폴더라면 모델 입력을 받는list나 직접 만든 명령을 선언하세요. - **
section**은 Markdown 파일의 섹션 하나를 출력합니다. 수준과 상관없이 텍스트가heading과 정확히 같은 첫 제목을 찾습니다.#제목과 밑줄 제목을 모두 찾되, 코드 블록 안의 제목은 제외합니다. 섹션은 그 제목부터 같거나 더 높은 수준의 다음 제목까지이므로 하위 섹션도 포함합니다. 일치하는 제목이 없으면 오류에 그 파일의 제목 목록이 나옵니다. 모델이 넘기는 제목은 1–4096자여야 하고, 선언한 제목은 비어 있으면 안 됩니다. 파일은 최대 8 MiB, 출력하는 섹션은 최대 64 KiB입니다. - **
help**는program subcommand... --help를 실행하고 stdout을 먼저 출력한 뒤 stderr를 이어서 출력하며, UTF-8로 읽고 터미널 색 코드와 탭, LF, CR을 뺀 ASCII 제어 문자를 지웁니다(DEL은 남깁니다). program에는 실행할 프로그램 이름이나 경로를 적으며, 적은 값을 바꾸지 않고 그대로 씁니다. 경로 없는 이름은PATH(Windows에서는PATHEXT도)로 찾습니다. 범위가 정해진 명령 도구 실행 파일과 달리 help는 일반적인 프로그램 찾기를 쓰므로 절대 경로, 상위 폴더 기준 상대 경로, 실행 파일 심볼릭 링크를 받습니다. 상대 경로는 선언한 Artifact 폴더에서 시작하고, 하위 명령 인자는 범위 해석 없이 그대로 넘깁니다. 프로그램은 그 폴더에서 빈 stdin으로 실행되며, 별도의 출력·임시 디렉터리를 받지 않습니다. Agent용help는 작성자의 환경을 쓰되,ARTIFACTIZE_*변수는 대소문자를 가리지 않고 모두 뺍니다. Human용help는ARTIFACTIZE_REMOTE_TOKEN같은 자격 증명과ARTIFACTIZE_*변수를 포함한 리뷰어의 전체 환경에서 실행됩니다. 10초 안에 끝나고, 종료 코드 0이어야 하며, stdout과 stderr를 합쳐 최대 64 KiB까지 출력해야 합니다. 종료 코드가 0이 아니면 stdout 대신 종료 상태와 프로그램의 stderr를 그대로 담은 오류를 돌려줍니다.open과 달리help가 실행한 프로그램은help명령이 끝날 때 함께 종료됩니다. 정상 종료든 시간 초과든 취소든, 그 프로그램과 그 프로그램이 백그라운드로 띄운 프로그램을 멈춥니다. 스스로 분리(detach)한 프로그램은 예외입니다. 실제 프로그램을 실행하므로 신뢰하는 프로그램만 적으세요. open(Human 전용)은 파일, 폴더,http:///https://URL 하나를 데스크톱의 기본 애플리케이션으로 엽니다. Linux와 WSL에서는xdg-open, macOS에서는open, Windows에서는 대상에 지정된 기본 애플리케이션을 씁니다. 대상은 셸을 거치지 않고 인자 하나로 넘깁니다.file:이나mailto:같은 다른 URL 스킴은 거부합니다. 결과에는 애플리케이션을 시작했다는 사실만 기록되며, 실행한 애플리케이션은 자동으로 종료되지 않으므로 리뷰어가 직접 관리합니다. Linux, WSL, macOS에서는 파일을 여는 OS 명령이 3초 안에 성공으로 끝나야 합니다. 명령을 찾을 수 없거나, 시간이 초과되거나, 종료 코드가 0이 아니면 도구 오류입니다. WSL에서는xdg-open의 종료 상태 4도 성공으로 간주합니다.explorer.exe를 통해 파일을 여는데,explorer.exe는 파일을 연 뒤에도 실패를 보고하기 때문입니다. 3초 제한은 애플리케이션을 여는 명령에만 적용되며, 열린 애플리케이션의 실행 시간에는 적용되지 않습니다.
view_image
view_image는 Agent 전용 도구이며 모델 입력 {"path":"board.png"}가 필요합니다. 경로는 허용된
Artifact 범위 안의 논리적 경로이며, 다른 내장 도구와 마찬가지로 거슬러 올라가는 경로와 심볼릭 링크를 확인합니다.
비어 있지 않은 일반 파일을 읽어서, 파일 이름을 출력하는 대신 내장 이미지 블록(type, base64
data, mimeType)을 돌려줍니다.
형식은 확장자가 아니라 파일 내용으로 정합니다. PNG, JPEG, WebP를 지원하고, GIF, BMP, 애니메이션 PNG와 그 밖의 형식은 거부합니다. 파일은 최대 4 MiB입니다. 명령 도구와 똑같이 적용되는 이미지 정리 방식과 MIME 유형·크기 검사는 이미지 결과 규약에서 설명합니다. 호출별 출력 디렉터리의 파일을 이미지 결과로 돌려줄 수 있는 것은 명령 도구뿐입니다.
현재 프로젝트 그래프
어느 Artifact에든 builtin = "graph", args = []를 선언하세요. 그래프 Artifact는 필요 없습니다.
이 도구는 고른 리뷰의 Run 기록이나 범위와 관계없이 항상 현재 프로젝트의 선언 전체를 읽으며,
eval을 시작하거나 의존성을 더하지 않습니다.
그래프 fingerprint가 포함하는 것과 같은 그래프를
보여 줍니다.
- Agent: 모델 입력이 없습니다(
{}만). 소스 파일은 읽지 않고 선언만 읽습니다. Artifact와 그 eval을 이름 기준으로 정리한 트리를 출력하며, 순환 참조가 있어도 같은 항목을 끝없이 반복하지 않습니다. 추출한 정의와 평가 기준 전체, 그래프 fingerprint, 입력에서 사용처로 향하는 화살표와 각 화살표의 이름도 함께 출력합니다. - Human:
kind = "launch". 설치된 데스크톱 앱을 프로젝트의 Current 화면으로 엽니다. Current는 워크트리의 파일을 읽어 Run 판정 대신 현재 선언을 보여 주며, 각 Artifact에 기존 결과를 재사용할지 새로 실행할지 표시합니다. 화면을 다루는 방법은 Run의 그래프와 같습니다. Artifact Detail의 eval 탭에는 그 eval의 지시문이 나오고, 선언된 나머지 정보는 Debug 아래에 있습니다. Refresh나 Ctrl+R/F5로 다시 읽습니다. Run이 하나도 없어도 동작합니다. 도구 실행 결과는 승인이 아니라 앱을 시작했다는 확인일 뿐이며, 도구 호출이 끝나도 앱은 계속 실행됩니다.
args의 경로
파일 시스템 대상은 실제 리뷰에 허용된 범위 안에 있어야 합니다.
- 고정 Agent 도구는
reqs/requirements.md처럼 선언한 Artifact 기준의 논리적 경로를 씁니다. 그 안에 선언된 폴더 Artifact로 들어가는 경로는 범위 밖입니다. 선언을 찾거나config check를 실행할 때 대상이 존재하고 그 Artifact 안에 있는지 확인하며, 조건에 맞지 않으면 거부합니다. 호출할 때도 다시 확인합니다. - Human 도구는 같은 논리적 경로와 함께
{artifactPath}나{artifactPath}/path,{name}이나{name}/path(name은 Artifact)도 받습니다. Human 도구를 보세요.--flag=접두어는 받지 않습니다. 선언을 찾거나config check를 실행할 때는 리뷰 범위보다 넓은 작업 공간 전체를 기준으로 참조 이름과 대상이 존재하는지 확인합니다. 그래서{other}/file이 존재하면 설정 검사를 통과할 수 있습니다. 사전 확인과 도구 호출 때other가 그 Human eval의 범위에 들어 있어야 하므로, 그 eval에서{other}를 직접 참조해야 합니다. Artifact만 대상으로 하는 도구 확인은 그 Artifact만 범위로 씁니다. 도구 인자는 의존성을 더하거나 범위를 넓히지 않습니다.
설정을 검사하거나 도구를 호출할 때마다 파일 시스템 대상이 절대 경로, .., 심볼릭 링크, 특수
파일이면 거부합니다. open은 HTTP(S) URL도 받습니다. help는 자리 표시자 없이 글자 그대로의 프로그램
이름이나 경로와 하위 명령 인자를 받습니다. 이 인자는 프로그램 인자이지, 이런 범위 확인을 받는
파일 시스템 대상이 아닙니다.
재사용
내장 도구의 이름과 args를 포함한 도구 선언은 재사용 키에
들어가지 않습니다. 도구는 Artifact를 보는 방법일 뿐이기 때문입니다. 도구를 바꿔도 이전 판정을
재사용하며, 내장 도구의 동작을 바꾼 새 artifactize 릴리스도 마찬가지입니다. 도구가 읽는 파일이
바뀔 때 다시 리뷰하려면 그 파일을 fingerprint에 포함하세요. 기본 artifactsum 계산에는 그 Artifact에
속한 파일이 들어갑니다.
artifactize-tools CLI
Microsoft Store를 포함해 어떤 방법으로 설치하든 artifactize tools로 현재 디렉터리에서 같은 도구를
쓸 수 있습니다. Store 이외의 방법으로 설치하면 artifactize-tools도 artifactize와 같은 디렉터리에 설치됩니다. 어느 명령을 쓰든 도구 하위 명령과 그 인자·옵션, 출력, 종료 코드는 같으며, artifactize tools --version도 같은 방식으로 동작합니다. 단, 단독 artifactize-tools는 artifactize의 --json, --repo, --state-dir 옵션을 받지 않습니다. 기존의
artifactize tools check는 현재 디렉터리 도구를 실행하는 것이 아니라 선언한 리뷰 도구를
확인합니다.
Runtime eval, fingerprint 스크립트, 직접 만든 스크립트에서 다음처럼 씁니다.
artifactize tools read DEV-CODING.md # also: artifactize-tools read DEV-CODING.md
artifactize-tools list [PATH]
artifactize-tools glob PATTERN [PATH]
artifactize-tools grep [--glob GLOB] [--case-insensitive] PATTERN [PATH]
artifactize-tools section spec.md "Install"
artifactize-tools help cargo build # cargo build --help
artifactize-tools open notes.md # or an http(s) URL
리뷰 중이 아닐 때는 Artifact 범위가 없으므로 현재 디렉터리를 범위로 삼습니다. read/list/glob/grep/section/open으로
여는 파일이나 폴더는 현재 디렉터리 아래에 있어야 하며, 상대 경로로 지정해야 합니다. .은 그 디렉터리 자체를 가리키며
list/glob/grep의 기본값입니다. 절대 경로 대상, .., 심볼릭 링크는 링크가 안쪽을 가리키더라도
거부합니다. help의 프로그램과 인자에는 이 규칙이 적용되지 않으며, help에서처럼
찾습니다. URL은 open만 받으며, http://나 https://만 됩니다.
read, section, help는 내장 도구에 설명된 한도까지 텍스트를 출력합니다. section은 제목이 정확히 일치해야 합니다. read와 section의 출력이 64 KiB를 넘으면 잘렸다는 표시를 끝에 붙입니다. help의 출력이 64 KiB를 넘으면 Help output exceeds 64 KiB.를 출력하고 종료 코드 1로 실패합니다.
list, glob, grep은 Agent 도구의 JSON 결과를 그 패턴 문법과 한도대로
출력합니다. 현재 디렉터리는 선언된 Artifact가 아니므로 artifactId는 "cwd"입니다. notes.md만
있는 폴더에서 artifactize-tools list .를 실행하면 다음이 출력됩니다.
{"artifactId":"cwd","path":"","entries":[{"kind":"file","name":"notes.md","path":"notes.md"}],"totalEntries":1,"truncated":false,"nextOffset":null}
명령줄에서 help는 터미널 환경에서 ARTIFACTIZE_* 변수를 모두 뺀 환경으로, 별도의
임시·출력 디렉터리 없이 프로그램을 실행합니다. 그 밖의 동작은 위의 help와 같지만, Linux와 macOS에서
Ctrl+C로 명령을 중단해도 그 프로그램과 프로그램이 시작한 것은 멈추지 않고 끝날 때까지 계속 실행됩니다. 도구 오류는 stderr에 출력하고 종료 코드 1을 돌려주며, 명령을 잘못 사용한 경우에는 종료 코드 2를 돌려줍니다. artifactize tools --help(또는 artifactize-tools --help)는
도구 목록을, artifactize tools SUBCOMMAND --help는 도구 하나의 설명을 보여 줍니다.
artifactize tools help PROGRAM SUBCOMMAND...는 다릅니다. PROGRAM SUBCOMMAND... --help를
실행해서 그 프로그램의 도움말을 출력합니다.
Artifact 범위가 없으면 list는 항목의 첫 페이지만 돌려주고 offset이나 limit을 받지 않습니다.
항목이 더 많은 폴더에는 glob이나 직접 만든 명령을 쓰세요.
Agent 도구
도구 Artifact의 [views.agent_tools.NAME] 아래에 명령 도구를 선언하고, eval에서 그 Artifact를
참조하세요. 그러면 그 eval의 Agent는 이 도구를 NAME_ARTIFACT라는 이름으로 쓸 수 있습니다. 리뷰하기 전에
tools check로 확인하세요. 단계별 예제는
도구에 있습니다.
명령 필드 description, protocol, command, args는 필수입니다. input_schema의 기본값은
{"type":"object","additionalProperties":false}(빈 인자만 허용)입니다. 스키마를 직접 지정할 때는 루트가 type: "object"여야 합니다. 로컬 $ref와 조합을 포함해 표준 JSON Schema가 동작하지만,
파일이나 URL 참조는 동작하지 않습니다. 스키마 기본값이 인자를 바꾸지는 않습니다. 스키마는 하나당
8 MiB까지입니다. 호출 인자는 최대 64 KiB인 JSON 객체여야 하며, 프로세스나 출력 디렉터리를
만들기 전에 이를 확인합니다. 인자 검사에 실패하면 오류 메시지에 이스케이프 처리한 인스턴스·스키마 경로를 최대 다섯 개(총 4 KiB 미만)
표시하며, 인자 값은 표시하지 않습니다.
설명은 비어 있지 않아야 하고, 4000자 이하여야 하며(이모지처럼 기본 다국어 평면 밖의 문자는
2자로 셉니다), {artifactName}
치환(정규 Artifact ID)만 지원합니다. 내장 도구 참조는 builtin, 선택 항목인 args와
description을 받습니다. args가 없으면 read, list, glob, grep, view_image는 아래의
모델 입력을 받습니다. args가 있으면 read, list, section, help는 고정된 대상에 대해
동작하고, args = []인 graph는 내장 도구에서 설명한 대로 현재 프로젝트 구조
전체를 출력합니다. 직접 선언한 도구만 목록에 나옵니다. 내장 도구에는 별도의 프로그램이 필요 없습니다. 다만 help는 요청한 프로그램을 시작합니다. view_image는 json 프로토콜의 명령 도구가 돌려주는 이미지 결과와 같은 검사를 이미지에 적용합니다.
| 내장 도구 | 인자 | 결과 |
|---|---|---|
graph | 고정 선언은 args = [], 호출은 {}입니다 | 이름순으로 정리한 전체 Artifact/eval 트리, 추출한 기준, 그래프 fingerprint, 입력 → 사용처 관계 |
read | {path, offset?, limit?}. offset은 1부터 세는 줄이며(기본 1, 최대 9007199254740991), limit은 기본 80, 범위 1–500입니다 | artifactId, resolvedArtifactId, path, lines: [{number, text}], startLine, null일 수 있는 endLine, lineCount, EOF를 알 때만 totalLines, truncated, null일 수 있는 nextOffset |
list | {path?, offset?, limit?}. offset은 0부터 세며(기본 0, 최대 9007199254740991), limit은 기본 200, 범위 1–200입니다 | artifactId, path, 정렬된 entries: [{name, path, kind}], totalEntries, truncated, null일 수 있는 nextOffset |
glob | {pattern, path?}. path는 디렉터리여야 합니다 | 검색한 path, 정렬된 논리적 files 최대 200개, truncated |
grep | {pattern, path?, glob?, caseInsensitive?, maxResults?}. 기본으로 대소문자를 구분하며, maxResults는 기본 200, 범위 1–200입니다 | 검색한 path, matches: [{path, line, text}](일치하는 줄마다 하나, 경로 다음 줄 번호 순), truncated |
limit이나 maxResults가 범위를 벗어나면(0 포함) 입력 스키마 검사에서 거부되어 호출이
실패합니다.
read.artifactId는 도구를 선언한 Artifact를 가리키고, resolvedArtifactId는 안에 선언된 폴더를
거쳐 찾은 Artifact를 가리킵니다. 예를 들어 app 폴더 안의 rules 폴더가 spec으로 선언되어 있고
eval이 {spec}도 참조할 때 app의 read 도구를 {"path":"rules/requirements.md"}로 호출하면, 줄 데이터와 함께 실제로 읽은
Artifact를 나타내는 정보 {"artifactId":"app","resolvedArtifactId":"spec","path":"rules/requirements.md"}를
돌려줍니다. path는 실제 머신 경로가 아니라 요청한 논리적 경로 그대로입니다. list의 최상위
artifactId도 마찬가지로 선언한 Artifact를 가리킵니다. 항목 종류는 file, directory,
symlink, other입니다. glob/grep은 검색한 논리적 path를 돌려주며, grep이 찾은 줄 번호는
1부터 셉니다.
경로는 도구를 선언한 Artifact를 기준으로 한 상대 논리 경로입니다. 그 안에 선언된 폴더 Artifact로
들어가는 경로는 eval이 그 Artifact도 참조할 때만 닿습니다. 참조하지 않으면 list, glob, grep은 그
폴더가 없는 것처럼 건너뜁니다. 경로를 생략하면 해당 Artifact의 루트를 가리킵니다. 다른 Artifact의 파일은 그 Artifact의 도구로 읽으며, eval이 그 Artifact를 참조하면
그 도구를 쓸 수 있습니다. 절대 경로, 경로를 거슬러 올라가는 구성 요소, 심볼릭 링크는 받지
않습니다. 논리적 경로는 4096자까지이고(이모지처럼 기본 다국어 평면 밖의 문자는 2자로 셉니다), 경로 전체가 . 하나이면 list/glob/grep에서
파일 Artifact나 aspect의 가상 루트로 해석합니다. 그 밖에는 ASCII 제어 문자, 백슬래시, 콜론, 빈 구간, .이나 .. 구간이 있으면
거부합니다. 도구는 그 eval 범위의 Artifact에만
접근할 수 있으며, 다른 eval의 범위에는 접근할 수 없습니다. 파일은 읽기 전용으로 열고, 심볼릭 링크는 따라가지
않으며, 특수 파일은 읽을 수 없습니다. list는 symlink/other 항목을 보여 줄 수 있지만,
검색에서는 건너뜁니다. Windows에서는 junction과 그 밖의 reparse point도 링크로 간주해 대상으로 쓸 수
없으며, list는 junction을 symlink로, 그 밖의 reparse point를 other로 보여 줍니다. 파일 Artifact는 대상 파일만 보여 주고, 작업 디렉터리에 함께 있는 다른 파일은 보여 주지 않습니다. 경로 없이 또는 path: "."로 list를 호출하면 그 가상 루트의 대상
파일을 보여 줍니다. 대상 파일을 읽을 때는 파일 이름을 지정하며, 경로는 그 파일이 있는 폴더를 기준으로 씁니다.
재사용을 끈 경우에도 내장 도구나 명령 도구를 호출하기 전에 허용 범위에 포함된 대상 파일을 매번 확인합니다. 대상이 없거나, 일반 파일이 아니거나, 심볼릭 링크로 바뀌었으면 명령을 실행하지 않고 오류를 돌려줍니다.
read는 원래 줄을 중간에서 자르지 않고 줄 전체를 최대 64 KiB까지 돌려주며, 각 줄의 text에 줄 끝(\n이나 Windows의
\r\n)과 UTF-8 바이트 순서 표시(일부 편집기가 파일 맨 앞에 넣는 보이지 않는 표시)를 그대로
둡니다. 요청한 줄만 디코딩합니다. 잘못된 UTF-8이나 NUL은 오류이고, 요청한 첫 줄이 너무
커도 오류입니다. 빈 파일은 줄 0개와 totalLines: 0을 돌려주고, 파일 끝을 넘는 페이지는 줄 0개와 0이
아닌 실제 전체 줄 수를 돌려줍니다. 돌려받은 text 값을 이어 붙이면 줄 번호가 붙지 않은 그 범위의 원문을
그대로 복원할 수 있습니다.
glob 내장 도구는 디렉터리 path가 필요하며, 내용을 보지 않고 일치하는 파일 이름을
고릅니다(바이너리 파일 이름 포함). 파일이나 폴더 이름이 올바른 UTF-8이 아니면, 일치하지 않는
이름이라도 list, glob, grep 호출 전체가 실패합니다. 경로를 좁히거나 이름을 바꾸세요.
grep은 파일이나 디렉터리를 받으며, 바이너리(NUL)나 잘못된 UTF-8 내용은 통째로 건너뜁니다.
선택 인자 glob은 파일 이름 필터이지 glob 도구를 호출하는 인자가 아닙니다.
glob 패턴은 path 기준입니다. *는 폴더 이름 하나 안에서, **는 여러 폴더에 걸쳐 일치하고,
?는 한 글자, [abc]나 [a-z]는 집합이나 범위에서 한 글자, {md,txt}는 둘 중 하나에
일치합니다. *, ?, [, {를 글자 그대로 찾으려면 [*]처럼 대괄호에 넣으세요. 백슬래시
이스케이프는 받지 않습니다. glob과 grep 패턴(grep의 선택 인자 glob 포함)은 비어 있지 않고
4096자 이하여야 합니다. glob은 상대 경로여야 하고, 앞의 슬래시, 백슬래시, 콜론, NUL, 빈 구성
요소나 ./.. 구성 요소가 없어야 합니다. grep의 패턴은 Rust regex 문법의 정규 표현식이며,
예를 들어 fn \w+_test는 fn 뒤에 _test로 끝나는 이름이 이어지는 줄을 찾습니다. 비어 있거나
잘못된 패턴은 오류입니다. 짧은 패턴이라도 너무 복잡할 수 있습니다. 반복 횟수가 크거나 대안이 많아서
컴파일한 결과가 2 MiB를 넘는 패턴은 Invalid or oversized regex pattern. 오류가 납니다. 이때는
글자 수를 줄이는 것만으로는 안 되니 반복이나 대안을 단순하게 바꾸세요. grep의 선택 인자 glob 필터는 상대 파일 경로(path가
파일이면 파일 이름)에 맞춰 봅니다. 숨김 파일도 포함하며, git ignore 규칙으로 결과를 거르지
않습니다. 탐색할 수 있는 항목은 최대 10,000개이며, grep은 파일당 8 MiB, 검색 전체에서 64 MiB까지 읽습니다. JSON 결과 하나의 크기는 최대 512 KiB입니다. 검색 한도에 도달하거나 너무 큰 파일을 건너뛰면 truncated: true가 되니, 경로나
패턴을 좁혀서 이어 가세요. 이와 별개로, 디렉터리에서 도구 범위 안의 항목을 10,000개 읽은 뒤에도 항목이 더 있으면, 그 항목이 범위 안에 있든 없든 list, glob, grep은 일부 검색 결과를 반환하는 대신 오류를 반환합니다. 그보다 적은 범위 밖 항목은 세지 않으므로, 큰 디렉터리에서 파일 하나만 고른 aspect는 평소처럼 목록을 보고 검색할 수 있습니다. list는 결과의 바이트 수가 한도에 이르면
항목 수 제한에 못 미쳐도 결과를 다음 페이지로 나눌 수 있습니다. 내장 도구의 인자에도 명령 도구와 같은 크기 제한과 JSON Schema
검사를 적용합니다.
json 프로토콜은 stdin으로 요청을 정확히 하나 받습니다.
{
"version": 1,
"context": {
"artifactId": "example",
"artifactPath": "/workspace/example",
"outputDir": "/external/private/output",
"tmpDir": "/external/private/tmp",
"scope": {
"example": {"path": "/workspace/example", "kind": "folder", "nested": {}}
},
"executionPaths": {"shared/rules.json": "/workspace/shared/rules.json"}
},
"args": {"section": "summary"}
}
scope 항목에는 정규화된 실제 경로, kind(file, folder, aspect, graph), 폴더 안에 선언된
폴더 Artifact의 논리적 경로인 nested, aspect의 select가 들어 있습니다. aspect의 path는 그 선언이
있는 폴더입니다. 파일 Artifact라면 context.artifactPath와 그 scope 항목의 path는 프로세스 작업
디렉터리가 아니라 그 파일을 가리키며, 작업 디렉터리는 파일이 들어 있는 폴더입니다. 파일
Artifact 참조 뒤에는 /path처럼 하위 경로를 붙일 수 없습니다. 이 프로토콜 키는 camelCase를 유지하며,
선언에서는 execution_paths와 input_schema를 씁니다. executionPaths는 비어 있으면
생략합니다. 실행 경로로는 작업 공간 기준 파일이나 디렉터리를 중복 없이 최대 64개 선언할 수 있으며, 각 경로는
1024자까지입니다(이모지처럼 기본 다국어 평면 밖의 문자는 2자로 셉니다). 경로는 심볼릭 링크를 거치지 않고 해석하며, 대상을 복사하지 않습니다. 파일
Artifact에서도 작업 공간 기준이며, 작업 디렉터리나 대상 기준이 아닙니다.
Agent 리뷰가 시작되면 artifactize는 eval 도구의 각 실행 경로에 대한 SHA-256(디렉터리라면 그
안의 파일과 심볼릭 링크)을 coverage_spec 같은 공개 도구 이름별로
executionPaths: {"TOOL": {"PATH": "sha256"}} 형태로 결과에 기록합니다. 이 기록은 원격 결과에도
함께 저장되고 재사용한 결과에도 남으므로, 재사용한 판정을 어느 바이너리가 만들었는지 알 수 있습니다.
경로가 없거나, 특수 파일이거나, 1 GiB를 넘거나, 파일과 심볼릭 링크 10,000개 뒤에 항목이 하나라도 더 있으면(디렉터리는 세지 않지만 그 뒤에 나오면 마찬가지입니다) Agent를 호출하기 전에
PREPARATION_FAILED로 리뷰가 실패합니다. 이 해시는 기록일 뿐
재사용 키에 들어가지 않습니다. 바이너리가 바뀔 때 다시
리뷰하려면 fingerprint에 그 바이너리를 포함하세요.
명령이 성공하면 stdout에 내용 블록 1–32개를 담은 JSON 객체 하나를 출력해야 합니다.
{"content":[{"type":"text","text":"..."},{"type":"json","data":{}}]}.
이미지 블록은 아래에서 설명합니다. 텍스트는 블록당 최대 64 KiB, 압축한 JSON
데이터는 블록당 최대 512 KiB, 정리한 결과 전체는 최대 8 MiB입니다. stdout과 stderr는 각각
16 MiB까지입니다. 결과 객체는 content와 선택 항목인 불리언 isError만 받습니다. 각 블록에도
정해진 필드 외의 필드를 넣을 수 없습니다. 텍스트 블록은 type과 text만, JSON 블록은 type과 data만, 이미지 블록은
type, mimeType, 그리고 data나 path 중 정확히 하나만 받습니다. 결과나 블록에 허용하지 않은 필드가
있으면 이를 메타데이터로 리뷰어에게 전달하지 않고 출력 형식 오류로 처리합니다. 명령이 종료 코드 0으로 오류를 알릴 때는 {"isError":true,"content":[{"type":"text","text":"Choose a smaller range."}]}처럼 비어
있지 않은 텍스트 블록이 정확히 하나여야 하며, 리뷰어에게 그대로 전달됩니다. 0이 아닌 종료 코드,
비정상 종료, 잘못되거나 잘린 JSON, 프로세스 실패는 일반 오류가 되며, stderr는 전달하지
않습니다.
이미지 결과
JSON 명령은 mimeType과, data(표준 base64 바이트)나 path(출력 파일) 중 정확히 하나를
담은 이미지 블록을 돌려줄 수 있습니다.
{"content":[{"type":"image","mimeType":"image/png","data":"<base64-encoded PNG bytes>"}]}
{"content":[{"type":"image","mimeType":"image/png","path":"screenshots/board.png"}]}
두 번째 형식으로 파일 경로를 반환하려면 해당 파일을 요청의 context.outputDir 아래에 저장하세요. 상대 경로는 context.outputDir을 기준으로 해석하며,
절대 경로도 이 디렉터리 안을 가리킬 때만 허용합니다. 상위 경로로 올라가는 경로, 어느
구성 요소에서든 심볼릭 링크를 거치는 경로, 특수 파일, 그 출력 디렉터리 밖의 파일은 거부합니다. artifactize는
호출의 출력을 지우기 전에 이미지 바이트를 읽어 결과에 담으므로, 돌려받는 결과는 로컬 파일 경로가 아니라 이미지
데이터가 모두 담긴 base64 문자열입니다.
이미지는 비어 있지 않은 PNG, JPEG, WebP 파일이며 최대 4 MiB입니다. 형식 검사를 통과한 파일도
손상되어 표시되지 않을 수 있습니다. 형식은 확장자가 아니라 파일 내용으로 판단하며, 각각
image/png, image/jpeg, image/webp와 맞아야 합니다. 잘못된 base64, MIME 불일치, GIF/BMP 같은
지원하지 않는 형식, 애니메이션 PNG는 거부합니다. base64로 인코딩한 뒤에도 정리한 도구 결과 전체
8 MiB 한도가 그대로 적용됩니다. view_image는 같은 형식의 이미지 블록을
돌려주고 같은 파일 크기 제한과 형식 검사 규칙을 쓰지만, 파일은 허용된 Artifact 범위에서 읽습니다.
plain에서는 선언한 input_schema.properties의 최상위 항목만 argv 자리 표시자로 쓸 수
있습니다. 인자 전체를 {query}로 쓸 수도 있고, --query={query}처럼 인자 일부에 넣을 수도 있습니다. 문자열은 그대로
치환하고, 다른 JSON 값은 압축한 JSON으로 치환합니다. 값이 없거나 NUL 바이트가 있으면 프로세스를
시작하기 전에 실패합니다. {{와 }}를 쓰면 중괄호 자체를 넣을 수 있습니다. 치환은 한 번만 하므로,
중괄호, 따옴표, 공백, $(), 세미콜론이 든 값도 셸 코드가 아니라 글자 그대로의 argv 요소 하나로
남습니다. plain 도구는 빈 stdin을 받습니다. stdout은 UTF-8로 읽어 텍스트 블록 하나로 반환하며, 잘못된 바이트는 대체 문자로 바꿉니다. 터미널 색 코드와 ASCII 제어 문자는 지우되 탭, LF, CR, DEL은 남깁니다.
64 KiB에서 자르고 잘렸다는 표시를 붙이며, 0이 아닌 종료 코드면 그 stdout이 도구 오류로
표시됩니다. stderr는 포함하지 않습니다. rg처럼 일치하는 것이 없을 때 0이 아닌 코드로 끝나는
명령이 빈 출력을 정상 결과로 돌려주게 하려면 eval 작성자가 래퍼를 만들어야 합니다.
명령의 실행 파일을 찾을 때도 공통 프로그램 찾기
규칙을 따르며, 파일 Artifact에 적용되는 예외도 같고, 허용 범위를 벗어나 위로 올라가는 경로도 똑같이 거부합니다. JSON 프로토콜 argv는
범위가 정해진 기존 Artifact 참조를 쓸 수 있지만, eval이 허용한 범위 밖의 Artifact를 더할 수는
없습니다. plain argv는 스키마 속성 자리 표시자만 씁니다. 명령 자체는 치환하지 않습니다. 명령은 작성자의 환경에서 해당 Artifact 폴더를 작업 디렉터리로 삼아 실행됩니다. 파일 Artifact라면 그 파일이 있는 폴더에서 실행됩니다. Runtime 환경과 마찬가지로 실제 홈 디렉터리를 쓰며, 호출한 쪽의 ARTIFACTIZE_* 변수는 전달하지 않습니다. 호출마다 별도의 임시·출력 폴더를 주고, 호출이 끝나면 그 폴더를 지웁니다. 기본 제한 시간은 120000ms(1–2147483647)이며, 호출이 정상 종료되거나 취소·시간 초과로 끝나면 명령 프로세스와 그 하위 프로세스를 모두 종료합니다.
계속 실행되어야 하는 보조 프로그램에는 도구 세션을 쓰세요.
명령은 사용자가 신뢰하는 읽기 전용 프로그램으로 보고 샌드박스 없이 실행합니다.
Agent eval은 그 eval의 범위에 있는 모든 Artifact의 Agent 도구를 coverage_spec처럼
<name>_<artifactId>라는 이름으로 쓸 수 있습니다. 두 도구가 같은 이름이 되면 config check는 통과하지만
리뷰는 PREPARATION_FAILED로 실패하며, artifactize tools check가 이를 알려 줍니다. 이름이
겹치지 않을 때까지 도구나 Artifact의 이름을 바꾸세요. Human 도구는
Agent에게 주지 않습니다.
도구 세션
도구 세션을 쓰면 리뷰 하나가 진행되는 동안 하네스를 계속 실행해 두고 여러 도구 호출에서 재사용할 수 있습니다. 저장된 Agent 대화와는 다릅니다. 세션의 start와 stop 명령은 세션에 묶이는 명령 도구와 같은 Artifact에 선언하세요.
[views.agent_sessions.app]
start = { command = "harness", args = ["start"], execution_paths = ["tools/harness"] }
stop = { command = "harness", args = ["stop"], execution_paths = ["tools/harness"] }
[views.agent_tools.click]
session = "app"
description = "Click an element of the running app."
command = "harness"
args = ["act"]
protocol = "json"
start와 stop에는 command와 args가 필요하고, 선택 필드는 execution_paths뿐입니다. 실행 파일을 찾는 방식과 argv에 적용하는 범위는 명령 도구와 같습니다. stdin으로는 명령 도구와 같은 형식의 JSON 요청을 받으며, args: {}를 씁니다. description,
protocol, timeout_ms, 동시 실행 옵션은 받지 않습니다. 명령 도구의 session은 그 명령
도구와 같은 Artifact에 선언한 세션을 가리켜야 하며, 내장 도구와 Human 도구는 session을 받지 않습니다. 도구
이름처럼, eval이 쓸 수 있는 세션의 <session>_<artifact> 이름도 겹치면 안 됩니다. 겹치면
config check는 통과하지만 리뷰는 PREPARATION_FAILED로 실패하니, 세션이나 Artifact의 이름을
바꾸세요.
하네스의 start 명령은 다음 규칙을 따라야 합니다.
- stdin으로 명령 도구와 같은 형식의 JSON 요청을 읽습니다.
ARTIFACTIZE_SESSION_DIR은 artifactize가 주는 별도의 디렉터리이며, 세션에 묶인 도구와 stop이 함께 쓰는 상태를 여기에 둡니다. - 준비되면 stdout에 줄바꿈으로 끝나는 줄 하나를 출력합니다. 그 내용은 무시합니다.
- 세션 내내 start 프로세스를 계속 실행해 둡니다. 이 프로세스가 끝나면 세션도 끝납니다.
세션에 묶인 도구(json과 plain 모두)와 stop 명령은 같은 ARTIFACTIZE_SESSION_DIR을 받으며,
다른 명령과 마찬가지로 실제 홈 디렉터리를 포함한 작성자의 환경에서 실행됩니다. 호출마다 별도의 출력·임시
디렉터리를 받습니다. 같은 Artifact를 동시에 리뷰하더라도 리뷰마다 별도의 세션 디렉터리와 환경을 씁니다. 포트나 디스플레이는 OS의 표준 방식(예: 포트 0이나 자동으로 고른 디스플레이)으로
고르세요. 데스크톱 하네스는 헤드리스 디스플레이를 직접 시작합니다. Agent는 인스턴스 ID를
보지 못하고 start나 stop을 부를 수 없습니다.
실행 경로는 이전과 마찬가지로 리뷰를 시작할 때 고정합니다. 도구 세션은 Agent가 그 세션에 묶인 도구를
처음 호출할 때 시작하고, 이후 도구 호출에서는 같은 세션을 재사용합니다. eval에서 쓸 수 있는 세션이라도 그 세션의 도구를 한 번도 호출하지 않으면 프로세스를 시작하지 않고 세션 디렉터리도 만들지 않습니다. 하네스를 시작하고 준비하는 데 걸린 시간도 리뷰 제한 시간에 포함됩니다. start를 실행할 수 없거나 준비되기 전에 끝나면 Agent에는
PREPARATION_FAILED가 아니라 그 도구 호출의 오류가 전달되며, 이후 그 세션을 호출해도 세션을 다시 시작하지 않고
같은 오류를 돌려줍니다. 준비 단계의 제한 시간은 따로 없으며, 준비가 끝나지 않으면 리뷰가 시간 초과되거나
취소될 때까지 start 프로세스가 계속 실행됩니다. 준비 완료 줄 뒤의 출력은 버립니다.
리뷰 중에 start 프로세스가 끝나면 artifactize는 그 프로세스의 하위 프로세스를 종료하고 실행 중인 세션
호출을 취소합니다. 이후의 세션 호출은 The tool session `app` ended.를 돌려주며, 다시
시작하지 않습니다. 이 오류는 다른 도구 오류와 마찬가지로 저장된 대화에 기록됩니다.
Agent 리뷰는 판정·오류·시간 초과·취소 중 어떤 경우로 끝나든, 결과를 확인하고 저장하기 전에 시작한 세션을 모두 종료합니다. 먼저 실행 중인 세션 호출을 취소하고, 그다음 stop을 실행하며, 최대 30초 뒤에는 artifactize가 세션의 프로그램을 직접 끝냅니다. 프로그램이 끝나면 stop이 실패하거나 멈춰 있더라도 세션 폴더를 지웁니다. artifactize 자체가 강제로 종료되면 stop을 실행할 수 없습니다. 정리에 실패하면 성공 결과 대신 그 실패를 알리며, 이전 세션이 정리되지 않으면 새 세션을 시작할 수 없습니다. 결과를 재사용하거나 실행 중인 리뷰에 합류할 때는 아무것도 시작하지 않습니다.
start와 stop의 실행 경로는 결과의 executionPaths에 <session>_<artifact>.start와 .stop
키로 기록되며, 이 정보는 원격 기록에도 포함됩니다. tools check는 명령을 실행하지 않고,
참조한 세션의 실행 파일과 인자만 확인합니다. 세션에 묶인 도구에 대한 tools check --execute와
session send는 각각 처음 세션 호출을 할 때 새 세션을 시작하고 끝나면 멈춥니다. 세션 도구를 호출하지 않는 follow-up은 아무것도 시작하지 않습니다.
세션 명령은 사용자가 신뢰하는 명령으로 보고 샌드박스 없이 실행합니다. 작업 공간을 바꿀 수 있고, 부모 프로세스와 일부러 분리해 실행한 프로그램은 계속 실행될 수 있습니다.
도구 선언을 확인하고 도구를 직접 실행하려면
tools check를 쓰세요.
Human 도구
Human 도구는 리뷰어가 리뷰하는 동안 실행하도록 미리 선언해 둔 도구입니다. 직접 선언한 명령일 수도 있고,
내장 도구(read, list, section, help, open, graph)일 수도 있습니다.
선언 예는 Human 리뷰에 있습니다. open과 graph는 프로그램을
실행하고, 나머지는 출력을 보여 줍니다. 이 아래에서는 명령 도구를 설명합니다.
리뷰어는 Agent 도구와 마찬가지로 명령 도구를 <operation>_<artifactId>라는 이름으로 씁니다. 이 이름은
eval 범위 안에서 겹치지 않아야 합니다. 예를 들어 Artifact b_c의 작업 a와 Artifact c의 작업 a_b는 둘 다
a_b_c가 됩니다. 이름이 겹치면 Artifact tool names collide: a_b_c 오류와 함께 리뷰의 도구를 쓸 수
없습니다. 작업이나 Artifact의 이름을 바꾸면 됩니다.
인자
인자는 고정된 목록입니다. 자리 표시자는 선언한 Artifact의 폴더나 파일을 가리키는
{artifactPath}와 다른 Artifact를 가리키는 {name}뿐입니다. 폴더 참조에는
{spec}/README.md처럼 경로를 붙일 수 있지만 파일 참조에는 붙일 수 없습니다. 둘 다 --flag=
형태 안에서도 쓸 수 있습니다. 그 밖의 중괄호 형태는 프로젝트를 읽을 때 오류가 됩니다.
도구는 eval의 리뷰 범위에 포함된 Artifact만 살펴봅니다. 의존성을 더하거나 eval 범위 밖의 Artifact에 접근할 수 없습니다. 범위 밖의 Artifact, 존재하지 않는 입력, 심볼릭 링크를 지정하면 호출할 때마다 명령을 실행하기 전에 도구 호출이 실패합니다.
실행
프로그램은 프로그램 찾기에서 설명한 대로 찾습니다. 셸을
거치지 않으며, 명령은 선언한 Artifact의 폴더(파일 Artifact라면 들어 있는 폴더)에서 실행됩니다.
명령에는 리뷰어의 환경 전체(HOME, 디스플레이, XDG 설정, ARTIFACTIZE_* 등)가 그대로 전달되며, 별도의 임시 폴더는
주어지지 않습니다. 리뷰어의 권한과 그 환경에 있는 자격 증명으로 실행되므로 신뢰하는 명령만
선언하세요.
명령 도구는 두 가지 방식 중 하나로 실행됩니다.
output방식에서는 명령이 끝난 뒤 결과가 나오며, 기본 제한 시간은 120000ms(timeout_ms)입니다. 각 줄은 출력되는 즉시 Tool log에 표시됩니다. 결과에는 stdout과 stderr가 각각 최대 64 KiB까지 담기며, 잘린 곳에는 표시가 붙습니다. 0이 아닌 종료 코드면 결과가 오류로 표시되고 종료 상태가 나옵니다.launch방식에서는 프로그램을 시작하자마자 호출이 끝납니다. 편집기나 뷰어를 열 때 씁니다. 리뷰 중에는 프로그램이 끝날 때까지 출력이 Tool log에 나옵니다. 프로그램은 리뷰를 닫거나 artifactize가 종료된 뒤에도 계속 실행되며,timeout_ms는 적용되지 않으니 리뷰어가 직접 닫아야 합니다.request tool과artifactize tools check는 그 출력을 보여 주지 않습니다. 프로그램을 시작했다고 판정이 내려지지는 않습니다.
Tool log
도구의 stdout과 stderr는 리뷰어의 Tool log에 실시간으로 나옵니다. 그래서 도구가 사용자의
선택 내용, 측정값, 저장한 파일 등의 정보를 출력하면 리뷰어가 이를 결과에 복사할 수 있습니다.
로그는 실행마다 ▶ HH:MM:SS · operation · Artifact를 보여 주고, 이어서 출력 줄(stderr는
빨간색), 마지막에 ■ exit CODE(또는 launched, done, cancelled, timed out,
error: …)를 보여 줍니다. 내장 도구의 텍스트는 끝날 때 나오고 ■ done으로 끝납니다. open은
파일을 기본 애플리케이션으로 열고 ■ launched로 끝납니다. graph는 뷰어가 끝날 때까지
그 출력을 기록합니다. 한 번 실행할 때 최대 1 MiB의 출력을 보여 주고, 나머지 출력은 생략했다고 알립니다. 4096바이트가 넘는 줄은 나눠서 보여 줍니다. 로그는 리뷰가 열려 있는 동안만 유지되며, 어디에도
저장되지 않습니다.
데스크톱 앱은 리뷰가 아니어도 Artifact의 Human 도구를 Detail에 보여 줍니다. 도구를 클릭하면 해당 브랜치 워크트리의 현재 상태를 기준으로 바로 실행합니다. 요청도, 담당 지정도, fingerprint 확인도 없고, 증거로 기록되는 것도 없습니다. 출력 줄은 그 Artifact의 Tool log에 기록되며, 이 로그는 앱이 실행되는 동안 남습니다.
리뷰 중에
요청을 맡은 리뷰어만 그 도구를 실행할 수 있습니다. Human 리뷰를 보세요.
도구는 요청과 함께 기록된 선언대로 실행됩니다. 그 뒤로 eval의 범위나 선언이 바뀌었으면 기록된 대로는
더 리뷰할 수 없으므로, 도구를 실행하지 않고 요청을 ERROR(INPUT_CHANGED)로 끝냅니다. 다음에 verify를
실행하면 새 선언으로 리뷰를 다시 요청합니다. 결과를 제출할 때, 그리고 Review나 데스크톱 앱에서 대기 중인
요청을 열 때도 똑같이 확인하고 같은 방식으로 끝냅니다. 도구 오류가 나면 문제를 고친 뒤 다시 시도하세요. 도구 오류는 판정이 아니며, 도구 실행은 결과와 함께 기록되지 않습니다. 도구를 실행하기 전에 eval이 리뷰하는
Artifact의 선언을 다시 읽습니다. 그중 파일 Artifact의 파일이 없는 경우처럼 선언을 읽을 수 없으면 도구를
실행하지 않으며, 요청은 대기 상태로 남으므로 파일을 되돌린 뒤 다시 시도하면 됩니다. 그 Artifact
eval이 읽지 않는 하위 부분이라도 선언을 읽을 수 없으면 도구를 실행하지 못할 수 있습니다.
프로젝트의 다른 곳에 설정 오류가 있어도 Human 작업을 진행하지 못할 수 있습니다. 보고된 선언을
고치고 다시 시도하세요. 그다음 리뷰한 파일을 확인합니다.
fingerprint가 바뀌었거나 계산할 수 없으면 도구를 실행하지 않고 요청을 ERROR(INPUT_CHANGED나
FINGERPRINT_RECHECK_FAILED)로 끝내며, 다음에 verify를 실행하면 리뷰를 다시 요청합니다.
request list는 저장된 요청을 모두(대기 중, 맡음, 확정됨) 보여 주며, --run으로 Run 하나만
볼 수도 있습니다. 요청, Run, eval ID와 상태, 리뷰어가 나옵니다. --json과 request show에는
저장된 이력, 현재 담당 정보, 재사용한 실행, eval 정의(정의를 기록하기 전에 저장된 Run이면 null)가
더해집니다. 이 명령은 저장소 없이도 동작하며 아무것도 실행하지 않습니다. run show와 verify --wait --json은
Run을 요약합니다. 상태별 개수, 종류별로 실행하고 재사용한 요청, 걸린 시간, 시도, 사용량이
나옵니다. provider가 보고하지 않은 사용량은 0으로 보여 주지 않습니다.
팀으로 일하기
artifactize server(설계)로 팀 리뷰 저장소를 하나 운영하면
여러 머신과 CI에서 서로의 판정을 재사용할 수 있습니다. 머신마다
독립된 상태를 사용합니다. 저장소는 각 재사용 키의 모든 기록을 보관하되 가장 최근 기록을
돌려주므로, 강제로 다시 리뷰하는 등 새 리뷰를 수행하면 모든 팀원이 이전 판정 대신 새 판정을 재사용합니다. 팀 워크스루에서 두 머신과 CI가 판정을 공유하는 전체 과정을 처음부터 끝까지 실습합니다.
서버. 소규모 서버에 별도의 상태 디렉터리를 두고 리뷰 저장소를 실행하세요.
artifactize --state-dir /srv/artifactize server token add alice-laptop --scopes read,publish,human
artifactize --state-dir /srv/artifactize server token add bob-laptop --scopes read,publish
artifactize --state-dir /srv/artifactize server token add ci --scopes read
artifactize --state-dir /srv/artifactize server run # http://127.0.0.1:8417/
token add는 각 토큰을 한 번만 출력하니 비공개로 보관하세요. server run은 루프백 주소(127.0.0.1)에서만 연결을 받으므로, 같은 머신의 프로그램만 직접 연결할 수 있습니다.
암호화되지 않은 네트워크로 토큰을 보내지 않고 팀원이 연결하게 하려면
아래의 안전한 연결 설정을 쓰세요.
SQLite 명령줄 도구를 사용해 저장소를 백업하세요. 아래 명령 하나로 위 상태 디렉터리의
데이터베이스를 읽어 별도의 파일에 백업할 수 있습니다.
sqlite3 -readonly /srv/artifactize/review-store.sqlite ".backup '/srv/backups/artifactize-reviews.sqlite'"
두 경로를 호스트에 맞게 바꾸세요. 원본은 서버의 실제
review-store.sqlite여야 합니다. 프로젝트 체크아웃 밖에 있는, 이미 존재하고 쓸 수 있는 백업 디렉터리를 고르세요
(이 예에서는 /srv/backups). -readonly를 쓰면 원본 경로를 잘못 입력해도
그 위치에 빈 데이터베이스가 새로 생기지 않습니다.
서버와 클라이언트는 함께 업그레이드하세요. 0.9에서 바뀌는 점은 0.9로 업그레이드를 보세요. 전체 레퍼런스는 리뷰 저장소 서버를 보세요.
팀원을 안전하게 연결하기
TLS 리버스 프록시는 저장소 앞에 두고, 클라이언트의 HTTPS 요청을 로컬 서버로 전달합니다. 터널은 트래픽을 암호화된 연결로 전달하는 통로입니다. 저장소 호스트에 이미 SSH 계정이 있다면 다음 절차에 따라 SSH 터널을 설정하세요.
-
위처럼 그 호스트에서
artifactize server run을 계속 실행해 두세요. -
팀원의 머신에서 터미널을 열고
you@reviews-host를 그 사람의 SSH 계정과 호스트 이름으로 바꾸세요.ssh -N -L 127.0.0.1:18417:127.0.0.1:8417 you@reviews-host이 터미널은 열어 두세요.
-N은 원격 명령을 시작하지 않고,-L은 로컬 포트 18417을 SSH를 통해 저장소의 포트 8417로 전달합니다. 로컬 포트에도 이 머신에서만 접속할 수 있으며, 머신 사이의 연결은 SSH로 암호화됩니다. -
팀원 머신의 다른 터미널에서 그 터널을 통해 로그인하세요.
artifactize remote login http://127.0.0.1:18417/ # enter this machine's token artifactize remote status
주소가 로컬이므로 여기서는 일반 HTTP가 허용됩니다. 네트워크 트래픽은 암호화된 SSH 터널을 통해 전송됩니다. 저장소의 일반 HTTP 포트를 네트워크에 직접 노출하지 마세요. 터널이 없으면 클라이언트는 TLS 리버스 프록시가 제공하는 HTTPS 주소를 요구합니다. SSH의 표준 호스트 확인과 인증 절차를 따르고, 이를 우회하지 마세요.
로그인하고 결과 공유하기
머신마다 한 번씩 로그인하세요. 토큰은 명령 인자가 아니라 stdin에서 읽습니다. 터미널이 지원하면 직접 입력하는 토큰은 화면에 표시되지 않습니다. Windows에서는 CLI가 토큰 입력을 숨기지 못하면 경고한 뒤 토큰이 화면에 표시된 채 계속 입력받고, Linux와 macOS에서는 입력을 중단합니다. 파이프로 들어온 입력은 터미널 모드를 바꾸지 않고 읽습니다.
artifactize remote login https://reviews.example/ # paste the token
artifactize remote status
로그인하면 다음과 같이 동작합니다.
verify는 저장소의 결과를 재사용하고 새로 만든 GREEN/RED 결과를 게시합니다.status는 원격 재사용을 예측합니다.request submit은 Human 승인을 게시합니다.remote push는 저장소에 연결할 수 없던 동안 만든 결과를 보냅니다.
전체 레퍼런스는 팀 리뷰 저장소 클라이언트를 보세요.
CI. CI는 환경 변수로만 설정합니다. CI를 보세요.
공유 수준. 기본값인 summary는 다음을 보냅니다.
- 판정
- 스키마로 검증한 추가 결과 필드(Runtime eval에서는 종료 코드, 소요 시간, 잘림 표시만)
- 재사용 키, eval 정의 해시, 그리고 키가 포함하는 각 Artifact의
fingerprint와 그 종류(
folder/file/aspect/graph) (기록의artifactKinds) - 프로필과 실행 옵션(백엔드, 모델, reasoning, 제한, 변형), 사용량 카운터. Agent 결과의
executionPaths에는 작업 공간 기준 상대 경로와 경로별 해시도 기록합니다. - 만든 사람(
user@host), Human 리뷰어, 타임스탬프 - Agent 결과라면 저장된 대화에 대한 참조
(
producer.session: 만든 사람, 그 상태 ID, Run, 요청, 세션 ID)
summary는 캡처한 stdout/stderr, 별도의 호출 감사 기록, 로컬
저장소 출처, Agent 대화 자체를 빼고 보냅니다. 그래도 명령과 인자를 포함한
선언된 Runtime 프로필 전체는 보냅니다. 프로필에 적은 경로나 민감한 리터럴은 가려지지 않고 공유됩니다.
executionPaths 기록에도 작업 공간 기준 상대 경로가 들어 있습니다.
full(remote login --share full 또는 ARTIFACTIZE_REMOTE_SHARE=full)은 추가로
캡처한 출력을 포함해 저장된 실행 기록을 그대로 보냅니다. 두 공유 수준 모두 추가 결과 필드에는
텍스트를 자유롭게 쓸 수 있으므로, 공유되는 선언과 pass_schema, fail_schema가 허용하는 필드에는
API 키나 토큰 같은 민감한 정보를 넣지 마세요.
신뢰.
- 서버는 기록에 인증된
publisher, 즉 토큰 이름을 남깁니다.producer와 Humanreviewer는 게시하는 머신이 보고한 값입니다. publish토큰이 있으면 어떤 키에든 GREEN이나 RED 판정 기록을 게시할 수 있습니다. 신뢰할 수 없는 CI(포크 풀 리퀘스트)에는read만 주고,human은 승인하는 사람에게만 주세요. 토큰이 유출되거나 오용되면server token revoke NAME --purge로 그 토큰이 게시한 항목도 삭제합니다.verify --force는 저장소에서 아무것도 읽지 않으므로 의심스러운 기록을 재사용하지 않으며, 새로 리뷰해 게시한 결과가 저장소의 최신 기록이 됩니다.cache rm은 로컬 키의 기록을 지우고,server rm은 저장소에서 키의 기록을 제거합니다.- 저장소는
.artf선언이 아니라$STATE/remote.json과 환경 변수로만 설정되므로, 복제한 저장소가 토큰을 다른 곳으로 보낼 수 없습니다. 토큰은 내 계정만 읽고 쓸 수 있는 파일에 저장되고, 발급받은 저장소에서만 쓰이며, 출력되지 않습니다. - 저장소의 오류 메시지에 토큰의 일부가 들어 있으면 그 메시지는
[withheld: it contained part of the credential sent]로 바뀝니다.
워크스루: 두 머신과 CI가 판정을 공유하기
이 실습에서는 examples/runtime-relations 예제 프로젝트를 사용합니다.
Alice와 Bob은 서로 다른 체크아웃과 상태 디렉터리를 씁니다. CI에는 세 번째
체크아웃이 있습니다. artifactize server 하나가 공유 판정을 보관합니다. 모든
단계를 머신 한 대에서 실행할 수 있습니다. 이 실습에서는 --state-dir로 상태 디렉터리를
달리 지정해 각 “머신“을 구분하고, USER로 결과를 만든 사람의 이름을 정합니다. Linux, macOS, WSL에서 POSIX 셸을 연 다음, examples/가 있는 artifactize 저장소
(git clone https://github.com/lhj6102/artifactize)의
루트 디렉터리에서 아래 명령을 실행하세요.
export WALK=$(mktemp -d) # outside any Git checkout
cp -r examples/runtime-relations "$WALK/alice"
cp -r examples/runtime-relations "$WALK/bob"
printf 'WALK directory: %s\n' "$WALK"
mktemp -d로 체크아웃 밖에 새 임시 폴더를 만듭니다. 생성된 폴더의 경로는 WALK에 저장되며 마지막 명령으로 출력됩니다. 출력된 WALK 경로를 복사해 두세요.
서버, Alice, Bob, 로컬 CI 시연에는 각각 별도의 터미널을 쓰세요.
새 터미널마다 다음을 실행하되, COPIED_WALK_PATH를 방금 출력된
절대 경로로 바꾸세요.
export WALK="COPIED_WALK_PATH"
한 터미널에서 export해도 다른 터미널의 변수는 설정되지 않습니다.
mktemp를 다시 실행하지 마세요. 이 로컬 예제는 모두 같은 폴더를 써야 합니다. 아래
출력은 Alice/Bob 역할을 보여 주는 예이며, 실제 Run ID와 user/host 라벨은
다릅니다.
1. 서버
저장소를 실행하는 호스트에서 머신마다 토큰을 하나씩 만드세요. token add는
각 토큰을 한 번만 출력하며 다시 볼 수 없으니, 그때 저장해 두세요.
artifactize --state-dir "$WALK/server" server token add alice-laptop --scopes read,publish,human
artifactize --state-dir "$WALK/server" server token add bob-laptop --scopes read,publish
artifactize --state-dir "$WALK/server" server token add ci --scopes read
artifactize --state-dir "$WALK/server" server run # Listening on http://127.0.0.1:8417/
server run은 별도 터미널에서 계속 실행해 두세요. 이 실습에서는 같은 머신에서
실행되는 프로그램끼리만 연결합니다. 서로 다른 머신에서 실행한다면 먼저
안전한 연결 설정을 따르세요.
2. Alice가 먼저 리뷰하기
Alice를 위한 두 번째 터미널을 여세요. 첫 번째 터미널에서는 서버가 계속 실행됩니다.
export WALK='/path/from/setup'
cd "$WALK/alice"
export ARTIFACTIZE_STATE_HOME="$WALK/state-alice"
artifactize remote login http://127.0.0.1:8417/ # paste alice-laptop's token; input is hidden when supported
artifactize verify --all --wait
guide/terms [run-FBh4xF-1]: GREEN
intro/heading [run-FBh4xF-2]: GREEN
usage/heading [run-FBh4xF-3]: GREEN
Summary: executed 3 (runtime 3, agent 0, human 0), reused 0 (runtime 0, agent 0, human 0)
verify는 각 결과의 fingerprint를 다시 확인한 뒤 GREEN으로 판정했으므로, 판정, 추가 결과 필드, 프로필, 사용량 카운터, 만든 사람, 타임스탬프를 담은 요약 기록을 게시했습니다.
요약에는 캡처한 stdout/stderr, 별도의 호출 감사 기록,
로컬 저장소 출처가 빠졌습니다. 선언된 Runtime 명령과 인자는
프로필의 일부로 공유되었으며, 그 인자 안의 경로와 민감한 리터럴은
가려지지 않습니다.
3. Bob이 Alice의 판정 재사용하기
Bob을 위한 세 번째 터미널을 열고, 앞에서 복사해 둔 것과 같은 디렉터리 경로를 설정하세요.
export WALK='/path/from/setup'
cd "$WALK/bob"
export ARTIFACTIZE_STATE_HOME="$WALK/state-bob"
artifactize remote login http://127.0.0.1:8417/ # bob-laptop's token
artifactize status | tail -1
artifactize verify --all --wait
Verify actions: will execute 0, will reuse 3, wait 0, blocked 0
guide/terms [run-MxxJJJ-1]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
intro/heading [run-MxxJJJ-2]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
usage/heading [run-MxxJJJ-3]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
Summary: executed 0 (runtime 0, agent 0, human 0), reused 3 (runtime 3, agent 0, human 0)
Bob의 체크아웃에서도 Artifact의 이름·종류·내용이 Alice의 체크아웃과 같으므로 fingerprint와 eval 정의 해시, 재사용 키가 모두 일치합니다. 경로는 상관없습니다. status는 Bob의 로컬 상태를 바꾸지 않고
저장소를 조회했으며, 저장소에서는 이 조회도 기록을 사용한 것으로 집계합니다. verify는 세 기록을 Bob의 로컬 캐시에 미러링했습니다.
artifactize cache list가 저장소를 출처로 하는 그 기록을 보여 줍니다. 이후의
verify는 저장소가 없어도 그 기록을 로컬에서 재사용합니다.
4. Bob이 오프라인으로 작업한 뒤 푸시하기
Bob의 터미널에서 작업 디렉터리를 $WALK/bob으로 유지한 채 다음 명령을 실행하세요.
printf 'Nothing unchanged is reviewed twice.\n' >> guide/usage/page.md
ARTIFACTIZE_REMOTE=off artifactize verify --all --wait
artifactize remote push --dry-run
artifactize remote push
guide/terms [run-PzLGma-1]: GREEN
intro/heading [run-PzLGma-2]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
usage/heading [run-PzLGma-3]: GREEN
Summary: executed 2 (runtime 2, agent 0, human 0), reused 1 (runtime 1, agent 0, human 0)
Would push 2, already in the store 0, skipped 0.
Pushed 2, already in the store 0, skipped 0.
guide/terms는 usage를 참조하므로 재사용 키에 usage가 들어 있습니다. 그래서 다시 리뷰한 Artifact는 usage와 guide뿐입니다.
저장소 연동을 off로 끈 것이 아니라 저장소에 연결할 수 없는 상황이었더라도, verify는 한 번 경고한 뒤
같은 방식으로 로컬에서 리뷰했을 것입니다. remote push는 각 키에 대해 저장소에
아직 없는 가장 최근 로컬 결과를 보냅니다. 미러링한 기록은 보내지 않으며, 토큰에 human이 없으면
Human 승인은 건너뜁니다.
5. CI가 둘 다 재사용하기
CI 설정은 환경 변수로만 합니다. 1단계의 읽기 전용 ci 토큰을 쓰며,
여기서는 CI_TOKEN 변수로 전달합니다. 토큰은 커밋한 파일이 아니라 CI 시크릿으로 등록하세요. --reuse-only agent,human을 쓰면 Agent 리뷰와 Human 승인은 저장소나 캐시에 있는 결과만 재사용합니다.
로컬 시연에서는 먼저 이 터미널에도 WALK를 복사하고,
1단계에서 server token add ci가 출력한 토큰을 CI_TOKEN으로 붙여 넣으세요.
export WALK='/path/from/setup'
export CI_TOKEN='token-printed-for-ci'
cp -r "$WALK/bob" "$WALK/ci" && cd "$WALK/ci"
ARTIFACTIZE_STATE_HOME="$WALK/state-ci" \
ARTIFACTIZE_REMOTE=http://127.0.0.1:8417/ \
ARTIFACTIZE_REMOTE_TOKEN="$CI_TOKEN" \
artifactize verify --all --wait --reuse-only agent,human
guide/terms [run-GpqdSQ-1]: GREEN (reused from remote: bob@laptop, run-PzLGma)
intro/heading [run-GpqdSQ-2]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
usage/heading [run-GpqdSQ-3]: GREEN (reused from remote: bob@laptop, run-PzLGma)
Summary: executed 0 (runtime 0, agent 0, human 0), reused 3 (runtime 3, agent 0, human 0)
CI는 아무것도 실행하지 않았습니다. 읽기 토큰으로는 결과를 게시할 수 없으므로, CI에서 만든 결과는 CI의 로컬 상태에만 남습니다. 서버를 멈추고 새 상태 디렉터리로 같은 명령을 실행해 보세요. 저장소에 연결할 수 없으므로 CI는 로컬에서 리뷰하고 계속 통과합니다.
Remote store is unreachable: Connection refused (os error 111); continuing without the remote review store.
Summary: executed 3 (runtime 3, agent 0, human 0), reused 0 (runtime 0, agent 0, human 0)
반면 토큰이 거부되면 작업은 종료 코드 2로 실패합니다.
Human 승인
Human 판정은 기본적으로 artifactsum을 통해 재사용되며, fingerprint = false면 재사용되지 않습니다. 아래 명령으로
Human 승인이 필요한 파일 하나짜리 프로젝트를 만들고, Bob이 쓸 복사본도 준비하세요. WALK가 아직 공유 디렉터리를
가리키고 있는 Alice의 터미널로 돌아가세요.
mkdir "$WALK/brand" && cd "$WALK/brand"
echo 'logo v1' > logo.txt
cat > index.artf <<'TOML'
name = "brand"
[evals.signoff]
title = "Sign off"
profile = { kind = "human" }
payload.instruction = "Approve the logo."
TOML
cp -r "$WALK/brand" "$WALK/brand-bob"
Alice가 verify --wait를 실행하면 Run이 제출되고 그 Run에 요청이 기록됩니다. 포그라운드에서는 Run이 끝날 때까지 진행 상황을 보여 주며 대기합니다. Alice는 두 번째 터미널에서 같은 디렉터리로 이동하고
ARTIFACTIZE_STATE_HOME을 같은 값으로 설정한 뒤 요청을 맡아
승인합니다. Alice의 토큰에는 human 범위가 있으므로 request submit이
승인을 게시하고, Alice의 verify --wait는 GREEN으로 끝납니다.
첫 번째 터미널에서는 Alice의 verify --wait를 계속 실행해 두세요.
export ARTIFACTIZE_STATE_HOME="$WALK/state-alice"
artifactize verify --all --wait
새 터미널에서도 앞에서 복사한 경로로 WALK를 설정하고, 같은 프로젝트 디렉터리로 이동한 뒤
Alice가 쓰는 상태 디렉터리를 지정하세요. REQUEST_ID는 request list가 출력한
대기 중인 요청의 식별자로 바꾸세요.
cd "$WALK/brand"
export ARTIFACTIZE_STATE_HOME="$WALK/state-alice"
artifactize request list
artifactize request claim REQUEST_ID
artifactize request submit REQUEST_ID --verdict GREEN
이제 $WALK/brand-bob에서 Bob의 상태로 verify --all --wait를 실행하면 그 승인을 재사용하며
(--reuse-only agent,human을 쓰는 CI도 마찬가지), 출력에
리뷰어와 인증된 게시자가 모두 나옵니다.
brand/signoff [run-rWExIl-1]: GREEN (reused from remote: Human sign-off by alice, published by alice-laptop, run-FD9ny6)
Summary: executed 0 (runtime 0, agent 0, human 0), reused 1 (runtime 0, agent 0, human 1)
Bob이 먼저 verify --all --wait를 실행했다면, Bob의 verify --wait는
Run의 진행 상황을 보여 주며 끝날 때까지 대기했을 것이고, Bob의 Run이 아직 열려 있는 동안
Alice가 제출한 승인이 저장소에 반영되면 Bob의 요청도 바로 확정됐을 것입니다. Bob은 승인 요청을 직접 맡지 않으므로
Bob의 Run은 2분 뒤 YELLOW로 끝나고 더는 저장소를 확인하지 않습니다. 그 뒤에 Alice가 승인하면 Bob은
verify를 다시 실행해 그 승인을 재사용합니다. Bob의 토큰에는 human이 없으므로, Bob이 제출한 승인은
경고와 함께 로컬에만 남습니다.
정리하려면 서버를 멈추고 rm -rf "$WALK"를 실행하세요.
CI
지속적 통합(CI)은 팀이 코드를 푸시하거나 풀 리퀘스트를 열 때 자동으로 검사를 실행합니다. CI 작업은 러너 머신에서 여러 명령을 차례로 실행하며, 개발자의 Agent/Human 승인 결과를 재사용할 뿐 그 결정을 직접 내려서는 안 됩니다.
CI 단계로 artifactize verify --all --wait --reuse-only agent,human을 실행하세요. 테스트는 실행하되 리뷰 결과는 캐시나 팀 리뷰 저장소에서 재사용하므로, CI에서는 모델을 호출하지 않고 사람에게 승인을 요청하지도 않습니다.
선택한 모든 eval이 GREEN이면 종료 코드는 0이며, RED(1), ERROR(2), INCOMPLETE(4)이면
CI 작업은 실패로 처리됩니다. 모든 종료 코드는 명령 레퍼런스에 있습니다. Agent 리뷰나
Human 승인에 재사용할 결과가 없으면 그 eval은 실행되지 않고 Run이 INCOMPLETE로 남으므로,
개발자가 verify로 현재 재사용 키에 맞는 결과를 만든 뒤에야 CI가 통과합니다. 기본 artifactsum을 쓰면 결과를 재사용하며, 대상이나 의존성에 fingerprint = false를 지정하면 재사용하지 않습니다.
대기 중인 승인을 병합 게이트에서 빼기
승인은 자동 eval을 막지 않으므로, 개발자의 verify는 사람이 자리를 비운 동안에도 자동 eval을 끝냅니다.
YELLOW(종료 코드 5), DEFERRED 승인, PROVISIONAL 자동 eval 결과는 모두 승인이 끝났다는 뜻이 아닙니다. CI의
--reuse-only agent,human 게이트를 유지하세요. 필요한 승인이 없으면 승인을 요청하지 않고 Run이
INCOMPLETE로 남으며, 통과로 간주되지 않습니다.
사람이 GREEN을 제출하면 CI는 바뀌지 않은 자동 eval 결과와 승인을 재사용합니다. RED는 의존하는 eval을 막습니다. verify가 접수됐다는 것만으로 CI가 성공했다고 보지 마세요.
팀 리뷰 저장소의 판정 재사용하기
아래 YAML은 완전한 워크플로가 아니라 GitHub Actions 단계 하나입니다. 리뷰된 커밋을
체크아웃하고 러너에서 artifactize를 쓸 수 있게 한 다음
(설치 참조), 기존 .github/workflows/NAME.yml 파일의
jobs.YOUR_JOB.steps 아래에 넣으세요. 이번이 처음이라면 GitHub의
워크플로 가이드에서 이 단계를 담을 워크플로와 작업을 만드는 방법을 확인하세요.
저장소 관리자에게 read 범위만 있는 토큰을 요청하세요. GitHub
저장소에서 Settings → Secrets and variables → Actions를 열고,
ARTIFACTIZE_READ_TOKEN이라는 저장소 시크릿(secret)을 추가해 그 토큰을 값으로 넣으세요. 아래의
예시 URL은 팀이 접근할 수 있는 저장소 URL로 바꾸세요. ${{ secrets... }}
표현식이 실행 시점에 시크릿에 저장한 토큰 값을 전달하므로, 토큰을 이 파일에 직접 붙여 넣지 마세요.
다른 CI 서비스에서도 시크릿 저장 기능이나 환경 변수 설정을 쓰세요.
- run: artifactize verify --all --wait --reuse-only agent,human
env:
ARTIFACTIZE_REMOTE: https://reviews.example/
ARTIFACTIZE_REMOTE_TOKEN: ${{ secrets.ARTIFACTIZE_READ_TOKEN }}
- 읽기 토큰으로는 결과를 재사용할 수 있지만 게시할 수는 없습니다.
- 리뷰 저장소에 연결할 수 없어도 검증을 멈추지 않습니다.
verify는 한 번 경고하고 로컬 캐시를 사용해 검증을 계속합니다. 그러면 저장소에만 있는 리뷰는 재사용되지 않으므로 Run은 INCOMPLETE가 됩니다. - 토큰이 거부되거나, TLS 연결에 실패하거나, 설정이 잘못되면 작업이 실패하므로(종료 코드 2), 잘못된 설정이 오류 없이 무시되는 일은 없습니다.
ARTIFACTIZE_REMOTE=off는 명령 하나에 대해 저장소를 끕니다. 그래도 읽을 수 없는remote.json이 있으면 명령이 실패하니, 먼저 고치거나 지우세요.
팀 워크스루에서 이를 처음부터 끝까지 실행해 봅니다.
모델 없이 Agent eval 테스트하기
CI 작업에서는 임시 상태 디렉터리를 쓰고 리뷰 저장소 연동을 끈 채, 루프백 주소로 띄운 가짜 provider에 연결해 Agent eval을 실행할 수 있습니다. 가짜 provider로 테스트하기를 보세요.
기타
실제 개발 환경에서 리뷰를 실행하고 관리하는 데 필요한 보조 기능을 설명합니다.
- 상태, 캐시, 제한에서는 Run과 증거가 어디에 있는지, 캐시를 살펴보고 지우는 방법,
백엔드별 동시 실행 한도, 저장된 Agent 대화와 그 보관 방식을 설명합니다.
artifactize doctor는 provider를 호출하거나 Run을 시작하지 않고 로컬 준비 상태를 확인합니다.models는 쓸 수 있는 모델 ID를 보여 주고,prune은 감사 기록을 남기고, 완료된 Run의 출력 파일 가운데 지워도 되는 파일을 지웁니다. - 운영체제에서는 Linux, macOS, Windows에서 공통으로 쓸 명령을 선언하는 방법과 실행 파일 찾기, 경로, 애플리케이션 열기, 상태를 다룹니다.
- 보조 레퍼런스에서는 기능 가이드보다 자세한 스키마, 라이브러리 API, 프로토콜, 제한을 확인할 수 있습니다.
명령 문법과 종료 코드는 CLI 영역을 보세요.
상태, 캐시, 제한
artifactize doctor를 실행하면 상태가 어디 있는지 볼 수 있습니다. 출력 첫 줄에 상태 디렉터리가 표시되고, 이어서 백엔드, 캐시, 저장된 대화를 점검한 결과가 나옵니다. 모두 준비됐으면 종료 코드 0으로 끝납니다. 이 페이지에서는 상태 디렉터리와 재사용 캐시를 살펴보고 제한하는 방법을 설명합니다. 머신 전체의 Agent 백엔드 사용량을 제한하는 방법과, 저장된 Agent 대화를 얼마나 보관하고 크기를 어떻게 제한하는지도 다룹니다.
상태
상태 데이터베이스인 state.sqlite 하나에 이 머신의 모든 저장소에서 만든 Run이 저장됩니다.
위치는 $ARTIFACTIZE_STATE_HOME, 없으면 $XDG_STATE_HOME/artifactize, 없으면
(Windows에서는) %LOCALAPPDATA%\artifactize, 없으면 $HOME/.local/state/artifactize입니다.
--state-dir PATH를 주면 각 Run의 출력(PATH/runs 아래)을 포함해 상태 전체를 다른 폴더에
둡니다. 저장된 Run은 저장소를 지운 뒤에도 계속 읽을 수 있습니다.
상태는 리뷰하는 저장소나 다른 artifactize 작업 공간 안에 둘 수 없습니다. 상태 디렉터리나 그 위의 어느 폴더에든 .artf 선언, 예전 artifactize.json이나 .artifactizeignore가 있으면 명령은 아무것도 쓰지 않고 실패합니다. 프로젝트 폴더들을 담고만 있는 상위 폴더에는 둘 수 있습니다. 예를 들어 /work/app/index.artf 옆의 /work/.state는 괜찮습니다. 상위 폴더를 탐색할 수는 있지만 목록을 볼 수 없으면 artifactize가
그 안의 선언을 모두 확인할 수 없으므로, 상태는 프로젝트 바깥에 두세요.
Microsoft Store 패키지는 zip이나 Cargo로 설치한 버전과 별도로 Run, 로그인 정보, 캐시를 저장하며, 패키지를 제거하면 Windows가 이를 지웁니다. 그렇다고 격리된 환경은 아닙니다. eval이 실행하는 프로그램은 실제 AppData에 쓰고, Store 앱도 패키지 없이 설치한 쪽의 기존 파일을 읽을 수 있습니다. 두 버전을 함께 설치하더라도 데이터가 격리되는 것은 아닙니다.
상태에는 모든 Run과 그 요청, 판정, 각 eval이 어떻게 실행됐는지, 시작할 때의 정의가 남습니다.
run list, run show, request list, request show,
cache list로 읽을 수 있습니다. Agent 리뷰의
진행 과정과 대화, 도구 호출 내역은 저장된 세션에서 확인할 수 있습니다.
업그레이드. 스키마 6, 7, 8, 9 형식으로 저장된 상태는 artifactize 명령으로 처음 열 때 현재 스키마 10으로 자동 업그레이드됩니다. Run, ID, 캐시 결과, Human 승인은 그대로 남고, SIGNOFFS_PENDING으로 끝난 Run은 YELLOW로 읽힙니다. 업그레이드에는 쓰기 권한이 필요하고 되돌릴 수 없습니다. 스키마 6~9만 지원하는 이전 바이너리로는 업그레이드된 상태를 열 수 없으므로, 이전 버전으로 돌아갈 수도 있다면 먼저 상태 디렉터리를 백업하세요. 스키마 1~5의 상태는 다음 메시지와 함께 거부됩니다(종료 코드 2).
This state was written by an earlier artifactize. Start a new state (set ARTIFACTIZE_STATE_HOME or move the old one away). Only schema 6 and later supported versions can be upgraded.
더 새로운 artifactize가 쓴 상태는 Unsupported state schema version: N; a newer artifactize wrote it.로 거부됩니다. 열려면 artifactize를 업데이트하세요.
부분을 반영하는 재사용 키로 바뀌어도 상태 형식은 그대로입니다. 다만 업그레이드 후 첫 verify에서는
부분이 있는 대상의 eval을 Human 승인까지 한 번 다시 리뷰합니다.
재사용 키를 보세요.
0.9로 업그레이드하면 모든 eval을 한 번 리뷰합니다.
0.9로 업그레이드를 보세요.
토큰은 저장소 밖에 둡니다. Codex 로그인 정보, 리뷰 저장소 토큰, 저장한 API 키와 커스텀
provider(providers.json)를 담는 $STATE/auth가
git 워크트리, artifactize 작업 공간, --repo 안에 있으면, gitignore된 폴더라도 거부합니다.
그러면 login, provider add, remote login은 아무것도 저장하기 전에 두 폴더 경로를 모두 알려
주며 실패합니다.
Codex sign-in storage /work/project/.state/auth is inside the git work tree /work/project; artifactize keeps tokens outside repositories. Use a state directory outside it, or set ARTIFACTIZE_CODEX_AUTH_FILE.
저장소 밖의 상태 디렉터리를 쓰거나, 아무것도 저장하지 않는 ARTIFACTIZE_CODEX_AUTH_FILE과
ARTIFACTIZE_REMOTE_TOKEN을 쓰세요. doctor는 그런 상태에 아직 로그인 정보가 없으면
경고하고, 로그인 정보가 저장되면(예를 들어 기존 상태 디렉터리나 그 상위 디렉터리에서 git init을 한 경우) 심각한 오류로
알립니다.
같은 상태를 쓰는 여러 Run은 완료된 결과를 공유해 재사용합니다. 재사용 키가 있는 완료된 결과는 같은 상태의 모든 Run이
재사용합니다. 두 Run에서 같은 프로필로 같은 리뷰를 동시에 요청하면, 서로
다른 워크트리나 프로세스에서 실행했더라도 두 번째 Run은 리뷰를 새로 실행하지 않고 첫 번째 Run의 결과를 사용합니다. 이런 요청은 원래 실행이
끝나면 그 결과를 쓰므로, 실행 시작 횟수에 포함되지 않고 백엔드 자리도 차지하지 않습니다. 이런 요청도 GREEN이나 RED 판정을
받거나 ERROR로 끝납니다. ERROR 결과는 이후 Run에서 재사용하지 않습니다. 첫 Runtime이나 Agent 리뷰가
취소되거나 끝나지 못하면, 대기 중인 Run 가운데 하나가 이어서 리뷰를 실행하고 나머지는 그 실행이 끝난 뒤 결과를 사용합니다. Human
승인 요청은 다시 생성하지 않습니다. 승인을 요청한 Run이 취소되거나 그 프로세스가 죽으면(OWNER_DIED), 해당 승인 요청과 그 결과가 나올 때까지 대기 중이던 다른 요청이 모두 ERROR로 끝나며, verify를 새로 실행하면 승인을 다시 요청합니다. Run이 YELLOW로 끝나면 대기 중인 승인과 그 결과가 나올 때까지 대기 중인 요청은 그대로 남아 있어 나중에도 제출할 수 있습니다. 대기 중이던 Run을 취소해도 첫 번째
Run은 취소되지 않습니다. --force를 쓰면 항상 따로 실행합니다. 진행 중인 리뷰는 원격
저장소를 통해 공유하지 않으며, 이를 지원하는 설정도 없습니다.
읽을 수 없는 기록
다른 상태 데이터가 정상이더라도 저장된 기록 하나를 읽지 못할 수 있습니다. 그러면 artifactize는 임의로 판정을
정하지 않고 그 기록을 증거에서 뺍니다. 그 요청은 Run 요약에서 빠지고, Run 자체를 읽지 못하면
그 사실을 표시합니다. status와 run show는 그런 기록을 unreadable 아래에 kind, id,
reason과 함께 알리고, 증거를 읽는 명령은 stderr에 Unreadable ... 줄을 출력합니다.
다만 run show로 요청한 Run 자체나 그 Run에 저장된 정의를 읽지 못하면 run show가 실패합니다. 종료 코드는 2이고,
이유는 stderr에 나오며 --json에서는 {"error": "..."}로 나옵니다.
run list는 그런 기록을 확인하지 않습니다. 개수가
모자란다고 그 리뷰가 통과했다는 뜻은 아닙니다. 진단할 수 있도록 상태를 그대로 두고, 새 증거가
필요하면 다시 verify하세요. doctor는 상태 데이터를 열 수 있는지와 해당 스키마를 지원하는지만 확인하며,
기록을 고치지는 않습니다.
캐시 제한
verify Run이 끝나면 저장된 결과를 정리합니다. 아직 남아 있는 프로젝트 폴더(또는 워크트리)마다
eval별 가장 최근 결과는 그 폴더에서 다음에 verify를 실행할 때 재사용하므로 항상 남깁니다. 그래서 큰
프로젝트에서 결과가 많이 쌓여도 각 프로젝트의 eval별 최신 결과는 삭제되지 않습니다. 나머지 결과, 즉 같은 eval의 새 결과로
대체된 이전 결과와 이미 없어진 폴더의 결과는 기록 10,000개와 1 GiB를 넘지 않도록 가장 오랫동안
재사용하지 않은 기록부터 지우며, 승인 결과는 다른 결과를 모두 지운 뒤에야 지웁니다. 기록 하나는 최대
16 MiB입니다. 이보다 큰 결과도 그 결과를 만든 Run과 그 결과가 필요한 Run에는 전달되지만, 나중에 재사용할 수 있도록 보관하지는 않습니다. 기록을 재사용한 경우만 사용으로 집계하며, 내용을
살펴보기만 한 경우에는 집계하지 않습니다. 실행 중인 리뷰나 다른 Run이 아직 필요로 하는 기록도 남깁니다.
정리에 실패하면 그 사실을 stderr에 출력하며, 판정은 절대 바뀌지 않습니다.
이 한도는 재사용에만 적용됩니다. 저장된 Run과 그 출력 파일은 남고, 시간이 지났다고 지워지는
것도 없습니다. 끝난 Run의 출력은 artifactize prune으로 지우세요.
백엔드 수용량
verify는 --jobs N을 주지 않으면 READY인 eval을 모두 한꺼번에 실행하며, --jobs N도 그
Run만 제한합니다. 한 머신에서 여러 Run(워크트리, CI 작업, 팀원의 실행)이 동시에 실행되면, 한 백엔드에 보내는
Agent 리뷰가 그 백엔드의 사용량 한도나 구독 요금제가 허용하는 수를 넘을 수 있습니다.
$STATE/limits.json은 그 상태를 쓰는 모든 verify를 통틀어 백엔드마다 동시에 진행하는 Agent
리뷰 수를 제한합니다.
{"backends": {"codex": 4, "openai": 16}}
키는 프로필에 적는 백엔드 이름(openai, anthropic, gemini, codex, claude-agent, 또는
커스텀 provider 이름)이고 한도는 1–100000입니다. 이 파일에
항목이 없는 백엔드는 동시 실행 수를 제한하지 않으며, 파일 자체가 없으면 어떤 백엔드도 제한하지 않습니다. verify는 시작할 때 이 파일을 읽습니다. 파일은 artifactize가
지원하는 필드만 담은 64 KiB 이하의 일반 UTF-8 JSON 파일이어야 합니다. 그렇지 않으면 verify가 Run을
만들기 전에 멈추고(종료 코드 2), doctor는 심각한 오류로 알립니다.
Agent 리뷰는 실행 중일 때만 그 백엔드의 동시 실행 수에 포함됩니다. 결과를
재사용하거나 합류한 요청은 여기에 포함되지 않습니다. 리뷰 프로세스가 죽으면 쓰던 자리가 비고
그 리뷰는 ERROR(OWNER_DIED)로 끝납니다. 자리가 모두 차 있으면 요청은 Waiting for a free codex slot: all 4 are in use on this machine (limits.json). 같은 사유와 함께 QUEUED로
표시되고, 자리가 비면 Run의 스케줄링 순서대로 대기 중인 요청을
실행합니다. 대기 중인 요청은 --jobs나 --max-executions에 포함되지 않으므로 Runtime eval과 Human 요청, 다른 백엔드의 Agent 리뷰는 계속 진행됩니다. eval mutex 태그가 겹치는 eval은 백엔드 자리를 차지하지 않은 채 별도로 대기합니다. run cancel RUN_ID는 그 Run에서 대기 중이던
요청을 ERROR(CANCELLED)로 끝내고 그 자리를 비웁니다. verify --wait를 중단해도 지켜보기만 멈추며 Run은 계속 실행됩니다.
오류로 백엔드 사용이 중단되면, 그 Run에서 대기 중이던 요청은 해당 백엔드로 실행하지 않습니다.
승인 유예 시간
limits.json으로 아무도 맡지 않은 승인만 남은 Run이 YELLOW로 종료되기까지의 대기 시간도
설정합니다(승인과 Run 종료).
{"signoffIdleGraceSeconds": 120}
값은 0–86400초이며, 필드나 파일이 없으면 120입니다. 0이면 그런 Run은 바로 끝납니다. 백엔드 한도와
마찬가지로 이 상태를 쓰는 모든 Run에 적용되고 Run이 시작할 때 읽으므로, 바꾼 값은 그 뒤에 시작한
Run에만 적용됩니다. artifactize limits(데스크톱 Settings에서도 가능)로 확인하거나 바꾸며, 파일의 다른
필드는 그대로 둡니다.
artifactize limits [--signoff-idle-grace SECONDS] [--state-dir PATH] [--json]
Agent 세션
Agent 리뷰의 대화는 상태 디렉터리에 저장되며,
session show와 session send로 읽거나 follow-up을 보낼 수 있습니다.
limits.json으로 대화 저장 여부와 저장 공간의 크기를 정합니다.
{"agentSessions": {"enabled": true, "maxBytes": 1073741824, "targetBytes": 805306368}}
| 필드 | 기본값 | 뜻 |
|---|---|---|
enabled | true | false면 새 대화를 저장하지 않습니다. 이미 저장된 대화는 계속 읽을 수 있습니다 |
maxBytes | 1 GiB | 이 크기를 넘으면 정리를 시작합니다. 1 이상이어야 합니다 |
targetBytes | maxBytes가 768 MiB보다 크면 768 MiB, 아니면 maxBytes를 4로 나눈 몫(소수점 이하 버림)에 3을 곱한 바이트 수 | 정리할 때 줄일 목표 크기입니다. maxBytes보다 작아야 합니다 |
정리는 verify Run이 eval을 마쳤을 때와 prune을 실행할 때 합니다. 대화가 maxBytes보다
많은 공간을 쓰면, 가장 오래된 세션부터 지워 targetBytes 이하로 줄입니다. 실행 중인 리뷰의
세션이나 session send가 쓰고 있는 세션은 지우지 않으므로, 다음 정리 때까지 목표 크기를 넘을
수 있습니다. verify 중에 정리가 실패하면 그 사실을 stderr에 출력하고 Run은 그대로 둡니다.
agentSessions 값이 잘못되면 verify와 prune이 실패하고(종료 코드 2) doctor가 이를
알립니다.
저장 위치는 $STATE/agent-sessions/이고 나만 읽을 수 있습니다. session show --json은 세션의
이벤트를 출력하며, 이벤트마다 kind가 있습니다.
kind | 담는 내용 |
|---|---|
review | 첫 줄입니다. 세션, Run, 요청, eval ID, 대상, 만든 사람, 백엔드, 모델, reasoning, 매개변수, 예산, 제공한 도구를 담습니다 |
message | 모델과 주고받은 메시지 하나와 그 텍스트, 도구 호출, 도구 결과입니다. follow-up에서 사람이 쓴 말은 question에 들어 있습니다 |
delivery | 스트리밍되는 동안 보여 준 텍스트(delta, complete, interrupted)입니다. 대화나 사용량에는 들어가지 않습니다 |
attempt | provider 시도 한 번입니다. 사용량 수치와, 실패했으면 error와 errorCode를 담습니다 |
end | 리뷰의 result, 또는 errorCode와 error |
send | follow-up의 시작입니다. 번호, 사람이 쓴 text, 제공한 도구를 담습니다 |
answer | follow-up 답변 text, 또는 errorCode와 error |
판정, 결과, 사용량은 Run에 남습니다. 대화와 그 도구 호출은 세션에만 기록되며,
session show --summary가 이를 집계합니다.
follow-up 재생
session send로 저장된 리뷰에 follow-up 질문을 할 수 있습니다.
질문, 답변, 도구 호출은 리뷰 대화 뒤에 이어서 그 리뷰의 세션에 저장되므로, session show가 리뷰와 함께
보여 주며 질문은 쓴 그대로 나옵니다. 아직 실행 중인 리뷰에는 질문할 수 없습니다.
로컬 진단과 유지보수
cache list, cache show, cache rm은 재사용할 결과를 살펴보고 지우며, doctor,
models, prune은 이 머신의 설정을 점검하고 끝난 Run을 정리합니다.
캐시와 유지보수를 보세요.
운영체제
모든 OS에서 공통으로 쓸 명령과 경로를 한 번만 선언하세요. 선언에 적힌 명령은
Linux(x86_64와 aarch64), macOS(Apple 실리콘과 Intel), Windows(x64)에서 실행됩니다. WSL 2에서는
Linux 빌드가 실행됩니다. 리뷰 전에 artifactize tools check를 실행하면 필요한 프로그램을
찾지 못하는 도구를 확인할 수 있습니다. 리뷰 중에 Runtime eval의 프로그램을 시작하지 못하면 그 eval은 RED가 아니라 ERROR가 되고, 도구의 프로그램을 시작하지 못하면 도구 오류를 돌려주며 리뷰는 계속됩니다. 각
OS의 설치 채널은 설치에 있습니다. 이 페이지는 OS마다 다른
점을 정리합니다.
프로젝트 명령은 선언된 그대로 실행
Runtime eval, fingerprint 스크립트, 명령을 실행하는 Agent 도구와 Human 도구는 모든 OS에서
command와 args를 인자 목록 하나로 실행합니다. 셸을 거치지 않으며 OS별로 선언을 따로 작성하지도 않습니다.
리뷰어의 실행 환경에서 쓸 수 있는 명령을 프로젝트에 선언하세요. python3나 grep을 실행하는 eval이라면 모든
리뷰어의 PATH에 그 명령이 있어야 합니다. 파일을 읽고 검색하는 데는
내장 도구가 외부 프로그램 없이 어디서나 동작합니다. open은 OS별로 파일을 여는
기본 명령을 사용합니다. macOS에서는 open, Windows에서는 기본 애플리케이션, Linux와 WSL에서는
xdg-open이며, xdg-open은 설치되어 있어야 합니다.
명령은 Runtime 실행에서 설명한 대로 작성자의 환경에서 실행됩니다. Windows에서는 다른 OS와 달리 시스템 변수도 전달합니다.
Linux에서 AppImage로 실행한 데스크톱 앱은 다른 프로그램을 시작할 때 앱을 실행한 당시의 환경 변수를 전달하되, AppImage가 추가한 설정은 제거합니다. 직접 설정해 둔 변수를 AppImage가 덮어썼다면(GTK_THEME 등) 원래
값으로 되돌리지 않고 지웁니다. 명령에 그 변수가 필요하면 다시 설정하세요.
프로그램 찾기
선언된 프로그램은 tools check, Runtime eval,
fingerprint 스크립트, 명령 도구에서 같은 방식으로 찾습니다.
python3같은 경로 없는 이름은PATH에서 찾습니다. 상대 경로와 빈PATH항목은 명령의 작업 디렉터리 기준으로 해석됩니다. 그래서 Unix에서PATH가 설정되지 않았거나 비어 있으면 명령의 작업 디렉터리에서 실행 파일을 찾습니다. Windows에서는 확장자 없는 이름에PATHEXT의 각 확장자를 차례로 붙여 보므로,npx를 지정하면npx.cmd도 찾습니다.PATHEXT가 없으면 순서는.COM;.EXE;.BAT;.CMD입니다../tools/check처럼/가 들어간 상대 이름은 폴더 Artifact의 허용된 범위 안에서 해석됩니다. 파일 Artifact에서는 상대 경로로 지정한 실행 파일을 대상 파일이 있는 폴더 아래에서 찾으며, 같은 폴더의 다른 파일을 가리켜도 됩니다(예:./inspect). 두 경우 모두..과 심볼릭 링크는 거부됩니다. 실행 파일을 이렇게 찾을 수 있다고 해서 그 파일을 내장 도구나 범위가 정해진 argv 참조의 대상으로 쓸 수 있는 것은 아닙니다.- 절대 경로는 적힌 그대로 실행합니다.
내장 help는 다릅니다. 인자로 지정한 실행 파일은 일반적인 cwd/PATH 검색으로 찾으며, 절대 경로, 상위 폴더 기준 상대 경로, 실행 파일 심볼릭 링크도 받습니다. 하위 명령 인자는 범위가 정해진 파일 인자로 해석하지 않고 그대로 전달합니다. help는 Artifact 범위 안의 파일을 읽는 작업에 한정되지 않고, 신뢰하는 프로그램을 실행합니다.
Windows 배치 파일(.cmd, .bat)도 명령으로 쓸 수 있지만, 모든 문자를 인자로 넘길 수는
없습니다. artifactize는 그런 인자를 바꿔서 넘기지 않고 거부합니다. 오류 메시지는
Process arguments could not be passed safely이고, 아무것도 실행되지 않습니다.
도구 세션은 모든 OS에서 같은 방식으로 멈추고 정리합니다. 세션을 끝낼 때 어떤 프로세스까지 정리하는지, 샌드박스 없이 실행하는 명령에서 무엇을 조심해야 하는지는 도구 세션 계약에서 설명합니다.
경로
선언, 도구 인자, 결과, 기록에 쓰는 논리적 경로의 구분자는 OS와 관계없이 /입니다.
artifactize는 모든 OS에서 경로를 비교할 때 대소문자를 구분합니다. Artifact
참조, 도구 경로, .artfignore, artifactsum files 패턴은
정확한 표기와 일치해야 합니다.
디스크의 표기를 확인하는 방식은 OS마다 다릅니다.
| OS | 디스크의 표기 |
|---|---|
| macOS, Windows | artifactize가 강제합니다. 대소문자를 구분하지 않는 볼륨(둘 다 기본값)에서는 경로의 대소문자 표기가 디스크에 저장된 파일·폴더 이름과 정확히 일치해야 하며, 안에 선언된 폴더 Artifact와 대소문자만 다른 이름의 파일이나 폴더는 읽지 않고 거부합니다. |
| Linux | 파일 시스템이 경로의 대소문자를 구분하는 방식에 맞춰 파일을 엽니다. 대소문자를 구분하는 파일 시스템(보통의 경우)에서는 디스크에 기록된 이름과 정확히 일치하는 경로로만 열 수 있고, 대소문자를 구분하지 않는 파일 시스템(casefold 폴더나 WSL에 마운트한 Windows 드라이브 등)에서는 대소문자만 다른 경로로도 같은 항목을 열 수 있습니다. |
파일과 브라우저 열기
내장 open 도구와 login codex 로그인은
데스크톱의 기본 애플리케이션으로 대상을 엽니다.
| OS | 여는 프로그램 |
|---|---|
| Linux | xdg-open |
| WSL | Linux 배포판 안의 xdg-open |
| macOS | open |
| Windows | 대상에 지정된 기본 애플리케이션 |
WSL은 Linux처럼 동작합니다. wslview나 Windows 프로그램으로 대체하지 않습니다.
xdg-open이 없거나 아무것도 열지 않으면 배포판의 xdg-utils를 설치하고
기본 애플리케이션을 설정하세요. WSL에서 xdg-open은 explorer.exe를 통해 파일을 여는데,
explorer.exe는 파일을 연 뒤에도 실패를 보고하므로, WSL에서는 xdg-open이
종료 상태 4를 돌려줘도 성공으로 처리합니다. login codex는 어떤 브라우저에서든 쓸 수 있도록 로그인 URL도 출력합니다.
데스크톱에서 콘솔 실행
Windows에서 시작 메뉴나 탐색기로 인자 없이 artifactize를 실행하면, 창이 바로 닫히지 않도록
도움말과 터미널 안내를 보여 준 뒤 Enter를 누를 때까지 창을 열어 둡니다. 인자가 있거나, 직접 연 터미널이나
스크립트에서 실행하면 멈추지 않습니다. Linux와 macOS에서는 인자 없이 실행하면 평소처럼 도움말을 보여 주고 바로 종료합니다.
Microsoft Store 패키지를 설치하면 항목 두 개가 표시됩니다. 데스크톱 앱을 여는 Artifactize와 도움말을 여는 Artifactize CLI이며, 명령 별칭은
artifactize 하나입니다. 도구 명령은 artifactize tools로 쓸 수 있습니다. Store 이외의 방법으로
설치하면 독립 실행형 artifactize-tools 명령도 함께 설치됩니다.
상태
기본 상태 디렉터리는 OS마다 다릅니다. Windows에서는 %LOCALAPPDATA%\artifactize,
Linux와 macOS에서는 ~/.local/state/artifactize입니다. Store 버전은
패키지 전용 상태를 따로 유지하며 패키지를 제거하면 Windows가 이 상태를 지웁니다. WSL은 별도의 Linux
상태를 유지합니다. 전체 우선순위와 Windows 오버레이 주의 사항은
상태를 보세요.
보조 레퍼런스
명령 문법과 출력, 정확한 한도, 스키마·프로토콜, 상태 저장 위치를 찾을 때는 아래 링크를 참고하세요. 공통 동작은 기능 영역에서 설명하고, 설정은 설치에서 다룹니다.
- 명령 레퍼런스
- Runtime CLI
- 상태
- 선언(.artf)
- Artifactsum
- Fingerprint 스크립트
- 완료된 결과 재사용
- 캐시 제한
- 파일 Artifact
- eval 의존성
- Agent 백엔드
- Codex
- 가짜 provider로 테스트하기
- Agent 도구
- 도구 진단
- Human 도구
- 리뷰 중의 Human 도구
- 내장 도구
artifactize-toolsCLI- 로컬 진단과 유지보수
- 리뷰 저장소 서버
- 팀 리뷰 저장소 클라이언트
- 운영체제
- 개인정보 처리방침
데스크톱
앱을 열면 이 머신에서 Run을 실행한 모든 프로젝트의 현재 브랜치와, 승인이 필요한 모든 Human 리뷰를 한 화면에서 볼 수 있습니다. Run을 살펴보고, 각 브랜치에서 지금 검증하면 실행될 작업과 증거를 확인한 뒤 Human 승인을 처리하세요. 앱은 CLI, TUI와 상태를 공유하므로 한쪽에서 변경한 내용이 다른 쪽에도 반영됩니다. 앱은 릴리스마다 명령과 함께 배포되며, 설치 방법은 데스크톱 앱을 보세요.
첫 실행 때의 명령 설정, PATH 세부 사항, 업데이트, 정리는 설치 안내를 보세요.
앱 열기
artifactize-desktop
artifactize-desktop monitor --repo PATH
artifactize-desktop review [REQUEST_ID]
artifactize-desktop graph --repo PATH
인자가 없으면 현재 디렉터리와 상관없이 아무것도 고르지 않은 채 앱이 열립니다.
--repo PATH는 그 폴더의 브랜치를 고르고 펼친 뒤 가장 최근 항목을 보여 줍니다. 기본값인 --all은
아무것도 고르지 않으며, 어느 쪽이든 모든 브랜치가 나열됩니다. review는
가장 최근에 승인 대기 상태가 된 Human 리뷰를, review REQUEST_ID는 지정한 요청을 엽니다. review는 --repo를 주어도 브랜치를 고르거나 펼치지 않습니다. graph에는
--repo가 필요하며 그 브랜치의 Current를 보여 줍니다. --state-dir PATH로
상태 디렉터리를 지정하며, 지정하지 않으면 공유 상태 디렉터리를 씁니다. --reviewer NAME으로
협업할 때 리뷰어로 표시할 이름(보통 사용자 이름)을 지정합니다. -h나 --help(모드 뒤에도
쓸 수 있음, 예: artifactize-desktop monitor --help)와 artifactize-desktop help [MODE]는 잘못된 인자와
마찬가지로 stderr에 도움말을 출력하고 2로 종료합니다. 앱을 정상적으로 닫으면 종료 코드는 0이고, 시작하지 못하면
1입니다.
Ctrl+K나 F1을 누르거나 Commands 버튼을 클릭하면 지금 실행할 수 있는 모든 명령을 키와 함께 검색할 수 있는 팔레트가 열립니다. Enter를 누르면 명령이 실행되고, Esc를 누르면 닫힙니다. ?를 누르면 Help가 열려 지금 초점이 있는 곳의 키와, 그래프에서는 각 표시의 뜻을 보여 줍니다. 창 전체에서 쓰는 키는 다음과 같습니다(macOS에서는 Ctrl 대신 Command).
| 키 | 동작 |
|---|---|
| Ctrl+K, F1 | 명령 팔레트 |
? | Help |
| Ctrl+, | Settings를 열고 닫기 |
| Ctrl+B | Pane을 숨기거나 보여 주기 |
/ | 브랜치 검색 |
| Ctrl+O | ID로 요청 열기 |
| Ctrl+R, F5 | 상태를 다시 읽고 브랜치(와 보이는 Current)를 다시 스캔. Human 리뷰에서는 Ctrl+R이 RED이므로 F5를 쓰세요 |
q | 종료 |
앱은 시스템 설정과 관계없이 항상 다크 모드로 표시됩니다.
새 릴리스가 나오면 헤더의 Settings 앞에
VERSION available이 나타납니다. 클릭하면 대화상자가 열리고, 이 앱의 버전과 앱을 설치한
방법에 맞는 업데이트 방법을 보여 줍니다. 실행할 명령은 선택해서 복사할 수 있는 텍스트로,
직접 내려받아 설치할 파일은 링크로 보여 주고, 설치 방법을 알 수 없으면 릴리스 페이지를
안내합니다. 링크는 브라우저에서 열리고, Esc나 Close로 대화상자를 닫습니다. 앱은 시작할 때와
실행 중 하루에 한 번 새 릴리스를 확인하며, 스스로 업데이트하지는 않습니다. Microsoft Store로
설치한 앱은 Store가 업데이트하므로 이 알림이 나타나지 않습니다.
마우스를 올리면 강조만 되고, 자세한 정보는 클릭해야 열립니다. 상자의 Minimize·Expand 버튼만 예외로, 마우스를 올리면 단축키 m을 알려 주는 툴팁이 나옵니다.
Pane
앱 화면은 왼쪽의 Pane과 그 옆의 Main area로 나뉩니다. Pane의 항목은 세로로 한 줄씩 배치됩니다. 맨 위에 검색 칸, 그 아래에 브랜치, 그리고 맨 아래에 사람의 승인이 필요한 리뷰가 있습니다. Pane과 Main area 사이의 구분선을 끌어 크기를 바꾸세요. Main area에 무엇이 표시되든 직접 조절한 비율이 그대로 유지됩니다.
Ctrl+B를 누르거나 헤더의 Pane 버튼을 누르면 Pane이 숨겨지고 Main area가 창 너비 전체를 씁니다. 다시 누르면 Pane이 원래 너비로 돌아옵니다. Pane이 숨겨져 있으면 키보드 초점은 Main area에 있고, /나 Pane으로 돌아가는 Esc를 누르면 Pane이 먼저 나타납니다.
브랜치
브랜치는 Git 저장소의 작업 이력을 나누어 관리하는 단위입니다. 워크트리는 브랜치 하나를 체크아웃해 작업하는 폴더입니다. 한 저장소에 워크트리를 여러 개 둘 수 있습니다. 각 워크트리에서는 브랜치를 체크아웃해 작업하거나, 브랜치에 연결되지 않은 특정 커밋을 체크아웃할 수 있습니다. 각 항목은 artifactize / feat/x처럼
프로젝트와 브랜치로 표시됩니다. 각 항목에는 현재 워크트리와 체크아웃한 브랜치가 표시되며, 분리된 상태에서는 브랜치 대신 폴더 이름이 표시됩니다. Git으로 관리하지 않는 프로젝트는 폴더 이름으로 표시합니다.
나열되는 프로젝트는 이 머신에 Run이 있는 프로젝트와 --repo나 graph --repo로 앱을 시작한
프로젝트입니다. --repo로 시작한 프로젝트는 아직 Run이 없어도 나열됩니다. 제거된
워크트리나 폴더, 또는 Git이 더 이상 나열하지 않는 워크트리는 보이지 않습니다. 추가되거나 제거된 워크트리는
다시 읽지 않아도 몇 초 안에 나타나거나 사라집니다. Run을 시작한 주체가 에이전트인지 사람인지에 따라 항목을 나누어 표시하지 않습니다. 각 브랜치에는 실행한 폴더와 관계없이 그 프로젝트의 해당 브랜치에서 실행한 Run이 나옵니다.
접힌 브랜치의 이름 아래에는 가장 최근 Run의 상태를 나타내는 색 점과 상태 이름, 실행 후 경과 시간(실행 중이면 지금까지 걸린 시간)이 표시됩니다. 브랜치를 클릭하면
펼치고 가장 최근 항목을 보여 줍니다. 이름 앞의 꺾쇠를 클릭하면 Main area는 바뀌지 않고
그 항목만 펼쳐지거나 접힙니다. 펼치면 타임라인이 Run을 최신순으로 나열하며, 각 Run에는
상태와 경과 시간이 나오고, 그 아래 한 줄에 verify를 요청할 때 남긴 코멘트를
한 줄로 줄여 보여 줍니다. 코멘트가 없으면 Run ID를 보여 줍니다. 맨 앞 항목은 워크트리의 지금 상태인 Current입니다. Run이
진행 중이면 그 Run이 Current 자리에 오고, Run이 끝나면 Current가 다시 표시됩니다. 끝의 Older runs는
더 오래된 Run을 가져옵니다. 항목을 클릭하면 회색의 둥근 배지로 표시되며 Main area에 나옵니다. 브랜치는
몇 개든 펼칠 수 있습니다. monitor나 graph 명령에 브랜치를 지정하면 해당 브랜치가 처음부터 펼쳐져 있습니다.
브랜치 이름 끝의 별을 클릭하면 즐겨찾기에 추가되어 별이 채워집니다. 별표가 있는 브랜치가 먼저 나오고, 두 그룹은 각각 검색 순서대로 정렬됩니다. 별표는 앱을 다시 열어도 남아 있습니다. 별표를 떼려면 채워진 별을 다시 클릭하세요.
↑/↓ 또는 j/k로 브랜치, 펼친 브랜치의 타임라인, 대기 중인 리뷰 사이를 이동할 수 있습니다. 브랜치로 이동하면 그 브랜치의 가장 최근 항목을, 타임라인 항목이나 리뷰로 이동하면 해당 항목을 보여 줍니다. →를 누르면 선택한 브랜치가 펼쳐지거나 그 타임라인으로 들어가며, ←를 누르면 타임라인에서 빠져나오거나 브랜치가 접힙니다. 타임라인의
가장 오래된 항목에서 ↓를 누르면 더 오래된 Run을 가져옵니다. Enter를 누르면 Main area로 이동하고, 그곳에서 Detail이 열려 있지 않을 때 Esc를 누르면 Pane으로 돌아갑니다. Pane이 숨겨져 있으면 먼저 Pane을 보여 줍니다.
검색
/를 누르면 검색 칸으로 이동하며, Pane이 숨겨져 있으면 먼저 보여 줍니다. Pane에 있거나 그래프가 보이지 않을 때는 Ctrl+F도 같습니다.
그래프가 보일 때 Ctrl+F를 누르면 그래프에서 찾기가 열립니다. 처음 검색어는 sort:recent입니다. 일반 검색어와
key:value 조건을 모두 만족하는 브랜치와 대기 중인 리뷰만
표시합니다. 일반 검색어는 대소문자를 구분하지 않으며, 프로젝트, 브랜치, 대기 중인 리뷰의 eval 이름에 그 검색어가 들어 있는 항목을 찾습니다. repo:와 branch:는 각각 저장소와 브랜치 필드에 그 검색어가 들어 있는 항목을 찾습니다. 값에 공백이 있으면 repo:"my project"처럼 따옴표로 묶으세요. 따옴표 안의 공백은 새 검색어를 시작하지 않고 그 값에 포함됩니다.
sort:recent는 가장 최근 Run이 있는 브랜치를 맨 앞에, Run이 없는 브랜치를
맨 뒤에 두고, sort:name은 프로젝트와 브랜치 순으로 정렬합니다. 자동 완성으로 검색 키와
값을 채울 수 있습니다. 검색어가 비어 있거나 커서가 공백 바로 뒤에 있을 때 ↓를 누르면 검색 키 후보가 표시됩니다. ↑/↓로 후보를 고른 뒤 Tab이나 Enter를 누르거나 후보를 클릭하면
검색어에 들어갑니다. 자동 완성 후보가 떠 있지 않을 때 Enter를 누르면 목록으로 돌아갑니다. 알 수 없는 키 등으로 검색어를 해석할 수 없으면 브랜치 목록 대신 오류를 보여 주고, 검색어를 고칠 때까지 두 목록을 비워 둡니다. Esc를 누를 때마다
자동 완성 후보를 닫고, 검색어를 sort:recent로 되돌리고, 목록으로 돌아가는 순서로 동작합니다.
대기 중인 리뷰
Pane 아래쪽에는 제거된 브랜치의 리뷰를 포함해 이 머신의 모든 저장소에서 대기 중인 Human 리뷰가 최신순으로 나열되며, 각각 eval, 프로젝트와 브랜치, 대기 시간이 나오고, 누군가 맡았으면 맡은 사람도 나옵니다. 대기 중인 리뷰가 없으면 이 영역은 **Waiting (0)**이라고 적힌 얇은 막대로 줄어듭니다. 대기 중인 리뷰가 생길 때마다 행이 하나씩 추가되고, 영역은 아래에서 위로 늘어나 Pane 높이의 절반까지 커집니다. 그보다 많아지면 목록이 스크롤됩니다. 하나를 클릭하거나 Enter를 누르면 Main area에 리뷰가 열립니다. 같은 Human 리뷰를 공유하는 요청은 하나의 리뷰로 묶어 표시합니다. 그런 요청을 열면 원래 리뷰가 열립니다. 제거된 브랜치의 리뷰는 그 저장소 폴더가 남아 있는 동안만 목록에 나옵니다. 폴더를 삭제하면 해당 행은 사라집니다. 다만 다른 워크트리에 같은 리뷰의 대기 중인 요청이 있으면 그 워크트리 아래에 계속 표시됩니다.
다른 곳에서 만든 새 Run, 결과, 담당 지정, 제출, 그리고 추가되거나 제거된 워크트리는 직접 다시 읽지 않아도 화면에 반영됩니다.
Main area
Main area에는 Pane에서 선택한 Run, 브랜치의 Current, 리뷰 또는 ID로 연 요청이 표시되며, 맨 위 헤더 행 하나가 무엇을 보여 주는지와 그 요약을 알려 줍니다. 아무것도 고르지 않았거나, 불러오는 중이거나, 오류가 났거나, 그래프가 비어 있으면 맨 위에 그 상태를 알리는 한 줄이 나오고 그래프 자리는 비어 있습니다. 다른 Run을 읽을 수 없는 등 이 머신의 기록을 읽는 데 문제가 있으면, 그래프를 옮기거나 가리지 않고 헤더 행 끝에 문제를 몇 단어로 빨갛게 표시합니다. 클릭하면 전체 내용을 볼 수 있고, 다시 클릭하면 접힙니다. 읽기에 실패하면 마지막으로 불러온 내용이 그대로 남아 실제 상태와 다를 수 있으니, 원인을 해결한 뒤 새로 고치세요(Ctrl+R). 선택한 Run 자체를 읽을 수 없게 되거나 그 그래프를 불러오지 못하는 경우는 다릅니다. 메시지가 그래프 자리를 대신하며, 다른 것을 고르면 됩니다. 손상된 기록은 검증을 통과했다는 근거로 삼지 않고 읽을 수 없는 기록으로 표시합니다.
Run
Pane에서 Run을 고르면 Main area에 그 Run의 Artifact Graph가 표시됩니다. 헤더 행에는 Run ID와 요약이 나옵니다. Run 요약에는 판정 표시와 이름이 해당 색으로 나옵니다. 이어서 RED·ERROR eval과 대기 중인 승인이 각각 표시와 이름으로 나오며, 공간이 부족하면 행 끝이 잘립니다. 요약을 클릭하거나 팔레트 명령 Open the Run’s Detail을 쓰면 Run의 Detail이 열립니다. 그 Run의 결과(상태, 실패한 eval, 상태별 eval 수, 걸린 시간, 코멘트 전문)와 대기 중인 항목을 먼저 보여 주고, What, Provenance, Technical은 펼칠 때까지 접혀 있습니다. t를 누르면 Technical이 표시되거나 숨겨집니다. Run이 끝날 때의 검증 결과는 기록으로 남습니다. 나중에 Human 판정을 제출해도
이전 Run의 판정은 바뀌지 않고, 현재 요청의 상태 표시만 바뀔 수 있습니다.
Current
브랜치의 Current는
artifactize status처럼 워크트리의 지금 상태를 스캔하고,
Run 없이 현재 선언의 그래프를 그립니다. 각 Artifact는 처음에 확인 중(checking)으로 표시되다가,
지금 verify를 실행하면 어떻게 될지를 보여 줍니다. reused(모든 eval에서 기존 결과를 재사용), would run,
waiting, blocked 중 하나이며, eval 중 몇 개를 재사용할지도 함께 나옵니다. 스크린 리더는 Artifact마다 이 상태와 실행될 eval 수를 읽어 줍니다.
스캔하는 동안 헤더 행에는 확인 중 표시와 아직 확인할 Artifact 수(3 left)가 나옵니다. 스캔이 끝나면 스캔한 시각을, 실패하면 원인을 표시합니다. Refresh는 그 행 끝에 있습니다.
Current를 다시 스캔하는 경우는 다음과 같습니다.
- Current를 다시 고르거나 그 브랜치의 Run이 끝날 때: 다시 스캔하며, 스캔 중이면 그 스캔을 이어 갑니다.
- 행 끝의 Refresh: 다시 스캔하며, 스캔 중에는 비활성화됩니다.
- 팔레트의 Refresh나 Ctrl+R/F5: 진행 중인 스캔이 끝난 뒤 다시 스캔합니다.
- 검색 때문에 브랜치가 Pane에 보이지 않을 때 Run이 끝나면: Refresh를 누르세요.
Human graph 도구와
artifactize-desktop graph --repo PATH는 이 보기로 앱을 엽니다. 이 보기를 열기만
해서는 어떤 리뷰도 승인되지 않습니다.
그래프
노드에는 상태 기호와 색 띠가 표시되고, 이름 뒤에는 GREEN인 eval 수가 2/3처럼 표시됩니다(Current에서는 재사용될 eval 수). 각 표시의 뜻은 Help(?)에서 볼 수 있습니다. 간선은 입력에서 사용처로 이어지며, RED, ERROR, blocked인 Artifact에서 나가는 간선만 색이 있고 나머지는 회색입니다. 결과가 나오면 노드와 간선이 바로 갱신됩니다.
Run의 그래프와 Current 그래프는 똑같이 조작합니다.
| 조작 | 동작 |
|---|---|
| 클릭, 또는 Tab으로 Artifact에 초점을 옮긴 뒤 Enter | Detail 열기 |
| Find, Ctrl+F | Artifact나 eval 찾기, 즐겨찾기 보기 |
m | 상자 최소화·펼치기(아래 설명) |
| Zoom out, Zoom in, 휠, 핀치, 배경 더블 클릭 | 확대·축소(최대 200%) |
| Fit | 그래프 전체 보기(100%를 넘지 않음) |
| 배경 드래그 | 이동 |
그래프는 처음 나타날 때 전체를 보여 줍니다. 이후 보기 영역은 사용자가 직접 옮기지 않는 한 그대로 유지되며, 새 결과나 스캔·재배치·Detail 열기로는 바뀌지 않습니다.
그래프 일부가 화면 밖에 있으면 그래프 오른쪽 아래(Detail이 열려 있으면 그 왼쪽)에 Navigator가 나옵니다. 그래프 전체를 작게 보여 주며, 각 Artifact는 그 상태 색의 사각형으로, 지금 보이는 부분은 테두리로 표시합니다. 그 안을 클릭하거나 드래그하면 확대 비율은 그대로 두고 그곳으로 보기 영역을 옮깁니다. 그래프 전체가 화면에 들어오면 사라집니다.
모든 그래프는 상위가 왼쪽에 오도록 배치됩니다. 노드가 500개를 넘는 그래프를 이름을 읽을 수 없을 만큼 축소하면 각 Artifact는 상태 색의 사각형으로, 부분이 있는 Artifact는 그 색의 상자 테두리로 보입니다. 그래도 클릭하면 열립니다. 화면에 노드가 500개 넘게 표시되면 이름을 읽을 수 있어도 같은 방식으로 그립니다. Tab과 Enter는 이름을 읽을 수 있고 화면에 500개 이하가 남을 때까지 확대하면 다시 쓸 수 있습니다. Artifact의 Detail에는 양쪽에 이웃이 각각 최대 16개까지 그려지고, 나머지는 개수만 표시됩니다.
부분으로 이루어진 Artifact는 부분들을 감싸는 상자로 그려집니다. 상자 위쪽의 제목 행에는 표시, 이름, 개수가 나오고, 그 아래를 상태 색의 띠가 닫습니다. 부분에 다시 부분이 있으면 그 안에 상자가 하나 더 들어갑니다. 상자가 곧 그 Artifact입니다. 부분이 없는 곳을 클릭하거나 Tab과 Enter를 쓰면 그 Artifact의 Detail이 열리고, 부분을 클릭하면 그 부분의 Detail이 열립니다. 여러 Artifact에 속한 부분은 각 Artifact 안에 하나씩 그려집니다. 그중 하나를 열면 모든 사본이 함께 강조되고, Detail에 몇 번 그려졌는지와 어느 Artifact 안에 있는지가 나옵니다.
상자 오른쪽 위에는 Minimize 버튼이 있습니다. Tab을 눌러 상자 다음에 있는 이 버튼으로 초점을 옮길 수 있으며, 툴팁에서 단축키 m을 확인할 수 있습니다. 누르면
부분을 숨기고 Artifact를 일반 노드 크기로 줄여 표시하며, 이름과 부분 개수, Expand 버튼을 보여 줍니다. 숨긴 부분에
이어진 간선은 이 노드에 이어지고, 숨긴 부분끼리 잇는 간선은 그리지 않습니다. 이 노드도 다른 노드처럼
Detail을 열 수 있고, 찾기 칸에는 숨긴 Artifact도 그대로 나옵니다. Expand를 누르면 상자가 다시
펼쳐집니다. m을 누르면 Tab으로 초점을 옮긴 상자를 최소화하거나 펼칩니다. 초점이 상자에 없으면 Detail이
열린 상자에서 같은 동작을 합니다. 입력하는 중이거나 키보드 초점이 Pane에 있으면 동작하지 않습니다. 최소화는 그 브랜치의
모든 그래프에 적용되고, 다시 펼치거나 앱을 끌 때까지 유지됩니다.
그래프에서 찾기
Run의 그래프나 Current가 보일 때 도구 줄의 Find를 누르거나, 키보드 초점이 Pane 밖(그래프나 Detail)에 있을 때 Ctrl+F를 누르면
그래프 왼쪽 위에 찾기 칸이 열립니다. 입력한 글자가 이름에 들어 있는 Artifact와 eval을 대소문자 구분 없이
그래프 순서대로 보여 줍니다. Artifact는 전체 이름으로, eval은 Artifact / eval 형태로 나오고, 각각
판정 기호와 색이 붙습니다(Current에서는 verify가 할 일). 처음 50개까지 보여 주고, 나머지는 몇 개가 더
있는지만 알려 줍니다. 찾은 항목이 없으면 없다고 표시합니다.
아무것도 입력하지 않으면 이 그래프에서 별표를 단 Artifact를 즐겨찾기로 보여 줍니다. 찾은 항목과 같은 모양으로, 그래프 순서대로 나옵니다. 이 그래프에 별표를 단 Artifact가 없으면 별표를 다는 방법을 알려 줍니다.
↑/↓로 항목을 고릅니다. Enter를 누르거나(고른 항목이 없으면 첫 항목) 항목을 클릭하면 그 Detail이 열리며, eval이면 그 eval의 탭으로 열립니다. 그 Artifact는 Detail 왼쪽 그래프의 한가운데로 오고, 이름을 읽을 수 있을 만큼 확대됩니다. Esc를 누르면 찾기 칸이 닫히고 키보드 초점이 돌아갑니다. 찾기 칸 바깥을 클릭해도 닫히며, 그 클릭은 평소처럼 동작합니다. 그래프가 아무리 커도 찾기로 모든 Artifact에 닿을 수 있습니다. 여러 Artifact 안에 그려진 부분은 한 번만 나오고, 열면 첫 번째 사본이 가운데로 옵니다. 최소화된 Artifact 안의 부분은 계속 숨겨져 있습니다. 열면 그 부분의 Detail이 열리고, 대신 최소화된 Artifact가 가운데로 오며 강조됩니다. 그래프에서 그 부분을 보려면 최소화된 Artifact를 펼치세요.
Detail
Artifact를 클릭하면 그래프 오른쪽에 해당 Artifact의 Detail 패널이 열립니다. 다른 Artifact를 클릭하면 그 Artifact의 Detail로 바뀌고, 그래프 배경을 클릭하거나 Close, Esc, ←를 누르면 닫힙니다. Human 리뷰의 Detail에서 ←는 편집하거나 실행하는 것이 없을 때만 Detail을 닫고, 나머지는 리뷰에서 Esc를 누를 때처럼 먼저 한 단계씩 되돌아갑니다. Detail의 왼쪽 가장자리를 드래그해, 내용을 읽기 편하면서도 그래프가 조금 보이는 너비로 조절하세요. 그 폭은 다음 실행에서도 유지됩니다.
섹션의 머리 행을 클릭하거나 그 위에서 Enter나 Space를 누르면 섹션을 접거나 펼칩니다. 섹션마다 마지막으로 선택한 접기·펼치기 상태를 저장해 두므로, 이후 열리는 Detail과 다음 실행에도 그 상태가 유지됩니다. 단, Human 리뷰의 Tools, Tool log, Result는 항상 펼쳐져 있습니다. 처음에 펼쳐진 섹션은 Evals, Tools, Path, Result, Outcome, Waits for이고, 처음에 접힌 섹션은 Neighbours, Execution options, Execution metadata, Fingerprint, What, Provenance, Debug, Technical입니다.
Artifact Detail은 해당 Artifact 탭에서 열리고, 제목에는 Artifact 이름이 나옵니다. Evals에는 eval마다 판정 표시, 그 색으로 쓴 상태가 나오고, 오른쪽 끝에는 Run에서는 걸린 시간이, Current에서는 선언된 제목이 나옵니다. 클릭하면 그 eval의 탭이 열립니다. Neighbours를 펼치면 그 Artifact를 중심으로 이웃 Artifact와의 관계를 그래프와 같은 노드와 간선으로 보여 줍니다. 왼쪽에는 이 Artifact의 eval이 사용하는 Artifact가, 오른쪽에는 이 Artifact를 사용하는 eval이 속한 Artifact가 있습니다. 이 그림은 이동하거나 확대할 수 없으며, 이웃을 클릭하면 그 이웃의 Detail이 열립니다. 그다음 Tools와 Path가 나오고, 도구를 한 번 실행하면 Tool log도 표시됩니다. Debug에는 대기 중인 의존성을 비롯한 나머지 정보가 접힌 상태로 표시됩니다.
eval의 탭에서는 제목 아래의 칩이 경로처럼([icon] {name} / [eval] …) 읽힙니다. Artifact의 탭으로 돌아가는 Artifact 칩 하나와 eval마다 판정의 표시와 색을 보여 주는 칩이 하나씩 있으며, Current에서는 실행될지, 재사용될지, 아직 확인 중인지를 보여 줍니다.
어느 탭을 보고 있든 Artifact Detail 제목 옆의 별을 클릭하면 그 Artifact에 별표가 붙어 즐겨찾기가 됩니다. 즐겨찾기는 Ctrl+F를 누르고 아무것도 입력하지 않으면 나옵니다. 별표는 그 프로젝트의 모든 브랜치에서 Run과 Current 모두에 적용되고, 앱을 다시 열어도 유지됩니다. 채워진 별을 다시 클릭하면 별표가 빠집니다.
Tools에는 Artifact가 선언한 Human 도구가 아래 리뷰 화면과 같이 operation과 설명이 붙은 버튼으로 나옵니다. 클릭하면 지금 보고 있는 Run과 무관하게, 그 브랜치의 현재 워크트리에서 도구 하나를 바로 실행합니다. 어떤 요청도 맡지 않으며, 실행 결과는 리뷰 증거로 남지 않습니다. 실행 내역은 Artifact의 Tool log에 나오며, Tool log는 첫 실행 때 나타나고 접어 두었다면 다시 펼쳐집니다. 정상 종료 여부는 로그의 마지막 줄에, 실패 내용은 도구 아래에 표시됩니다. 도구 하나가 실행되는 동안 같은 Artifact의 다른 도구 버튼은 비활성화되며, 실행 중 표시 옆의 Cancel 버튼으로 실행을 멈출 수 있습니다. Detail을 닫아도 멈추지 않으며, 출력은 계속 Artifact의 Tool log에 쌓여 Detail을 다시 열면 보입니다. 실행 기록은 앱이 실행되는 동안 그 Tool log에 남습니다. 그래프의 노드에는 도구 버튼이 없습니다. Tools와 별 표시는 Pane의 검색 결과에 그 브랜치가 남아 있을 때만 보이므로, 검색 때문에 브랜치가 숨겨지면 검색어를 지우거나 넓혀야 다시 나타납니다.
eval의 탭은 Summary를 보여 줍니다. 상태 줄에는 표시와 상태, 실행에 든 시간과 토큰(k나 M 단위), 사용한 모델, 끝난 방식이 나오고, 재사용했다면 절약한 시간과 토큰이 나옵니다. 그다음 지시문,
Result(지적 사항은 item과 where를 제목으로 붙인 번호 목록)가 나옵니다. 관련 정보가 있으면
Execution options, Execution metadata(시간과 사용량), Fingerprint, 그리고 나머지 정보를 담은 Debug가 이어집니다. 상태 줄에 나온 내용은 그 아래에서 다시 말하지 않습니다.
Current에서는 eval이 실행될지, 재사용될지, 아직 확인 중인지와 그 이유, 그리고 재사용할 결과를
보여 줍니다. Artifact나 eval의 탭(Current의 Human eval 포함)의 Summary와 Human 리뷰에서 t를 누르면 Debug가 표시되거나 숨겨집니다. 로그를 보고 있을 때는 Summary로 돌아간 뒤 누르세요. 로그가 있는 eval에서는 칩 아래의 Summary와 로그를 전환해 볼 수 있습니다. 전환 버튼에는 텍스트만 표시되며, 선택한
항목은 굵고 진한 글씨로 강조됩니다. 로그는 Agent eval의 Agent log(대화. 별도의 스크롤 막대가 있음) 또는 Runtime eval의 Runtime log(저장된 stdout/stderr. 실시간
로그 스트림이 아님)입니다. 대화가 없거나 원격에만 있으면
이 머신에서 볼 수 없는 이유를 보여 줍니다. Run 안의 Human eval 탭에는 리뷰와 승인이 들어 있으며,
아래에 설명한 컨트롤이 있습니다. 일부 eval만 골라 verify를 실행했을 때처럼, Run에서 선택하지
않은 eval에는 그 Run의 요청이 없습니다. 그 탭은 결과의 Summary, Human 컨트롤, Tool log 없이
섹션을 읽기 전용으로 보여 줍니다.
Agent log는 실시간으로 갱신됩니다. 초점이 있는 Agent log에서 ↑/↓ 또는 j/k는 행 단위로,
PgUp/PgDn은 페이지 단위로 이동하고, Home/End나 Top/Bottom은 양 끝으로 가며, 마우스 휠은
스크롤합니다. 위로 이동하면 자동 스크롤이 멈추고, Bottom으로 돌아가면 새 메시지에 맞춰 다시 자동으로 스크롤됩니다.
Space나 Enter로 화면에 보이는 묶음을 펼치거나 접을 수 있으며, 묶음 제목을 클릭해도
같습니다. 숨겨진 reasoning은 보이지 않고, 공개 reasoning 요약만 보입니다.
ID로 요청 열기
Ctrl+O나 팔레트의 Open a request by ID를 쓰면 저장소에 관계없이
저장된 요청을 Main area에서 열 수 있습니다. 대기 중인 Human 리뷰는 Pane에서 열 때처럼 조작할 수 있고,
다른 요청은 읽기 전용이며 헤더 행의 제목에 read-only가 붙습니다. 완료된 Human 요청을 열면 Human 리뷰 화면이 읽기 전용으로 표시되며,
t를 누르면 Debug가 표시되거나 숨겨집니다. 로그가 있는 다른 읽기 전용 요청을 열면 eval의 탭에서처럼 Summary와 Agent log
또는 Runtime log를 전환해 볼 수 있고, Summary에서 t로 Debug를 표시하거나 숨길 수 있습니다. Close를 누르면 Pane으로 돌아갑니다. 다른 곳에서 일어난
요청의 변경도 화면에 반영되며, Ctrl+R이나 F5로 다시 열지 않고 다시 읽을 수 있습니다.
Human 리뷰
Pane에서 대기 중인 리뷰를 고르거나 ID로 열면 Main area에 Human 리뷰 화면이 표시되고, 그 위 헤더 행에 eval과 제목이 나옵니다. 브랜치나 타임라인 항목을 고르면 리뷰 상태를 유지한 채 그 화면으로 바뀝니다. 열린 양식은 초안을 유지하고, 실행 중인 리뷰 작업은 계속됩니다. Esc는 한 번에 한 단계씩 되돌아갑니다. 실행 중인 작업을 취소하고, 다음에는 양식에서 나가고, 그다음에는 리뷰에서 나가 Pane으로 돌아갑니다(Pane이 숨겨져 있으면 먼저 보여 줍니다). Detail에서는 Detail을 닫습니다.
Human 리뷰는 지시문, 사용할 Tools, 도구의 Tool log, 작성할 Result 순서로 이어지고, 마지막에 요청 ID, 모드, 맡은 사람, 대기 시간이 담긴 Debug가 접혀 있습니다(t를 누르거나 클릭하면 보입니다). 리뷰 화면에는 현재 단계를 나타내는 표시가 하나 있습니다. 맡기 전이면 CLAIM이고 다른 리뷰어가 맡았으면 그 옆에 맡은 사람 이름이 나오며, 내가 맡으면 **REVIEW (yours)**가 됩니다. Main area의 너비가 Detail의 두 배 이상이면 Tool log는 헤더 아래 왼쪽에 표시하고, 나머지 내용은 오른쪽에 Detail과 같은 너비로 표시합니다. 그보다 좁거나 Detail의 Human eval 탭에서는 한 열로 위에서 아래로 읽으며, Tool log는 Tools와 Result 사이의 상자로 나옵니다. 지시문은 전체가 표시되므로, 기준이 길면 열을 스크롤해 읽으세요.
리뷰를 열기만 해서는 아무것도 맡지 않습니다. c나 Claim to review로 요청을 맡습니다. 텍스트 필드 밖에서 u를 누르거나 Release claim을 누르면 담당을 해제하며, 양식을 편집하는 중에도 초안을 남긴 채 해제할 수 있습니다. 다른 사람이 맡은 리뷰는 해제될 때까지 읽기 전용입니다. 담당 지정은 계정을 인증하는 기능이 아니라 리뷰어끼리 작업이 겹치지 않게 하는 잠금이며, 요청을 맡은 사람만 도구를 실행하거나 결과를 제출할 수 있습니다. Human 요청을 처리하는 공통 절차와 DEFERRED 상태의 승인 요청에 관한 설명은
Human을 보세요.
도구는 그 도구를 선언한 Artifact별로 묶이며, 리뷰 대상 Artifact가 먼저 옵니다. 도구를 선언한 Artifact가 둘 이상일 때만 묶음에 Artifact 이름이 붙습니다. 도구마다 실행 표시로 시작하는 operation 버튼과 설명이 있으며, 실행할 수 없으면 그 이유도 표시됩니다. 요청을 맡기 전에는 버튼이 비활성화됩니다. 클릭하거나, 초점이 있는 버튼에서 Enter나 Space를 누르면 바로 실행됩니다. Tab으로 버튼 사이를 이동할 수 있습니다. launch 도구는 애플리케이션을 시작하자마자 호출을 마치며, 도구 실행에 실패하면 판정을 기록하지 않고 Result의 동작 행에 오류만 표시합니다. 도구를 실행하려면 현재 선언이 요청에 저장된 정의와 여전히 일치해야 합니다. 선언이 바뀌었으면 리뷰를 열거나, 도구를 실행하거나, 제출할 때 요청이 ERROR(INPUT_CHANGED)로 끝나며, 다음에 verify하면 리뷰를 다시 요청합니다.
이 리뷰에서 도구를 실행할 때마다 Tool log에 실행 내역이 바로 추가되며, 시작 시각은 로컬 시간으로 표시됩니다. Tool log에서는 긴 줄이 화면 너비에 맞게 줄바꿈되고, 새 출력이 오면 최신 줄이 보이도록 자동으로 스크롤됩니다. 위로 스크롤해 읽으면 그 자리에 머물고, 맨 아래로 다시 스크롤하면 다시 자동으로 스크롤됩니다. 그 텍스트는 선택할 수 있는 일반 텍스트이므로, 도구가 출력한 내용을 결과에 복사하세요. 로그는 앱이 실행되는 동안 유지되며 이 창에서 제출하면 지워집니다. CLI나 다른 창에서 결과를 제출하면 이 창의 편집은 끝나지만 로그는 그대로 남습니다. 로그는 어디에도 저장되지 않습니다.
요청을 맡은 뒤 g나 GREEN을 누르면 GREEN 양식이, r이나 RED를 누르면 RED 양식이 열립니다. 각각 eval의
스키마로 만든 양식입니다(쓸 수 있는 형태).
*는 필수 필드를 표시하고, 비어 있는 선택 필드에는 Optional이 보이며, Add와 지우기 표시로 목록 항목과 그룹을 더하거나 지웁니다. Tab으로 컨트롤
사이를 이동하고 Ctrl+G/Ctrl+R이나 판정 버튼으로 판정을 바꿉니다. Result는 한 행으로 끝나며, 왼쪽에 Release claim, 오른쪽에 Submit GREEN이나 Submit RED가 있고, 그 사이에 실행 중인 작업이나 실패 내용이 나옵니다. Ctrl+S를 누르거나 Submit을 누르면
제출되며, 필드 안에서 Enter를 눌러서는 제출되지 않습니다. 스키마 오류가 나면 문제가 된 필드를
알려 주고 양식을 연 채로 두므로 고칠 수 있습니다. 판정마다 초안이 따로 남으며, 같은 창 안에서는 양식을 나가거나 다른
곳에서 같은 요청을 열어도 제출하기 전까지 유지됩니다. 입력기로 한국어 등을 입력하는 동안에는 단축키가
실행되지 않습니다. 백업을 복원하는 등으로 상태 디렉터리가 바뀌면 열린 리뷰가 닫히고, 그 초안과
Tool log는 버립니다.
완료된 결과는 화면에 열린 채로 남습니다. 결과를 로컬에 저장한 뒤에도
원격 게시에 실패할 수 있습니다. 그러면 양식이 닫히고, 결과는 로컬에 저장됐지만 원격 게시에는 실패했다는 알림이 나옵니다.
판정은 이미 기록되었으니, 다시 제출하지 말고 Settings의 Push results
(또는 artifactize remote push)로 게시를 다시 시도하세요.
나가기와 종료
텍스트 필드 밖에서 q를 누르거나, Commands에서 Quit을 고르거나, 창을 닫으면 종료합니다. 키보드
초점이 편집이나 작업이 진행 중인 Human 리뷰에 있으면 q를 눌러도 종료되지 않으니, 먼저 그 작업을
마치거나 취소하세요. Settings가 열려 있을 때는 q가 동작하지 않습니다.
이 창에서 맡은 Human 요청 중 아직 제출하지도, 담당을 해제하지도 않은 요청이 있으면 그 요청을 알려 주고 먼저 묻습니다.
| 선택 | 키 | 담당한 요청 |
|---|---|---|
| Stay | Esc | 아무것도 바뀌지 않고 앱이 열린 채로 남습니다. |
| Release and quit | u | 담당을 해제하므로 다른 리뷰어가 맡을 수 있습니다. |
종료하면 아직 출력을 내고 있는 도구와 진행 중인 리뷰 작업을 취소하고, 제출하지 않은 초안은 버립니다. launch 도구가 연 프로그램은 계속 실행되니 직접 닫으세요.
Settings
Settings는 화면 위에 모달 창으로 열립니다. Esc를 누르거나 Close를 누르거나 Settings 버튼을 다시 누르면 닫히고, 아래 화면은 열기 전 그대로입니다. 열 때마다 계정, 키, 저장소 정보를 다시 불러오며, 팔레트의 Refresh settings 명령으로도 다시 불러올 수 있습니다. 탭은 Providers, Remote, Limits 세 개이며, 탭 목록에 초점이 있을 때 ←와 →로 차례로 오갈 수 있습니다.
Providers 탭 왼쪽에는 기본 provider(Codex, Claude Agent, OpenAI, Anthropic, Gemini)가 차례로 나오고, 그 아래에 직접 추가한 커스텀 provider의 이름과 Custom provider가 나옵니다. 하나를 고르면 오른쪽에 그 provider의 설정이 나오고, List models로 제공하는 모델을 볼 수 있습니다.
- Codex: 계정 상태를 항목별로 보여 줍니다. 로그인하지 않은 상태, artifactize가 저장한 토큰과 만료 시각, 읽기 전용
ARTIFACTIZE_CODEX_AUTH_FILE, 또는 저장이 거부된 이유 중 하나입니다. 저장된 액세스 토큰이 만료되면 다음에 쓸 때 갱신되고, 외부 파일의 토큰이 만료되면 Codex에 다시 로그인해야 합니다. 외부 파일 모드와 저장 거부 모드에서는 여기서 로그인할 수 없으며, 로그아웃은 artifactize가 저장한 계정에서만 쓸 수 있습니다. Sign in with Codex는 브라우저로 로그인하며, 로그인하는 동안 계정 항목에 진행 중이라고 나오고 Cancel sign-in으로 멈출 수 있습니다. 브라우저가 앱으로 돌아오지 못하면 Finish by hand를 펼치세요. 복사할 수 있는 로그인 주소와 리디렉션 URL을 넣을 칸, Finish sign-in이 나옵니다. 포트 1455를 다른 프로세스가 사용 중이면 브라우저가 여기로 돌아올 수 없다고 알려 주니, 페이지 로드에 실패한 뒤 브라우저 주소 표시줄에서 전체http://localhost:1455/auth/callback?code=…URL을 복사해 붙여 넣으세요. Sign out of Codex는 로컬 토큰을 삭제하며, 서버에서 토큰이 폐기됐는지 확인할 수 없으면 경고합니다. 로그인된 상태에서는 Commands의 Sign in to Codex again으로 로그아웃하지 않고 다시 로그인할 수 있습니다. - Claude Agent: Claude Code의 로그인 상태를 Claude Code가 직접 알려 주는 그대로
(
claude auth status) 보여 줍니다.PATH에claude가 없음, 로그인 안 됨, 로그인 방식과 요금제(예:claude.ai · max)로 로그인됨, 또는 실패한 오류 중 하나입니다. 터미널에서 로그인한 뒤처럼 상태를 다시 확인하려면 Check again을 누르세요. Sign in with Claude Code는artifactize login claude-agent처럼claude auth login을 실행합니다. Claude Code가 브라우저를 엽니다. 브라우저에서 마치세요. 브라우저가 열리지 않았거나 돌아오지 못하면 Finish by hand를 펼쳐 Claude Code가 출력한 URL과 페이지에 나온 코드를 넣을 칸을 보고, 코드를 붙여 넣은 뒤 Finish sign-in을 누르세요. Cancel sign-in은 Claude Code를 멈춥니다. Sign out of Claude Code는claude auth logout을 실행합니다. 어느 쪽이든 끝나면 상태를 다시 보여 줍니다. 로그인 정보는 Claude Code가 보관하며, artifactize는 이를 읽거나 복사하거나 저장하지 않습니다. List models를 누르면 Claude Code가 그 로그인으로 제공하는 모델이 나옵니다 (Claude Agent). - OpenAI, Anthropic, Gemini: 키가 환경 변수(그 이름과 함께)에서 오는지, 여기 저장되어 있는지, 없는지를 보여 주며,
값 자체는 보여 주지 않습니다. 키를 붙여 넣고 Save key를 누르면
artifactize login처럼 저장하고, Remove saved key로 지웁니다. 환경 변수가 설정되어 있으면 그 키를 먼저 씁니다. 이때 함께 저장한 키는 보관되지만 쓰이지 않는다고 표시되며, 지울 수도 있습니다. - 커스텀 provider: Custom provider를 누르면 빈 양식이 열립니다. 이름을 정하고, 종류로 기본 provider의 별칭(그 provider의 로그인이나 키를 씀)과
엔드포인트(API, Base URL, 키(선택 사항)) 중 하나를 고른 다음 Save를 누르세요. 필요한 만큼 추가할 수 있고, 목록에서 하나를 고르면 양식에서 바꾸거나
Remove provider로 삭제할 수 있습니다. 엔드포인트에 저장한 키는 보여 주지 않습니다. 키 칸을 비워 두면
저장된 키를 그대로 쓰고, No key를 체크하면 키 없이 저장합니다. eval에서는
backend에 이 이름을 씁니다. 커스텀 provider를 보세요.
Remote 탭에서는 리뷰 저장소 연결을 관리합니다. 로그인하지 않았을 때는 저장소 URL, 공유 수준, 토큰 칸과 Sign in to the store가 나옵니다. 로그인하면 저장소 URL과 공유 수준은 각각 항목으로, 현재 상태는 한 줄(로그인 상태와 리뷰어, 오늘 이 머신에서 푸시한 결과 수, 또는 푸시나 확인 결과)로 보여 주고, Check status, Push (dry run), Push results, Sign out of the store가 나옵니다. 로그아웃하면 입력 칸이 다시 나옵니다. 저장소가 저장된 토큰을 거부하거나 저장소에 연결할 수 없으면 로그인 입력 칸이 저장소 URL, 문제 내용과 함께 다시 나오고, Sign in to the store 외에는 Check status만 있습니다. 유효한 토큰으로 다시 로그인하거나, 연결을 복구한 뒤 Check status를 고를 때까지 Push results는 없습니다. Summary는 호출 세부 사항, 캡처한 출력, 도구 호출 이력을 빼고, Full은 저장된 실행 기록도 보냅니다. 다만 Summary에도 리뷰 메타데이터, 추가 결과 필드, 선언된 Runtime 명령과 인자, Agent 실행 경로 메타데이터는 포함되어 공유됩니다. 그 선언에는 경로나 민감한 리터럴이 들어 있을 수 있으며, Summary를 골라도 이런 정보가 자동으로 가려지지는 않습니다. 팀에 필요한 개인정보 보호 수준에 맞춰 공유 수준을 고르세요. 로그아웃은 로컬 설정을 제거할 뿐, 서버 토큰은 제거하지 않습니다. 저장소 관리자가 그 토큰을 폐기해야 합니다. 공유와 푸시 동작을 보세요.
Limits 탭에서는 아무도 맡지 않은 승인만 남은 Run이 YELLOW로 종료되기까지의 대기 시간을 설정합니다. 초 단위 칸에 지금 적용 중인 값이 들어 있으며, 따로 바꾸지 않았다면 120입니다. 새 값(0–86400)을 넣고 Save를 누르면
그 뒤에 시작하는 Run에 적용됩니다. artifactize limits와 같은 머신 전체 설정입니다.
Settings에서 하는 계정과 저장소 관리 작업은 CLI와 같습니다. 자격 증명은
.artf에 넣지 않습니다.
Claude Code와 Codex용 플러그인
플러그인은 코딩 어시스턴트에 한 번에 설치할 수 있는 패키지입니다. artifactize
플러그인은 Claude Code와 Codex에 다음을 함께 제공합니다.
- Hey Arti 스킬: 어시스턴트가 artifactize로 프로젝트를 구성하고 검증하게 해 주는 안내
- focus-then-sweep 스킬: 어시스턴트가 RED eval을 고치는 동안 verify를 어떻게 다시 실행할지 알려 주는 안내
- artifactize MCP 서버: 어시스턴트가 프로젝트를 살펴보고 검증 Run을 시작한 뒤 진행 상황을 확인하는 데 쓰는 도구
플러그인은 이 저장소에서 설치합니다. Claude Code와 Codex 모두 이 저장소를 플러그인 마켓플레이스로 인식하므로, 같은 플러그인을 양쪽에서 쓸 수 있습니다. 플러그인은 프로그램을 설치하지 않고, 훅을 실행하지 않으며, 자격 증명을 담지 않습니다.
시작하기 전에
플러그인은 artifactize 프로그램을 실행하므로 먼저 artifactize를 설치하세요.
같은 페이지에서 데스크톱 앱을 받는 방법도 확인할 수 있습니다. 프로그램이
설치되어 있지 않으면 Hey Arti가 이를 알리고, 설치 페이지를 바탕으로 사용 중인 시스템의 기본 설치 방법을 안내합니다.
어시스턴트에 플러그인 추가하기
Claude Code 세션에서 마켓플레이스를 추가한 다음, 그곳에서 플러그인을 추가하세요.
/plugin marketplace add lhj6102/artifactize
/plugin install artifactize@artifactize
셸에서는 claude plugin marketplace add lhj6102/artifactize와
claude plugin install artifactize@artifactize가 같은 일을 합니다.
Codex에서는 셸에서 다음을 실행하세요.
codex plugin marketplace add lhj6102/artifactize
codex plugin add artifactize@artifactize
또는 Codex CLI에서 /plugins를 실행하고 artifactize 마켓플레이스를 고르세요.
Claude Code: /reload-plugins를 실행하거나 새 세션을 시작한 다음, /mcp에서
artifactize 서버를 확인하세요. 평소 말투로 요청하거나, 스킬을
/artifactize:hey-arti 또는 /artifactize:focus-then-sweep로 호출하세요. 서버는 artifactize --repo <project> mcp로 실행되며,
<project>는 세션이 시작된 디렉터리입니다.
Codex: 프로젝트 디렉터리에서 새 Codex 세션을 시작하세요. 서버는
플러그인 폴더에서 artifactize mcp로 실행되며, 도구가 프로젝트를 지정하지 않았다고 답하면 스킬이
그 뒤의 호출마다 세션의 프로젝트 폴더를 넘깁니다(서버가 프로젝트를 찾는 방법). 평소 말투로 요청하거나
$artifactize:hey-arti 또는 $artifactize:focus-then-sweep를 입력해 스킬을 호출하세요.
업데이트
플러그인을 업데이트하면 이 저장소의 main 브랜치에 반영된 릴리스 버전이 적용됩니다.
Claude Code에서는 /plugin marketplace update artifactize로 업데이트하세요. /plugin에서 마켓플레이스의 자동 업데이트를 켜도 됩니다. Codex에서는 codex plugin marketplace upgrade artifactize로 업데이트하세요.
artifactize 프로그램 자체를 업데이트하는 방법은 업데이트와 제거에 있습니다.
플러그인 없이
다른 호스트나 직접 관리하는 설정에서는 서버를 직접 등록하고
(MCP 설정), Hey Arti에 설명된 대로 어시스턴트에
SKILL.md를
제공하세요. focus-then-sweep SKILL.md도
같은 방법으로 제공하세요. 호스트마다 플러그인을 설치하거나 같은 서버를 수동으로 등록하는 방법 중 하나만 쓰세요.
Hey Arti: 프로젝트 리뷰 설계하기
코딩 어시스턴트에게 “Hey Arti, 이 프로젝트는 어떻게 리뷰하면 좋을까요?“라고 물어보세요. Arti는 프로젝트를 파악하고 무엇이 중요한지 물은 뒤, 리뷰가 제대로 이뤄지고 결과를 재사용할 수 있도록 Artifact와 eval 구성을 제안합니다. 선언은 동의를 받은 뒤에만 바꿉니다. 애플리케이션을 빌드하거나 실행하지 않으며, 사람을 대신해 승인하지도 않습니다.
Arti의 안내서인 스킬은
SKILL.md이며,
플러그인에 함께 들어 있습니다.
스킬 받기
Claude Code와 Codex에서는 플러그인을 설치하세요. 플러그인은 이 스킬 파일과 MCP 서버를 함께 제공합니다. Arti는 먼저 artifactize가 설치되어 있는지 확인합니다. 설치되어 있지 않으면 설치 페이지를 안내하고, 사용 중인 시스템에 맞는 기본 설치 방법을 제안합니다. 설치는 요청을 받은 경우에만 진행합니다.
다른 호스트에서는 MCP 설정을 따라 코딩
호스트를 연결하세요. 등록은 도구를 제공할 뿐, 스킬을 설치하지는 않습니다. 링크된
SKILL.md를 수정하지 말고 원본을 그대로 어시스턴트에게 제공하세요.
예를 들어 “이 안내를 따르세요. 편집하기 전에 이 저장소를 파악하고 Artifact와
eval을 제안하세요.“라고 요청하세요. 수정한 사본을 따로 두지 말고 원본 안내서를 그대로 쓰세요.
Arti가 함께 하는 일
평소 말투로 요청하세요. Arti는 먼저 사용자의 상황을 파악해 알맞은 절차를 안내하고, 사용자가 동의한 내용만 변경합니다.
- 개념에 대한 질문: 그 개념을 설명하는 페이지를 바탕으로 답하고, 사용자 프로젝트에 적용한 예와 다음 단계를 제시합니다.
- 도입할 만한지, 어디서 시작할지: 지금 리뷰와 CI에서 무엇이 문제인지 묻고, 가장 도움이 될 곳 두세 곳과 도움이 되지 않을 곳을 짚고, 첫 단계로 eval이 한두 개 있는 Artifact 하나를 제안합니다.
- 새 프로젝트 구성하기: 아래에 설명한 순서대로 진행합니다.
- 큰 저장소에 점진적으로 도입하기: 문제가 가장 큰 영역부터 선언하고, 나머지는 선언하지 않은 채 둡니다. 저장소 전체를 리뷰 하나로 묶지는 않습니다. 첫 영역의 판정을 신뢰할 수 있게 된 뒤 다음 영역을 추가합니다.
- 기존 설정 점검하기:
config_check와config_graph를 실행하고, 결과를 모범 사례와 대조하고, 문제점과 해결 방안을 먼저 설명한 뒤 수정해도 되는지 사용자에게 묻습니다. - 프로젝트가 성장하거나 바뀌었을 때: 먼저 새 구성 요소를 별도 Artifact로 둘지, 어떤 eval이 그것을 쓰는지
사용자와 합의합니다. Artifact가 너무 커지면 따로 편집할 수 있는 단위로 나누고, 변경 전후의
status를 비교합니다. - “왜 이게 다시 실행됐지?” 또는 “verify가 느려요”:
status를 읽습니다. 너무 자주 다시 실행된다면 Artifact의 범위를 너무 넓게 잡았거나 fingerprint에 불필요한 파일까지 포함했기 때문일 수 있고, 너무 드물다면 입력을 쓰는 eval이 그 Artifact를 이름으로 참조하지 않았을 수 있습니다. 실행 옵션을 조정하는 대신, 찾은 원인을 해결할 방법을 제안합니다. - 아래에서는 결과를 설명하는 방법, 실행 중인 애플리케이션을 리뷰어가 확인해야 하는 상황, 팀 공유와 CI 설정을 다룹니다.
새 프로젝트를 구성할 때 Arti는 다음 순서로 진행합니다.
- 프로젝트를 파악합니다. 코드, 문서, 명세, 에셋, 빌드와 테스트 명령을 읽은 다음, 파일만 읽어서는 알기 어려운 프로젝트의 목표, 함께 바뀌는 요소, 사람의 판단이 필요한 부분, CI가 보장할 사항을 사용자에게 확인합니다.
- 구성을 제안합니다. 각 Artifact와 eval에 대해 누가 어떤 입력을 어떤
기준으로 판단할지 정리해 제안하고, 구조를 바꾸기 전에 그 이유를 설명한 뒤
사용자의 동의를 받습니다. 프로젝트 지침을
따르고 기존 Human 리뷰 담당자와 승인 책임은 그대로 유지하며, 새 승인 절차를 추가하기 전에 사용자에게 설명합니다.
팀에서 아무도 리뷰하지 않기로 합의한 입력에만
basis = true를 설정하며, 끝나지 않은 리뷰를 우회하려는 목적으로는 절대 표시하지 않습니다. - 필요한 내용만 담아 간단한 선언을 작성합니다. 현재 형식으로 쓰고,
config_check로 검증하며,status로 무엇이 실행되고 무엇이 재사용될지 보여 줍니다. 그다음 무엇이 바뀌었는지 알려 줍니다. - artifactize에 검증을 요청하고 Run의 진행 상황을 확인합니다(아래).
Arti가 추천하는 모범 사례
- 독립적으로 고치고 리뷰할 수 있는 단위로 Artifact를 나누고, 각각의 검증 요건을 구체적으로 정하세요. 저장소 전체에 대한 리뷰 하나는 피하세요.
- eval은 실제로 쓰는 각 입력을
{name}으로 가리킵니다. 같은 저장소에 있다고 해서 의존 관계가 생기지는 않으며, 명령이 읽는 파일도 eval의 입력에 자동으로 추가되지는 않습니다.app폴더 안의ui같은 부분은app을 이루지만,app의 eval이 이름을 적지 않으면 그 입력이 아닙니다. - 부분이 실패했을 때 전체도 통과하지 않아야 한다면 그 Artifact를 전체의 부분으로 선언하세요
(구성 참고). 전체의 폴더 안에 선언한 Artifact는 자동으로
부분이 됩니다. 다른 곳에 있거나 여러 상위 Artifact가 함께 쓰는 부분은 각 상위 Artifact의
parts에 적으세요. 부분이 실패하면 전체도 실패하고,verify whole은 부분까지 함께 다룹니다. 각 부분은 자기 몫을 검사하고, 전체는 부분들이 함께 동작하는지만 검사하며 그 eval이 쓰는 부분의 이름을 적습니다. 파일 하나인 부분은 파일 Artifact로, 큰 폴더 곳곳에 파일이 흩어진 부분은 그 파일을 골라 담는 aspect로 선언합니다. - eval 하나에는 확인할 것을 하나만 두세요. 명령으로 확인할 수 있으면 Runtime eval을, 판단이 필요하면 Agent eval을, 사람이 직접 판단하거나 승인해야 하는 경우에만 Human eval을 쓰세요. Artifact의 Runtime eval과 Agent eval이 모두 GREEN이 된 뒤에만 사람에게 Human eval을 요청합니다.
- Artifact 하나에 대한 기준은 그 eval 안에 두고, 여러 Artifact가 공유하는 규칙은 그 eval들이 읽는 규칙 문서에 두세요.
- 결과 스키마는 작게 유지하세요. GREEN에는 요약을, RED에는 구체적인 지적 사항을 담습니다(문법은 선언에 있습니다).
- 기본 fingerprint(artifactsum)를 유지하고, 리뷰어에게는 필요한 읽기 전용 도구만 주세요.
아래 표에서 Arti가 추천하는 조합별로 Artifact에 선언할 eval과 각 eval의 참조 대상을 확인할 수 있습니다.
- 라이브러리와 그 사용처: 라이브러리에 테스트를 두고, 라이브러리를 쓰는 코드의 리뷰에서는
{library}를 참조합니다. - 명세와 앱: 앱에는 앱의 테스트를 실행하는 Runtime eval과
{spec}을 기준으로 리뷰하는 Agent eval을 둡니다. - 앱과 E2E 테스트: 테스트 모음을 실행하는 eval은 앱에 선언하며, 그 인자에
{e2e-tests}가 들어갑니다. 테스트 코드의 eval에서는 코드 스타일을 리뷰하고, 테스트가 각 기능을 충분히 검증하는지 확인합니다. - 문서와 에셋: 문서가 설명하는 코드와 문서 내용이 맞는지 리뷰합니다. 각 에셋은 각각 별도의 파일 Artifact이며, 필요하면 사람의 승인을 받습니다.
- 모노레포의 연동 규약: UI와 API에 각각 eval을 두고, 통합 eval에서 두 구성 요소와 그 사이의 인터페이스 규약을 참조합니다.
- 생성된 파일: 생성기와 그 입력을 리뷰하거나, 생성기를 참조해 출력을 리뷰합니다.
- 규칙 문서: 규칙 문서는 대개 Human 승인을 받는 Artifact로 선언하며, 그 규칙이 적용되는 Artifact의 eval이 읽습니다.
Arti는 다음 방식을 피하도록 안내합니다.
- 암묵적인 의존성
- 저장소 전체를 한 번에 리뷰하는 eval
- 구현 담당자가 규칙을 어기는지 감시하는 데만 쓰는 eval(예: 아무도 테스트를 고치지 않았는지 해시로 확인하는 eval)
- 요청하지 않은 실행 옵션
- GREEN을 얻으려고 판단 기준을 완화하는 일
Arti는 사용자 상황에 맞는 예제로 리뷰 구성 방법을 보여 줍니다.
예제에서는 Runtime 관계, 승인이 있는 Agent 도구,
파일 Artifact로 선언한 글을 볼 수 있습니다. 데모 프로젝트 website/demo/shop에서는 페이지가
사용하는 스타일 토큰을 기준으로 검사하고, website/demo/brand에서는 페이지에 들어간
로고의 승인을 받습니다. artifactize 자체 저장소에서는 승인받은 규칙 문서를
그 규칙이 적용되는 코드의 eval이 읽고, 앱의 eval이
E2E 테스트 모음을 실행합니다. 스킬 안내서 끝에는 프로젝트에 맞게 고쳐 쓸 수 있는 간단한 시작용 선언 예제가 있습니다.
eval의 지시문, 결과 스키마, Runtime 명령을 바꾸면 eval의 평가 기준도 달라집니다. 태그, 제목, 실행 옵션, 도구 선언은 그렇지 않습니다. 수정한 뒤 status를 실행해, 바뀐 입력과 그에 의존하는 대상만 다시 리뷰하고 나머지는 재사용한다고 표시되는지 확인하세요. Fingerprint와 재사용을 보세요.
MCP를 먼저 쓰기
프로젝트에 어떤 Artifact와 eval, 의존성이 선언되어 있는지, 변경이 어디에 영향을 미치는지
Arti에게 물어보세요. 선언이 올바른지, 어떤 eval을 실행하거나 재사용하거나 대기시킬지, 도구와
세션이 제대로 설정되어 있는지도 확인해 달라고 하세요. Arti는 artifactize의 MCP 도구가 등록되어 있으면 그것으로,
없으면 artifactize config check, artifactize config graph, artifactize status --all,
artifactize tools check로 확인해 답합니다.
도구 세션
리뷰어가 실행 중인 프로그램을 살펴봐야 할 때, Arti는
views.agent_sessions.<name>.start/stop으로 선언한 세션과 session = "<name>"으로 묶은 명령 도구를 보여 주며,
프로그램 파일도 Artifact의 fingerprint에 반영되도록 해당 Artifact 안에 둡니다.
세션의 시작부터 종료까지는 artifactize가 관리합니다.
도구 세션을 보세요.
계속 실행되는 Run 지켜보기
Arti는 verify_start로 시작하고 돌려받은 Run ID를 보관하며,
호스트가 MCP 진행 상황을 보여 주면 verify_watch로, 그렇지 않으면 verify_wait로 진행 상황을 확인하고,
verify_result로 지적 사항을 읽습니다. Run이 접수되었다고 해서 검증을 통과한 것은 아닙니다. Runtime eval의 실패 원인은 request_logs로, Agent eval의 지적 사항은 session_show로 살펴봅니다.
Run은 artifactize가 관리합니다. 터미널을 닫거나, 연결을 끊거나, 에이전트의
턴을 끝내도 Run은 멈추지 않으며, Run을 취소하는 방법은 verify_cancel뿐입니다.
Run과 스트리밍을 보세요.
Arti는 verify 요청마다 추측 실행을 켤 수 있습니다. 이번 Run에서 실행 대상으로 선택한 승인 요청은
다른 eval의 실행을 막지 않습니다. 선택 범위 밖의 승인은 다른 eval의 실행을 막으므로, 선택 범위에 해당 Artifact를 추가하거나
선택 범위를 {"kind": "all"}로 넓히지 않으면 Run은 INCOMPLETE로 끝납니다. YELLOW는 완전한 승인이 아니라 사람의 승인이 아직 남아 있다는 뜻이며, 그 승인은 사람이 직접 제출해야 합니다.
Arti는 각 결과를 다음과 같이 다룹니다.
- GREEN: 현재 내용에 대한 검증이 끝났습니다.
- RED: 지적 사항을 사용자가 이해하기 쉬운 말로 설명하고, 부정확한 문서나 기준처럼 eval이 판단하는 Artifact 쪽을 고칩니다. 올바른 코드를 잘못된 문서나 기준에 억지로 맞추거나 리뷰 기준을 완화하지 않으며, 그다음 다시 검증합니다.
- BLOCKED: 그 eval을 실행하기 전에 통과해야 할 상위 eval이 실패했습니다. 보통 해당 eval이 입력으로 쓰는 Artifact에서 RED나 ERROR가 난 경우입니다. Arti는 그 입력을 먼저 고친 뒤 다시 검증합니다.
- ERROR: eval을 실행할 수 없었습니다. Arti는
request_logs나session_show를 읽고 필요한 프로그램이 없는 등 실행을 막은 원인을 해결하며, 판정 자체를 고치지는 않습니다. - YELLOW: 나머지는 모두 통과했고 사람의 승인만 남았습니다. 완전한 승인이 아니며, Arti는 사람에게 넘깁니다(아래).
- INCOMPLETE: 필요한 증거가 없습니다. 예를 들어 CI가 기존 리뷰를
재사용하기만 하는 경우입니다. Arti는
verify로 빠진 eval을 실행해 부족한 증거를 확보합니다.
사람에게 넘긴 뒤 대화 마치기
Arti는 request_list/request_show로 대기 중인 요청과 그 리뷰 기준을 알려 주고,
artifactize review REQUEST_ID(또는 평소 쓰는 리뷰 인터페이스)로 요청을 여는 방법을 안내합니다.
Human 리뷰를 절대 맡거나, 승인하거나, 제출하지 않습니다. 독립적인 작업을 계속하거나, 저장소, Run, 대기 중인 요청, 다음 할 일을 짧게 정리해 사용자에게 넘깁니다. Run이 아직 끝나지 않았다면 나중에 진행 상황을 확인하고 작업을 이어 갑니다. YELLOW로 끝난 Run의 판정은 바뀌지 않고, 나중에 제출한 승인은 요청에만 반영됩니다. 따라서 Arti는 verify를 다시 실행해 새 Run에서 그 승인을 재사용합니다. 사용자에게 넘기고 응답을 마쳐도
Run은 취소되지 않으므로, 연결을 유지하려고 대화를 이어 가거나 상태를 반복해서 조회할 필요가 없습니다.
팀과 CI
기존의 팀 리뷰 저장소를 쓰고, 자격 증명은
선언, 스킬 사본, 대화 기록, MCP 등록에 넣지 마세요. CI는
읽기 전용 토큰과 artifactize verify --all --wait --reuse-only agent,human을 쓰므로,
Runtime eval을 실행하고 Agent와 Human 증거를 재사용합니다.
CI 가이드를 보세요.
Focus then sweep: verify를 반복하는 방법
코딩 어시스턴트가 RED eval의 지적을 반영해 Artifact를 고치면, 그 Artifact를 읽는 eval을 모두 다시
리뷰해야 합니다. 이전에 GREEN이었던 eval도 마찬가지입니다. 수정할 때마다 verify --all을 실행하면 매번 시간과 비용이 들지만, eval 하나의 지적 사항을 고치다가 다른 eval까지 실패하는 경우는 드뭅니다.
focus-then-sweep 스킬은 어시스턴트가 고치고 있는 eval만 다시 실행하고, 나머지는 마지막에
한 번에 리뷰하도록 안내합니다.
스킬 파일은
SKILL.md이며,
플러그인에 함께 들어 있습니다. Claude Code에서는 /artifactize:focus-then-sweep로
호출하고, Codex에서는 $artifactize:focus-then-sweep를 입력하세요. Run 결과가 RED로 나오면
어시스턴트가 알아서 이 스킬을 쓰기도 합니다. 다른 호스트에서는 Hey Arti와
같은 방법으로 원본 파일을 그대로 대화에 첨부하세요.
세 가지 방식
어시스턴트는 작업마다 하나를 고르며, 기본은 방식 A입니다. 어시스턴트는 MCP 도구로 답할 수 있으면 MCP 도구를 쓰고, 그렇지 않으면 CLI를 씁니다.
- 방식 A: 먼저 집중 실행, 마지막에 전체 실행
- 집중 실행(focus): RED eval 하나를 고친 뒤 GREEN이 될 때까지 그 eval만 다시 실행하고
(
artifactize verify --eval app/review --speculate --wait, 또는 scope{"kind": "eval", "evalId": "app/review"}와speculate: true로verify_start), 그다음 RED eval로 넘어갑니다. 서로 겹치지 않는 수정을 한다면, 관련된 RED eval 여러 개를 한 Run에서 함께 실행 대상으로 선택할 수 있습니다(--evals app/review,docs/matches-app, 또는 scope{"kind": "evals", "evalIds": [...]}). 수정 때문에 다시 리뷰해야 하는 eval은 반복할 때마다 실행하지 않습니다. 고칠 대상은 그 eval이 평가하는 Artifact이며, GREEN을 받으려고 eval을 느슨하게 바꾸지 않습니다. 집중 실행한 Run의 결과는verify_start다음에verify_wait와verify_result로 확인합니다.verify_result는 실패한 eval과 그 요청 ID를 알려 주고, 리뷰어가 보고한 결과는request_show로, Runtime eval의 출력은request_logs로 봅니다(CLI에서는artifactize run show RUN_ID --json). 다시 리뷰해야 하는 eval의 결과가 아직 없으므로 이런 Run은 보통Unmet obligation:줄과 함께 INCOMPLETE(종료 코드 4)로 끝납니다. 예상한 결과이므로 어시스턴트는 집중 실행 대상으로 삼은 eval의 판정만 확인합니다. BLOCKED eval에는Dependency verdict RED: core/tests처럼 막고 있는 RED eval이나 ERROR로 끝난 eval이 나옵니다. 어시스턴트는 해당 eval을 먼저 고친 뒤 다시 실행합니다. ERROR는 검사를 실행하지 못했다는 뜻이므로, 어시스턴트는 판정이 아니라 그 원인을 고칩니다.--speculate를 붙이면 eval이 참조하는 입력이 수정 때문에 다시 리뷰 대상이 되었어도 그 eval을 실행합니다. RED 승인을 다시 받을 때는 eval 대신 그 Artifact를 선택합니다. 같은 Artifact의 자동 eval이 모두 GREEN이 된 뒤에야 사람에게 승인을 요청하기 때문입니다. - 전체 실행(sweep): RED eval이 모두 GREEN이 되면 전체를 한 번 실행합니다.
artifactize verify --all --wait를 쓰거나, scope{"kind": "all"}로verify_start를 호출한 뒤verify_wait와verify_result로 결과를 봅니다. 바뀌지 않은 결과는 앞서 집중 실행한 Run의 결과까지 재사용하고, 다시 리뷰해야 하는 eval만 실행합니다. 새 RED eval이 나오면 해당 eval을 집중 실행하는 단계로 돌아가고, 전체 실행 결과가 GREEN이나 YELLOW이면 반복을 마칩니다.
- 집중 실행(focus): RED eval 하나를 고친 뒤 GREEN이 될 때까지 그 eval만 다시 실행하고
(
- 방식 B: 영향받을 eval까지 집중 실행, 마지막에 전체 실행: 공유 명세나 규칙 문서를 바꾼 경우처럼
수정이 다른 eval에도 영향을 줄 수 있으면, 집중 실행 단계에서 해당 eval도 함께 실행합니다. 어시스턴트는
config graph ARTIFACT --impact(MCP에서는impact를 켠config_graph)와status로 그 eval을 찾습니다. 순환에 속한 eval은 함께 실행합니다. Artifact를 선택하면 같은 순환에 속한 Artifact의 eval도 함께 실행됩니다. - 방식 C: 매번 전체 실행: 수정할 때마다
verify --all을 실행합니다. 집중 실행으로 절약할 수 있는 것이 적을 때 씁니다. eval이 적거나 비용이 적을 때, 대부분의 eval이 참조하는 입력을 바꿨을 때, 여러 RED eval의 원인이 하나일 때가 그렇습니다.
선택자와 Run에 필요한 결과는 Run에, --speculate가
바꾸는 점은 추측 실행에 있습니다.
YELLOW를 목표로
반복의 목표는 나머지가 모두 통과하고 승인만 남은 YELLOW입니다. 승인은 다른 eval을 막지
않습니다. 아무도 승인 요청을 맡지 않은 채 승인 유예 시간
(따로 바꾸지 않았다면 2분)이 지나면 Run은 YELLOW로 끝납니다. 어시스턴트는 승인할 요청이 남아
있어도 작업을 계속하고, 남은 요청을 알려 주며 artifactize review REQUEST_ID 같은 방법으로
사용자에게 넘깁니다. 사용자 대신 승인 요청을 맡거나 제출하지 않습니다. 승인 결과를 기다리지 않고
작업을 마치며, 상태를 반복해서 확인하거나 대화를 이어 가지 않습니다. 사용자가 나중에
승인하면 다음 verify가 그 승인을 재사용합니다. 사용자가 승인하기 전까지 YELLOW는 승인된 상태가
아닙니다.
MCP stdio 서버
**MCP(Model Context Protocol)**는 코딩 어시스턴트를 artifactize의 도구에 연결해, 어시스턴트가
프로젝트를 살펴보고 리뷰를 시작하거나 지켜볼 수 있게 합니다. artifactize mcp는 CLI와 같은
바이너리로 검증 도구와 비대화형 확인 도구를 stdio로 제공합니다. 호스트는 네트워크 포트에
연결하는 대신 artifactize mcp를 실행하고, 그 프로그램의 표준 입력과 출력으로 메시지를
주고받습니다. 프로젝트 디렉터리에서 시작해 코딩 호스트에 등록하세요.
아래의 등록 방법을 보세요.
--state-dir PATH는 상태 디렉터리를 지정합니다. Run, 요청, 세션을 조회할 때는 호출에서 지정한
프로젝트의 기록만 읽으며, 캐시 기록은 같은 상태를 쓰는 여러 저장소에서 재사용할 수 있습니다.
대상 프로젝트 정하기
각 도구 호출은 프로젝트 하나를 대상으로 합니다. 프로젝트를 정할 때는 다음 항목을 차례로 확인하고, 가장 먼저 찾은 값을 씁니다.
- 도구 호출의
project인자로 준 프로젝트 폴더의 절대 경로(모든 도구가 이 인자를 받습니다) - 서버를 시작할 때 준
--repo PATH - 호스트의 첫 로컬 MCP root. 첫 호출 때 호스트에 질의하고, 10초 안에 응답이 오면 그 응답의 root를 사용합니다. 호스트의 root가 바뀌면 다시 질의합니다.
- 호스트가 root를 주지 않으면 서버를 시작한 디렉터리. 단, 그 디렉터리가 서버를 실행한 플러그인의 폴더라면 제외합니다.
이 방법으로도 프로젝트를 정할 수 없으면, 서버는 project 인자가 필요하다는 오류를 돌려줍니다. 이 오류는 root를 지원하는 호스트가 제때 답하지 않거나 로컬 폴더를 지정하지 않았을 때, 또는 서버가 플러그인 폴더에서 시작됐을 때 납니다.
최신 버전과 이전 버전의 MCP 호스트에서 모두 동작합니다. 프로토콜 메시지는 stdout으로,
진단 정보는 stderr로 출력합니다. 제한 시간 안에서 실행되는 verify_watch 호출은 표준 MCP 진행 알림도 보낼 수 있습니다. 자세한 내용은
프로토콜 버전을 보세요.
MCP 서버 등록하기
설치 설정을 마친 다음, 프로젝트 디렉터리에서
코딩 호스트를 실행하세요.
이 서버는 HTTP 리뷰 저장소(artifactize server)가 아니므로, 토큰을 인자로 넘길 필요도, 호스트의 시간 제한을 바꿀 필요도 없습니다.
Claude Code와 Codex에서는 플러그인이 Hey Arti 스킬과 함께 이 서버를 등록합니다. 아래 명령은 수동 등록입니다. 이 명령으로 호스트에 서버를 직접 등록해야 하며, artifactize가 호스트 설정을 자동으로 추가하거나 바꾸지는 않습니다. 호스트에서 제공하는 신뢰 확인과 승인 절차를 따르세요.
Claude Code
프로젝트 디렉터리에서 다음을 실행하세요.
claude mcp add --transport stdio --scope project artifactize -- artifactize mcp
claude mcp get artifactize
프로젝트 범위로 등록하면 호스트가 프로젝트 폴더에 .mcp.json 파일을 만듭니다. 이를 공유한다면
자격 증명과 머신별 경로를 넣지 마세요. 이 프로젝트에서 Claude Code를 시작/재시작하고,
MCP 보기에서 서버가 연결되었는지 확인한 뒤, 아래의 검증 도구와 확인 도구가
나열되는지 확인하세요.
Codex CLI
stdio 명령을 등록한 다음, 프로젝트 디렉터리에서 Codex를 시작하세요.
codex mcp add artifactize -- artifactize mcp
codex mcp get artifactize
등록한 명령은 Codex의 MCP 설정에 기록됩니다. 명령을 전역으로 등록했더라도 Codex는 해당 프로젝트 디렉터리에서 시작해야 합니다. 호스트가 프로젝트에서
실행될 수 없다면, 스킬 디렉터리를 가리키지 말고
artifactize --repo PATH mcp로 프로젝트별 명령을 등록하세요.
호스트에서 평소 쓰는 권한·인증 절차가 그대로 적용되므로 우회 플래그는 필요 없습니다.
이렇게 등록하면 도구만 제공되며, Hey Arti 스킬은 제공되지 않습니다.
검증 도구
| 도구 | 인자 | 답 |
|---|---|---|
verify_start | scope, 선택적으로 request_key, comment, jobs, speculate | Run을 제출합니다. Run 상태 요약이며 승인 결과는 아닙니다 |
verify_status | run | 저장된 상태, 개수, 경과 초, next_check |
verify_wait | run, 선택적으로 seconds | Run이 끝나거나 한도에 도달할 때까지 대기합니다. 기본값은 30이며 0–40의 정수입니다. 첫 호출에서 호스트에 root를 요청해야 한다면 응답을 받은 뒤 대기하며, 한 번의 확인은 45초 안에 끝납니다 |
verify_watch | run, 그리고 도구 호출에 선택적으로 표준 _meta.progressToken | 최대 30초 동안 변경을 지켜봅니다. 진행 메시지에는 JSON Run 이벤트가 들어 있습니다. 호출이 끝나면 간단한 상태 요약을 반환합니다 |
verify_result | run, 선택적으로 cursor | 판정과 간결한 지적 사항 최대 20개, next_cursor를 돌려줍니다. 실행 중이면 ready:false입니다 |
verify_cancel | run | 명시적 취소 확인입니다. 취소 뒤 정리가 끝났는지는 Run이 최종 상태가 될 때까지 지켜보세요 |
comment에는 에이전트가 지금 하는 일을 짧게 적습니다. 터미널의 Monitor와 데스크톱 앱,
run_show에서 Run과 함께 표시되며 Run의 동작에는 영향을 주지 않습니다. 제어 문자와 앞뒤 공백이 없는 한
줄이어야 하며, 길이는 1–200자여야 합니다. 그 밖의 값은 Run을 접수하기 전에 거부됩니다.
scope에는 kind 필드로 선택 유형을 지정하는 공통 형식의 JSON 객체를 전달합니다.
{"kind":"all"}
다른 형식으로는 {"kind":"artifact","artifactId":"library"},
{"kind":"eval","evalId":"library/tests"},
{"kind":"artifacts","artifactIds":["library","consumer"]},
{"kind":"evals","evalIds":["library/tests","consumer/review"]}가 있습니다.
배열로 선택할 때는 ID를 1–64개 넣을 수 있으며, 처음 나온 순서를 유지합니다. 의존성 처리와 결과 재사용에는 CLI와 같은 기본 규칙이 적용되며,
전송 방식에 따른 별도의 스케줄링이나 수명 주기 설정은 없습니다. 이 JSON 객체는
CLI에서 쓰는 선택 파일과 형식이 다릅니다. --evals-file과 --artifacts-file은 kind 태그 없이
ID의 JSON 배열이나 한 줄에 ID 하나를 받습니다.
request_key는 ASCII 문자/숫자/._:- 1–128개입니다. 프로젝트를 고쳤거나 Run이 끝났더라도,
같은 저장소에서 같은 키로 다시 요청하면 처음 만든 Run을 돌려줍니다. 새 시도에는
새 키를 쓰거나 키를 쓰지 마세요. 키를 생략하면 언제나 새 Run을 만들며, 기존
eval 결과 재사용은 유지됩니다.
동시 실행은 기본으로 무제한입니다. READY eval은 모두 시작할 수 있으며,
limits.json의 백엔드 제한만 따릅니다. 선택 인자 jobs(1–4294967295)는 CLI --jobs와 같은
Run별 상한이며, 제한 없는 동시 실행이 문제를 일으킬 때만 추가하세요. 동시 실행 상한이 없는
Run에는 jobs 필드가 없습니다.
speculate는 기본값이 false이며 CLI의 --speculate와 뜻이 같습니다. 요청된 Runtime과 Agent 작업을 상위 eval의 판단이 끝나기 전에 시작하되, 일반 스케줄링 한도는 그대로 적용합니다. 상위 eval이 RED나 ERROR가 되면 그 결과로 무효가 된 하위 작업만 취소합니다.
자세한 내용은 추측 실행에 있습니다. 승인 대기 중인 Run이 언제
waiting_human이 되고 언제 yellow로 끝나는지는 승인과 Run 종료에 있습니다.
yellow Run에서 verify_result는 판정 YELLOW를 보고하며, 이는 완전한 승인이 아닙니다.
Run 실행 중에는 응답 크기가 2 KiB 미만입니다. 대기 상태는 오류가 아니라 정상입니다.
verify_wait는 Runtime, Agent, Human eval을 똑같이 다룹니다. 사람이 필요하다는 이유만으로
일찍 끝나지 않습니다. next_check는 다음에 상태를 확인할 시점을 알려 주는 값일 뿐,
빠르게 폴링하거나 모델 컨텍스트를 유지하라는 뜻이 아닙니다.
Run은 artifactize가 관리합니다. MCP 요청 처리를 중단하거나, MCP 연결을 닫거나,
진행 상황 확인을 중단하거나, 에이전트 턴을 끝내도 Run은 취소되지 않습니다. Run을 취소하는 방법은 verify_cancel뿐입니다.
RED/INCOMPLETE/ERROR/취소됨은 잘못된 도구 호출이 아니라 저장된 Run 결과입니다.
Human 요청의 담당 지정·해제와 판정 제출은 사람이 직접 처리하며, MCP에서는 이 기능을 제공하지 않습니다.
확인 도구
모든 확인 도구는 아래 나열한 인자 외에, 세부 결과를 페이지별로 읽을 때 사용하는 cursor도 선택적으로 받을 수 있습니다.
CLI 대응 명령과 같은 JSON을 세부 페이지로 나눠 돌려줍니다.
| 도구 | 인자(필수라고 표시한 것 외에는 선택) | CLI 대응 명령 |
|---|---|---|
status | scope(기본 all) | status --all 또는 선택한 status |
config_check | 없음 | config check |
config_graph | scope(기본 all), impact(false) | config graph [ARTIFACT] [--impact]. MCP는 eval/여러 개 선택도 받습니다 |
request_logs | id, stream(stdout/stderr/both), tail, start, end, search | 해당 플래그를 쓴 request logs ID |
run_list | limit(0–20, 기본 20), offset(0–4294967295, 기본 0) | 이 저장소에 대한 run list --limit 20 --offset N, 최신 순 |
run_show | run | run show RUN |
request_list | run | 이 저장소로 제한된 request list [--run RUN] |
request_show | id | request show ID |
session_show | reference, summary(기본 false) | session show REF [--summary] |
tools_check | eval, 또는 artifact/audience/tool | 정적 tools check입니다. audience는 agent 또는 human입니다 |
doctor | 없음 | doctor |
models | provider(기본 provider openai, anthropic, gemini, codex, claude-agent 또는 커스텀 provider 이름입니다. 이름은 ASCII 영문자, 숫자, _, -로 된 1–64자이며 영문자나 숫자로 시작합니다) | models PROVIDER |
remote_status | 없음 | remote status |
cache_show | key, history(기본 false) | cache show KEY [--history] |
session_show.reference는 저장된 세션 참조, 요청 ID, 세션
ID를 받으며, CLI와 마찬가지로 producer(리뷰를 실행한 user@host)와 상태를 확인합니다. 캐시 기록이 없으면
CLI의 JSON 출력과 마찬가지로 null을 반환하고, history를 지정하면 빈 배열을 반환합니다. 정적
tools_check는 프로젝트 도구를 호출하거나 세션을 시작하지 않습니다. status는
신뢰하는 fingerprint 명령을 실행하고 설정된 리뷰 저장소를 조회할 수 있습니다. 선언된
명령은 OS 샌드박스 안에서 실행되지 않습니다. MCP는 로그인/로그아웃 동작을 제공하지 않으며
자격 증명을 돌려주는 일도 없습니다. models, doctor, remote_status는 백엔드
준비 상태를 확인할 수 있고, doctor는 CLI와 마찬가지로 새 릴리스도 확인합니다. Codex 모델 목록을 조회할 때는 CLI와 마찬가지로 artifactize에 저장된 토큰을 갱신할 수 있으며, 갱신이 영구히 거부되면 저장된 로그인 정보를 지울 수 있습니다.
세부 페이지
세부 페이지에는 텍스트 항목이 최대 하나 들어 있으며, 구조화된 답과 이전 형식의 텍스트 사본을 포함한 전체 크기가 64 KiB 미만입니다. 각 항목은 잘라 낸 미리 보기나 별도 형식의 결과가 아니라 CLI가 출력하는 JSON 원문을 UTF-8 텍스트로 나눈 조각입니다.
{"encoding":"json","entries":[{"offset":0,"text":"{\"ok\":true,\"artifacts\":3,\"evals\":4}"}],"next_cursor":null}
next_cursor가 null이 될 때까지 entries[].text를 순서대로 이어 붙인 다음,
이어 붙인 텍스트를 JSON으로 파싱하세요. JSON은 공백 없이 직렬화되므로, CLI가 보기 좋게 출력할 때 넣는 공백은
보존되지 않습니다. 이전 페이지의 cursor를 더해 같은 도구를 같은 인자로 다시 호출하세요.
offset은 UTF-8 바이트 오프셋입니다. run_list.offset은
다음 Run 기록 묶음을 지정하고, cursor는 같은 묶음의 JSON에서 다음 조각을 읽을 때 씁니다.
verify_result는 대신 구조화된 findings 배열을 페이지 단위로 넘깁니다.
cursor는 같은 도구와 같은 인자에서만 쓸 수 있습니다. 다음 페이지를 요청할 때마다 확인을 다시 실행하며, 그 결과가 바뀌지 않았을 때만 cursor를 쓸 수 있습니다. 새 Run이나 결과가 생겼을 때뿐 아니라
파일, 모델 목록, 백엔드 상태가 바뀌어도 거부됩니다. 시간이 흐른다고 만료되지는 않습니다. cursor가 거부되면 같은 도구를 첫 페이지부터 다시 호출하세요. 실패한
도구 호출은 {code,message}와 함께 MCP isError:true를 돌려줍니다. operation_failed에는 CLI의
오류 메시지가 처음 2,048자까지 담깁니다. response_too_large는 응답이 세부 페이지 하나에 담기지
않는다는 뜻이므로, request_logs의 조회 범위나 검색 조건을 조정해 조회할 내용을 줄이세요. 내용 일부를 생략한
페이지를 전체 결과인 것처럼 반환하지 않습니다.
제공하지 않는 기능
자격 증명 로그인/로그아웃, Human 담당 지정/제출/담당 해제, prune, 캐시 제거, 원격 푸시, 대화형 Monitor/review, 저장소 서버, 프로젝트 도구 실행, Agent 세션 follow-up은 없습니다. 이런 동작은 CLI와 일반 Human 리뷰 인터페이스에서 하세요.
스트리밍과 집중 진단
verify_start로 제출하고 Run ID를 보관한 다음, _meta에 표준
도구 호출 메타데이터 {"progressToken":"your-observer"}를 넣어 verify_watch를 호출하세요.
호출이 처리되는 동안 artifactize는 Run이 바뀔 때마다
notifications/progress를 보냅니다. 알림의 message는 JSON 객체입니다.
{"kind":"update","data":...}: 간결한 실시간 상태/개수입니다. 승인이 아닙니다.{"kind":"eval_result","data":...}: 저장된 요청/eval 상태 하나와 간결한 요약입니다. 재사용된 결과와 잠정 결과를 포함하며, Run 판정이 아닙니다.{"kind":"outcome","data":...}:verify_result의 스키마를 쓰는 최종 Run 검증입니다. 남은 지적 사항은 그next_cursor를verify_result에 넘겨 읽으세요.
연결할 때마다 기준 상태와 이미 완료된 eval을 다시 보내므로, 필요하면
요청 ID와 상태를 기준으로 이전 연결에서 받은 항목과 겹치는 것을 걸러 내세요. 호출 제한 시간이 끝나 반환될 때
Run이 이미 끝났더라도, 클라이언트가 outcome 알림을 받았다고 단정할 수는 없습니다.
최종 검증 결과는 verify_result로 확인하세요. 진행 토큰이 없어도
호출은 같은 방식으로 대기하지만 진행 알림은 보내지 않습니다. 진행 알림을 쓰지 않는 클라이언트에서는
verify_wait를 쓰세요. 빠른 폴링은 필요 없습니다.
구독은 호출이 끝나거나(30초 한도) 클라이언트가 취소하거나 연결이
끊기면 끝나며, 이후의 호출은 저장된 Run에 다시 연결합니다(Run을 누가 관리하는지는
검증 도구를 보세요). 함께 도착한 변경은 알림 하나로 합쳐질 수 있으며,
각 알림은 전체 이벤트 이력이 아니라 저장된 상태를 반영합니다.
진행 상황과 알림을 표시할 수 있는지는 코딩 호스트에 따라 다릅니다.
알림이 모델의 새 응답을 시작하지는 않으며, 호출이나 연결이 끝나면 알림도 멈춥니다. artifactize가 호스트의 대화에
직접 글을 올릴 수는 없습니다. 호스트가 셸 명령을 실행할 수 있다면 artifactize verify --all --watch나
artifactize run watch RUN이 Run이 끝날 때까지 같은 진행 상황을 JSON 줄로 출력합니다. 다만 모든 코딩 호스트가 진행 상황을 대화에 실시간으로 보여 줄 수 있는 것은 아닙니다.
실패 원인을 조사할 때는 run_show로 감사 기록 전체를 읽는 대신 그 request ID로 request_logs를 조회하세요. stream의 기본값은 both입니다. 범위가 없으면 일치하는 마지막 50
줄을 돌려주며, tail은 일치하는 줄 1–200개를 고릅니다. start/end는 1부터 세는
원래 줄 번호이며 양 끝을 포함하고, tail과 함께 쓸 수 없습니다. search는 대소문자를 구분하는
리터럴이며(UTF-8 1–2048바이트), tail 선택 전에 적용됩니다. 시작 줄부터 순서대로 읽는 범위 조회는
최대 200줄과 스트림별 바이트 한도까지만 돌려주며, 이어서 읽으려면 stream/search/end를 그대로 두고
next_start를 다음 시작 위치로 쓰세요. 원본 줄이 2048바이트를 넘으면 앞부분과 끝부분만 정해진 길이만큼 보여 주고 clipped 표시를 붙이며, 원본 전체는 로컬 디스크에 남습니다. 줄 중간이
잘려 보이지 않더라도 그 부분에 검색어가 있으면 검색 결과에 포함될 수 있습니다. 결과는 원본 바이트를 그대로 내보낸 것이 아니라, 읽기 좋게 정리한 UTF-8 진단 텍스트입니다. 이 응답에도 앞서 설명한 세부 페이지 나누기와 크기 제한이 그대로 적용됩니다.
각 스트림의 evidence는 complete(끝부분을 포함한 전체 로컬 캡처),
partial(실행 중이거나 중단된 캡처처럼 확인된 EOF가 없음), saved_audit
(로컬 캡처가 오래되었거나 정리된 경우, 또는 원격 실행의 기록만 있는 경우. 처음 128 KiB만 있을 수 있음), missing,
또는 not_runtime(대신 요청/세션 증거를 쓰세요) 중 하나입니다. 내용이 비어 있는 로그와 로그가 아예 없는 경우는 구분합니다.
재사용된 요청의 로그는 결과를 만든 원래 로컬 실행에서 찾으며, 원격 기록만으로는
로그가 로컬에 보존되어 있다고 보장할 수 없습니다. 원본 캡처를 얼마나 오래 보관하는지와
artifactize prune이 무엇을 남기는지는
Runtime 실행 레퍼런스에 있습니다.
config_graph는 훅을 호출하지 않고 정적 정의, eval, 같은 순환에 속한 Artifact, 입력 → 사용처
관계를 찾습니다. Artifact나 eval을 고르면 그 대상의 의존성 범위가 나오며,
impact:true를 더하면 영향을 받을 수 있는 하위 Artifact와 각각에 필요한 입력도
포함됩니다. 이는 구조상 영향을 받을 가능성이 있는 대상을 넉넉히 포함할 뿐이며, 포함된 모든 eval의 재사용 키가 실제로 바뀌었다는 뜻은 아닙니다. 실제로 어떤 결과를 재사용할지는 status로 확인하세요.
프로토콜 버전
서버는 MCP 버전 2026-07-28과 그 이전 버전을 쓰는 클라이언트와 호환됩니다. MCP Tasks 확장은 제공하지 않으며, 진행 알림은 그 알림을 요청한 호출이 끝날 때까지만 옵니다.
CLI
프로젝트에서 artifactize verify --all --wait를 실행하면 리뷰가 시작됩니다. 명령은 Run ID를
알려 주고, Run이 끝나면 eval마다 결과를 출력하며, 모두 GREEN이면 0으로
종료합니다. 이 페이지는 모든 명령의 플래그, 출력, 종료 코드를 정리하고, 이어서 verify의 정책, 예산, 선택 파일, 프로필 변형을 자세히 설명합니다.
명령 레퍼런스
모든 명령에서 --repo PATH, --state-dir PATH, --json은 하위 명령 앞이나 뒤에 각각
한 번만 지정할 수 있습니다. 저장소를 읽는 명령은 --repo를 생략하면 대개 현재 디렉터리를 쓰지만,
기본값은 명령마다 다릅니다. doctor는 --repo를 직접 줄 때만 프로젝트 선언을
확인합니다. Monitor와 Review는 아래 설명처럼 ALL에서 시작합니다. 상태는 기본으로 공유
상태 디렉터리에 저장됩니다. 저장소나 상태를 쓰지 않는 명령은 이
옵션들을 무시합니다. Monitor와 Review는 --json을 거부합니다. mcp는 항상 stdout에
JSON-RPC를, stderr에 시작할 때의 진단 메시지를 씁니다. 현재 디렉터리 도구의 출력은 이미 아래 표처럼 텍스트나
JSON이므로 --json을 줘도 바뀌지 않습니다. tools help에서 프로그램 인자 뒤에 오는 플래그는
artifactize가 아니라 그 프로그램에 전달됩니다.
SELECTOR 자리에는 위치 인자 ARTIFACT나 ARTIFACT/EVAL, --eval ID, --evals CSV,
--artifacts CSV, --evals-file PATH, --artifacts-file PATH, --all 중 하나만
씁니다. CSV는 verify --evals app/lint,app/tests나 verify --artifacts app,docs처럼
이름이나 eval ID를 쉼표로 이은 목록입니다. --evals와 --artifacts는 여러 번 줄 수 있으며,
값은 순서대로 합쳐지고 중복은 빠집니다.
help [COMMAND]와 -h/--help는 도움말을 출력합니다. 명령 없이 artifactize만
실행해도 도움말이 나옵니다(종료 코드 0, --json을 줘도 텍스트). -V/--version은 루트
명령과 artifactize tools에서 버전을 출력합니다.
| 명령 | 플래그 | 출력 | 종료 코드 |
|---|---|---|---|
verify SELECTOR | --profile NAME, --recursive, --force, --jobs N(필요할 때만), --fingerprint-jobs N(CPU 수), --max-executions N, --wait 또는 --watch, --request-key KEY, --comment TEXT, --reuse-only KINDS, --speculate | Run ID 또는 {run,state}를 출력합니다. --wait면 최종 텍스트/JSON을, --watch면 JSON 줄 이벤트를 출력합니다 | 접수되면 0, --wait나 --watch면 Run 결과 |
status [SELECTOR] | --profile NAME, --recursive, --force, --fingerprint-jobs N(CPU 수). 기본값은 --all입니다 | 텍스트 또는 JSON | 충족하면 0, 아니면 1 |
mcp | MCP stdio 프로토콜입니다. 진단은 stderr로 출력합니다 | 정상적으로 연결이 끊기면 0 | |
config check | 텍스트 또는 JSON | 0 | |
config graph [ARTIFACT] | --impact | 텍스트 또는 JSON | 0 |
run list | --repo-only | --all, --limit N(50), --offset N(0) | 텍스트 또는 JSON | 0 |
run watch RUN_ID | JSON 줄로 상태 변화, eval 결과, 최종 검증 | Run 결과 | |
run cancel RUN_ID | 취소 요청을 받았다는 JSON | 0 | |
run show RUN_ID | --wait, --timeout-ms MS(600000, --wait 필요) | JSON | 0, --wait면 Run 결과 |
request list | --run RUN_ID | 텍스트 또는 JSON | 0 |
request show ID | JSON | 0 | |
request logs ID | --stream stdout|stderr|both, --tail N, --start N, --end N, --search TEXT | 크기가 제한된 증거 JSON | 0 |
request claim ID | --reviewer NAME($USER) | JSON | 0 |
request unclaim ID | --reviewer NAME($USER) | JSON | 0 |
request tool ID TOOL | --reviewer NAME | 텍스트 또는 JSON | 0, 도구 오류면 2 |
request submit ID | --verdict GREEN|RED, --fields JSON | --fields-file PATH, --reviewer NAME | JSON | 0, RED여도 0 |
session show REF | --summary | 텍스트, 또는 저장된 이벤트(또는 요약)를 담은 JSON | 0 |
session send REF MESSAGE | 텍스트 또는 JSON | 0 | |
cache list | --history | 텍스트 또는 JSON | 0 |
cache show KEY | --history | JSON | 0, 없으면 4 |
cache rm KEY | JSON | 0 | |
tools check [EVAL] | --eval ID, --artifact ID, --audience agent|human, --tool NAME, --execute, --args JSON | JSON | 준비됐으면 0, 아니면 1 |
tools read PATH | — | UTF-8 텍스트 | 성공 0, 도구 오류 1, 사용법 오류 2 |
tools list [PATH] | — | JSON | 성공 0, 도구 오류 1, 사용법 오류 2 |
tools glob PATTERN [PATH] | — | JSON | 성공 0, 도구 오류 1, 사용법 오류 2 |
tools grep PATTERN [PATH] | --glob GLOB, --case-insensitive | JSON | 성공 0, 도구 오류 1, 사용법 오류 2 |
tools section PATH HEADING | — | Markdown 텍스트 | 성공 0, 도구 오류 1, 사용법 오류 2 |
tools help PROGRAM [SUBCOMMAND...] | 뒤따르는 인자는 --help 앞에 붙여 PROGRAM에 전달합니다 | 텍스트 | 성공 0, 도구 오류 1, 사용법 오류 2 |
tools open TARGET | — | 기본 애플리케이션으로 엽니다 | 성공 0, 도구 오류 1, 사용법 오류 2 |
login codex | 로그인 URL은 stderr에 출력합니다. 터미널에 붙여 넣은 리디렉션 URL을 표준 입력에서 읽을 수 있습니다 | Signed in with Codex.라고 출력합니다. JSON은 {"provider":"codex","signed_in":true}입니다 | 0 |
login openai|anthropic|gemini | API 키를 stdin에서 읽습니다 | Saved the PROVIDER API key.라고 출력합니다. JSON은 {"provider":…,"saved":true}입니다 | 0 |
logout codex | 로컬 토큰을 지우고 폐기를 시도합니다. 읽기 전용 인증 파일은 건드리지 않습니다 | Signed out of Codex.라고 출력합니다. JSON은 {"provider":"codex","signed_in":false,"revoked":BOOL}입니다 | 로컬 로그아웃 뒤 0 |
logout openai|anthropic|gemini | 저장한 키를 지웁니다. 변수는 건드리지 않습니다 | Forgot the saved PROVIDER API key.라고 출력합니다. JSON은 {"provider":…,"saved":false}입니다 | 0 |
login claude-agent | Claude Code 자체 명령인 claude auth login을 실행합니다. 그 URL은 stderr에 출력하고, stdin에 붙여 넣은 코드는 Claude Code에 전달합니다 | Claude Code is signed in with METHOD (PLAN).이라고 출력합니다. Claude Code가 요금제를 알려 주지 않으면 (PLAN) 부분을 뺍니다. 로그인한 뒤 확인한 상태에 로그인 정보가 없으면 Claude Code signed in.이라고 출력합니다. JSON은 {"provider":"claude-agent","signed_in":true}입니다 | 0. claude가 없거나 Claude Code가 실패하면 2 |
logout claude-agent | Claude Code 자체 명령인 claude auth logout을 실행합니다 | Signed out of Claude Code.라고 출력합니다. JSON은 {"provider":"claude-agent","signed_in":false}입니다 | 0. claude가 없거나 Claude Code가 실패하면 2 |
provider list | 기본 provider별 키 출처와 커스텀 provider 전체를 보여 줍니다. 키 값은 출력하지 않습니다. 형식은 텍스트 또는 JSON입니다 | 0 | |
provider add NAME | --alias PROVIDER, 또는 --api API --url URL과 선택 항목 --key(키는 stdin에서 읽습니다. 없으면 엔드포인트에 키가 없습니다) | Saved custom provider NAME.라고 출력합니다. JSON은 {"provider":NAME,"saved":true}입니다 | 0 |
provider remove NAME | Removed custom provider NAME.라고 출력합니다. JSON은 {"provider":NAME,"saved":false}입니다 | 0 | |
remote login URL | --share summary|full(summary). 토큰은 stdin으로 받습니다 | Signed in to URL as NAME (scopes: …).라고 출력합니다. JSON은 {"url":…,"share":…,"principal":…,"scopes":[…]}입니다 | 0 |
remote logout | Signed out of the remote review store.와 함께, 서버에서는 server token revoke 전까지 토큰이 유효하다고 안내합니다. JSON은 {"signedIn":false}입니다 | 0 | |
remote status | URL, 공유 수준, 토큰 출처, 접속 가능 여부를 보여 주고, 이어서 주체와 범위 또는 오류를 보여 줍니다. JSON은 아래를 참고하세요 | 로그인 상태면 0, 아니면 1 | |
remote push | --dry-run | 텍스트 또는 JSON | 0 |
models PROVIDER | 기본 provider나 커스텀 provider | 텍스트 또는 JSON | 0 |
doctor | 텍스트 또는 JSON | 준비됐으면 0, 심각한 오류면 1 | |
limits | --signoff-idle-grace SECONDS(0–86400) | 지금 적용되는 머신 전체 한도를 보여 줍니다. 형식은 텍스트 또는 JSON입니다 | 0 |
prune | --older-than DURATION, --dry-run | 텍스트 또는 JSON | 0 |
monitor [PATH] | ALL에서 시작합니다. PATH나 --repo PATH는 처음 고를 저장소만 정합니다. --all은 경로와 함께 쓸 수 없습니다 | 터미널 UI | 0 |
review [REQUEST_ID] | --repo PATH(repo: 검색어), --all(기본값이며 --repo와 함께 쓸 수 없습니다), --reviewer NAME($USER) | 터미널 UI | 0 |
server run | --listen ADDR(127.0.0.1:8417): 숫자로 쓴 IP:PORT(IPv6은 [::1]:8417) 형식이며, 호스트 이름은 사용할 수 없습니다. 포트가 0이면 사용 가능한 포트를 골라 그 번호를 출력합니다 | Listening on http://ADDR/라고 출력합니다. JSON은 {"listen":ADDR}입니다 | 0 |
server token add NAME --scopes SCOPES | --scopes(필수이며 기본값은 없습니다. read, publish, human을 쉼표로 이은 목록입니다) | 토큰을 한 번 출력하고 저장해 두라고 안내합니다. JSON은 {"name":NAME,"scopes":[...],"token":TOKEN}입니다 | 0 |
server token list | 텍스트 또는 JSON | 0 | |
server token revoke NAME | --purge | JSON(--json이 없어도) | 0 |
server rm KEY | JSON | 0 |
verify --wait와 run show --wait는 Run 결과에 따라 종료 코드가 정해집니다. GREEN이면 0, RED이면 1,
ERROR 또는 취소면 2, INCOMPLETE면 4, YELLOW면 5입니다. YELLOW는 승인이 남아 있을 뿐, 승인된 상태는 아니라는 뜻입니다.
옵션 없는 verify는 검증 결과와 관계없이 Run이 접수되면 종료 코드 0으로 끝납니다. Ctrl-C로 지켜보기를
중단하면 명령은 종료 코드 130으로 끝나지만 Run은 계속 실행됩니다. run show --wait는 RUNNING이나
WAITING_HUMAN 상태의 Run이 끝날 때까지 상태를 계속 확인합니다. Run이 끝나기 전에 이 명령의 제한 시간이 지나면 현재 Run을 출력하고 3으로
종료하며, Run은 계속 실행됩니다. 모든 명령은 사용법 오류(알 수 없는 옵션, 반복할 수 없는 옵션의 반복, 충돌하거나 빠진 옵션과 값)나 동작 오류가 나면 종료 코드 2로 끝납니다. 오류는 stderr에 텍스트로, 또는
--json이면 stdout에 {"error":"..."}로 나옵니다(stdout을 프로토콜에만 쓰는 mcp는
예외). 도구 실패에는 두 가지 예외가 있습니다. 현재 디렉터리 도구(tools read, list, glob,
grep, section, help, open)는 --json을 줘도 공유 도구 실행기의 종료 코드 1과 진단
메시지를 그대로 씁니다. request tool로 실행한 Human 도구가 실패하면 평소와 같은 결과(출력된
내용, --json이면 {"content":[…],"isError":true})를 stdout에 출력하고 2로 종료합니다.
tools check는 선언, 사전 점검, 실행, 정리 실패를 진단 보고서에 담고(--execute 호출이
실패한 경우 포함) 1로 종료합니다. 세 경우 모두 사용법 오류는 일반 규칙을 따릅니다. plan,
history, --full은 없습니다.
목록 옵션인 --reuse-only와 server token add --scopes는 여러 번 줄 수 있으며, 쉼표로
구분한 값이 모두 합쳐집니다. 공통 옵션인 --repo, --state-dir, --json은 한 번만
받습니다. run show --timeout-ms는 1부터 2147483647까지의 정수(밀리초)여야 하며, 범위를
벗어나면 사용법 오류(종료 코드 2)입니다.
logout codex가 0을 돌려주는 것은 로컬에서 로그아웃했다는 뜻이지, 서버에서 토큰이
폐기됐다는 뜻은 아닙니다. 서버에 토큰 폐기를 요청하지만, 폐기가 성공한다고 보장하지는 않습니다. 폐기를 확인하지 못하면 stderr에
경고하고, JSON 결과에 "revoked":false가 들어갑니다(확인되면 true). 로컬 토큰은 그래도
지워지며, 읽기 전용 외부 인증 파일은 절대 바꾸지 않습니다.
식별자 인자
Run ID와 요청 ID 인자(request list --run과 review REQUEST_ID 포함)는 ASCII 글자,
숫자, -, _, .로 이뤄진 1–200자여야 하며 점만으로 이뤄질 수는 없습니다. cache show, cache rm, server rm의 재사용 키 인자는 정확히 64자의 소문자
16진수여야 합니다. 형식이 잘못된 식별자를 지정하면 사용법 오류로 처리하고 종료 코드 2로 끝납니다. 형식은 맞지만 해당
재사용 키로 저장된 기록이 없으면 cache show는 null(--history면 [])을 출력하고 4로 종료하며, cache rm은
removed: false를 알립니다.
server token add NAME과 server token revoke NAME은 글자, 숫자, -, _, .로 이뤄진
1–64자의 ASCII를 받습니다. 빈 이름, 공백, 슬래시, ASCII가 아닌 글자, 너무 긴 이름은
거부되며 2로 종료합니다. 이 이름은 표시용이며, 인증에 쓰는
비밀 토큰이 아닙니다.
session show와 session send는 Agent 리뷰의
저장된 대화를 읽고 이어 갑니다. 인자, 출력, 오류는
Agent 세션에 있습니다.
이전 버전의 상태를 여는 명령은 상태에서 설명한 대로 그
상태를 업그레이드합니다. 열 수 없는 상태면 2로 종료하고, doctor는 이를 심각한 오류로 알리고
1로 종료합니다.
제출과 지켜보기
옵션 없는 verify는 Run을 제출하고 Run ID를 출력한 뒤, 접수되면 0으로 종료합니다. 스크립트에서
결과에 따른 종료 코드가 필요하면 --wait를 붙이세요. 같은 --request-key로 다시 제출하면 처음
만든 Run을 돌려줍니다. 키는 ASCII 글자, 숫자, ., _, :, -로 이뤄진 1–128자이며, 조건에 맞지 않는 키를 쓰면 명령이 종료 코드 2로 끝납니다. 자세한 내용은
제출, 지켜보기, 취소에 있습니다.
--comment TEXT를 붙이면 지금 하는 일을 짧게 적어 Run과 함께 남기고, Run을 지켜보는 사람이 이를
볼 수 있습니다. Run의 동작은 바뀌지 않습니다. 코멘트는 제어 문자와 앞뒤 공백이 없는 한 줄이어야 하며,
길이는 1–200자여야 합니다. 조건에 맞지 않으면 종료 코드 2로 끝납니다. verify --wait는 Comment: 줄에, run list는 COMMENT
열(없으면 -)에 보여 주고, verify --wait, run list, run show의 JSON에는 comment로 나옵니다.
--wait 없이 verify가 출력하는 JSON은 Run과 그 상태만 알려 줍니다.
artifactize verify --all --request-key build-42
artifactize verify --all --comment "Fixing the login form"
artifactize run show RUN_ID --wait
artifactize run cancel RUN_ID
verify --wait는 Run ID를 stderr에 출력한 뒤 Run이 끝나면 eval별 결과를 보여 주고,
Run의 종료 코드를 반환합니다. Run 자체의 진단(최대 64 KiB)과
Run 오류도 stderr에 나오며, --json일 때도 마찬가지입니다.
runtime-relations 예제에서 GREEN, RED, 막힌 eval을 나란히
볼 수 있습니다.
Verify 모드
--speculate는 요청마다 켜는 스위치이며, 기본으로 꺼져 있습니다. 접수된 Run은
modes: {speculate}를 기록하며, 같은 --request-key로 다시 시도하면 처음 요청의 선택을 그대로 씁니다.
| 모드 | 실행 방식 |
|---|---|
| 기본 | 실행 게이트가 막지 않으면 eval을 시작합니다. 선택한 승인이 아직 대기 중이어도 그에 의존하는 eval은 바로 실행되며, GREEN 결과는 승인 결과가 GREEN이 될 때까지 PROVISIONAL로 표시됩니다 |
--speculate | 게이트가 정해지기 전에 Runtime과 Agent 리뷰를 시작합니다 |
승인은 앞선 eval이 통과하기 전에 추측으로 미리 요청하지 않으며, --speculate Run에서도 앞선 eval이 통과하면 평소처럼 요청합니다. 승인을 언제 요청하는지, 그 승인에 의존하는 eval이 어떻게 실행되는지는
승인과 Run 종료를 보세요. --speculate에서는 새로 준비된 작업을
실행할 --jobs나 백엔드 자리가 모자라면 artifactize가 실행 중인 추측 실행 리뷰를 중단할 수 있습니다. 그 리뷰는 나중에
다시 시작하며, 다시 시작할 때도 --max-executions로 정한 실행 횟수에 한 번 더 포함됩니다. 추측 실행은 실행 순서를 바꿀 뿐 승인 여부를
바꾸지 않습니다. verify --wait는 평소와 같은 Run 결과 종료 코드로 끝납니다.
추측 실행의 스케줄링과 취소는 추측 실행에서 설명합니다.
Runtime CLI
선택자, 게이트, 결과, 출력은 Run, 상태, 검증에서 다룹니다.
없어진 예전 게이트 우회 설정은 업그레이드 안내를
보세요. --force는 직접 선택한 실행 가능한 eval만 새로 리뷰하도록 표시하며, 재귀로 포함된
의존성에는 적용되지 않습니다. 실행 범위를 넓히거나 게이트를 건너뛰지도 않습니다. Run에는 결정된
정책과 각 요청의 force 여부가 기록됩니다. 강제로 실행하는 eval은 캐시 결과를 읽지 않고,
실행 중인 작업에도 합류하지 않습니다. --force로 새로 실행한 eval의 결과가 GREEN이나 RED면 그 키의 가장 최근 기록으로 추가되고, 리뷰
저장소가 설정되어 있으면 게시되어 이후 Run이 재사용합니다. 의존성은 로컬 기록을 계속
재사용할 수 있지만, --force로 실행한 Run은 저장소에서 아무것도 읽지 않습니다. 추측 실행과 대기 중인 승인도
최종 검증 요건을 면제하지 않습니다.
동시에 실행되는 Run이 언제 같은 리뷰에 합류하는지, --force가 이를 어떻게 바꾸는지는
Run끼리 작업 나누기에서 설명합니다.
eval 동시 실행 수에는 기본 상한이 없어서, READY인 eval은 준비되는 즉시 시작합니다. 동시
실행이 문제를 일으킬 때만 --jobs N(1–4294967295)을 붙이세요. 그러면 이 Run의 eval 수가
제한됩니다. Agent 리뷰는 이와 별개로 $STATE/limits.json에 따라 머신 전체에서 백엔드마다
제한됩니다(백엔드 수용량). 백엔드 자리가
빌 때까지 대기 중인 요청은 --jobs의 동시 실행 수에도, 실행 시작 횟수에도 포함되지 않습니다.
--fingerprint-jobs N(verify와 status, 1–4294967295)은 fingerprint를 동시에 몇 개까지
계산할지 정합니다. 기본값은 프로세스가 쓸 수 있는 CPU 수입니다. verify에서는 준비 단계와
Runtime/Agent 리뷰가 끝날 때 하는 재확인이 한도 하나를 함께 쓰며, eval 수를 제한하는
--jobs와는 별개입니다. Human 도구 실행과 제출은 CPU 수만큼 따로 fingerprint를 계산하며 이
설정을 따르지 않습니다. 결과와 출력은 이 한도나 완료 순서와 상관없이 같습니다.
verify --max-executions N은 Run 하나에서 실행을 시작할 수 있는 횟수를 0–18446744073709551615
사이로 정합니다(생략하면 무제한). Artifact 선언 필드가 아닙니다. Run은 직접 지정한 jobs
상한(무제한이면 필드가 없음), fingerprintJobs, maxExecutions, executionsStarted를
기록합니다. Runtime이나 Agent 리뷰는 실행 준비가 끝나면 시작 횟수를 1 늘리며, 이후
프로그램을 시작하지 못하거나 리뷰가 ERROR로 끝나도 이 횟수는 유지합니다. 사람의 판정을 기다리는 시간, 담당 지정, Human 도구 사용은 시작 횟수에 포함되지 않습니다. fingerprint 계산과 재확인, 저장된 결과 재사용, 이미 실행 중인 리뷰에
합류하는 것도 마찬가지입니다. 실행할 준비가 끝나기 전에 실패한 리뷰도 시작 횟수에 넣지 않습니다. execution_paths에
지정한 도구 파일을 읽지 못한 Agent 리뷰는 시작 횟수에 들어가고, 모델을 호출하지 않은 채
ERROR/PREPARATION_FAILED로 끝납니다.
0으로 두면 재사용, 합류, Human 리뷰만 할 수 있습니다. 합류한 Run이 실패해서 리뷰를 다시
실행해야 하면, 다시 실행하는 리뷰는 그 리뷰가 속한 Run의 남은 횟수를 씁니다. 횟수를 다 써도 실행 중인 eval은 멈추지 않지만,
남은 READY 요청은 BUDGET_EXHAUSTED가 되고 Run은 이유와 함께 INCOMPLETE(종료 코드 4)로
끝납니다. 모든 요청을 시작했다면 실행 횟수가 한도에 정확히 도달해도 오류가 아닙니다.
Human 대기와 취소는 제출, 지켜보기, 취소를 따릅니다. 담당 지정, 도구, 승인은 Human 가이드에서 다룹니다.
선택 파일은 4 MiB 이하의 일반 파일이어야 합니다. ID를 JSON 문자열 배열로 담거나, 앞뒤 공백을 뺀 ID를 한 줄에 하나씩 담으세요. UTF-8 BOM과 CRLF도 쓸 수 있습니다. 중복을 빼기 전 기준으로 ID가 1–100000개여야
합니다. 빈 줄은 무시하며, ID에는 ASCII 공백, 제어 문자, 쉼표를 쓸 수 없습니다. 형식이 잘못된
JSON 배열을 줄 단위 형식으로 다시 읽지는 않습니다. 상대 경로는 --repo가 아니라 CLI의 현재
디렉터리를 기준으로 합니다.
verify ... --profile NAME은 선택과 재귀 정책으로 정한 범위에 포함된 실행 가능한 모든 eval에서
이름이 NAME인 profile_variants 항목을 통째로 선택합니다. 변형은 그다음에 적용됩니다. 실행 가능한
eval마다 이름 규칙에 맞는 프로필 변형을 최대 64개 선언할 수 있으며, 각 변형은 원래 리뷰어 종류를
유지합니다. 없는 변형 이름을 주면 Run을 만들기 전에 실패하며, 원본 선언 파일은 수정하지 않습니다.
--recursive를 주면 이미 선택된 의존성에도 변형이 적용됩니다. 예를 들어 app/review --profile fast가 실행하는 Runtime 변형의 인자에 {fixtures}가 있으면, fixtures의 eval은
fast가 아니라 기본 프로필로 Run에 들어옵니다. 고른 변형은 실행 옵션일 뿐 재사용 키에 들어가지
않습니다. 따라서 Runtime 변형에서 명령이나 인자를 바꾸지 않았다면, 프로필 변형이나 기본 프로필이
달라도 결과를 서로 재사용할 수 있습니다. 저장된 요청의 profile과 options는 결과를 만든 실행을
나타내고, 캐시가 다른 프로필의 결과를 돌려주면 requestedProfile에 요청한 프로필이 남습니다.
텍스트 출력은 결과를 만든 프로필의 설정이 다를 때만 재사용 표시에 profile NAME을 붙입니다.
설정이 같은 변형의 결과에는 표시가 붙지 않으며, 저장된 options.variant로 구분합니다.
재사용만 하기
verify --reuse-only KINDS는 runtime, agent, human을 쉼표로 이은 목록을 받습니다.
목록에 있는 종류의 eval은 기존 결과만 재사용할 수 있습니다. 재사용할 수 있는 것은 로컬 캐시에
있는 그 재사용 키의 완료된 기록이나, 설정되어 있다면 리뷰 저장소에 있는
기록입니다. 그런 기록이 없으면 eval을 실행하지 않습니다. 실행 프로세스를 시작하거나 provider를 호출하거나 Human 요청을 만들지 않으며, 같은 재사용 키의 리뷰가 진행 중이어도 거기에 합류하지 않습니다.
강제로 실행하는 eval은 캐시 결과를 읽지 않으므로, 목록에 있는 종류에 --force를 주면 절대 실행되지
않습니다. 목록에 없는 종류는 평소처럼 실행합니다. CI에서
artifactize verify --all --wait --reuse-only agent,human을 쓰면 테스트는 실행하고 리뷰는
모두 캐시나 저장소에서 가져옵니다(CI).
실행하지 않은 eval은 STALE로 표시되고, 이유는 blockedReason에 나옵니다.
docs/review [run-Hq2b9X-4]: STALE — Not reused (--reuse-only agent): no cached or stored result, so it was not executed.
이 eval에 의존하는 eval도 다른 증거가 없을 때와 마찬가지로 대기 상태가 되거나 실행이 차단됩니다. 예산을 다 썼을
때처럼, 다른 eval이 RED나 ERROR여도 Run은 이유와 함께 INCOMPLETE(종료 코드 4)로 끝나며, 그
종류들을 reuseOnly로 기록합니다. status는 이 플래그를 받지 않으며, 옵션 없는 verify가
무엇을 할지 예측합니다.
의존성 선택과 출력
artifactize verify app/e2e는 --eval app/e2e처럼 그 eval을 선택합니다. 필요한 의존성
범위의 eval까지 실행하려면 --recursive를 붙이세요. 붙이지 않으면 입력 증거가 이미 있어야
합니다. Artifact를 선택하면 그 부분의 eval과, 같은 순환에 속해 그
Artifact를 리뷰하는 다른 Artifact의 eval도 함께 실행됩니다. --force는 선택한 Artifact와 그 부분의
eval만 새로 리뷰하도록 표시하며, 순환에 속한 다른 Artifact나 의존성에는 적용되지 않습니다. 파일
Artifact는 선언된 이름으로 선택하며, 파일 Artifact를 둘러싼 폴더 Artifact를 선택하면 부분인 파일
Artifact도 함께 선택됩니다.
의존성 순환을 포함해 어떤 eval이 대기 상태가 되거나 실행이 차단되는지는 eval 의존성을 보세요.
status 출력의 동작 값은 execute, reuse, wait, blocked입니다. 요청, 검증, status에는
blockedBy로 eval ID가 들어갑니다. 태그, 파일 종류, 경로는 graph와 status 출력에 나오고,
Monitor는 이를 화면에 보여 줍니다.
status 상태
status는 Artifact와 eval마다 상태를 출력합니다. 상태는 저장된 판정이 아니라 지금의 파일과
선언을 기준으로 합니다. 저장된 GREEN 결과의 재사용 키가 현재 키와 일치하면 PASS로 표시되며, 동작 항목에는 다음에 verify를 실행하면 무엇을 할지 나옵니다.
| 상태 | eval | Artifact |
|---|---|---|
PASS | 현재 재사용 키에 맞는 GREEN 결과가 있고 게이트도 충족합니다 | eval이 모두 PASS이고, 부분과 의존하는 Artifact도 모두 검증 요건을 충족합니다 |
RED | 현재 재사용 키에 맞는 RED 결과가 있습니다 | eval이나 부분 중 하나가 RED입니다 |
BLOCKED | 게이트가 RED입니다 | eval이나 부분 중 하나가 BLOCKED입니다 |
WAIT_DEPENDENCY | 게이트에 아직 현재 결과가 없습니다 | eval이나 부분 중 하나가 대기 중입니다 |
WAITING_HUMAN | 이전 버전의 artifactize가 요청했고 아직 사람이 처리하지 않은 승인이 있습니다 | — |
DEFERRED | 다른 작업을 막지 않으며, 아직 사람이 처리하지 않은 승인 요청이 있습니다 | eval이나 부분 중 하나가 DEFERRED입니다 |
PROVISIONAL | GREEN이지만 게이트가 아직 DEFERRED나 PROVISIONAL입니다 | eval이나 부분 중 하나가 PROVISIONAL입니다 |
STALE | 전에 리뷰했지만 현재 재사용 키에 맞는 결과가 없습니다(이전 오류, 키 없는 결과, --force 포함) | eval이나 부분 중 하나가 STALE입니다 |
UNREVIEWED | 리뷰한 적이 없습니다 | 리뷰한 eval이 없거나, eval도 부분도 없습니다 |
INCOMPLETE | — | 그 Artifact의 eval은 PASS이지만 의존하는 Artifact의 검증 요건이 충족되지 않습니다 |
BASIS | — | 의존하는 Artifact가 모두 검증 요건을 충족한 basis Artifact입니다 |
Artifact의 eval과 부분의 상태 중 RED, BLOCKED, WAIT_DEPENDENCY, DEFERRED, PROVISIONAL,
STALE, UNREVIEWED에 해당하는 것이 여러 개라면, 이 목록에서 가장 앞에 있는 상태를 Artifact에 표시합니다.
그래서 자기 eval이 없는 Artifact는 부분의 상태를 그대로 보여 줍니다. ERROR는 Run 출력에만 나오며,
status는 마지막 시도가 실패한 eval을 STALE로 보여 줍니다.
저장된 Run 증거와 터미널 화면
저장된 증거가 있으면 run show RUN_ID --json과 verify --wait --json의 출력 객체 최상위에
evidence 필드가 들어갑니다. Run 필드는 run으로 감싸지 않고 출력 객체에 바로 들어갑니다. evidence에는 이 Run에서 새 요청을 만들지 않고 사용한 저장된 판정이 eval ID별로 담깁니다. 일부 eval만 실행한 Run에서 상위 eval의 결과를 캐시에서 가져와 쓴 경우가 그 예입니다. 전체 기록에서 가장 최근 판정을 담는 것은 아닙니다. Run을
보세요. 터미널에서 쓰는 키와 화면 배치는 Monitor와
Human 리뷰에 있습니다.
현재 디렉터리 도구
artifactize tools read|list|glob|grep|section|help|open ...은 내장 도구를 현재
디렉터리에서 실행합니다. Store 이외의 방법으로 설치하면 artifactize-tools 명령도
함께 설치됩니다. stdout에 텍스트나 JSON을 출력하고, 도구가 실패하면 stderr에 오류를 남기고 1로,
사용법이 잘못되면 2로 종료합니다. artifactize tools --help가 도구 목록을 보여 주며,
artifactize tools check는 이와 달리 선언된 리뷰 도구를 점검합니다. 하위 명령별 범위
규칙과 제한은 artifactize-tools에
있습니다.
Agent 스트리밍과 Runtime 로그
verify SELECTOR --watch는 Run을 제출한 직후부터 진행 상황을 보여 주고, run watch RUN_ID로는 나중에 진행 상황 보기를 시작할 수 있습니다. 둘 다 --json과 상관없이 JSON 줄을 바로바로 내보냅니다. kind: update
이벤트에는 실시간 상태와 개수가, kind: eval_result 이벤트에는 저장된 요청의 간단한 결과가,
kind: outcome 이벤트에는 Run의 최종 검증 결과가 담깁니다. --watch와 --wait는 함께 쓸 수 없습니다. 지켜보는 명령은 Run 결과에 맞는 종료 코드로 끝나며, 중단하면
130으로 끝나고 지켜보기만 멈춥니다. 다시 연결하면 완료된 eval을 다시 보여 줄 뿐, 지난 이벤트를
그대로 재생하지는 않습니다. 자세한 내용이 필요하면 결과의 next_cursor를 MCP
verify_result에 넘겨 다음 내용을 읽거나 저장된 Run을 살펴보세요.
Runtime eval이 실패했을 때:
artifactize request logs REQUEST_ID --stream stderr --tail 30
artifactize request logs REQUEST_ID --stream stdout --start 100 --end 150
artifactize request logs REQUEST_ID --search 'failure' --tail 10
artifactize config graph INPUT_ARTIFACT --impact --json
로그 조회 결과에는 전체 감사 기록 대신 로그 보존 여부와 원래 줄 번호가 담깁니다. tail은 기본으로 스트림마다 조건에 맞는 마지막 50줄을 돌려줍니다. 범위 조회는
스트림마다 최대 200줄과 제한된 바이트만 돌려주고, 이어서 볼 위치를 next_start로 알려
줍니다. tail과 범위 조회는 함께 쓸 수 없습니다. search는 1–2048바이트의 문자열을 대소문자를
구분해 그대로 찾습니다. 원래 2048바이트가 넘는 줄은 clipped로 표시하고 앞뒤 일부만
보여 줍니다. Runtime 원본 스트림 전체는 저장된 감사 기록의 128 KiB 한도를 넘는 뒷부분까지 Run 출력에 남습니다. prune은 이 원본 로그를 지우지 않으며, 정해진 주기로 지우는 기능도 없습니다. 원본 로그가 없거나 이전 버전 또는 원격 실행의 감사 기록만 남아 있으면 그 상태를 분명히 표시합니다. 공통
Runtime 보존 레퍼런스를 보세요. 공통 증거와
이벤트 스키마, 클라이언트 전달 제한은 MCP 집중 진단에
있습니다.
도구 진단
artifactize tools check # every Agent/Human eval's scope
artifactize tools check app/review # same as --eval app/review
artifactize tools check --artifact app --audience agent
artifactize tools check --execute --artifact app --audience agent --tool read --args '{"path":"README.md"}'
artifactize tools check --execute --artifact app --audience human --tool inspect
artifactize tools check --execute --eval app/review --tool coverage_app --args '{}'
tools check는 선언의 유효성, 실행 파일이 있는지, 범위가 정해진 argv 인자와 선언된 실행 경로를 확인한 뒤 범위, 스키마, 도구별 준비 상태를 JSON으로 출력합니다. 기본으로는
정적으로만 확인하므로 프로젝트 도구나 fingerprint 스크립트를 실행하지 않고 상태나 출력 폴더도
만들지 않습니다. 위치 인자 선택자나 --eval은 Agent/Human eval 하나를 고르며, --artifact나
--audience와 함께 쓸 수 없습니다. 실제로 실행하려면 --tool을 지정하고, eval 선택자를 쓰거나 --artifact와 --audience를 함께 지정해야 합니다. --artifact를 쓰면 짧은 동작 이름과 공개된
이름을 모두 받으며, 범위는 그 Artifact 하나입니다. eval을 쓰면 그 eval이 공개하는
이름(<tool>_<artifact>)으로 도구를 지정합니다. 도구는 그 eval의 범위에서 실행되므로, 인자가
다른 Artifact를 가리키는 도구도 그 eval의 리뷰에서처럼 실행됩니다.
--args는 Agent 실행에서만 쓸 수 있고, 생략하면 Agent 도구는 {}를 받습니다. Human 스키마는 빈
객체만 받고, Human 명령에는 임의의 인자를 넘길 수 없습니다. --execute를 쓰면 보고서의
result에 도구의 응답이 함께 담깁니다. content가 들어 있고, 도구가 실패하면 isError: true이며
종료 코드는 1입니다. 점검은 Run, 판정, 캐시 항목을 만들지 않습니다. Agent 호출은 작성자의
환경에서 별도의 임시 출력 폴더(실행 뒤 삭제)를 쓰고, Human 호출은 리뷰어의 실제 환경을 씁니다.
종료 코드는 준비 완료나 성공이면 0, 선언·사전 점검·도구·정리 실패면 1, 호출이 잘못되면
2입니다. --repo, --state-dir, --json을 받으며, --json이 없어도 보고서는 JSON입니다.
Run 목록
run list [--repo-only | --all]은 저장된 Run을 최신순으로 텍스트 표로, --json이면 JSON
배열로 보여 줍니다. 기본 대상은 정규화한 --repo 경로(생략하면 현재 디렉터리)입니다.
--repo-only는 이 기본값을 명시하고, --all은 공유 상태의 모든 저장소를 포함합니다.
--limit N(기본 50)과 --offset N(기본 0)은 각각 0–4294967295 범위로, 걸러 낸 결과를
페이지로 나눕니다. 범위를 벗어난 값을 지정하면 종료 코드 2로 끝납니다. 각 행에는 Run ID, 저장소, 생성·완료
시각, 상태, 판정과 상태별 요청 수(해당 상태가 없으면 0), Run의
코멘트(있을 때)가 나옵니다. run list는 손상된 기록을 확인하지
않으며, 손상된 기록과 그 이유는 status와 run show가 알려 줍니다. 상태 문제 해결을 보세요. 읽기만 하므로
프로젝트 코드를 실행하지 않고, 없는 상태를 만들지 않으며, 저장소가 지금 남아 있지 않아도
됩니다. 별도의 history 명령은 없습니다.
Config graph
config graph [ARTIFACT]는 기본으로 프로젝트 전체를 보여 주고, ARTIFACT를 주면 순환으로
묶인 Artifact까지 포함해 그 Artifact에 필요한 범위를 보여 줍니다. --impact는 그 결과를 쓰는 하위 Artifact와 각 Artifact가 쓰는 입력도 포함합니다. 이는 구조상 영향이 미칠 수 있는 범위를 넉넉하게
잡은 것이지, 재사용 키를 정확히 예측한 것은 아닙니다. MCP config_graph에서도 Artifact나 eval을 하나 또는 여러 개 골라 같은 정의를 볼 수 있습니다. 실제로 무엇을 실행하고 재사용할지는
status로 확인하세요. 텍스트 출력에는 태그와 파일 종류 표시가 붙은 Artifact, eval, 구성 요소,
입력에서 사용처로 가는 관계가 나옵니다. 전체 JSON에는 정해진 정적 Artifact/eval 정의(프로필,
payload, 스키마, 도구 뷰), 태그, 부분·지시문·argv 관계 정보, 순환 표시, 그리고 서로 의존하는
Artifact 묶음인 강한 연결 요소(SCC)가 의존성 순서대로 들어 있습니다. Artifact 항목에는
kind(file, folder, aspect, graph)와 작업 공간 기준 대상 path가 있습니다. status도 파일 종류와
경로를 보여 주며, Monitor는 이를 화면에 보여 줍니다. 강한 연결
요소의 ID는 전체 그래프를 기준으로 매기므로, 일부만 보여 주면 번호가 띄엄띄엄 나올 수 있습니다. config check는 프로젝트 코드를 실행하지 않고 선언이 유효한지 확인하며, JSON 출력에는 Artifact와 eval 개수를 담습니다. 출력 형식은
텍스트와 전체 JSON 두 가지이며, plan, --compact, --full은 지원하지 않습니다. 예전의 최상위
graph 명령은 도움말에 나오지 않으며, 실행하면 graph moved to "artifactize config graph"를
출력하고 2로 종료합니다.
Human 요청
claim, unclaim, tool, submit은 기본 리뷰어 이름으로 $USER 값을 사용하며, 값이 없으면 Linux와
macOS에서는 $LOGNAME, Windows에서는 %USERNAME% 값을 사용합니다. 모두 없으면 --reviewer NAME을
주세요. --reviewer NAME으로 동작마다 같은 리뷰어를 직접 지정할 수도 있습니다. 리뷰어 이름은
계정 인증이 아니라 담당자를 구분하는 데 쓰이며, 같은 요청을 여러 리뷰어가 겹쳐 처리하지 않도록 로컬 잠금을 겁니다. 요청을 맡은 사람만 도구를 실행하고,
제출하고, 담당을 해제할 수 있습니다. request claim은 담당 정보를, request unclaim은 해제한
담당 정보를 출력합니다. 다른 리뷰어가 맡았거나 더 이상 대기 중이 아닌 요청의 담당을 해제하려
하면 종료 코드 2로 끝납니다. 도구 이름은 <operation>_<artifactId> 형식이며, 호출할 때 임의의 인자를 넘길 수 없습니다.
텍스트 출력은 캡처한 텍스트나 실행 알림을 보여 주고, --json은 도구 결과를 출력합니다. 도구가
실패하면 2로 종료하며 판정을 만들어 내지 않습니다.
제출하려면 --verdict GREEN|RED가 필요합니다. --fields와 --fields-file은 함께 쓸 수
없습니다. 둘 중 하나로 추가 결과 필드만 담은 JSON 객체를 넘기며, 판정은 이 객체에 넣지 않습니다. 생략하면 {}입니다. 파일은
일반 파일이어야 하고, 필드와 전체 결과는 256000바이트까지입니다. JSON, 스키마, 리뷰어 이름,
판정이 잘못되면 2로 종료하며, 요청은 수정 후 다시 제출할 수 있는 상태로 남습니다. 제출에 성공하면 RED여도
0으로 종료하며, 별도의 검증 과정을 시작하지 않습니다.
도구를 실행하거나 제출을 저장하기 전에 선언과 리뷰한 파일을 다시 확인합니다. 요청을 기록한 뒤로
eval의 선언이나 범위가 바뀌었거나, fingerprint가 바뀌었거나 계산할 수 없으면 요청은 판정 없이 ERROR 처리되고 명령은 종료 코드 2를 반환합니다. 오류 코드는 INPUT_CHANGED이며, fingerprint를
계산할 수 없을 때만 FINGERPRINT_RECHECK_FAILED입니다. 새 요청을 받으려면 verify를 다시
실행하세요.
이미 맡은 요청에 같은 리뷰어로 request claim을 다시 실행해도 기존 담당 정보를 돌려주고 0으로
종료하므로, 담당 지정은 반복해도 안전합니다. 제출은 한 번만 받으며, 다시 제출하면 종료 코드 2로 끝납니다. 명령이 중단되는 등 제출
결과가 불확실하면 다시 제출하기 전에 request show로 요청을 확인하세요.
Agent 세션
읽기. REF는 ref, 요청 ID(run-FiVNCV-1), sessionId 중 하나입니다.
artifactize session show run-FiVNCV-1
Session e83bf374-5136-484c-8d2f-2ce38ee4ca57 · codex gpt-6-luna (reasoning max)
Reference: alice@laptop/34bb3c3a-…/run-FiVNCV/run-FiVNCV-1/e83bf374-…
Request run-FiVNCV-1 (Run run-FiVNCV), eval notes/review: GREEN
── System
You are an artifactize evaluator. …
── User (turn 1)
Eval: Review notes (notes/review)
Target Artifact: notes
Instruction: Check notes. …
Artifacts:
[{"name":"notes","role":"target","tools":["read_notes"]}]
── Assistant (turn 1)
[reasoning] Reading the notes
[tool call read_notes] {"path":"notes.md"}
── User (turn 2)
[tool result read_notes]
{"artifactId":"notes","lines":[{"number":1,"text":"notes: R1 holds.\n"}], …}
── Assistant (turn 2)
{"verdict":"GREEN","verdictFields":{}}
── Repair prompt (turn 3)
Your final response did not match the required schema: …
── Assistant (turn 3)
{"verdict":"GREEN","verdictFields":{"covered":["R1"]}}
── Result: {"covered":["R1"],"verdict":"GREEN"}
모델은 pass 또는 fail 스키마의 필드를 verdictFields 안에 담아 답하고, 결과에는 그 필드가
verdict와 나란히 들어갑니다. Agent 리뷰를 보세요.
텍스트 출력은 도구 결과를 2000자에서 자르고 reasoning은 요약만 보여 줍니다. --json은
{"reference", "file", "events"}를 출력합니다. 이 JSON에는 참조, 세션 파일, 저장된
이벤트 전체가 들어 있어 대화를 그대로 재생할 수 있습니다.
세션 요약
--summary는 세션 파일만 읽어 대화의 토큰 사용량과 도구 호출 수 등을 집계합니다. 턴(provider
요청)별 토큰 수와 합계, 도구별 호출 수와 실패 수, follow-up, 백엔드, 모델, 시간 범위가
나옵니다. 오류를 반환했거나, 예산 한도·시간 제한·리뷰 종료 때문에 실행하지 못한 호출을 실패한 호출로 셉니다.
artifactize session show run-FiVNCV-1 --summary
Session e83bf374-5136-484c-8d2f-2ce38ee4ca57 · codex gpt-6-luna (reasoning max)
Reference: alice@laptop/34bb3c3a-…/run-FiVNCV/run-FiVNCV-1/e83bf374-…
Request run-FiVNCV-1 (Run run-FiVNCV), eval notes/review: GREEN
Time: 2026-10-06T09:14:02.118604115Z to 2026-10-06T09:16:41.502330019Z (159.4 s)
Turns: 5 · follow-ups: 1
Tokens: input 21410 · output 1318 · cache read 15872 · reasoning 704
turn 1: input 3920 · output 212 · cache read 0 · reasoning 128
turn 2: input 4310 · output 260 · cache read 3840 · reasoning 160
turn 3: input 4402 · output 96 · cache read 4224 · reasoning 64
follow-up 1, turn 1: input 4366 · output 410 · cache read 3840 · reasoning 224
follow-up 1, turn 2: input 4412 · output 340 · cache read 3968 · reasoning 128
Tool calls: 3 (1 failed)
read_notes: 2
search_notes: 1 (1 failed)
여러 번 시도한 턴에는 (2 attempts)처럼 시도 횟수가 붙습니다. 토큰 수는 그 턴의 각 시도에서
provider가 보고한 값을 합산한 것이며, 한 번도 보고되지 않은 항목은 생략합니다. --json은 같은
내용을 객체 하나로 출력합니다. backend, model, reasoning, startedAt, endedAt,
durationMs, followUps, turns(각 턴마다 follow-up에 대한 답이면 followUp, 그리고
turn, attempts, tokens), tokens, toolCalls
({"read_notes": {"calls": 2, "failed": 0}, …}), sessionId, requestId,
reference가 들어 있습니다.
follow-up으로 이어서 묻기.
artifactize session send run-FiVNCV-1 "Which line shows R1, and does it still hold?"
Session e83bf374-5136-484c-8d2f-2ce38ee4ca57 · follow-up 1 · codex gpt-6-luna (reasoning max) · files changed since this review
notes.md line 1 says R1 holds, but it now reads "R1 fails", so the verdict would change.
헤더에는 follow-up 번호와 리뷰의 백엔드, 모델, reasoning이 표시됩니다(session show와 같은 정보입니다).
--json을 주면 send는 {"reference", "sessionId", "requestId", "send", "filesChanged", "answer", "usage"}를 출력합니다. send는 follow-up 번호, filesChanged는 리뷰한 입력이
바뀌었는지(알 수 없으면 null), answer는 답변 텍스트, usage는 시도별 토큰 수입니다.
follow-up은 저장된 대화를 같은 모델과 현재 프로젝트 도구로 이어 갑니다. 답변은 일반 텍스트이며, 기록된 판정, 결과, 재사용에는 영향을 주지 않습니다. 리뷰한 입력이 바뀌었으면 헤더에 경고가 나옵니다. 질문마다 프로필의 예산이 새로 적용되며, 한 세션에 보낸 질문은 차례대로 처리합니다. follow-up을 저장하는 방식은 follow-up 재생 레퍼런스를 보세요.
다른 머신이나 다른 상태의 참조를 주면 그 대화가 저장된 위치를 알려 주고 실패합니다. 예를 들면
Session e83bf374-… lives in alice@laptop's state 34bb3c3a-…; this is bob@desk's state 5d0e…입니다. 오래된 대화를 자동으로 정리하는 과정에서 세션이 지워졌으면 was removed by the session GC라는 안내가 나오고, 처음부터 저장하지 않은 세션에는 was not saved라는 안내가 나옵니다. 이런 경우, 아직 실행 중인 요청에
session send를 쓴 경우, follow-up이 실패한 경우에 session show와 session send는 종료 코드 2로 끝납니다.
보관. 저장소가 크기 한도를 넘으면 오래된 대화부터 지웁니다. 한도와 이를 바꾸는 방법은 Agent 세션에 있습니다.
개인정보. 대화에는 리뷰어가 도구로 읽은 모든 내용(파일 내용 포함)과 리뷰어가 쓴 모든 내용이
들어 있습니다. 대화는 이 머신에 본인만 읽을 수 있는 파일로 저장하며, 팀 리뷰 저장소를 비롯해 어디에도
올리지 않습니다. follow-up은 리뷰의 매 턴과 마찬가지로 대화를 그 리뷰의 백엔드로 보냅니다.
저장하지 않으려면 "agentSessions": {"enabled": false}로 끄고, 이미 저장된 대화는
$STATE/agent-sessions를 지워서 없애세요.
리뷰 저장소 서버와 클라이언트
artifactize server token add alice --scopes read,publish(토큰을 한 번 출력합니다)와
artifactize server run으로 저장소를 시작하고,
printf '%s\n' "$TOKEN" | artifactize remote login https://reviews.example/로 그 머신에서 로그인하면 Signed in to … as alice가 출력됩니다. 이 페이지는 서버와 클라이언트가
정확히 어떻게 동작하는지 설명합니다. 설정 과정은 팀 리뷰 저장소
가이드에서 차례대로 따라 할 수 있습니다.
리뷰 저장소 서버
artifactize server token add alice-laptop --scopes read,publish
artifactize server token add ci --scopes read
artifactize server run [--listen 127.0.0.1:8417]
artifactize server token list
artifactize server token revoke alice-laptop [--purge]
artifactize server rm KEY
artifactize server는 팀 리뷰 저장소를
--state-dir 아래 별도의 review-store.sqlite에 둡니다. state.sqlite와는 다른 파일입니다.
각 재사용 키의 모든 기록을 보관하며, 조회할 때는 게시자나 도착 순서와 관계없이 완료 시각이 가장 늦은 기록을
판정(GREEN 또는 RED)과 함께 돌려줍니다. server run은 기본으로 루프백에서 일반 HTTP로 동작하고
(다른 주소에 바인딩하면 경고합니다) Ctrl-C로 멈춥니다. 클라이언트는 루프백이 아니면
HTTPS를 요구하므로 앞에 TLS 프록시나 터널을 두세요. 서버 실행 중에도 토큰 관리 명령은
같은 파일을 사용하며, 토큰 변경 사항은 즉시 반영됩니다.
토큰 이름은 비밀값이 아니라 길이가 제한된 ASCII 표시 이름입니다. 토큰 이름의 문법은 CLI 식별자 규칙에 있습니다.
token add는 무작위 bearer 토큰을 한 번만 출력합니다. 저장소에서 다시 볼 수 없으니
그때 저장해 두세요. --scopes는 필수이고 기본값이 없어서, 빠뜨리면 종료 코드 2로 끝납니다.
범위는 read(조회), publish(Runtime과 Agent 기록 게시), human(publish와 함께 쓰면
Human 승인도 게시)입니다. 신뢰할 수 없는 CI에는 read만 주세요. token list는 이름,
범위, 생성·폐기 시각을 보여 주고 토큰은 보여 주지 않습니다. token revoke NAME을 실행하면 즉시 해당 토큰을 사용할 수 없게 됩니다. --purge를 붙이면 그 토큰이 게시한 기록도 모두 지우며, 같은 명령을 나중에 다시
실행해도 됩니다. 폐기하면 --json이 없어도 항상 다음과 같은 JSON 보고서를 출력합니다.
{"name":"alice-laptop","revokedAt":"2026-10-06T09:14:02Z","purgedEntries":0}.
purgedEntries는 --purge가 지운 기록 수입니다. 폐기된 토큰 이름은 다시 쓸 수 없습니다.
rm KEY는 그 키의 기록을 모두 지우고 {"removed":true}(없었으면 false)를 출력합니다.
저장소에 기록을 쓰는 것은 artifactize 클라이언트뿐입니다. verify, request submit,
remote push가 게시하고, verify와 status가 조회합니다. 서버는 아래 경로로 들어오는 요청을 처리하므로,
프록시나 방화벽 규칙을 정할 때 참고하세요. 모든 경로는 Authorization: Bearer TOKEN을 받고
JSON으로 응답합니다. 실패하면 {"error":...}를 돌려주며, 토큰이 없거나 알 수 없거나
폐기된 토큰이면 401, 토큰에 필요한 권한이 없으면 403입니다.
| 경로 | 범위 | 쓰는 명령 |
|---|---|---|
GET /v1/whoami | 필요한 범위가 없습니다 | remote login, remote status |
POST /v1/lookup | read | verify, status, remote push |
PUT /v1/entries/{key} | publish(Human 승인이면 human도) | verify, request submit, remote push |
기록에는 eval, 판정, 리뷰에 포함된 fingerprint, 결과를 만든 Run, 결과를 만든 사람이 들어 있습니다.
요약 기록(공유 수준 summary)에는 eval에 선언된 프로필도 들어가므로 Runtime eval의 명령과
인자도 함께 공유됩니다. 다만 캡처한 출력, 명령이 실제로 무엇을 실행했는지에 대한 기록,
저장소 경로는 들어가지 않습니다. 전체 기록(공유 수준 full)에는 저장된 실행과 그 출력이
더해집니다. 요약을 공유한다면 선언하는 인자에 API 키나 토큰 같은 민감한 정보를 넣지 마세요. 기록 크기는 요약이 최대
256 KiB, 전체 기록이 최대 16 MiB입니다. 서버는 형식이 잘못됐거나, 완료 시각이 없거나, 기록의
재사용 키와 보낸 키가 다른 기록을 거부하고, 게시한 토큰의 이름과 서버 시각을 기록에 남깁니다.
그다음 각 클라이언트는 받은 기록의 평가 기준과 fingerprint가 요청한 값과 일치하는지 확인하고, 다르면
경고한 뒤 무시합니다. 따라서 저장소에서 다른 평가 기준이나 입력의 결과를 보내더라도 클라이언트는 이를 재사용하지 않습니다. 무엇이 공유됐는지는 클라이언트에서 artifactize cache list로
보고, 키의 기록을 지우려면 artifactize server rm KEY를 쓰세요. 조회도 사용한 것으로 기록되며,
저장소는 기록이 100,000개 또는 4 GiB를 넘으면 가장 오랫동안 쓰지 않은 기록부터 지웁니다.
업그레이드. 서버와 클라이언트는 함께 업그레이드하세요. 0.3이나 0.4의 저장소는 토큰은 그대로 두고 기록은 버리므로, 클라이언트가 한 번 더 리뷰하고 다시 게시합니다. 0.3과 0.4 클라이언트에는 업그레이드하라는 안내가 갑니다.
0.9 이전 기록은 재사용하지 않습니다. 0.9로 업그레이드를 보세요. 로컬 상태는 따로 업그레이드됩니다. 상태를 보세요.
팀 리뷰 저장소 클라이언트
printf '%s\n' "$TOKEN" | artifactize remote login https://reviews.example/ [--share full]
artifactize remote status [--json]
artifactize remote push [--dry-run] [--json]
artifactize remote logout
클라이언트의 연결 설정은 .artf 선언이 아니라 상태 디렉터리와 환경 변수로만 정합니다. 따라서 복제한 저장소의 선언으로 토큰 전송 대상을 바꿀 수 없습니다. remote login URL은 토큰을
argv가 아닌 stdin에서 읽으므로 토큰을 한 줄로 붙여 넣으세요. 4096바이트가 넘는 토큰은 거부합니다.
터미널에서는 입력한 토큰이 화면에 나타나지 않도록 처리하며, Windows에서 입력을 숨기는 데 실패하면 토큰이 화면에 보인다고 경고한 뒤 계속 읽습니다. 터미널이 아닌 stdin은 터미널 에코를 건드리지 않고 읽습니다.
GET /v1/whoami로 토큰을 확인한 다음, 내 계정만 읽을 수 있는
$STATE/auth/remote-token.json에 저장하고 $STATE/remote.json에
{"url":"https://reviews.example/","share":"summary"}를 씁니다. URL은 시스템이 신뢰하는
인증서로 검증할 수 있는 HTTPS 주소여야 하며, 일반 HTTP는 localhost, 127.0.0.0/8, [::1]에서만
허용합니다. 자격 증명, 쿼리, 프래그먼트가 붙은 URL은 거부합니다. 저장된 토큰은 발급받은
출처에서만 씁니다.
ARTIFACTIZE_REMOTE(URL 또는 off), ARTIFACTIZE_REMOTE_TOKEN(CI용),
ARTIFACTIZE_REMOTE_SHARE(summary 또는 full)는 remote.json과 저장된 토큰보다
우선합니다. remote status는 URL, 공유 수준, 토큰 출처(env, file, none), 접속 가능
여부를 출력하고, 이어서 주체와 범위 또는 저장소가 돌려준 오류를 출력합니다. 토큰 인증에 성공하면 0, 실패하면 1로 종료합니다. JSON은
{"configured":true,"url":…,"share":…,"tokenSource":…,"reachable":BOOL,"principal":…,"scopes":[…],"error":…}
형태입니다. 로그인한 상태가 아니면 principal과 scopes가 null이고, 로그인한 상태면
error가 null입니다. 토큰이 거부되면 reachable: true에 오류가 함께 나오고, 저장소에 연결하지
못하면 reachable: false입니다. 설정된 저장소가 없으면 No remote review store is configured.(JSON은 {"configured":false})를 출력하고 1로 종료합니다. 요청의 제한 시간은 연결에 2초, 전체 처리에 5초이며, 리디렉션은 따라가지 않습니다. remote logout은 저장된 토큰과
remote.json을 지웁니다. 서버에서는 server token revoke를 하기 전까지 그 토큰이 계속
유효합니다. 토큰은 출력하지도, 로그에 남기지도 않습니다.
저장소가 설정되어 있으면 verify는 각 리뷰를 실행하기 전에 저장소를 조회하고, 로컬 결과와 저장소 결과 중 완료 시각이 더 늦은 결과를 재사용합니다. 저장소 결과는 origin과 함께 로컬 상태로
복사되므로 run show, cache, Monitor에 재사용으로 나옵니다. 아직 결과가 없거나 사람의
승인 여부가 아직 결정되지 않은 리뷰가 있으면 verify는 약 1초마다 저장소를 다시 확인합니다. 다른 곳에서
누군가 게시한 승인이 들어오면 대기 중인 요청은 그 승인을 재사용해 완료되고, 해당 요청에서 대기 중이던 Human 승인 작업은 ERROR(SUPERSEDED)로 끝납니다. 텍스트 출력에는 결과의 출처가 나옵니다.
app/check [run-Hq2b9X-1]: GREEN (reused from remote: alice@laptop, run-x05qFq)
brand/signoff [run-Hq2b9X-2]: GREEN (reused from remote: Human sign-off by alice, published by alice-signoff, run-Ksl1Qr)
만든 사람(user@host)과 Human 리뷰어는 게시한 머신이 기록한 값이고, 게시자는 서버가 인증한
토큰 이름입니다. Agent 결과에는 만든 머신에 있는
저장된 대화를 가리키는 참조도 들어 있습니다. 대화
자체는 게시하지 않으며, 재사용한 요청에 session show를 실행하면 대화가 어느 머신, 어느 상태에
있는지 알려 줍니다. 이전 버전 클라이언트도 업그레이드 없이 같은 저장소를 쓸 수 있습니다.
게시되는 것. 재사용 키가 있는 GREEN이나 RED 결과가 로컬에 저장되면 verify는 요약 기록을
게시하고, 공유 수준이 full이면 전체 기록을 게시합니다. 게시에 실패해도 로컬 결과는 남고 실패가
보고됩니다. request submit은 Human 승인을 게시합니다. --speculate Run은 스케줄링이 끝난 뒤에,
끝까지 유효한 결과만 게시합니다(추측 실행).
토큰에 부여된 권한 범위 안에서만 작업할 수 있습니다. read가 없으면 아무것도
조회하지 않고, publish가 없으면 아무것도 게시하지 않으므로 읽기 전용 CI 토큰을 사용하면 결과를 재사용할 수만 있고 새 결과를 게시할 수는 없으며,
human이 없으면 Human 승인은 경고와 함께 로컬에만 남습니다. 재사용 키가 없는 eval은 아무것도
게시하지 않으며, --force 결과는 게시되어 가장
최근 기록이 됩니다. status도 읽기 전용 조회로 같은 비교를 하므로 reuse 예측에 더 새로운 원격
결과가 반영되며, status --force는 원격 호출을 하지 않습니다.
remote push는 키마다 이 머신이 만든 가장 최근 GREEN/RED 기록을 보냅니다. 저장소에 연결하지
못했을 때, remote login 전에, 또는 ARTIFACTIZE_REMOTE=off로 만든 결과가 대상입니다.
미러링한 기록은 보내지 않습니다. read 권한이 있는 토큰을 쓰면 먼저 각 키에 대해 저장소의 최신 기록을
조회하고, 이미 최신인 기록은 다시 보내지 않습니다. 저장소는 각 실행을 한 번만 보관하므로 이미
있는 기록에는 created: false로 응답합니다. 두 경우 모두 existing으로 집계되므로 두 번 푸시해도
문제없습니다. human 범위 없이 보내는 Human 승인과 크기 제한을 넘는 기록은 stderr에 이유를
남기고 skipped가 됩니다. 출력은 Pushed N, already in the store M, skipped K. 또는 JSON
{"dryRun":false,"pushed":N,"existing":M,"skipped":K}입니다. --dry-run은 아무것도 보내지
않고 Would push N, already in the store M, skipped K.(JSON은 "dryRun":true)를
출력합니다. verify와 달리 push는 원격 실패가 하나라도 있으면 실패하며, publish 범위가
필요합니다.
연결 오류, 요청 시간 초과, 5xx 응답이 나면 경고를 한 번 출력하고 원격 저장소를 쓰지 않은 채 작업을 계속합니다. 각 키의
로컬 최신 기록을 재사용하고, 기록이 없는 것은 로컬에서 리뷰합니다. 401/403, TLS 실패, 그 밖의
오류 응답, 잘못된 설정, 그리고 성공 응답이지만 본문을 읽거나 해석할 수 없는 경우(본문 시간
초과 포함)는 오류로 처리하고 멈춥니다. 401/403 응답이면 artifactize가 저장소에서 토큰을 거부했다고 안내하며, 다른 4xx 응답이면 저장소가 보낸 오류 메시지가 있을 때 그 메시지를 보여 줍니다. verify는
Run이 접수되었다는 사실을 먼저 저장한 뒤 원격 증거를 조회합니다. 그래서 조회에 실패해도 Run이 사라지지
않고 ERROR Run으로 남습니다. 제출만 하는 verify는 접수되면 0으로 종료하고, verify --wait는 그 ERROR를 확인하고 2로 종료합니다. 설정이 잘못되었으면 접수 전에 제출이 거부될 수도
있습니다. status 같은 동기 명령은 조회 오류로 중단되면 곧바로 종료 코드 2로 끝납니다. 검증을
통과하지 못한 기록은 경고와 함께 무시하고, 그 eval은 로컬에서 리뷰합니다.
캐시와 유지보수
artifactize prune --older-than 30d --dry-run은 완료된 지 30일이 넘은 Run 중 출력 폴더를 삭제할 Run을 미리 보여 줍니다(wouldRemove). 확인했으면 --dry-run 없이 다시 실행해 지우세요.
이 페이지에서는 prune과 함께 캐시 결과를 확인하고 삭제하는 명령, 이 머신의 설정을
점검하는 명령을 설명합니다. 이 명령들이 다루는 대상은 상태, 캐시, 제한에서
설명합니다.
캐시 살펴보기
artifactize cache list [--history] [--json]
artifactize cache show KEY [--history]
artifactize cache rm KEY
이 명령들은 공유 상태나 --state-dir PATH를 쓰며 저장소가 없어도 됩니다. 재사용 키마다
완료된 GREEN/RED 기록을 모두 보관하고, verify는 그중 가장 최근 기록을 재사용합니다.
list는 키마다 가장 최근 기록을 보여 줍니다. 키, eval, 판정, 완료 시각, 만든 사람,
저장소(또는 그 기록을 가져온 원격 저장소), 그 키에 쌓인 기록 수, 크기, 마지막 사용 시각이
나옵니다. JSON에는 eval 정의 해시, 대상의 fingerprint, 프로필 변형도 들어 있습니다.
--history는 모든 기록을 최근 것부터 보여 줍니다.
show는 그 키의 가장 최근 기록을 JSON으로 출력합니다. 결과, 실제로 쓴 profile,
options(백엔드, 모델, reasoning, 제한, 변형), 키가 포함하는 각 Artifact의 fingerprints,
artifactKinds(포함한 이름마다 folder, file, aspect, graph 중 하나), 사용량, producer
(user@host와 artifactize 버전)가 나오고, Human 결과에는 그 결과를 제출한 사람인 reviewer도 따로 나옵니다.
팀 리뷰 저장소에서 온 기록에는 origin(저장소, 게시자, 게시 시각)이
붙어 있습니다. 키가 없으면 null을 출력하고 4로 종료합니다. --history는 모든 기록을 배열로
출력합니다. 읽기만 하므로 아무것도 바뀌지 않습니다.
rm은 그 키의 기록이 더는 재사용되지 않게 하고 {"removed":true}(없었으면 false)를
출력합니다. 저장된 Run의 결과는 그대로 남습니다. 지금 리뷰 중인 키의 기록은 지울 수 없습니다. 키는
cache list에서, 또는 verify --wait --json과 run show에 나오는 요청의 key에서 얻을
수 있습니다. 키를 만드는 방법과 캐시가 적중했을 때 무엇을 돌려주는지는
완료된 결과 재사용에 있습니다.
로컬 진단과 유지보수
artifactize doctor [--repo PATH] [--state-dir PATH] [--json]
artifactize models PROVIDER [--json]
artifactize login openai|anthropic|gemini|codex|claude-agent [--json]
artifactize logout openai|anthropic|gemini|codex|claude-agent [--json]
artifactize provider list [--json]
artifactize provider add NAME (--alias PROVIDER | --api API --url URL [--key]) [--json]
artifactize provider remove NAME [--json]
artifactize prune [--older-than 7d] [--dry-run] [--state-dir PATH] [--json]
prune은 현재 저장소뿐 아니라 선택한 상태 디렉터리에 저장된 모든 저장소의 Run을 다룹니다.
GREEN, RED, ERROR, INCOMPLETE로 끝났고 아직 실행 중인 작업이 없는 Run의 출력을
지웁니다. YELLOW Run은 승인이 모두 제출된 뒤에도 항상 건너뛰며, 끝나지 않은
Run도 건너뜁니다. --older-than에는 s, m, h, d, w를 붙인 정수로 기간을 지정합니다. Run이 끝난 시각을 기준으로 이 기간이 지났는지 확인합니다. 이 옵션이 없으면 대상이 되는 Run을 모두 정리합니다. 지우는 것은
state/runs/<run-id> 안의 출력 폴더(Runtime의 output, 남은 도구 출력, 이전 버전이 남긴 tmp,
home, cache)뿐이므로 run show와 request show는 계속 동작합니다. --dry-run일 때도 심볼릭
링크와 프로젝트처럼 보이는 폴더(.git이나 Artifact 선언이 있는 폴더)는 건드리지 않습니다. 다른
프로그램이 그 폴더를 바꾸는 동안에는 실행하지 마세요. prune은 --older-than과 상관없이
Agent 세션 저장소도 크기 한도까지 줄입니다. 텍스트
형식으로는 지운 폴더마다 Removed PATH(--dry-run이면 Would remove PATH), 건너뛴 Run마다
Skipped Run ID, 지운 세션마다 Removed Agent session ID(--dry-run이면 Would remove Agent session ID)를 한 줄씩 출력하고, 마지막에 데이터베이스와 저장소 파일은 그대로 두었다고 알립니다.
--json이면 같은 내용을 removed 또는 wouldRemove, skippedRuns, removedSessions 또는
wouldRemoveSessions로 돌려줍니다. 미리
보기에서는 실행 중인 session send가 쓰는 세션을 확인할 수 없으므로, 실제 정리에서는 이보다
적게 지울 수 있습니다.
Doctor, models, prune
doctor는 provider를 호출하지 않고 Run, 판정, 캐시 항목, 로그인 정보도 만들지 않습니다.
상태 디렉터리를 알려 주고, 쓸 수 있는지와 작업 공간 밖에 있는지 확인합니다. 상태 데이터베이스의
스키마를 artifactize가 지원하는지 확인하고 필요하면 업그레이드합니다.
지원하지 않는 스키마이면 심각한 오류로 처리하며, 현재 스키마는 schema에, 지원하는 스키마는 supported에 표시합니다.
--repo를 주면 config check의 검사도 함께 합니다. 그 밖의 검사는 다음과 같습니다.
limits: 백엔드 수용량입니다.limits.json이 잘못되었으면 심각한 오류입니다.sessions: Agent 세션 저장소입니다. 세션 수와 바이트 수,maxBytes,targetBytes,enabled, 저장 위치directory, 상태의stateId가 나옵니다.openai,anthropic,gemini: API 키가 변수에 있는지, 저장되어 있는지, 없는지만 알려 주며, 키가 유효한지 검사하거나 값을 출력하지는 않습니다. 사용하는 백엔드의 키만 있으면 되므로, 키가 없으면 오류가 아니라 경고로 처리합니다. 테스트 엔드포인트를 쓰면 어떤 엔드포인트인지testEndpoint로 알려 주는 경고가 나오고, 잘못된 엔드포인트는 심각한 오류입니다.codex: 로그인 정보를 갱신하거나 온라인에 접속하지 않고 읽습니다. 로그인하지 않았으면 경고입니다. 로그인 정보가 저장되어 있으면 액세스 토큰이 만료됐어도 검사를 통과합니다. 만료된 토큰은 다음에 쓸 때 갱신합니다.ARTIFACTIZE_CODEX_AUTH_FILE의 토큰이 만료됐으면 경고입니다.$STATE/auth가 저장소 안에 있으면 거부 메시지를refused에 담은 경고가 나오고, 그곳에 로그인 정보가 저장되어 있으면 심각한 오류가 됩니다. 세부 정보에는source(stored,file,none),expiresAt,expired, 테스트 엔드포인트가 나옵니다.claude-agent:PATH에서 찾은claude의 위치를 실행하지 않고program으로 보여 줍니다. 없으면 경고입니다. 로그인과 버전은 리뷰나models claude-agent가 Claude Code를 실행할 때 확인합니다.providers: 이 머신에 등록한 커스텀 provider와 각각이 연결되는 곳을 보여 줍니다. 키 값은 보여 주지 않습니다.$STATE/auth가 저장소 안에 있으면, 저장한 것이 없는 동안에는 경고이고 저장한 것이 있으면 심각한 오류입니다.- 팀 리뷰 저장소: 이것도 오프라인으로 확인하며 URL, 공유 수준, 토큰 출처를 보여 줍니다. 토큰이 없으면 경고이고, 설정이 잘못됐거나(루프백이 아닌 호스트에 일반 HTTP를 쓰는 경우 포함) 토큰 파일이 안전하지 않으면 심각한 오류입니다.
desktop: 데스크톱 앱이 설치되어 있는지 앱을 실행하지 않고 확인합니다.artifactize명령과 같은 폴더,PATH, 이 시스템의 설치 프로그램이 앱을 두는 위치에서 찾고, 세부 정보의path에 앱 위치가 나옵니다. 앱이 없으면 설치 페이지 링크와 함께 경고가 나옵니다. 명령은 앱 없이도 동작합니다.release: artifactize의 새 릴리스가 나왔는지 확인합니다.doctor가 네트워크에 접속하는 유일한 검사입니다(새 릴리스 알림). 새 릴리스가 있으면 경고를 표시하고,latest에는 최신 버전을,update에는 현재 artifactize의 설치 방식에 맞는 업데이트 방법을 담습니다. 실행할command, 내려받을 파일download(.deb는 설치할command포함), 설치 방법을 알 수 없으면 릴리스page입니다.channel은 설치 방식을,running은 지금 실행 중인 artifactize의 버전을 나타냅니다. 확인에 실패해도 경고입니다. Microsoft Store 설치, 개발 빌드,ARTIFACTIZE_NO_UPDATE_CHECK를 설정한 경우에는 확인하지 않습니다.
심각한 오류가 없으면 0, 있으면 1, 호출이 잘못되었으면 2로 종료합니다.
models PROVIDER에는 프로필의 backend에 쓸 수 있는 이름이면 무엇이든 줄 수 있습니다.
models openai, models anthropic, models gemini는 API 키로 쓸 수 있는 모델을, models codex는
로그인한 Codex 계정의 모델을, models claude-agent는 메시지를 보내지 않는
Claude Code 세션에서 읽은, Claude Code가 지금 로그인으로 제공하는 모델을
(Claude Agent), 커스텀 provider는 그 별칭이나
엔드포인트가 제공하는 모델을 보여 줍니다. 여기서도 테스트 엔드포인트가 provider를 대신하며, 다른
계정이나 백엔드로 넘어가지 않습니다. 텍스트 출력은 탭으로 구분한 slug와 이름 쌍이고, JSON은
provider가 준 순서대로 {"backend":"openai","models":[{"slug":"model-id","display_name":"model-id"}]}
형태입니다.
키와 커스텀 provider
login openai|anthropic|gemini는 stdin에서 API 키를 읽어 저장합니다. API 키도 remote login의
토큰 입력과 마찬가지로 한 줄에서 처음 8192바이트까지만 읽은 뒤 앞뒤
공백을 제거합니다. 터미널에서는 입력이 화면에 나타나지 않으며, Windows에서 입력을 숨기는 데 실패하면 키가
화면에 보인다고 경고한 뒤 계속 읽습니다. 같은 이름으로 logout을 실행하면 저장한 키를 지웁니다. 키 변수가 설정되어 있으면
그 변수를 먼저 씁니다. login codex와 logout codex는 Codex 로그인입니다.
login claude-agent와 logout claude-agent는 Claude Code 자체 명령인 claude auth login과
claude auth logout을 실행합니다(Claude Agent).
provider add NAME은 커스텀 provider를 저장하며, 같은 이름이
있으면 바꿉니다. --alias PROVIDER는 기본 provider를 다른 이름으로 쓰고, 엔드포인트는
--api openai-responses|openai-chat|anthropic|gemini와 --url로 지정합니다. --key는 선택 사항이며,
주면 같은 방식으로 키를 stdin에서 읽습니다. --key 없이 저장한 엔드포인트에는 키가 없으며, 키가 있던
엔드포인트를 바꿀 때도 마찬가지입니다. provider remove NAME은 삭제합니다. provider list는 기본 provider마다 키의
source(environment, saved, absent 중 하나이며 변수를 먼저 봅니다), 변수를 쓰는 동안에도 키가 저장되어 있는지(saved), 커스텀
provider 전체를 출력하며, 키 값은 출력하지
않습니다.
{"keys":[{"provider":"openai","variable":"OPENAI_API_KEY","source":"environment","saved":true}],
"custom":{"local":{"kind":"endpoint","api":"openai-chat","url":"http://localhost:11434/v1","key":false},
"work":{"kind":"alias","provider":"codex"}}}
TUI
터미널용 Monitor와 Review에서도 다른 인터페이스에서 보는 것과 같은 Run 기록과 Human 요청을 확인할 수 있습니다. CLI와 함께 설치되며, 별도의 터미널 패키지나 서비스는 필요 없습니다. 요청을 직접 맡거나, Human 도구를 실행하거나, 판정을 제출하지 않는 한 목록과 미리 보기를 살펴보기만 해서는 아무것도 바뀌지 않습니다. 다만 선언이 바뀐 대기 중 Human 요청을 열면 그 요청은 ERROR로 끝납니다(아래 Tools 참고).
Review
artifactize review [REQUEST_ID] [--repo PATH | --all] [--state-dir PATH] [--reviewer NAME]
저장된 요청을 검색하고 대기 중인 Human 요청을 리뷰하는 터미널 UI이며,
request와 같은 단계를 거칩니다. 맡고, 도구를 실행하고, 담당을 해제하고, 제출하며, 제출한 결과를
request submit과 똑같이 팀 리뷰 저장소에 게시합니다. 작업 중인 터미널은 그대로 두고, 별도의
터미널이나 tmux 창에서 실행하세요.
ID를 지정하지 않으면 상태 디렉터리에 기록된 모든 저장소에서 검색 조건에 맞는 요청을
최신 Run부터 나열합니다. 각 요청에는 eval, 요청 ID, 상태, 담당자, 경과 시간, 저장소가 표시되며,
Enter를 누르면 선택한 요청이 열립니다. 처음 검색어는 대기 중인 Human 승인을 뜻하는 kind:human status:waiting_human입니다.
--repo PATH는 그 저장소의 repo: 조건을 더하며, --all도 쓸 수 있고 이것이
기본값입니다. 어느 저장소의 요청이든 ID로 열 수 있습니다.
검색어에는 일반 텍스트와 key:value 조건을 함께 쓸 수 있으며, 모든 조건을 만족하는 항목만 표시됩니다. 일반 단어는
저장소 경로, eval, 요청 ID, 맡은 사람 이름에서 대소문자를 구분하지 않고 부분 문자열로 찾습니다. 키를 붙이면
그 필드에서만 찾습니다. 공백이 있는 값은 따옴표로 감싸고(repo:"/work/my repo"), 단어를
글자 그대로 검색하려면 따옴표로 감싸세요("type:style").
| 조건 | 일치 대상 |
|---|---|
repo: | 저장소 경로의 일부 |
eval: | eval ID의 일부 |
request: | 요청 ID의 일부 |
reviewer: | 맡은 사람 이름의 일부입니다. 맡지 않은 요청은 일치하지 않습니다 |
tag: | eval의 Artifact에 선언된 태그 중 일부(선언의 tags, Run과 함께 저장된 그대로) |
kind: | eval 종류: runtime, agent, human |
status: | waiting_human(deferred 승인 포함), green, red, error 같은 요청 상태 |
is:mine | 내가 맡은 것($USER 또는 --reviewer) |
is:claimed | 누구든 맡은 것 |
is:unclaimed | 아무도 맡지 않은 대기 중인 Human 요청 |
대기 중인 Human 요청만 맡을 수 있으므로, 그 밖의 요청은 is: 조건의 검색 결과에 포함되지 않습니다. 알 수 없는 키나
값을 쓰면 쓸 수 있는 값을 알려 주는 오류가 나며, 요청은 나열하지 않습니다.
/로 검색어를 편집하며, 입력할 때마다 목록이 갱신됩니다. 검색어를 입력하면 끝에만 추가되며, Backspace로 마지막 글자를 지울 수 있습니다. 방향키로 검색어 안의 커서를 옮길 수는 없습니다. Tab을 누르면 마지막 조건이 자동으로 완성됩니다. 완성 후보는 검색 키이고,
키를 이미 입력했다면 나머지 검색 조건에 맞는 요청의 값(저장소 폴더, eval, 요청, 맡은 사람, 태그)이나
kind, status, is: 값입니다. 후보가 하나면 Tab으로 그 후보를 넣고, 여럿이면 공통 부분까지만 채우며,
후보를 차례로 바꿔 가며 고르지는 않습니다. 아래쪽 안내줄에 후보가 여섯 개까지(그 뒤는 +N) 나오니, 더 입력해서
고르세요. 붙여 넣은 텍스트는 끝에 한 줄로 더해지며, 제어 문자는 공백으로 바뀝니다. 검색을 바꾸거나
완성하면 첫 페이지로 돌아갑니다. Enter나 ↓를 누르면 바꾼 검색어를 유지한 채 편집이 끝납니다. Esc를 누르면 편집 전 검색어로 되돌아가고, Ctrl-U를 누르면 검색어가 지워집니다. 검색어가 비어 있으면
처음의 대기 중인 Human 요청뿐 아니라 모든 종류의 요청이 나옵니다. 한 페이지에는 요청 100개가 나오며,
PgDn을 누르면 더 오래된 요청을, PgUp을 누르면 더 새로운 요청을 볼 수 있습니다.
목록에는 대기 중인 승인이 하나씩 나옵니다. 이후 Run의 요청이 대기 중인
Human 실행에 합류하면 원래 요청만 한 번 나열되며, Monitor에서처럼 Human 도구와 결과 필드 스키마는
원래 요청에 기록되고, 담당 지정, 도구 실행, 제출도 모두 원래 요청을 기준으로 처리합니다. 팔로워의 ID로 열어도 원래 요청이 열립니다. 검색 대상은 원래 요청이므로,
팔로워가 속한 저장소를 검색 조건으로 써도 그 요청을 찾을 수 없습니다. 원래 요청이 더 이상 대기 중이 아니면 팔로워도 별도 항목으로 나열됩니다. Human 요청을 고르면 아래에 설명한 Human Detail이 열리며, 확정된 요청은 읽기 전용으로 표시됩니다. 그 밖의
요청을 고르면 Detail이 읽기 전용으로 열립니다. 이 Detail은 Monitor에서 해당 Run의 eval을 열었을 때와
같은 섹션을 보여 주며(d로 섹션을 보여 줌), 저장된 Runtime 출력이나 Agent 대화도 같은 방식으로
표시합니다. 담당 지정, 도구, 양식은 없습니다.
목록과 Detail의 배치는 터미널 크기에 따라 달라집니다(반응형 창). 목록에 초점이 있으면
목록이 Full로, 선택한 요청이 읽기 전용 Preview로 나옵니다. Enter나 →를 누르면 Compact 목록 옆에 Detail이 열립니다. 작은 터미널에서 창을
어떻게 배치하는지는 반응형 창에서 설명합니다.
이동 경로는 artifactize review › search › eval입니다. ↑/↓ 또는 j/k로 요청을 고르고, r로 목록을 새로 고칠 수 있습니다. Tab을 누르면 선택한 요청이 열리고 Tools로 초점이 이동합니다. 목록에서
Esc를 누르면 그 자리에 머물며, 종료되지 않습니다. 단독 UI에는 ? 도움말 오버레이나 ! 주의 항목
이동이 없으며, 그 키는 Monitor에서만 씁니다.
마우스 캡처는 기본으로 켜져 있습니다. 목록 행을 클릭하면 선택하고, 다시 클릭하면
엽니다. 휠은 목록에 초점이 있을 때 목록을 스크롤하며, 열린 Detail 옆의 Compact
목록은 스크롤하지 않습니다. Human Detail에서도 Monitor와 같은 방식으로
마우스를 쓸 수 있습니다. 단독 Review에서 Human 요청이 아닌 요청의 Detail은 키보드로만 조작할 수 있습니다.
대화 기록 묶음과 내용은 클릭이나 휠에 반응하지 않습니다. F2를 누르면 마우스 캡처가 꺼져 터미널에서 텍스트를 선택할 수 있으며, 헤더에 mouse off · F2가 나옵니다.
터미널의 bracketed paste는 마우스 캡처를 켜든 끄든 동작합니다.
단독 Review에서는 Runtime 증거를 섹션 아래의 고정 창에 보여 줍니다. 그 출력은 따로 스크롤되지 않습니다. 화살표 키나 페이지 이동 키를 누르면 섹션이 스크롤되며, Tab을 눌러도 초점은 증거 창으로 이동하지 않습니다. Monitor에는 대신 폭에 따라 섹션 옆이나 아래에 따로 스크롤되는 Runtime 증거 창이 있습니다.
공용 Human Detail
Monitor와 단독 review는 Human 리뷰를 똑같이 보여 줍니다. 요청을 열거나
미리 보기만 해서는 요청을 맡지 않습니다. 상태, 맡은 사람, 대기 시간을 담은
한 줄 아래에 지시문이 먼저 나옵니다. t를 누르면 Technical이 표시되거나 숨겨집니다. Technical에는 요청,
Run, 저장소, 담당 정보의 전체 세부 사항, 공유 실행, 생성 시각, GREEN/RED
결과 필드 스키마가 나옵니다. 대기 중인 팔로워라면 원래 요청의 정보가 나옵니다.
맡기 전에는 지시문이 본문을 채우고 도구는 한 줄에 나옵니다. 맡은 뒤에는 지시문이 Tools, Tool log,
필드 위의 두 줄로 접힙니다. 편집 중이 아닐 때 i로 지시문을 펼치거나 접고, 펼친 지시문은 ↑/↓로
스크롤합니다. Technical이 보이는 동안에는 지시문이 펼쳐진 채로 있으니 먼저 t로 Technical을
숨기세요. 긴 기준은 어느 하위 영역에서든 Ctrl-PgUp/PgDn으로, Monitor에서는 지시문 위의 휠로도
스크롤합니다. Tools에 초점이 가면 Tools와 Tool log 열이 폭의 60%로 넓어지고, 고른 도구의 기능과 설명이
나옵니다. 명령 도구는 리뷰를 열 때 정한 명령줄을 아무것도 실행하지 않고 미리 보여 줍니다. 정하지
못한 명령은 대신 선언을 보여 주고, 도구를 실행하면 그 이유를 알려 줍니다.
내장 도구는 셸 명령줄 대신 대상 경로와 실행할 작업을 보여 줍니다.
예를 들어 notes.md 열기, Markdown 섹션 출력, 디렉터리 나열입니다.
아래쪽 안내줄에는 언제나 초점이 있는 영역의 키가 나옵니다. 마우스로 도구 행을 클릭하면 Tools로
초점이 옮겨 가고 해당 도구가 선택됩니다. Tools에 초점이 있을 때 선택한 도구를 클릭하거나 [Run tool ⏎]를 클릭하면 실행합니다.
| 키 | Human Detail 동작 |
|---|---|
c | 대기 중인 요청을 명시적으로 맡습니다. Detail에 초점이 있을 때만 동작합니다 |
g / r | 맡은 뒤 GREEN / RED를 고르고 그 양식을 엽니다 |
u | 판정 없이 담당을 해제합니다 |
| Ctrl-G / Ctrl-R | 편집 중에 판정을 고르거나 바꿉니다 |
| Ctrl-S | 고른 양식을 제출합니다 |
| PgUp / PgDn | 초점이 있는 필드나 완료된 결과 보기 영역을 스크롤하고, Tools에 초점이 있으면 Tool log를 스크롤합니다. Tab/화살표로는 계속 필드를 고릅니다 |
| Ctrl-U | 편집 중에 담당을 해제합니다 |
| Tab / Shift-Tab | Tools와 Fields 사이를 전환합니다. 편집 중인 Fields에서는 Tab은 필드 사이를 이동하고 Shift-Tab은 Tools로 전환합니다 |
i / t | 편집 중이 아닐 때 지시문을 펼칩니다 / Technical을 켜고 끕니다 |
| Enter | Tools에 초점이 있으면 선택한 도구를 바로 실행합니다(맡은 뒤) |
| Esc | 작업을 취소하고, 그다음 편집을 멈추고, 그다음 Detail에서 나갑니다 |
+ Add에서 Enter / Ctrl-D | 그룹 목록에서 그룹을 추가합니다 / 선택한 그룹을 제거합니다 |
Human 요청을 맡거나 담당을 해제하고, 도구를 실행하거나 결과를 제출하는 작업이 진행 중인 동안에는, 초점이 있는 영역과 상관없이 보조 키 없이 누른 PgUp/PgDn이 Tool log를 스크롤합니다. 작업이 끝날 때까지 양식을 편집하거나 초점을 옮길 수는 없지만, Ctrl-PgUp/PgDn으로 지시문을 스크롤할 수는 있습니다.
-
담당 지정. 요청을 맡으면 기본으로 내 사용자 이름(
$USER)이 리뷰어 이름으로 기록됩니다. 단독review는--reviewer NAME도 받고, Monitor는 항상 기본값을 씁니다. 유효한 사용자 이름이 설정되어 있지 않으면 Monitor는 오류를 보여 주고 그 요청의 읽기 전용 Detail을 그대로 둡니다. 사용자 이름을 설정하거나artifactize review REQUEST_ID --reviewer NAME으로 요청을 여세요. 도구를 실행하거나 판정을 제출해도 요청을 자동으로 맡지는 않습니다. 다른 사람이 맡았거나 승인 대기가 끝난 요청은 읽기 전용이며, Detail에서 나가도 내가 맡은 상태는 그대로입니다. -
도구. ↑/↓로 고르며, 편집 중이 아닐 때는
j/k로도 고릅니다. 도구 실행에는 확인 단계가 없습니다. 도구를 실행하려면 대기 중인 요청을 내가 맡고 있어야 하며, 실행 전에 이를 확인합니다. 다른 곳에서 담당을 해제했거나 요청을 확정했다면 맡지도 실행하지도 않습니다. 실행할 때마다 선언을 다시 읽고 해석합니다. 기록된 Artifact 범위나 eval 선언(도구 포함)이 바뀌었으면 동작을 거부하고 요청을 ERROR(INPUT_CHANGED)로 끝냅니다. 선언이 바뀐 대기 중 요청은 열기만 해도 같은 방식으로 끝납니다. 새 요청을 받으려면 다시 verify하세요. 도구가 실행되는 동안 열린 양식은 열린 채로 있습니다.launch도구는 프로그램을 시작한 뒤 “launched“를 표시하며, UI에서 작업을 계속할 수 있습니다.output도구가 실행되는 동안에는 스피너가 표시되며, Esc나 Ctrl-C로 실행을 취소할 수 있습니다. 명령의 종료 코드가 0이 아니면 판정이 아니라 도구 오류로 처리합니다. -
Tool log. 도구 아래의 Tool log에는 이 리뷰의 모든 도구 실행이 시작 시각(UTC)과 함께 표시됩니다. 자세한 내용은 Tool log를 보세요. 로그는 화면 폭에 맞춰 줄바꿈되고, 새 출력이 보이도록 자동으로 스크롤됩니다. Tools에 초점이 있을 때 PgUp으로 위로 스크롤하면 새 줄이 들어와도 보던 위치가 유지되고, PgDn으로 맨 아래로 돌아가면 자동 스크롤이 다시 시작됩니다. 마우스 캡처를 끄면(F2) 터미널의 텍스트 선택·복사 기능을 쓸 수 있습니다. 단독 Review는 다른 요청을 열면 로그를 지웁니다. Monitor는 요청마다 로그를 메모리에 유지하며, 다른 요청을 본 뒤에도 그 Detail을 다시 열면 복원합니다. 어느 UI에서든 제출에 성공하면 그 요청의 로그가 지워집니다. 다른 곳에서 요청을 확정했거나 로컬에 저장한 뒤 원격 게시에 실패하면 로그가 메모리에 남습니다. 어느 UI도 로그를 디스크에 저장하지 않습니다.
-
양식. 판정을 고르면 별도의 판정 팝업 없이 그 스키마에 맞는 양식이 열립니다. Human 스키마에는 양식으로 입력할 수 있는 형태만 쓸 수 있습니다. 텍스트, 정수, 숫자 필드, 불리언, 문자열 선택지, 상수, 텍스트 목록, 그리고 그런 스칼라 값으로 이루어진 그룹의 목록입니다. 상수는 값이 자동으로 채워지고 행으로 표시되지 않습니다.
*는 필수 필드를 표시합니다. 값을 입력하지 않은 선택 필드는 제출할 결과에서 제외됩니다. 필수가 아닌 불리언은 true, false, 미설정 중에서 고를 수 있으며, 필수 불리언은 true/false 중에서만 고를 수 있습니다. Tab이나 ↑/↓로 행 사이를 이동하고, Space나 ←/→로 값을 고르세요. 글자를 입력하면 편집이 시작됩니다. 텍스트 목록을 편집할 때는 마지막 항목에 입력합니다. Enter를 누르면 다음 항목을 입력할 수 있으며, 빈 항목에서 Backspace를 누르면 그 항목이 제거됩니다. 그룹 목록은 각 그룹의 필드마다 행 하나(findings 2 · problem)와+ Add findings행을 보여 줍니다. 그룹 추가 행에서 Enter를 누르면 그룹이 추가되고, Ctrl-D를 누르면 선택한 행의 그룹이 제거됩니다. 아무것도 입력하지 않은 그룹은 제외됩니다. Enter로는 제출되지 않습니다. 검증 오류가 나면 요청을 대기 상태로 두고 검증에 실패한 경로를 보여 줍니다. 이 규칙이 생기기 전에 저장된 스키마라도 어떤 양식으로도 입력할 수 없는 형태라면 그 이유를 보여 주고 거부합니다. Human 정의가 기록되지 않은 저장된 요청에 빈 스키마를 임의로 적용하지 않습니다. 그 도구 정보는 확인할 수 없다고 표시하며, GREEN/RED 결과 양식은 사용할 수 없습니다. 이런 오래된 요청을 열 때도 기록에 없는 도구나 스키마 선언을 임의로 보충하지 않습니다. -
편집. 담당을 맡고 있는 동안에는 글자, ←/→, Tab이 필드에 입력되고, bracketed paste는 편집 한 번으로 들어갑니다. Esc는 키 표에 나온 대로 한 단계씩 되돌아가고, Monitor의 Close는 진행 중인 작업이 없으면 트리로 돌아갑니다(단독
review에서는 Esc와 같이 동작합니다). 양식이 열려 있거나 작업이 진행 중일 때는 Human Detail 밖을 클릭해도 아무 일도 일어나지 않으며, 휠 스크롤은 그대로 됩니다.상황 결과 담당을 해제하거나 잃음 편집이 멈추고 Fields에 담당 안내가 보입니다. 초안은 남으며, c로 다시 맡으면 이어서 편집합니다다른 요청을 봄 GREEN과 RED의 초안이 남습니다. 단독 review는 다른 요청을 열면 새로 시작합니다붙여 넣기가 256000바이트를 넘음 붙여 넣기 전체를 거부하고 초안은 그대로 둡니다 다른 곳에서 요청이 확정됨 새로 고칠 때 편집이 끝납니다
양식을 편집하거나 작업을 실행하는 중이 아니라면 Detail에서도 q로 종료할 수 있습니다. Ctrl-C를 누르면 먼저 진행 중인 담당 지정, 도구 실행, 제출, 담당 해제가 취소됩니다. 진행 중인 작업이 없으면 양식 안에서도 종료됩니다. Esc로는 종료할 수
없습니다.
단독 review를 종료할 때 이 세션에서 맡은 요청 중 아직 제출하지 않은 요청이 있으면 처리 방법을 묻습니다.
| 키 | 동작 |
|---|---|
k, n, q | 맡은 상태를 유지하고 종료합니다 |
u, r, y | 담당을 해제하고 종료합니다(여기서 r은 새로 고침이 아니라 해제입니다) |
| Esc | 머무릅니다 |
| Ctrl-C | 맡은 상태를 유지하고 종료합니다 |
이 목록은 이 세션에서 맡은 요청을 기준으로 하므로, 다른 곳에서 이미 담당을 해제했거나 제출한 요청도 남아
있을 수 있습니다. 유지를 고르면 그 요청은 건드리지 않고 종료합니다. 담당 해제에 실패하면 Review에 오류가 나오고 창은 열린 채로 있으며, 요청도 계속 그 리뷰어가 맡은 상태로 남습니다. Monitor는
종료할 때 맡은 상태를 유지하니, 다른 사람이 맡을 수 있게 하려면 종료하기 전에 u로 담당을 해제하세요.
단독 Review에서 결과를 제출하면 요청 목록으로 돌아갑니다. 리뷰를 마쳐 현재 페이지가 비면
요청이 남아 있는 가장 가까운 이전 페이지로 이동하며, review는 검색에
일치하는 요청이 더 이상 없을 때만 종료합니다. 이렇게 종료할 때는 검색 결과에 없는, 이 세션에서 맡은
미제출 요청의 담당을 해제할지 묻지 않습니다. 그 요청은 맡은 채로 남으니, 검색을 좁혔다면 먼저 u로 담당을 해제하세요.
Monitor는 완료된 결과를 Detail에 열어 둡니다.
Monitor
artifactize monitor [PATH | --repo PATH | --all] [--state-dir PATH]
Monitor는 이 상태의 모든 저장소를 목록으로 보여 줍니다. 인자 없이 실행한 monitor는 현재 디렉터리와 상관없이
ALL에서 시작합니다. monitor ., monitor PATH, --repo PATH는 처음에 그 저장소나
워크트리를 고르며, --all도 쓸 수 있습니다. 위치 인자 경로는 --repo와 함께 쓸 수 없고,
--all은 둘 다와 함께 쓸 수 없습니다. 이 옵션은 처음 선택만 정하며, 실행한 뒤에도
ALL이나 다른 저장소·워크트리로 이동할 수 있습니다.
Scope → Runs → Run tree → Detail 순서로 이동하며 세부 내용을 확인합니다.
반응형 창
초점이 있는 창이 Full입니다. Compact는 왼쪽 단계의 내용을
좁은 창에 줄여 보여 줍니다. Preview는 초점을 옮기지 않고 다음 단계를 보여 줍니다. 숨겨진 단계는
이동 경로에 남습니다. artifactize › scope › Run › eval.
초점이 있는 창은 가운데에 있고, 왼쪽에 Compact, 오른쪽에 Preview가 옵니다. Scope에는 Compact가, Detail에는 Preview가 없습니다. 옆 창은 터미널이 넓을수록 넓어지고, 좁은 터미널에서는 초점이 있는 창이 보이지 않을 수 있습니다. 초점이 있는 창에 공간이 더 필요하면 터미널을 넓히세요.
- Scope. 같은 Git 공통 디렉터리를 공유하는 클론은 한 항목으로 묶어 표시합니다.
ALL을 고르면 상태 전체가 선택되고, 저장소 행을 고르면 그 저장소의 워크트리가 모두 선택됩니다. 저장소마다 ALL 행을 따로 두지는 않습니다. Run이 없는 워크트리는+N without Runs (Space)항목 아래에 접어 두며, Space를 누르면 그 목록을 펼치거나 접을 수 있습니다. 선택한 범위는 계속 보입니다. Git이 아닌 경로와 삭제된 경로도 계속 나열됩니다. Run에는 작업 공간인repoPath가 기록되며,commonDir,worktreePath,branch는 선택적으로 기록됩니다. - Runs. 선택한 범위의 Run이 최신순으로 나오며, 경과 시간, 걸린 시간,
요청 수(
✓GREEN,✗RED,!ERROR,?Human 대기,◐실행 중)가 붙고, 마지막에 Run의verify --comment가 남은 너비에 맞춰…로 줄여 나옵니다. 좁은 창에서는 부차적인 열이 빠지며, 코멘트가 가장 먼저 빠집니다. 범위로 Run을 거른 다음 페이지를 나눕니다. 마지막 Run에서 Down/j를 누르면 더 오래된 Run을 불러오고, 더 오래된 페이지의 첫 Run에서 Up/k를 누르면 더 새로운 페이지를 불러와 그 마지막 Run을 고릅니다. - Run tree. 파일을 다시 평가한 결과가 아니라, 선택한 Run의 저장된 정의, 기록된 증거, 현재
요청 상태로 구성한 트리입니다. 머리줄은 상태, 경과
시간, 개수를 보여 주며, 사용량은 토큰 합계만 보여 줍니다. 실행 중에는
validation pending을, 그다음 SATISFIED / NOT SATISFIED at Run end를 보여 줍니다. 이어서 오류, 대기 중인 Human 요청, 실행 중인 eval을 주의 항목으로 최대 세 줄까지 보여 주고, 나머지는+N more로 표시합니다. Run 행에서 Enter를 누르면 Detail이 열리며, 코멘트, 검증 결과와 충족되지 않은 최종 검증 요건, 요청 수와 오류, 대기 중인 작업과 실행 중인 작업, 시간과 예산, 실행·재사용 횟수, 실제 사용량과 재사용에 따른 절감량을 모두 확인할 수 있습니다. 검증 결과는 Run이 끝난 시점 그대로이고, 트리의 행은 이후의 Human 제출을 포함해 지금 상태의 요청을 보여 줍니다. 흐린*는 Run이 끝난 뒤 상태가 바뀐 행을 표시하며 파일이 바뀌었다는 뜻은 아닙니다. Artifact Detail에도At Run end필드가 남습니다.
Scope 배지와 헤더에는 주의가 필요한 항목 수가 같은 !N ✗N ◐N ?N 형식으로 나옵니다. ERROR와 RED인
요청, 아직 끝나지 않은 Run, 사람의 결정이 필요한 승인입니다. 이 수는 지금 보이는 Run 페이지가 아니라 전체 Run을 기준으로 셉니다. 한 Human 실행의 팔로워들은
대기 중인 승인 하나로 셉니다.
Artifact와 eval
eval마다 행이 하나씩 있습니다. Artifact 행에는 지금 보이는 eval 행의
통과 수/전체 수(passed/total)와 표시 우선순위가 가장 높은 상태가 요약됩니다. [file]은 파일 Artifact를 표시하며, 그 대상
경로와 태그는 Detail의 Technical 섹션에 있습니다. basis Artifact는 행 하나로 나옵니다.
◇ engine basis. Artifact 행에는 그 부분의 상태도 반영됩니다.
부분이 하나라도 끝나지 않았으면 그 Artifact도 끝나지 않은 것으로 표시하고, 그 부분을 parts: 뒤에
나열합니다. 자기 eval이 없는 Artifact는 made of N을 보여 주거나, 끝나지 않은 부분을 pending: 뒤에
보여 줍니다. 별도의 관계 행이나 항상 표시되는 의존성 목록은 없습니다.
Artifact의 완료 여부는 eval의 상태와 상위 게이트의 충족 여부를 함께 보고 정합니다.
eval의 GREEN 결과를 재사용할 수 있어도, 그 Artifact는 통과 0개(예를 들어 0/1)로
done, but waits for X나 done, but blocked by X를 보여 줄 수 있습니다.
따라서 eval 행이 모두 GREEN이어도, 그 Artifact를 입력으로 쓰는 eval을 실행할 준비가 끝났다고 볼 수는 없습니다.
그 Artifact가 의존하는 상위 Artifact의 검증 요건도 충족되어야 합니다.
일부만 실행한 Run은 이 Run에 요청이 없는 eval에 대해 저장된 증거를 쓸 수
있습니다. 그 행에는 GREEN · saved result, not in this Run(또는 저장된 RED)이 나옵니다.
그 증거는 완료 개수와 게이트에 반영됩니다. 저장된 GREEN 결과로 입력의 검증 요건을 충족할 수 있고, 저장된 RED 결과가 있으면 그 입력을 쓰는 eval의 실행이 막힐 수 있습니다. 대시는 어느 쪽도 없다는 뜻입니다.
| 보기 상태 | 의미 |
|---|---|
✓ done | GREEN입니다. 실행했거나 재사용했습니다 |
○ PROVISIONAL | 실행했거나 재사용해 기준은 충족했지만, 의존하는 승인이 남아 있습니다(PROVISIONAL · sign-offs remain) |
✗ / ! failed | RED / ERROR |
◐ / ? / · in progress | 실행 중, Human 대기(맡은 사람과 함께), 실행 허가 대기, 백엔드 자리나 명시적 --jobs 상한 대기, 또는 실행에 합류 중인 상태입니다 |
… waits for X | 실행 중인 Run에서 X에 필요한 eval이 GREEN이 될 때까지 대기합니다 |
⊘ blocked by X | 상위의 RED나 막힌 eval 때문에 실행할 수 없습니다 |
○ / $ / - not run | Run이 끝날 때 X의 결과가 아직 나오지 않았거나, 증거가 오래되었거나, eval을 리뷰하지 않았습니다(○). 예산이 바닥났습니다($). eval에 요청도 저장된 증거도 없습니다(-) |
실행 중인 행과 Human 행은 굵은 글씨와 색으로 강조됩니다. 대기열에 있는 행에는 색이 있는 ·가 계속 표시됩니다.
대기 상태인 eval의 행과 일반 not-run 행은 흐리게 표시됩니다. 상위 eval이
ERROR이면 RED일 때처럼 막지 않고, 다시 시도해야 한다고 표시합니다. Run이 끝난 뒤에도
아직 처리되지 않은 Human 요청이 남아 있을 수 있습니다. 이 보기 상태는 저장된 요청 상태를 설명할 뿐,
JSON의 상태 이름을 바꾸지는 않습니다.
이 표시가 뜻하는 바는 Run이 승인과
추측 실행을 다루는 방식에 따라서도 달라집니다. 승인은 DEFERRED로 나오고 의존하는 작업은
승인된 것이 아니라 PROVISIONAL일 수 있습니다. 제출되지 않은 승인 요청이 있는 진행 중인
Run은 WAITING_HUMAN이며, RUNNING과 마찬가지로 진행 중인 상태이므로 조금 더 진한 파란색으로 표시됩니다.
남은 승인이 모두 제출되면 다시 RUNNING으로 표시됩니다. YELLOW로 끝난 Run은
그 승인만 남았다는 뜻입니다. 나중에 승인을 제출해도 Run 종료 때 기록한 판정은 바뀌지 않고 현재 요청에만
반영됩니다. --speculate에서는 상위 eval의 판정이 아직 나오지 않았어도 하위 eval이 READY이거나 실행 중일 수 있습니다. 이후 상위 eval의 결과가 RED/ERROR이면 추측 실행 중인 하위 작업의 실행이 차단되거나 취소됩니다.
eval의 대기 조건은 eval 의존성 규칙에 따라 정해집니다.
각 행은 게이트를 Artifact별로 묶어, 아직 검증 요건을 충족하지 못한 Artifact를 최대 두 개까지
완료 상태와 함께 보여 주고, 나머지 개수는 +N으로 표시합니다. 대기 중인 대상도 모두 다른 작업 때문에 실행이 보류된 상태라면 그 원인도 한 단계 더 보여 줍니다. 예를 들어 waits for cli … waiting (cli waits for code-style)입니다.
같은 순환에 속한 Artifact에는 모두 ↻ peer 표시가 붙습니다.
의존 관계에 따라 상위 Artifact부터 표시하되, 같은 순환에 속한 Artifact와 eval은
이름순으로 정렬합니다.
모두 done인 Artifact는 자동으로 접힙니다. 다른 Artifact는 직접 접지 않는 한
펼쳐진 채로 있으며, 새로 고쳐도 사용자가 펼치거나 접어 둔 상태는 그대로입니다. 새 Run을 열면 진행 중이거나
실패한 eval 중 첫 번째가 선택됩니다. h는 접고, l은 펼치고, Space는 선택한 트리 행을 접거나 펼칩니다.
선택한 eval의 상위 Artifact 행에는 ↑가 붙습니다. 충족되지 않았으면 밝게,
완료되었으면 흐리게 표시됩니다. 하위 Artifact는 강조하지 않습니다. 화면 밖의 대상은 ↑N above나
↑N below로 나옵니다. b를 누르면 그 Artifact 행을 검증 요건이 충족되지 않은 것부터 차례로 선택하며, Backspace를 누르면 원래 행으로 돌아갑니다. Artifact 행에서 b를 누르면 그 Artifact의 모든 eval이 의존하는 상위 항목을 한 목록으로 모아 차례로 고릅니다.
키와 마우스
| 키 | 동작 |
|---|---|
| Enter / → | 다음 단계로 갑니다. 트리 행에서는 Detail을 엽니다 |
o | 선택한 트리 행의 Detail을 엽니다 |
| ← / Esc | 한 단계 물러납니다. Esc로는 종료하지 않습니다 |
| Tab / Shift-Tab | Scope, Runs, 트리 사이를 순환합니다. Detail 안에서는 하위 영역을 전환합니다 |
↑/↓ 또는 j/k | 행을 고릅니다. Detail 안에서는 스크롤합니다 |
? | 도움말을 보여 줍니다. 보조 키 없이 누른 다음 키는 동작하지 않고 도움말을 닫습니다. 이때도 Ctrl-C는 종료하고 F2는 마우스 캡처를 켜고 끕니다 |
! | 이 Run의 다음 ERROR, RED, 또는 대기 중인 Human eval로 이동합니다. 끝에 닿으면 처음으로 돌아갑니다 |
r | Scope, Runs, 트리에 초점이 있으면 새로 고칩니다. 내가 맡았고 진행 중인 작업이 없는 Human Detail에서는 RED를 고르며, 읽기 전용 Detail은 새로 고치지 않습니다 |
q / Ctrl-C | 편집 중도 작업 실행 중도 아니면 q로 종료합니다. Ctrl-C는 진행 중인 담당 지정·해제, 도구 실행, 판정 제출이 있으면 취소를 요청하고, 없으면 종료를 시작합니다 |
| F2 | 터미널 텍스트 선택을 위해 마우스 캡처를 켜고 끕니다 |
Detail에서 !는 다음 주의 항목의 Detail을 엽니다. Human 리뷰 작업을 하려면 Detail에 초점이 있어야 합니다. 초점 잠금, Esc와 Close 동작, 유지되는 초안은
공용 Human Detail에서 다룹니다.
항목을 클릭하면 그 항목이 선택되고 초점이 옮겨 갑니다. 더블 클릭은 트리 행의 Detail을 엽니다. peek를 클릭하면 Full로 엽니다. Human Detail에서는 Tools에 초점이 있을 때 선택한 도구를 클릭하면 실행합니다. 첫 클릭은 Tools에 초점만 옮깁니다. 휠은 초점을 옮기지 않고 포인터 아래의 창을 스크롤합니다. 트리에서는 선택이 아니라 보기 영역을 움직이므로, peek에 표시되는 eval은 바뀌지 않습니다. 이동 경로의 각 항목은 클릭할 수 없습니다. 터미널의 bracketed paste는 마우스 캡처 설정과 관계없이 동작합니다.
Detail
트리에 초점이 있으면 Detail은 j/k로 고른 행에 따라 바뀌는 peek(간략 보기)입니다. Outcome과
그 eval을 실행하기 전에 결과가 나와야 하는 Artifact를 보여 줍니다. 실행 중인 Agent의 peek는 대화 기록의 마지막
줄도 보여 줍니다. Enter나 →를 누르거나 peek를 클릭하면 모달 대신 Full Detail이 열립니다.
Detail에서 나가면 Full 보기가 닫히고 다시 peek가 나옵니다.
읽기 전용 섹션은 이 순서로 나옵니다. Outcome → Waits for → What → Provenance
→ Technical. Outcome은 판정이나 오류를 먼저 보여 줍니다. What에는 지시문과
원시 결과가 있습니다. Provenance에는 작업, 사용량, 예산, 시간이 있습니다. Technical에는
식별자와 해시가 있으며, 접힌 채로 시작하며, t로 펼치거나 접을 수 있습니다. Waits for는 트리와 같은
상위 Artifact를 그 완료 상태와 참조 출처와 함께 나열하며,
w를 누르면 해당 Artifact에서 대기 중인 eval이 표시되거나 숨겨집니다. 빈 섹션은 빠집니다. Tab으로 섹션과 증거 사이를 전환하고, ↑/↓와 PgUp/PgDn으로 초점이 있는 영역을 스크롤할 수 있습니다.
Home을 누르면 Monitor에서는 초점이 있는 읽기 전용 섹션이나 Runtime 증거의 맨 위로 이동하고, 단독 Review에서는 읽기 전용 섹션의 맨 위로 이동합니다.
Detail에 표시되는 내용은 eval 종류에 따라 다릅니다.
- Agent: 실시간 대화입니다. 실행 중인 리뷰의 대화와, 재사용한 결과를 만든 원래 로컬 리뷰의 대화를 포함합니다. ↑/PgUp을 누르면 자동 스크롤이 멈춰 앞 내용을 읽을 수 있으며,
Home을 누르면 처음으로, End를 누르면 최신 메시지로 이동합니다. Monitor는
Top, Bottom, Details 버튼도 제공하며, Bottom을 누르면 자동 스크롤이 다시 시작됩니다. 어느 UI에서든 Space나 Enter를 누르면 화면에 보이는 도구 묶음이 펼쳐지거나 접힙니다. 묶음을 펼치면 도구 이름, 대상, 기록된 상태가 나옵니다. Monitor에서는
도구 묶음의 제목을 클릭해도 펼치거나 접을 수 있습니다. 어느 UI에서든
d를 누르면 저장된 결과와 세부 정보 화면, 대화 기록 사이를 오갑니다. Esc를 누르면 Monitor에서는 저장된 세부 사항에서 대화 기록으로 돌아가고, 단독 Review에서는 Detail에서 나가 목록으로 돌아갑니다. provider가 공개 reasoning 요약을 주는 경우 그 요약만 나오며, 비공개 reasoning은 숨겨진 채로 있습니다. 대화가 없거나 원격에만 있으면 이 화면에서 볼 수 없는 이유를 안내합니다. 저장된 기록 전체를 보려면session show --json을 실행하세요. 스트리밍이 끝나면 수신 중이던 텍스트가 최종 텍스트로 바뀌고, 도중에 중단된 출력에는 표시가 붙습니다. 창 크기를 바꿔도 읽던 위치가 유지되며, 긴 대화도 빨리 열리고 처음까지 스크롤할 수 있습니다. 리뷰가 끝난 뒤session send로 이어서 주고받은 답변도 읽을 수 있습니다. - Runtime: Detail의 안쪽 내용 폭이 90열 이상(바깥 테두리를 포함해 92열)이면 저장된 stdout/stderr, 종료 코드, 캡처한 출력이 잘렸는지 여부가 섹션 옆에 나오며, 창이 더 좁으면 이 정보를 섹션 아래에 표시합니다. 아직 실행 중인 작업, 시간 초과/취소된 결과, 원격 저장소의 요약 정보만 있는 결과는 로그를 볼 수 없다고 표시하며, 실행 중인 작업의 로그를 실시간으로 보여 주지는 않습니다.
- Human: 요청 담당 지정, 도구 실행, 판정 입력, 리뷰 화면 나가기에는
공용 Human Detail 컨트롤을 쓰세요. Monitor에서만 다른 점은
완료된 결과를 열어 둔다는 것입니다. 양식을 편집 중이 아니고 실행 중인 작업도 없으면
q로 종료하고,?로 Monitor 도움말을 보며,!로 다음 주의 항목을 엽니다.
제출한 뒤 팀 리뷰 저장소에 게시하는 데 실패하면, Detail에는 다시 제출하라는 안내 대신 완료된 로컬 결과와 게시 실패가 표시됩니다. 터미널 설정은 종료할 때 복원됩니다. Monitor와 Review는 Run이 바뀌면 늦어도 5초 안에 자동으로 갱신됩니다.
새로 고침에 실패하면 시각이 찍힌 read failed at … 알림이 기록됩니다. Monitor와 Review 목록에는 마지막으로 읽어 온 데이터가 남으므로, 보이는 요청, 결과, 담당 정보가 현재 상태와 다를 수 있습니다. 단독 Review에서 Human이 아닌 요청의 Detail을 보고 있으면
목록으로 돌아갈 때까지 알림이 나타나지 않을 수 있고, 그 Detail을 다시 읽지 못하면 이전에 보이던 내용이
지워질 수 있습니다. Review에서는 요청 목록으로 돌아가
r을 누르고, Monitor에서는 Scope, Runs, 트리에서 새로 고침을 요청하세요.
읽기에 성공하면 실패 알림이 지워집니다.
저장된 Run 하나를 읽을 수 없거나 그 기록 안에 모순이 있는 경우는 다르게 처리합니다. Monitor는 read failed 알림을 띄우지 않고 그 Run의 오류를 목록에 보여 주며, 그 Run의 트리는 열지 않습니다. 다른 Run은 계속 쓸 수 있습니다.
Monitor가 열려 있는 동안 백업을 복원하는 등으로 상태 디렉터리가 교체되면, Monitor는 진행 중인 Human 작업을 취소하고, Detail을 닫고, 저장하지 않은 초안을 버립니다. 이 초안은 교체된 상태로 넘어가지 않습니다.