archwhere가 AI 코딩 에이전트의 변경을 구조도로 보여준다

archwhere는 AI 코딩 에이전트가 만든 PR과 작업을 선언형 아키텍처 지도에 연결하는 도구다. GitHub를 통해 에이전트와 대화하고, 어떤 구성 요소가 바뀌었는지와 보안 관련 변경, 검토가 필요한 PR을 한곳에서 확인할 수 있다.

archwhere 저장소는 의존성 없이 JSON 파일 하나로 아키텍처 모델을 관리한다. 제작자는 사람이 모델을 계속 갱신해야 하는 기존 아키텍처 도구와 달리, 에이전트가 병합 전에 지도를 갱신하도록 설계했다고 설명한다. SKILL.md가 에이전트에 작업 방식을 안내하며, archwhere check는 지도가 오래됐거나 파일이 매핑되지 않은 경우 CI를 실패시킨다.

저장소의 빠른 시작 명령은 다음과 같다.

npx archwhere init

초기화는 저장소의 디렉터리 구조, package.json 워크스페이스, 가져오기 관계를 바탕으로 모델 초안을 만든다. 구성 요소 종류도 추정하며, PR 댓글 워크플로와 에이전트 리스너 두 개를 작성한다. 초안은 처음부터 검사를 통과하도록 만들어지고, 사용자는 빈 파일 대신 이름과 분류를 다듬을 수 있다. 초기화 과정은 에이전트가 저장소를 살펴 모델을 보완하도록 전달할 프롬프트도 출력한다.

일상적으로는 작업 트리나 브랜치가 건드리는 구성 요소를 확인하고, 검사를 실행하거나, 최근 변경이 잦았던 구성 요소를 살필 수 있다. --fix는 매핑되지 않은 파일을 가장 가까운 구성 요소에 포함한다.

npx archwhere # what is my working tree touching?
npx archwhere --base origin/main # what does this branch touch?
npx archwhere check # CI guard: model valid, no file unmapped, no stale glob
npx archwhere check --fix # adopt unmapped files into the nearest component
npx archwhere heat # which components churned most in the last 30 days?
npx archwhere doc --out ARCHITECTURE.md
npx archwhere mission # the UI at http://localhost:4610

GitHub Action을 추가하면 PR마다 변경된 구성 요소와 종류, 파일, 보안 표시, 변경된 구성 요소를 강조한 시스템 지도가 댓글로 달린다. PR에서 모델에 없는 파일이 추가되면 댓글이 가까운 구성 요소에 파일을 포함하거나 새 구성 요소를 만드는 패치를 제안한다. archwhere check --fix로 제안을 적용할 수 있다.

npx archwhere mission은 로컬 인터페이스를 실행한다. 보안 항목, 막힌 결정, 주의가 필요한 PR, 병합 준비가 된 PR을 보여주는 주의 영역이 있고, 구성 요소를 눌러 GitHub 이슈 기반 대화를 열 수 있다. 에이전트의 답변은 지도에 표시된다. 인터페이스에는 구조, 변경, 변경 빈도, 런타임 상태를 보는 네 가지 렌즈가 있다. 런타임 상태는 RUNTIME_URL이 가리키는 엔드포인트에서 가져오며, 병합 버튼은 사용자의 토큰을 사용하고 에이전트는 병합하지 않는다.

에이전트와 직접 통신하는 대신 GitHub를 중계 수단으로 쓴다. Claude는 초기화 과정에서 작성되는 agent-reply.yml과 Claude GitHub App을 통해 응답할 수 있다. API가 있는 에이전트는 agent-webhook.yml이 스레드 이벤트를 AGENT_WEBHOOK_URL로 보내도록 설정할 수 있고, 이미 GitHub를 살피는 에이전트는 component:* 라벨이 붙은 이슈를 확인하면 된다. 인터페이스가 덧붙일 멘션은 arch/mission.config.json의 agentMention으로 지정하며, AGENT_MENTION 환경 변수로 덮어쓰거나 빈 문자열로 끌 수 있다.

모델에는 core, security, feature, infra, product, ops, docs 종류를 둘 수 있다. flows는 구성 요소 위에 프로세스 흐름을 표현하는 C4 스타일 동적 뷰다. 예시 모델을 확인할 수 있다. npx archwhere ir은 모델을 Archify IR로 변환하며, 이를 Archify CLI로 렌더링할 수 있다.

에이전트용 지침은 SKILL.md에 있다. 작업 전에 지도의 위치를 확인하고, 모듈을 추가할 때 모델을 확장하며, 사용자에게 보이는 과정이 바뀌면 흐름도 갱신하고, archwhere check가 통과하도록 하라는 내용이다. Claude Code의 에이전트 스킬로 쓰거나 다른 에이전트 지침에 붙여 넣을 수 있다. 제작자는 전체 온보딩이 20분 이내라고 설명하며, 단계별 안내를 문서에 공개했다. 라이선스는 MIT다.