Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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이 없는 bundle Artifact를 참조한다면, 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가 REDdocs/matches-cli는 그대로 실행되고 판정도 바뀌지 않습니다.
core/tests가 REDcli/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 파일을 직접 생성해서 커밋하세요. 선언 찾기와 검사 규칙은 선언 검사에 있습니다.