Floorplan Skill: AI가 그려주는 코드베이스 지도로 온보딩과 아키텍처 문서화를 한 번에
AI 코딩 어시스턴트용 오픈소스 플러그인 Floorplan Skill로 코드베이스를 인터랙티브 맵으로 시각화하고 온보딩·문서화를 자동화하는 방법을 소개합니다.
신규 팀원이 합류했을 때, 혹은 오래된 레거시 코드를 처음 마주했을 때 느끼는 그 막막함을 아시나요? 수백 개의 파일을 하나씩 열어보며 "이 엔드포인트가 저 컴포넌트와 연결되나?"를 추적하는 시간, Floorplan Skill은 바로 그 고통을 해결하기 위해 만들어진 도구입니다.
Floorplan Skill이란 무엇인가?
Floorplan Skill은 Claude Code, Codex 같은 AI 코딩 어시스턴트에 연결해 사용하는 플러그인·익스텐션입니다. 개발자 haydenschmitty가 제작했으며 MIT 라이선스 오픈소스로 공개되어 있습니다.
핵심 기능은 단순합니다. 코드베이스를 스캔해서 파일·엔드포인트·컴포넌트의 관계를 줌 가능한 인터랙티브 맵으로 시각화합니다. 결과물은 로컬 서버(127.0.0.1)에서 열리는 floorplan/index.html 파일 하나로 떨어집니다. 별도 클라우드 서비스 가입도, 복잡한 설정도 필요 없습니다.
"코드베이스의 평면도(Floorplan)를 그린다"는 비유가 이름에 그대로 담겨 있습니다.
동명 도구들과 헷갈리지 않으려면
"Floorplan"이라는 단어가 들어간 AI 도구가 여럿 존재하기 때문에, 처음 접하는 분들이 종종 혼동합니다. 아래 표로 한 번에 정리합니다.
Floorplan Skill은 코드베이스 시각화 전용으로, 건축·인테리어 도메인의 동명 도구와 목적이 완전히 다르다.
| 도구 이름 | |||
|---|---|---|---|
| Floorplan Skill | haydenschmitty (MIT) | 코드베이스 구조 시각화 | yes |
| floor-plan-generation | EachLabs | 건축 평면도 이미지 생성 | no |
| floorplan-vectorizer | Claude 활용 프로젝트 | 평면도 이미지 → 벡터 변환 | no |
세 도구 모두 "Floorplan"이라는 이름을 쓰지만, 개발자 도구로서의 Floorplan Skill은 코드 구조 파악이라는 완전히 다른 목적을 가집니다. 검색할 때 "Floorplan Skill Claude Code" 혹은 "haydenschmitty floorplan"으로 찾으면 혼동을 피할 수 있습니다.
150개 파일 기준, 병렬 서브에이전트를 쓰는 이유
Floorplan Skill의 기술적 특징 중 가장 눈에 띄는 부분은 평행(Parallel) 서브에이전트 활용입니다. 대형 레포지토리, 구체적으로 약 150개 파일 이상 규모에서 이 방식이 작동합니다.
왜 150개일까요? AI 코딩 어시스턴트는 한 번의 컨텍스트 윈도우에서 처리할 수 있는 토큰 양에 한계가 있습니다. 파일이 많아질수록 단일 에이전트가 전체 코드를 한 번에 읽고 분석하는 것은 불가능해집니다. Floorplan Skill은 이 한계를 코드베이스를 여러 청크로 나눠 병렬 서브에이전트에 분배하는 방식으로 우회합니다.
병렬 서브에이전트 분기로 컨텍스트 윈도우 한계를 넘어 대형 레포지토리도 완전 스캔한다.
파일 수 ~150개 기준으로 단일/병렬 처리 경로를 결정합니다.
파일 그룹별로 독립 서브에이전트를 생성해 병렬 스캔을 시작합니다.
각 서브에이전트가 자신이 담당한 영역의 구조 정보를 수집합니다.
모든 서브에이전트 결과를 합쳐 하나의 인터랙티브 맵으로 렌더링합니다.
로컬 서버(127.0.0.1)에서 바로 열 수 있는 HTML 파일로 완성됩니다.
5단계 중 1단계
코드베이스 규모 측정
파일 수 ~150개 기준으로 단일/병렬 처리 경로를 결정합니다.
이 구조 덕분에 단순한 소규모 프로젝트뿐 아니라 엔터프라이즈 수준의 대형 레포지토리도 완전한 맵으로 시각화할 수 있습니다.
Health Check: AI 생성 코드의 안티패턴을 잡아내는 방법
Floorplan Skill에는 단순 시각화 이상의 기능이 있습니다. Health Check 기능이 그것입니다. 특히 AI가 생성한 코드에서 반복적으로 나타나는 대표적인 안티패턴들을 탐지합니다.
Health Check가 감지하는 주요 항목은 다음과 같습니다.
- 하드코딩된 시크릿(API 키, 비밀번호 등): AI 코딩 어시스턴트가 빠르게 생성한 코드에는 환경 변수 대신 직접 값을 박아넣는 경우가 발생합니다.
- 미처리 에러(Unhandled Error):
try-catch없이 넘어가는 비동기 호출, 에러 핸들링이 빠진 API 응답 처리 등을 탐지합니다. - 미사용 라우트(Dead Route): 정의는 되어 있지만 어떤 컴포넌트나 클라이언트도 호출하지 않는 엔드포인트를 발견합니다.
AI 도구가 코드를 빠르게 생성해주는 시대에, 이런 패턴은 오히려 더 자주 발생합니다. "일단 동작하는 코드"를 뽑아내는 AI 특성상 보안 모범 사례나 에러 처리가 누락되기 쉽기 때문입니다. Floorplan Skill의 Health Check는 그 맹점을 체계적으로 보완해줍니다.
실전 워크플로우: 온보딩과 아키텍처 문서화에 바로 쓰기
신규 팀원 온보딩에 활용하기
전통적인 온보딩 방식은 선임 개발자가 몇 시간에 걸쳐 코드 구조를 설명하거나, 신규 팀원이 직접 파일을 뒤지며 파악하는 방식입니다. Floorplan Skill을 활용하면 이 과정을 아래처럼 바꿀 수 있습니다.
- 합류 당일, 즉시 맵 생성: 신규 팀원의 개발 환경 세팅이 끝나는 시점에 Floorplan Skill을 실행해 코드베이스 맵을 바로 생성합니다.
- 맵을 보며 질의응답 세션 진행: 추상적인 말 설명 대신 인터랙티브 맵을 함께 보면서 "이 서비스가 저 컴포넌트를 호출한다"를 직접 짚어줍니다.
- 팀원이 직접 맵을 탐색하며 궁금한 부분 체크: 줌 인·아웃이 가능한 인터랙티브 맵이기 때문에 스스로 탐색하고 이해하는 시간이 크게 줄어듭니다.
팀 위키 및 PR에 첨부해 아키텍처 문서화 자동화
Floorplan Skill의 출력물인 floorplan/index.html은 단순한 로컬 미리보기에서 그치지 않습니다. 이 파일을 활용하는 실전 방법을 소개합니다.
- 팀 위키(Notion, Confluence 등)에 임베드: HTML 파일을 정적 호스팅에 올리거나 스크린샷을 캡처해 위키 페이지에 첨부하면 아키텍처 다이어그램이 자동으로 최신 상태를 유지합니다.
- PR(Pull Request)에 첨부: 대규모 리팩터링이나 신규 기능 추가 PR을 올릴 때, 변경 전·후의 맵을 함께 첨부하면 리뷰어가 구조적 변화를 한눈에 파악할 수 있습니다.
- 코드 리뷰 기준선 설정: 주기적으로(예: 스프린트 종료 시점) 맵을 갱신하고 버전 관리해두면 아키텍처가 어떻게 진화했는지 추적할 수 있습니다.
기존에는 Mermaid 다이어그램을 수작업으로 그리거나, 외부 다이어그램 툴을 별도로 운영해야 했습니다. Floorplan Skill은 이 과정을 AI 코딩 어시스턴트 명령 하나로 대체합니다.
결론: 코드 지도가 팀 전체의 생산성을 바꾼다
Floorplan Skill이 제공하는 가치를 정리하면 다음과 같습니다.
- Claude Code·Codex 등 AI 코딩 어시스턴트와 연동되는 MIT 오픈소스 플러그인
- 코드베이스를 줌 가능한 인터랙티브 맵(
floorplan/index.html)으로 시각화 - 150개 파일 이상 대형 레포지토리는 병렬 서브에이전트로 컨텍스트 한계 극복
- Health Check로 AI 생성 코드의 하드코딩 시크릿·미처리 에러·미사용 라우트 탐지
- 신규 팀원 온보딩, 팀 위키 첨부, PR 아키텍처 문서화에 즉시 적용 가능
건축 도구인 floor-plan-generation(EachLabs)이나 floorplan-vectorizer와 이름이 비슷하니, 개발자 도구로 찾을 때는 "Floorplan Skill Claude Code" 또는 "haydenschmitty floorplan"으로 검색하세요.
코드베이스가 클수록, 팀이 커질수록, 아키텍처를 한눈에 보는 능력은 경쟁력이 됩니다. Floorplan Skill을 다음 스프린트 시작 전에 한 번 실행해 보세요. 팀 전체의 온보딩 시간과 문서화 부담이 눈에 띄게 달라질 것입니다.
댓글
댓글을 불러오는 중…
