다이어그램 배치 검증과 라벨을 지키는 수리 - Archify

Archify는 에이전트가 쓴 JSON 명세를 검증한 뒤 대화형 HTML 다이어그램으로 만드는 스킬과 렌더러의 저장소다. 이 자료에서 재사용할 판단은 세 가지다. 검증 단계마다 증명하는 범위를 나누는 방법, 배치를 고칠 때 관계 라벨의 의미를 지키는 순서, 자동 진단을 따라 고치는 반복을 언제 멈출지다. 간격·선분 길이·노드 수 같은 고정 수치는 이 도구의 제작 규칙으로 원천에 남긴다.

원천과 확인 범위

  • 원자료: tt-a1i/archify. MIT 라이선스.
  • 확인 버전: main의 9e35d2b, commit 시각 2026-09-23 11:45:48 UTC, 패키지 버전 2.17.0-dev.1. 지속 갱신 저장소이므로 이를 최초 게시일로 해석하지 않는다.
  • 2026-09-28에 SKILL.md, 작성·전달 계약 문서, 상태 흐름·시퀀스 렌더러 설명서, 제품 원칙, 영문 README를 읽었다. 코드는 CLI 사용법, 글자 폭 추정, 뷰어 언어 목록, 브라우저 검사, 업데이트 확인 부분만 읽었다.
  • 실행하지 않았다. 아래 검증 동작은 문서와 코드에 적힌 계약이며, 결과물을 직접 만들어 확인한 것이 아니다.
  • 다이어그램 제작 흐름에 이 도구를 들일지 판단하려고 읽었다. 도구는 들이지 않고 아래 판단만 증류했다.

검증 단계마다 증명하는 범위를 나눈다

Archify의 전달 계약은 결과물에 대한 주장을 셋으로 나눈다.

  • 결정적 검사(deliver): 명세를 같은 폴더의 비공개 스냅샷으로 고정해 렌더링하고, 결과물 검사를 모두 통과할 때만 이전 결과물을 교체한다. 영수증에는 명세와 결과물의 SHA-256과 바이트 수를 남긴다.
  • 브라우저 증거(visual-check): 전달된 HTML을 다시 만들지 않고 Chrome을 DevTools 파이프로 띄워, 네 가지 화면 크기에서 넘침을 재고 두 크기에서 밝은·어두운 테마를 캡처한다. 이 영수증은 시각 검토를 항상 대기 상태로 남긴다.
  • 시각 검토: 사람이나 이미지를 읽을 수 있는 검토자가 실제 결과물을 보고 판정한다.

한 주장의 통과는 다른 주장을 뜻하지 않는다. 결정적 영수증에는 브라우저 증거도 시각 검토도 들어 있지 않고, 결과물을 실제로 보지 않았으면 시각 검토를 통과로 보고하지 않는다. 전달이 실패했는데 같은 경로에 이전 결과물이 남아 있으면 그 파일로 브라우저 검사를 돌리지 않는다. 그것은 거부된 후보가 아니라 이전 결과물을 재는 일이기 때문이다. 전달 계약

배치를 고칠 때 관계 라벨의 의미를 지킨다

관계선의 라벨은 의미 데이터로 다룬다. 라벨이 들어갈 틈이 모자라면 라벨 위치를 옮기고, 다음으로 선의 경로나 간격을 조정하고, 그래도 모자라면 뜻을 유지하는 범위에서 문구를 줄인다. 의미 있는 라벨을 지우는 것은 간격 수리가 아니다. 뺄 수 있는 말은 양 끝점이 이미 완전히 나타내고 프로토콜·동작·방향·동기/비동기 여부·경계를 넘는 방식을 담지 않은 것뿐이다. 처음부터 라벨 없이 그린 관계도 그 말이 왜 중복인지 설명해야 하며, 이것은 간격 수리가 아니라 작성 단계의 의미 선택이다.

간격은 중심 사이 거리가 아니라 상자 사이의 빈 틈으로 잰다. 폭 165px인 노드의 중심을 200px 떼어도 빈 틈은 35px뿐이다. 라벨이 들어갈 틈은 라벨이 가리는 폭에 여유 8px를 더한 값보다 커야 하며, 한글·한자 같은 전각 글자는 폭 계산에서 두 단위로 센다. 작성 계약의 간격과 라벨

자동 진단을 따라 고치는 반복과 멈출 조건

검증이 실패하면 스택 추적 대신 규칙 코드·대상·측정값·허용되는 수정 방법(supportedFixes)을 JSON으로 돌려준다. 에이전트는 진단된 대상만 고치고, 한 번에 진단된 배치 조정 하나만 적용한 뒤 다시 검증한다. 오류 수가 최솟값을 새로 경신하는 동안에만 계속하고, 연속 두 번 나아지지 않으면 멈춰 남은 진단을 그대로 보고한다. 고치는 순서는 명세 오류, 노드 겹침과 범위 이탈, 선의 노드 관통과 끝점 방향, 교차·모호한 통로·테두리를 따라 달리는 선·선 리듬, 라벨 간격이다. 시각 검토에 따른 수정도 최대 두 차례로 제한한다. SKILL.md, 수리 순서

선과 라벨의 배치 규칙

확인 버전의 검사 규칙은 다음 배치를 받아들이지 않는다. 수치는 이 도구의 제작 규칙이다. 실행 가능한 기하 규칙

  • 선이 관계없는 불투명 노드를 지나간다. 품질 수준과 관계없이 실패다.
  • 라벨이 다른 선을 가린다.
  • 발표용 품질(showcase)에서는 관계없는 선끼리 같은 직선 위에서 8px 이상 겹치는 것, 선분이 8px보다 짧거나 꺾인 사이의 선분이 16px보다 짧은 것도 실패다. 끝점을 공유하는 통로는 의미가 분명할 때만 허용한다.

끝점이 붙는 변은 방향 계약이라 첫 선분과 마지막 선분이 그 변에 수직으로 나가고 들어와야 한다. 묶음 테두리는 선이 지나가도 되는 경계지만, 긴 선이 구조 테두리를 따라 달리는 것은 허용하지 않는다.

대화형 기능도 작성한 사실에서만 나온다

제품 원칙은 초점, 도달 범위, 경로, 이야기 보기, 출처 링크, 영수증이 모두 작성했거나 검증한 근거에서 나와야 한다고 둔다. 명세에 없는 관계나 활동을 움직임으로 암시하는 그래프 데모를 피할 대상으로 꼽는다. 제품 원칙

도구로 들일 때 확인할 점

확인 버전 기준의 사실이다. 다시 판단할 때는 새 버전에서 확인한다.

  • 결과물은 뷰어를 포함한 HTML 한 파일이며, 예제 HTML은 파일당 약 810~820KB다. PNG·JPEG·WebP·SVG·WebM 내보내기는 뷰어의 내보내기 메뉴에 있고 CLI 명령에는 없다.
  • 뷰어 언어는 en과 zh-CN뿐이다. 다른 언어는 본문을 그 언어로 쓰되 뷰어 고정 UI와 기본 범례 문구가 영어로 남는다고 사용자에게 밝히게 한다. 한국어 뷰어 언어는 #458·#499로 열려 있었다. 글자 폭 추정은 한글 음절을 두 단위로 센다.
  • SKILL.md는 첫 결과물을 만든 뒤 업데이트 확인 스크립트를 실행하게 한다. README에 따르면 약 72시간 간격으로 고정 매니페스트를 조회하며 ARCHIFY_UPDATE_CHECK_DISABLED=1로 끈다.
  • 상태 흐름(lifecycle) 유형은 위 띠 5칸, 아래 두 띠 각 3칸의 고정 배치다. 설명서는 이 유형을 밀집한 상태 전이 그래프가 아니라 단계 지도로 쓰라고 한다.

증류와 연결

백링크

그래프 뷰

이 문서로 이어지는 주제