검증기가 통과 여부가 아니라 수정 목록을 돌려준다

에이전트에게 붙이는 검증기는 보통 "통과 / 실패"를 말한다. 실패하면 스택 트레이스나 자유 텍스트가 나오고, 에이전트는 그걸 읽고 추측으로 다시 시도한다.

Archify의 검증기는 다르게 실패한다.

return stable rule codes, the exact subject, measured evidence, and only supported repair controls instead of a Node stack or an unstructured retry guess

안정적인 규칙 코드, 정확한 대상, 측정된 증거, 그리고 지원되는 수정 수단만. 다이어그램 도구의 얘기지만, 에이전트에 검사를 붙이는 사람이라면 여기서 가져갈 게 있다.

출처: github.com/tt-a1i/archify (MIT)

확인된 것

저장소에서 직접 확인한 것만 적는다.

코드베이스를 분석하거나 말로 설명하면 탐색 가능한 다이어그램을 만든다. 아키텍처·워크플로·시퀀스·데이터 흐름·생명주기 다섯 유형. Cursor·Claude Code·Codex CLI·OpenCode에서 쓴다. 2026-04-15 생성(5개월), 별 71,415, 포크 4,804, 열린 이슈 165. MIT.
파이프라인은 생성 → 검증 → (선택) 프리뷰 → 전달 → 반복이다. 에이전트가 타입 있는 JSON IR을 만들고, 검증기가 그걸 검사하고, Node 렌더러가 HTML/SVG로 낸다.
교체 조건이 명시돼 있다.

Atomic validation before delivery — schema, layout, HTML/SVG, route, and label-to-route clearance checks must all pass before a showcase artifact replaces the last known good output.

프리뷰도 같은 규칙이다. 저장이 불완전하거나 유효하지 않으면 직전의 검증된 다이어그램을 그대로 보여준다.
수정 라운드가 2회로 묶여 있다. 각 진단 대상의 supportedFixes만 적용하라고 적혀 있다.
위상을 지어내지 않는다고 못박는다 — 포커스, 상하류 추적, 경로, 역할 비교, 스토리는 작성된 노드와 관계를 재사용하고 없는 연결이나 런타임 영향을 주장하지 않는다. 근거가 필요한 노드는 SRC n으로 표시하고 하나의 공개 커밋에 핀된 파일·줄 범위를 연다.
범위 밖을 적어뒀다.

Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.
로케일은 en과 zh-CN이다. 본문은 요청한 언어를 보존한다고 쓰지만, UI·범례·상태 문구는 둘 중 하나다.

판단

1. 검증기의 출력은 사람이 읽을 에러가 아니라 에이전트가 실행할 목록이어야 한다

이게 이 저장소에서 가장 이전 가능한 설계다.

에이전트에 검사를 붙여본 사람은 안다. 검사가 실패하면 에이전트는 에러 메시지를 해석한다. 해석은 틀릴 수 있고, 틀린 해석으로 엉뚱한 곳을 고치고, 그 수정이 다른 검사를 깨뜨린다.

Archify는 그 해석 단계를 없앤다. 규칙 코드와 대상과 적용 가능한 수정 수단의 목록이 나온다. 에이전트가 고를 수 있는 선택지가 유한해지고, 그러면 창의적으로 틀릴 여지가 준다.

9월에 다이어그램 스킬을 보면서 검증 스크립트가 진짜 알맹이라고 썼는데, 여기는 한 걸음 더 갔다. 검사가 판정만 하는 게 아니라 수정을 안내한다.

→ 오늘 적용할 것: 내 CI나 훅이 에이전트에게 돌려주는 메시지를 한 번 읽어봐라. 사람용 문장이면 에이전트는 그걸 추측으로 읽는다. 규칙 이름 + 위치 + 허용된 수정 방법으로 바꾸는 게 그다음 단계다.

그리고 수정 라운드가 2회로 묶여 있다는 점도 같이 본다. 자동 수정 루프는 무한히 돌며 돈을 쓰거나 점점 이상해지는 실패 모드가 있다. 상한을 문서에 적어둔 건 그 실패 모드를 알고 있다는 뜻이다. 내 루프에 상한이 있는가.

2. 통과해야만 기존 파일을 대체한다

원자적 교체는 오래된 기법이지만, 에이전트가 파일을 쓰는 환경에서 다시 중요해진다.

에이전트는 반쯤 완성된 결과를 자주 만든다. 그게 멀쩡한 기존 파일을 덮으면 원본과 결과를 동시에 잃는다. 여기는 후보를 같은 디렉터리에 만들고, 전부 통과한 뒤에만 원자적으로 교체한다. 프리뷰도 실패하면 직전의 검증본을 계속 보여준다.

→ 이건 다이어그램과 무관하게 규칙으로 쓸 만하다. 에이전트가 산출물을 쓰는 모든 경로를 "생성 → 검증 → 통과 시에만 교체"로 바꾼다. 순서 하나로 "돌리다 말았더니 파일이 망가졌다"가 사라진다.

3. 지어내지 않겠다고 적은 것이 다이어그램에서는 특히 중요하다

다이어그램은 틀려도 그럴듯해 보인다. 존재하지 않는 화살표 하나가 그림 안에서는 자연스럽고, 보는 사람은 그걸 검증하지 않는다. 코드는 실행하면 틀린 게 드러나지만 그림은 아니다.

그래서 "작성된 노드와 관계만 재사용하고 위상을 발명하지 않는다"는 문장이 장식이 아니다. SRC n 표시로 하나의 커밋에 핀된 파일과 줄 범위를 여는 것도 같은 맥락이다 — 그림에서 코드로 되돌아갈 수 있게 해둔 것.

광고 운영 에이전트를 보면서 "조인이 안 되면 비워두고 메우지 않는다"를 좋은 신호로 꼽았는데, 같은 성질이다. LLM의 기본 성향은 빈칸을 채우는 쪽이고, 그걸 막는 건 프롬프트가 아니라 파이프라인이다.

4. 범위 밖 목록은 읽고, 별 개수는 조심해서 읽는다

Mermaid 자동 파싱, 범용 자동 레이아웃, 호스팅 공유, WYSIWYG 편집이 의도적으로 범위 밖이라고 적는다. 안 하는 것을 적어둔 저장소는 평가하기 쉽다.

별 개수는 다르게 읽어야 한다. 5개월에 71,415개다. 그런데 3주쯤 전에 본 다이어그램 스킬도 40,648개였다. 같은 영역에 큰 저장소가 둘 있다는 사실에서 읽을 것은 **"이게 좋은 도구다"가 아니라 "이 자리에 수요가 크다"**까지다.

수요가 크다는 건 대체재가 계속 나온다는 뜻이기도 하다. 그러니 둘 중 무엇을 고르느냐보다, 두 저장소가 공유하는 설계(검증기를 파이프라인에 박아두는 것)를 내 것으로 만드는 쪽이 오래 간다.

모르는 것

직접 설치해 돌려보지 않았다. 저장소 README와 API 메타데이터를 읽은 결과다.
두 번의 수정 라운드로 실제 몇 퍼센트가 통과하는지 수치가 없다. 자동 수정의 성공률이 이 설계의 값어치를 정하는데, 그 숫자가 비어 있다.
SRC n 증거 기능의 정확도를 모른다. 커밋에 핀된다는 서술까지만 확인했다.
생성에 드는 토큰 비용 수치가 없다. 대형 저장소를 분석할 때 얼마가 드는지 모른다.
큰 코드베이스에서 구조 분석의 품질과 한계를 확인하지 못했다.
로케일이 en과 zh-CN뿐이다. 본문 내용은 요청한 언어를 보존한다고 적혀 있지만 UI·범례·상태 문구는 둘 중 하나로 나온다. 한국어로 결과물을 공유할 생각이면 확인하고 들어갈 항목이다.