inkboard/system-atlas

해결하는 문제

System Atlas는 오래되고 정적인 아키텍처 다이어그램의 문제를 해결합니다. 빠르게 "거짓"이 되는 수동 그림 대신, 단일 진실의 원천(데이터 파일)을 제공하여 인터랙티브한 등축도 시각화 맵과 구조화된 텍스트 문서(SYSTEM.md)를 자동으로 생성합니다. 이로 인해 시각적 및 텍스트 기반 시스템 아키텍처 표현이 항상 일치하며, 단일 편집으로 간편하게 업데이트할 수 있습니다.

작동 방식

이 도구는 데이터 기반 접근 방식으로 시스템을 매핑합니다:

1. 단일 진실의 원천: 모든 시스템 구조, 흐름, 결정은 data.mjs 파일에 정의됩니다.
2. 생성: 빌드 스크립트(build.mjs)가 이 데이터를 처리하여 두 가지 출력물을 생성합니다: 인터랙티브 탐색용 자체 포함형 atlas.html 파일과 문서용 SYSTEM.md 파일.
3. 인터랙티브 맵: 생성된 HTML 맵은 구조물 위로 마우스를 올리면 내용을 확인하고, 클릭으로 고정하며, 실행 단계로 탐색할 수 있습니다. 정보 과부하를 방지하기 위해 "진행형 노출 챕터"를 통해 시스템을 작고 관리 가능한 단위로 단계적으로 노출합니다.
4. 에이전트 통합: "에이전트 스킬"로 설계되어, AI 에이전트가 자연어 요청에 따라 아틀라스를 생성, 업데이트, 탐색할 수 있습니다.

대상 사용자

다른 사람들에게 복잡한 시스템 설계를 전달해야 하는 개발자 및 아키텍트, 안정적인 ID로 아키텍처 결정과 미해결 질문을 추적하고, 실제 코드베이스와 동기화된 문서를 유지하고자 하는 사람들을 위한 도구입니다.

주요 특징

• 인터랙티브 등축도 맵: 확대/축소 및 이동이 가능한 HTML 맵으로, 다양한 시스템 구성 요소(예: 브레인, 스토어, 게이트)에 따라 역할별 모양을 사용합니다.
• 텍스트 트윈: 자동으로 SYSTEM.md 파일을 생성하여 의사결정 테이블, 흐름 테이블, 질문 인덱스를 포함합니다.
• 진행형 노출: 시스템을 챕터 단위로 조직하여 구조와 데이터 흐름을 단계적으로 노출합니다.
• 검사 가능한 데이터 패킷: 실제 요청을 움직이는 점으로 시각화하고, 클릭하여 JSON 페이로드를 확인할 수 있습니다.
• 질문 추적: 안정적인 ID(Q-<code><n>)를 사용하여 피드백 라운드를 통해 미해결 및 해결된 아키텍처 질문을 추적합니다.