Architecture Explainer (아키텍처 설명기)
자체 포함된 HTML 파일 하나로 설명기를 생성합니다: 런타임, 토폴로지, 산문, 서체 및 스타일이 모두 인라인으로 포함되며 런타임에 네트워크 호출이 없습니다. 어디서든 호스팅하고, 오프라인에서 열고, 페이지에 <iframe>으로 삽입하거나 이메일에 첨부할 수 있습니다.
모델
하나의 토폴로지, 다양한 투영. 시스템은 한 번 전체 깊이로 작성됩니다. 나머지 모든 것은 단일 그래프에 대한 선택기일 뿐입니다 — 두 번째 다이어그램은 없습니다.
TOPOLOGY nodes + edges + metadata ← 작성하는 유일한 것
──────────────────────────────────────
PERSONA resolution policy — vocabulary, collapse depth, which facts surface
LENS concern overlay — which edges exist, which fact each node advertises
ERA past / present / planned — presence and status styling
BEATS narrative — camera, focus, prose, in sequence
런타임이 적용하고 절대 어겨서는 안 되는 두 가지 규칙:
- 색상은 렌즈에 속합니다. 노드 종류는 모양으로 전달됩니다 — 소스는 접힌 모서리, 저장소는 등뼈, 인간 단계는 그림, 게이트는 모따기. 종류별 색상 체계를 다시 도입하지 마십시오. 다이어그램이 무지개가 되어 렌즈 전환을 무의미하게 만듭니다.
- 가이드 투어가 없는 다이어그램은 완성된 것이 아닙니다. linter는 비트가 0개이면 빌드에 실패합니다. 이것이 이러한 다이어그램을 예쁘기보다는 자명하게 유지하는 규칙입니다.
워크플로우 — 순서대로 따르세요
1. 인터뷰. 시스템을 발명하지 마십시오.
가장 큰 실패 모드는 사용자가 설명한 적이 없는 그럴듯한 아키텍처를 생성하는 것입니다. 무엇이든 작성하기 전에 질문하십시오. 에이전트에 구조화된 질문 도구가 있다면 사용하십시오.
다음을 다루십시오:
- 계층. 상위 5~8개 단계 또는 그룹은 무엇입니까? 이것들이 L1 박스가 됩니다.
- 계층별 컴포넌트. 보여줄 가치가 있는 것만. "Postgres"는 박스이지만, 그 테이블은 아닙니다.
- 수명 주기. 하나의 대표적인 요청 또는 작업을 처음부터 끝까지 따라가 보십시오. 이것이 엣지를 생성합니다.
- 읽는 사람. 일반적으로 임원/아키텍트/엔지니어이지만 물어보십시오 — "클라이언트/우리 팀" 또는 "학생/실무자"일 수 있습니다.
- 관심 있는 사항. 데이터 흐름에 더해 2~4가지: 비용, 지연 시간, 신뢰 및 거버넌스, 실패 모드, 소유권, 보안. 각 렌즈는 고유한 엣지 또는 팩트가 필요합니다.
- 역사가 있는지. v0 → 현재 → 계획은 클라이언트 작업과 로드맵에서 가장 가치 있는 축입니다. 의미 있는 과거가 없다면 건너뛰십시오.
- 주장. 읽은 후 독자가 무엇을 믿어야 합니까? 이것이 비트가 됩니다. 사용자에게 주장이 없다면 설명기는 척추가 없는 것입니다 — 주장을 요구하십시오.
2. 기본 축 선택
깊이가 흥미로운 축인 경우는 드뭅니다. 다이어그램이 무엇을 위한 것인지 물어보십시오:
| 목적 | 기본 축 |
|---|---|
| 작동 방식 교육 | 시간 — 하나의 요청을 따라가는 비트 |
| 클라이언트/이해관계자 피치 | 시대 — 존재하는 것, 제안된 것 |
| 설계 검토, 위험 | 렌즈 — 실패 모드, 신뢰 경계 |
| 온보딩, 참조 | 깊이 — 계층, 그다음 컴포넌트 |
3. 스펙 작성
하나를 작성하기 전에 references/spec-format.md를 전체적으로 읽으십시오. 모든 선택적 필드가 포함된 완전한 노드/엣지/비트 참조입니다.
assets/runtime/specs/llm-eval.js를 작업 예제로 복사하십시오 — 모든 기능을 사용하며 모방하기 좋은 형태입니다. 새 스펙을 specs/<name>.js에 작성한 다음 src/spec.js가 이를 가리키도록 하십시오(한 줄 — 진입점과 linter 모두 이를 통해 읽습니다).
4. 빌드
먼저 assets/runtime을 작업 디렉토리에 복사하고 거기서 빌드하십시오. 설치된 스킬 폴더 내에서 npm install을 실행하지 마십시오 — 종종 공유되거나 심볼릭 링크된 설치 위치입니다.
cp -R <skill-dir>/assets/runtime ./explainer
cd explainer
npm install # 네트워크 필요; ~20초
npm run build # 먼저 스펙을 lint한 다음 dist/index.html 생성
lint 출력은 투영 수를 알려줍니다. 실패하면 스펙을 수정하십시오 — linter를 약화시키지 마십시오. linter가 적용하는 모든 규칙은 실제 다이어그램이 그것 없이 배송되어 더 나빴기 때문에 존재합니다. 각 규칙의 의미는 references/spec-format.md를 참조하십시오.
5. 시각적 확인 — 필수, 두 가지 폼 팩터 모두
이것은 가장 자주 건너뛰는 단계이면서 가장 결과가 큰 단계입니다. 레이아웃 수학은 간단하지 않으며 실패는 조용히 발생합니다: 잘린 레이블, 다섯 개의 박스를 통과하는 엣지, 빈 공간을 프레임하는 카메라. 보지 않고 완료되었다고 선언하지 마십시오.
node scripts/shots.mjs # 데스크톱 매트릭스 → shots/
그런 다음 직접 휴대폰 크기(390×844)로 스크린샷을 찍고 이미지를 열어 검사하십시오. 확인:
- 모든 페르소나 × 시대 조합이 겹침이나 잘림 없이 렌더링되는지.
- 각 렌즈가 실제로 그림을 변경하는지 — 두 렌즈가 동일해 보이면 엣지 세트가 잘못된 것입니다.
- 비트 프레이밍. 비트를 단계별로 진행하십시오. 각 비트는 빈 공간이나 전체 시스템이 아닌 보이는 컨텍스트와 함께 포커스를 프레임해야 합니다.
- 레이블. 잘린 것, 박스 위에 놓인 것이 없어야 합니다.
- 휴대폰. 한 열로 재배치, 100%에서 읽을 수 있음, 컨트롤이 넘치지 않음.
- 콘솔. 오류 0개, 샌드박싱된 iframe 내부 포함.
문제가 보이면 레이아웃 코드를 변경하기 전에 references/troubleshooting.md를 읽으십시오.
6. 전달
사용자에게 빌드된 dist/index.html을 제공하십시오. 파일이 자체 포함되어 있으며 호스팅, 삽입 또는 오프라인에서 열 수 있다고 알려주십시오.
Claude Code / Claude 앱만 해당.
SendUserFile로 파일을 보내십시오. 사용자가 다시 방문할 것(대부분의 설명기가 그렇습니다)이면create_artifact로도 저장하십시오.
양보할 수 없는 사항
- 모든 노드에는
why가 있습니다 — 박스가 무엇인지가 아니라 왜 존재하는지에 대한 한 문장. - 임원이 볼 수 있는 모든 것은 임원 수준의
detail을 임원 어휘로 가지고 있어야 합니다. - 최소 6개의 비트, 각각 실제 산문이 있어야 합니다. 얇은 비트는 슬라이드쇼를 만들 뿐 주장을 만들지 않습니다.
- ≤34개의 리프 노드. 그 이상이면 여러 설명기로 나누십시오.
- 빌드당 하나의 테마. 독자는 라이트/다크 토글만 얻습니다.
적응
- 다른 시각적 방향 —
src/themes.js에 다섯 가지가 있습니다(house,swiss,editorial,draft,shadcn).src/App.jsx에서THEME_ID를 변경하십시오. 서체를 추가하는 경우 반드시metrics.charFactor를 올바르게 설정해야 합니다 그렇지 않으면 모든 레이블이 잘립니다.references/troubleshooting.md를 참조하십시오. - 더 많은 페르소나 / 렌즈 / 시대 — 순수 스펙 데이터, 코드 변경 없음.
- 소스에서 생성 — 저장소를 탐색하고
DIAGRAM트리를 출력하는 스크립트는 합리적인 확장이지만why,detail및 비트는 여전히 사람이 제공해야 합니다.
범위
이 스킬은 설명적 그림을 구축합니다. 라이브 대시보드, 자유형 그리기 도구 또는 인프라 인벤토리가 아닙니다. 사용자가 계속 드래그할 수 있는 편집 가능한 다이어그램을 원하면 drawio를 원하는 것입니다. 페이지에 숫자 하나를 원하면 차트를 원하는 것입니다.