선언(.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 도구를 쓰세요. 명령은 사용자가 신뢰하는 로컬 코드로 보고 샌드박스 없이 실행합니다. 명령은 현재 사용자 계정의 권한으로 실행되므로, 그 계정에 허용된 작업은 모두 수행할 수 있습니다. 명령은 리뷰 대상인 입력을 바꾸면 안 됩니다. 부모 프로세스에서 일부러 분리해 실행한 프로그램은 명령이 끝난 뒤에도 계속 실행될 수 있습니다.