Transcript
00:00:00코딩 에이전트에게 리포지토리 매핑을 시키면 존재하지도 않는 Kafka, Redis 또는 API 게이트웨이가 튀어나오곤 합니다.
00:00:07다이어그램은 그럴싸해 보이지만 놓치는 부분이 아주 많죠.
00:00:10여기 에이전트가 직접 그림을 그리지 않는 도구인 Archify가 있습니다.
00:00:14에이전트가 타입이 지정된 그래프를 출력하면 Archify가 이를 검증한 뒤 다이어그램을 렌더링합니다.
00:00:19어쩌면 아키텍처를 시각화하는 가장 좋은 방법 중 하나일지도 모릅니다.
00:00:23직접 확인해 보겠습니다.
00:00:30사실 우리 모델은 다이어그램을 직접 그리도록 내버려 두면 안 됩니다.
00:00:33Archify의 작동 방식은 시스템을 구조화된 타입의 JSON으로 기술하는 것입니다.
00:00:37이 JSON이 검증을 거친 후에야 로컬 컴파일러가 최종 HTML로 변환해 줍니다.
00:00:42그래프가 유효하지 않으면 곧바로 실패 처리됩니다.
00:00:45이것이 바로 Archify입니다. Cloud Code, Cursor, Codex에 직접 연동되기 때문에 몇 달 만에 4만 4천 개의 스타를 받았죠.
00:00:53그래서 직접 테스트해 보려고 합니다.
00:00:54Archify를 설치하고 특정 리포지토리에 적용한 뒤 아키텍처에 관한 질문 하나에 답하게 만들겠습니다.
00:01:00그런 다음 이 결과를 PR에 실제로 사용할 수 있는지 살펴보겠습니다.
00:01:03물론 이걸 절대 쓰지 말아야 할 유스케이스도 몇 가지 있는데, 곧 자세히 알아보겠습니다.
00:01:08작업 흐름을 빠르게 만들어 주는 코딩 도구를 좋아하신다면 구독해 주세요.
00:01:11유용한 영상들이 계속 업로드됩니다.
00:01:13자, 설치는 여기 있는 명령어 단 한 줄이면 끝납니다.
00:01:17그리고 이건 제가 따로 설정하는 앱이 아닙니다.
00:01:19실제로는 에이전트 스킬이죠.
00:01:22설치하고 나면 편집기나 워크플로를 바꿀 필요 없이 앞서 말한 Cloud Code 등에서 동일한 스킬을 그대로 사용할 수 있습니다.
00:01:28편집기나 워크플로를 바꿀 필요 없이 그대로 쓸 수 있죠.
00:01:32이제 제대로 된 작업을 던져줄 수 있습니다.
00:01:34이 리포지토리의 전체 아키텍처를 그려달라고 요청하진 않을 겁니다.
00:01:37그것도 나쁘진 않겠지만요.
00:01:39결국 쓸모없는 쓰레기 정보만 잔뜩 돌아올 뿐입니다.
00:01:42그래서 딱 하나의 명확한 질문을 던지겠습니다.
00:01:45Archify를 사용해 아키텍처 다이어그램을 노드 8~12개 정도로 만들어줘.
00:01:49이 서비스에서 캐시 미스(cache miss)가 발생하면 어떻게 되나?
00:01:52이 리포지토리에 실제로 존재하는 상자만 포함할 것.
00:01:54컴포넌트를 증명할 수 없으면 생략할 것.
00:01:58자체 완결된 HTML로 전달할 것.
00:02:00이런 식의 하나의 계획, 하나의 질문이죠.
00:02:02대략 8개에서 12개 사이의 노드로요.
00:02:04에이전트에게 전체 코드베이스를 매핑하라고 시키면 과연 복잡함이 줄어들까요,
00:02:08아니면 이해하기 더 어려워질까요?
00:02:10자칫하면 제 리포지토리 트리를 단순한 순서도로 바꾼 꼴이 되어버립니다.
00:02:14에이전트는 아키텍처를 JSON으로 작성합니다.
00:02:16그러면 Archify가 이를 검증하죠.
00:02:18지금 여기서 보여드리는 것처럼 검증 과정만 따로 직접 실행할 수도 있습니다.
00:02:23이 기능은 정말 멋지고 유용하다고 느꼈습니다.
00:02:27노드에는 커밋과 특정 라인 범위에 연결된 리포지토리 증거(evidence)도 포함될 수 있습니다.
00:02:32그런 증거가 없다면, 답변에서 아무리 그럴듯하게 들리더라도 해당 노드에는 SRC 배지가 부여되지 않습니다.
00:02:37답변에서 그럴듯하게 들려도 말이죠.
00:02:39좋습니다.
00:02:39이게 대체 어떻게 도움이 되는 걸까요?
00:02:41그냥 일반적인 아키텍처 다이어그램처럼 보이는데요.
00:02:43물론 그렇지만, 꼭 그런 식으로만 쓸 필요는 없습니다.
00:02:46이 안에서 실제 서비스를 검색할 수 있거든요.
00:02:50특정 서비스를 클릭하면 업스트림과 다운스트림에 무엇이 있는지 즉시 확인할 수 있습니다.
00:02:55그런 다음 해당 경로를 따라 시스템 내의 캐시 미스 경로를 추적해 볼 수 있죠.
00:02:59따라서 10개의 화살표를 멍하니 보며 머릿속으로 역추적하느라 애쓸 필요 없이 이제 직접 따라가며 볼 수 있습니다.
00:03:05있습니다.
00:03:06그뿐만 아니라 내보내기 기능도 지원합니다.
00:03:08PNG로 복사하거나 1200x36 크기의 공유 카드로 생성할 수 있죠.
00:03:13여기서 진짜 차이점은 기존의 Mermaid와 다르다는 점입니다.
00:03:17Mermaid 같은 도구는 보통 눈으로 읽기만 하는 용도죠.
00:03:20하지만 이건 질문을 던지고 상호작용할 수 있는 대상입니다.
00:03:23부실한 구조를 숨기는 데 모션이 쓰이는 게 아니라, 다이어그램을 정적 이미지로 내보내도 핵심 의미는 그대로 살아남습니다.
00:03:28의미가 그대로 살아남죠.
00:03:31그리고 어쩌면 더 유용할 수도 있는 두 번째 유스케이스가 있습니다.
00:03:35무엇일까요?
00:03:36바로 코드 리뷰입니다.
00:03:38변경 작업이 일어나기 전의 시스템 상태가 이렇다고 해보죠.
00:03:41여기에 기존 재시도 워커(retry worker)를 추가합니다.
00:03:44에이전트에게 엉뚱한 걸 지어내지 말고 아키텍처를 업데이트하라고 지시할 수 있습니다.
00:03:49그러면 Archify는 검증된 두 개의 스냅샷을 비교하여 추가, 삭제, 이동 및 경로 변경 사항을 파악해 냅니다.
00:03:54따라서 단순히 생성된 다이어그램 두 개를 보는 대신 무엇이 실제로 바뀌었는지 정확히 볼 수 있습니다.
00:03:59인터페이스는 여전히 그냥 채팅창일 뿐입니다.
00:04:02하지만 이 아키텍처를 다음 에이전트 세션까지 유지하고 싶다면 JSON을 커밋하면 됩니다.
00:04:07현재 단계에서 Archify를 가장 쉽게 이해하는 방법은 다음과 같습니다.
00:04:11시스템 맵을 위한 HTML 가상 머신(VM) 관점에서, 코딩 에이전트는 프런트엔드입니다.
00:04:15JSON은 중간 표현(intermediate representation)이고요.
00:04:19HTML은 컴파일된 결과물입니다.
00:04:21그리고 이 중간 레이어가 정말 많은 역할을 해내고 있죠.
00:04:24JSON은 엄격한 스키마를 따릅니다.
00:04:26알 수 없는 필드가 들어가면 검증에 실패합니다.
00:04:28또한 5가지 다이어그램 모드가 있습니다.
00:04:30아키텍처, 워크플로, 시퀀스, 데이터 흐름, 라이프사이클 모드가 있죠.
00:04:34하지만 가장 흥미로운 결정 중 하나는 모델이 제어하지 않는 부분입니다.
00:04:38바로 레이아웃입니다.
00:04:39모델은 시스템을 기술할 뿐입니다.
00:04:41모든 상자가 정확히 어디에 배치될지 모델이 직접 결정하지는 않습니다.
00:04:44그들도 자동 학위 레이아웃을 적용한 테마형 Mermaid를 시도해 본 적이 있습니다.
00:04:48하지만 일반 Mermaid보다 나을 게 없었죠.
00:04:51또한 검증은 실패 시 차단(fail-closed) 방식으로 작동합니다.
00:04:54잘못된 JSON이 그럴듯한 예쁜 다이어그램으로 둔갑하는 일은 절대 없습니다.
00:04:58진단 정보, 규칙 코드, 지원되는 수정 방안 등이 제공됩니다.
00:05:02자, 이 모든 걸 통틀어서, 아키파이를 쓰지 않을 만한 상황도 짚어볼게요.
00:05:06README 파일 안에 직접 다이어그램을 넣어야 한다면 아마 아닐 겁니다.
00:05:10시간이 좀 걸릴 수 있죠.
00:05:11GitHub은 이걸 렌더링하지만,
00:05:12Archify HTML은 그렇지 않거든요.
00:05:15Archify는 훨씬 더 다른 성격의 문제를 해결하고 있습니다.
00:05:18이미 작업 루프 안에 에이전트가 존재합니다.
00:05:20그 에이전트가 아키텍처 산출물을 만들어내죠.
00:05:23PR에 포함될 수도 있고,
00:05:25설계 검토 문서에 들어갈 수도 있습니다.
00:05:27바로 이 지점에서 검증된 출력이 중요해지기 시작합니다.
00:05:30전반적으로 이 도구에서 마음에 드는 점이 아주 많습니다.
00:05:32우리가 매일 이미 사용하고 있는 도구들 속에서 동작하니까요.
00:05:35출력물을 외부로 내보낼 수도 있습니다.
00:05:38리포지토리 증거 덕분에 실제로 무엇을 확인해야 할지 구체적인 근거가 생깁니다.
00:05:41또한 아키텍처가 구조화되어 있어서 시간이 지나도 내용이 제멋대로 바뀌지 않고 계속 수정해 나갈 수 있습니다.
00:05:46시각적으로도 꽤 괜찮아서 Figma나 기타 다른 도구로 이걸 다시 그려야겠다는 생각이 들지 않을 정도입니다.
00:05:53하지만 그렇다고 해서 Archify가 여러분의 아키텍처를 온전히 알고 있는 것은 아니라는 점을 명심해야 합니다.
00:05:58그래프가 완전히 유효하더라도 여전히 잘못된 시스템을 묘사하고 있을 수 있습니다.
00:06:02결국 직접 읽고 확인해야죠.
00:06:03아시다시피 성능이 나쁜 모델은 실행은 되지만 여전히 엉망인 JSON을 대충 만들어내기 일쑤입니다.
00:06:08그리고 다이어그램이 최종적으로 들어갈 곳이 README라면 여전히 Mermaid가 더 나을 수 있습니다.
00:06:13Archify를 쓸 때는 JSON과 HTML을 함께 커밋하거나 이미지를 내보내게 되니까요.
00:06:18그리고 여기서 절대 피해야 할 실수가 하나 있습니다.
00:06:21거대한 리포지토리를 지정하고 “전부 다 매핑해줘”라고 하지 마세요.
00:06:25결과가 어떻게 나올지 뻔히 짐작 가실 겁니다. 쓸모없는 쓰레기 정보만 잔뜩 보게 될 테니까요.
00:06:29하지만 그건 Archify의 결함이 아닙니다.
00:06:32그저 질문을 잘못 던진 것뿐이죠.
00:06:34이미 코딩 에이전트와 함께 일하고 있고, 나중에 자신이나 다른 사람이 참고할 다이어그램을 정기적으로 만든다면 이 도구는 아주 훌륭한 선택입니다.
00:06:42PR 리뷰나 설계 문서 작업이라면 저는 아마 이걸 사용할 것 같습니다.
00:06:47단순히 우리가 이미 가지고 있는 것(예: Mermaid)의 조금 더 예쁜 버전을 원한다는 이유만으로 이걸 설치하진 않을 겁니다.
00:06:52그리고 이 도구가 알아서 뭔가를 역공학해주기를 기대하지도 않고요.
00:06:55한번 써보려는 진입 장벽은 정말 낮습니다.
00:06:58npx 명령어 하나면 되고, 로컬에 Node만 있으면 되죠.
00:07:00무거운 모델 가중치 같은 것도 없습니다.
00:07:02제 M4 Pro 성능은 여기서 거의 상관도 없을 정도입니다.
00:07:05하지만 꼭 지켜야 할 규칙이 하나 있습니다.
00:07:07파일당 질문은 딱 하나씩만.
00:07:08다이어그램이 답하고 있는 질문이 무엇인지 명확하게 말할 수 없다면 다이어그램을 생성하지 마세요.
00:07:14BetterStack의 Josh였습니다.
00:07:15이와 같은 코딩 팁과 요령이 마음에 드셨다면 채널을 구독해 주세요.
00:07:19그럼 다음 영상에서 뵙겠습니다.
00:07:20그럼 다음 영상에서 뵙겠습니다.
Community Posts
No posts yet. Be the first to write about this video!
Write about this video