Floorplan 사용법, 설치 두 줄과 안전 점검

핵심 요약
별 4,167개 Floorplan은 설치가 두 줄이고 훅·MCP·설치 스크립트가 없다. 저장소 파일 184개를 직접 열어 확인한 안전 점검과 처음 쓰는 순서를 정리했다.
AI에게 시켜서 앱을 만들었는데, 누가 “결제 버튼을 누르면 서버에서 무슨 일이 일어나?“라고 물으면 대답할 수 없는 경우가 있다. 코드는 돌아가고 화면도 잘 뜨는데, 어디서 어디로 연결되는지는 내가 본 적이 없다. 이럴 때 쓰라고 나온 도구가 Floorplan이다. Claude Code나 Codex가 내 코드를 읽고, 앱의 각 부분과 파일, 웹 요청마다 쉬운 말 이름을 붙여 클릭해서 돌아다닐 수 있는 지도를 만들어 준다.
이 글은 코딩 에이전트에게 코드를 맡겨 앱을 만들어 본 적은 있지만 “내 앱이 어떻게 생겼는지”를 한눈에 본 적은 없는 사람을 위해 썼다. 결론부터 적는다. 설치는 명령 두 줄이고, 저장소를 열어 보니 훅(hook)도 MCP 서버도 의존성도 설치 스크립트도 없었다. 다만 이 글은 플러그인을 설치하거나 실행해 보지 않았다. 저장소를 빈 폴더에 내려받아 파일과 코드를 읽고, 문서가 한 말과 코드가 맞는지 대조한 결과다. 이 구분은 글 끝까지 유지한다.
먼저 말 몇 개를 풀어 둔다. 코딩 에이전트는 코드를 쓰고 터미널 명령까지 실행하는 AI다. 플러그인은 에이전트에 붙여 쓰는 확장 묶음이고, 스킬은 그 안에서 에이전트가 읽는 사용 설명서 파일(SKILL.md)이다. 훅은 에이전트가 세션을 열 때마다 자동으로 코드를 실행하게 만드는 장치라서 악성 확장이 숨기 좋은 자리로 꼽힌다. MCP 서버는 에이전트에 도구를 연결해 주는 별도 프로그램이다. 의존성은 다른 사람이 만든 코드 꾸러미를 npm으로 받아 쓰는 것을 말한다.
확인한 숫자와 날짜: 2026년 11월 14일
| 항목 | 내용 |
|---|---|
| 이름·저장소 | Floorplan, haydenschmitty/floorplan (소유자 표기: Hayden Smith, 개인 저장소) |
| 라이선스 | MIT |
| 버전 | 0.8.0 (저장소 마지막 커밋이 11월 12일, 커밋 메시지가 “Floorplan 0.8.0”) |
| 만든 날 | 저장소 생성 10월 27일 |
| GitHub | 별 4,167개, 포크 347개 (11월 14일 오후 확인) |
| 요구 사양 | Node.js 18 이상, Claude Code 또는 Codex |
| 비용 | 별도 API 키 없음. 쓰고 있는 Claude나 ChatGPT 요금제 안에서 돈다 (README 설명) |
| 지원 환경 | Claude Code 플러그인, Codex 플러그인 |
| 내가 한 것 | 저장소 내려받아 파일 184개 읽기. 설치·실행은 안 함 |
저장소가 열린 지 3주도 안 됐는데 별이 4천 개를 넘었다는 점은 관심이 크다는 신호이지 품질 보증이 아니다. 이 숫자는 그날의 스냅숏이다. 버전이 0.8.0이라는 점도 명령과 동작이 바뀔 수 있다는 신호로 읽는 편이 안전하다.
에이전트에게 한 줄 부탁하면 만들어지는 것: 이름 붙은 앱 지도
README 첫 줄이 이 도구를 설명한다. “See how your app actually fits together.” 우리말로 하면 “내 앱이 실제로 어떻게 맞물려 있는지 보세요”다. 에이전트가 코드를 읽고 floorplan/index.html 한 장을 만든다. 브라우저에서 열면 앱의 부분들이 카드로 보이고, 카드를 더블클릭해 파일 단위, 웹 요청 단위까지 파고들 수 있다.
README가 내세우는 기능은 아래 일곱 가지다.
- 줌 단계별 지도. 앱 전체에서 시작해 한 부분, 파일 묶음, 파일, 그 파일의 엔드포인트(서버가 요청을 받는 주소)까지 내려간다.
- 쉬운 말 이름. “Stripe API wrapper” 같은 기술 이름 대신 “결제할 때 카드 결제를 처리한다”처럼 쓴다. 기술 용어는 마우스를 올리면 풀이가 뜨고, 스위치 하나로 개발자용 보기로 바꾼다.
- 저장소가 달라도 이어지는 연결. import 관계를 따라가고, 프런트엔드가 보내는 웹 요청을 그걸 받는 서버 엔드포인트와 짝지어 준다. 프런트와 백엔드가 별개 저장소여도 마찬가지라고 한다.
- 화면에서 시작하기. 아는 페이지 하나를 고르면 그 뒤에 있는 부분, 요청, 서버 코드, 데이터, 바깥 서비스까지 보여 준다.
- 지도에게 묻기. “환불은 고객 카드까지 어떻게 가?“처럼 물으면 답과 함께 관련된 조각만 그린 작은 지도가 나온다.
- 건강 점검(Health check). AI로 만든 앱에서 자주 나오는 실수를 찾는다. 코드에 들어간 키, 브라우저로 새어 나가는 키, 아무나 읽을 수 있는 Supabase 테이블, 열려 있는 Firebase 규칙, 누구나 위조할 수 있는 Stripe 웹훅, 로그인 없는 엔드포인트가 예로 적혀 있다. 고칠 문장이 붙어 나온다. README는 이것을 “점검이지 감사가 아니다”라고 선을 긋는다.
- 최근 작업 표시. 에이전트가 방금 고친 카드가 초록색으로 켜지고, 왜 고쳤는지 메모가 붙는다.
지원 언어는 TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Scala와 Vue·Svelte·Astro 파일이고 나머지는 “가벼운 지원”이다. 엔드포인트는 Express, Fastify, Hono, Next.js, Flask, FastAPI, Django, Spring 같은 프레임워크를 읽는다고 적혀 있다. 이 목록에 없는 프레임워크를 쓰면 지도에서 연결이 빠질 수 있고, 문서도 연결이 빠졌을 때 직접 추가하는 방법을 따로 안내한다.
설치 두 줄과 처음 하는 말
Claude Code에서는 터미널에 아래 두 줄을 차례로 입력한다. README와 docs/getting-started.md에 같은 명령이 적혀 있다.
claude plugin marketplace add haydenschmitty/floorplan
claude plugin install floorplan@floorplan
첫 줄은 이 저장소를 플러그인 목록(마켓플레이스)으로 등록하는 명령이고, 둘째 줄이 그 목록에서 floorplan을 설치하는 명령이다. 새 세션을 열면 준비가 끝난다. Codex는 앱의 Plugins 화면에서 마켓플레이스 소스에 haydenschmitty/floorplan을 넣고 설치하거나, 터미널에서 codex plugin marketplace add haydenschmitty/floorplan과 codex plugin add floorplan@floorplan을 쓴다.
설치했으면 프로젝트 폴더를 연 채로 에이전트에게 이렇게 말한다.
Make me a floorplan of this app.
Codex에서는 $floorplan이라고 입력해도 된다. 앱이 프런트와 백엔드로 저장소가 나뉘어 있다면 둘을 모두 품은 상위 폴더에서 시작하라고 README가 안내한다. 첫 지도는 작은 앱이면 몇 분, 큰 앱이면 더 걸린다. 파일과 엔드포인트마다 설명을 쓰는 일을 에이전트가 하기 때문이고, 큰 프로젝트는 여러 도우미로 나눠 처리한다고 한다. 나중에 코드를 더 고쳤다면 “Update the floorplan.“이라고 하면 바뀐 부분만 다시 읽는다.
아직 코드가 없다면 설계 문서(PRD)를 보여 주고 “이 문서로 필요한 것의 floorplan을 만들어 줘”라고 할 수도 있다. 이때는 “계획된 시스템”이라고 표시된 청사진(blueprint) 지도가 나온다.
업데이트는 자동이 아니다. 문서에 따르면 GitHub에서 설치한 플러그인은 자동 갱신을 켜지 않으면 claude plugin update floorplan@floorplan을 직접 실행해야 한다. 지울 때는 claude plugin uninstall floorplan@floorplan을 실행한 다음, 써 본 프로젝트의 floorplan/ 폴더와 CLAUDE.local.md의 Floorplan 구간을 직접 지운다.
내 프로젝트에 생기는 파일: 폴더 하나와 선택 한 줄
도구를 쓰기 전에 가장 궁금한 건 “내 코드를 건드리나”다. 문서(docs/project-files.md)의 답은 두 곳에만 쓴다는 것이다.
- 프로젝트 루트의
floorplan/폴더. - Claude Code에서 “예”라고 답했을 때만
CLAUDE.local.md안에 표시 구간(<!-- floorplan:start -->와<!-- floorplan:end -->사이).
floorplan/ 안에는 지도 한 장(index.html), 지도 데이터(graph.json), 앱 구조 정의(architecture.json), 파일별 이름과 설명(descriptions/*.json), 지도를 내 컴퓨터에서 띄워 주는 서버(serve.mjs), 지도 조회용 스크립트(query.mjs)가 들어간다. 이 폴더는 스스로 git에서 빠지도록 .gitignore를 만들고, CLAUDE.local.md는 내 저장소 사본의 개인 제외 목록(.git/info/exclude)에 올라간다. 문서는 .gitignore나 CLAUDE.md 같은 추적되는 파일은 건드리지 않는다고 적는다.
이름과 설명이 마음에 안 들면 직접 고칠 수 있다. architecture.json과 descriptions/ 안의 파일 수정은 업데이트 때 보존된다. 에이전트에게 “지도에서 ‘Main server’ 이름을 ’Shop API’로 바꿔 줘”라고 해도 된다.
저장소를 열어서 직접 확인한 것
문서는 “안전하다”고 말한다. 그 말이 코드와 맞는지 확인하려고 저장소(커밋 5e3eaac, 2026년 11월 12일)를 빈 폴더에 내려받았다. 파일은 모두 184개였다. 아래는 읽기만 한 결과이고, 어떤 파일도 실행하지 않았다.
훅과 MCP 설정은 없었다. 저장소 전체에서 hooks로 시작하는 이름의 파일이나 폴더, .mcp.json이나 mcp*.json 파일을 찾았지만 하나도 나오지 않았다. 플러그인 정의 파일(.claude-plugin/plugin.json)에도 훅이나 MCP 항목이 없다.
의존성이 없다. 루트 package.json에는 dependencies 항목이 없고, 설명에도 “이 파일은 npm test가 돌 자리만 준다”고 적혀 있다. 지도 배치에 쓰는 엔진(elkjs)과 글꼴은 저장소 안 skills/floorplan/assets/vendor/에 라이선스 파일과 함께 들어 있다. 설치할 때 인터넷에서 받아 오는 코드가 아니라는 뜻이다.
스킬 파일이 에이전트에게 미리 허락하는 명령은 자기 스크립트뿐이다. skills/floorplan/SKILL.md 머리말의 allowed-tools는 node ${CLAUDE_SKILL_DIR}/scripts/ 아래의 build, describe, open, plan, recent, refresh, scan, status 여덟 스크립트로 한정돼 있다. 앞서 다룬 Playwright CLI의 스킬 파일이 해당 명령 전체를 미리 허락하던 것과 대비된다. 다만 문서가 인정하듯 환경에 따라 에이전트가 node 실행 허락을 계속 물을 수 있고, 그때 “이 프로젝트에서는 항상 허용”을 고르는 방법을 안내한다.
바깥으로 나가는 요청은 한 곳이었다. 스킬과 도구 폴더에서 fetch(를 검색하니 지도 화면이 내 컴퓨터의 서버로 보내는 요청들이 나왔고, 인터넷으로 나가는 요청은 serve.mjs의 대기자 명단 전송 한 줄(267행)뿐이었다. 문서가 말하는 “유일한 외부 요청은 선택 가입하는 대기자 명단”과 일치한다.
한 가지는 문서 설명과 결이 달라 보였다. 문서는 “eval도, 실행 중에 코드를 불러오는 일도 없다”고 말하는데, serve.mjs 192행에는 new Function(...)이 있다. 읽어 보니 같은 폴더의 query.mjs 파일 내용을 읽어 그 안의 함수들을 꺼내 쓰는 용도였다. 인터넷에서 받은 문자열이 아니라 플러그인이 내 프로젝트에 복사해 둔 파일을 읽는다. 위험하다는 뜻은 아니지만, “eval 계열이 전혀 없다”는 문장을 글자 그대로 받아들이면 안 된다는 점은 기록해 둔다.
외부 프로그램은 몇 개 실행한다. child_process를 쓰는 파일은 다섯 개다. 문서의 표대로 git(읽기 전용으로 추적 파일 목록과 변경분 조회), which·where(Claude Code나 Codex 위치 찾기), 그리고 지도의 질문창에서 질문할 때 claude나 codex를 실행한다. 코드에는 이 밖에 자기 스크립트(업데이트가 scan과 build를 부른다)와 브라우저를 여는 시스템 명령도 있었다.
릴리스 파일 지문이 있다. 저장소 루트 CHECKSUMS.txt는 플러그인이 실행하는 모든 파일의 SHA-256 값을 적어 둔다. 내려받은 사본이 진짜인지 node tools/checksums.mjs --check <설치 폴더>로 비교하라고 안내한다. 나는 이 비교는 해 보지 않았다.
코드와 정보가 어디로 가나
README와 docs/privacy-and-security.md의 표를 우리말로 줄이면 이렇다.
| 일 | 어디서 도나 | 무엇이 나가나 |
|---|---|---|
| 코드 스캔·지도 생성 | 내 컴퓨터(Node.js) | 없음 |
| 이름·설명 쓰기 | 내 Claude/Codex 세션 | 에이전트가 읽는 파일 내용. 다른 작업을 시킬 때와 같음 |
| 지도 보기 | 내 브라우저 | 없음. 엔진과 글꼴이 파일에 들어 있어 오프라인으로 열림 |
| 지도 서버 | 내 컴퓨터, 127.0.0.1만 |
스스로는 없음 |
| 지도에서 질문 | 내 컴퓨터의 claude -p나 codex exec |
질문과 에이전트가 고른 파일 내용 |
| 사본 내보내기 | 내 컴퓨터 | 없음. 폴더 경로·git 주소·소스 코드는 담기지 않는다고 함 |
여기서 놓치기 쉬운 문장은 “에이전트가 읽는 파일 내용은 내 계정을 통해 나간다”는 것이다. Floorplan이 코드를 따로 어디에 올리지는 않지만, 이름과 설명을 쓰는 동안 에이전트는 평소 작업처럼 파일을 읽고 그 내용은 Claude나 ChatGPT 쪽으로 간다. 회사 코드를 이미 에이전트에게 보여도 되는 환경이면 새 위험은 늘지 않고, 아니라면 이 도구도 쓰면 안 된다.
지도 서버에 대해서는 문서가 꽤 구체적이다. 서버는 127.0.0.1에서만 연결을 받고, 시작할 때마다 새로 만드는 토큰을 지도 화면에만 넘기며, 질문과 흐름 저장은 그 토큰이 있어야 하고, 다른 웹사이트에서 온 요청은 거절한다. 자기 도메인을 내 컴퓨터로 연결해 접근하는 공격(DNS 리바인딩)도 막는다고 적혀 있다. 마지막 탭을 닫은 뒤 두 시간이 지나면 서버가 스스로 꺼지고, 바로 끄고 싶으면 node floorplan/serve.mjs --stop을 쓴다. 이 보호 장치들이 실제로 문서대로 동작하는지는 실행해 보지 않아 확인하지 못했다.
지도의 질문창과 건강 점검은 얼마나 믿나
질문창은 Claude Code에서는 읽기 전용 도구(파일 읽기, 검색, 지도 조회 스크립트)로만 돌고, Codex에서는 읽기 전용 샌드박스에서 돈다고 문서가 말한다. 질문 때문에 내 파일이 바뀌지 않는다는 설계다. 청사진 지도에서 “Change(변경)“를 켜면 서버가 plan.json, architecture.json, recent-work.json만 검사한 뒤 쓰고, 이전 사본을 Undo용으로 남긴다.
건강 점검은 조심해서 읽어야 한다. 문서 스스로 “점검이지 감사가 아니다”라고 하고, 비밀 값은 저장하거나 보여 주지 않고 어디에 있는지만 알려 준다고 한다. 이 점검이 아무것도 못 찾았다고 해서 안전하다는 보증은 아니다. 반대로 문제를 찾았다면 “Not a problem(문제 아님)” 표시 기능이 있고, 그걸 표시하면 사유와 함께 health-dismissed.json에 남는다. 이 표시를 누르면 오탐 신고용 GitHub 이슈 창이 브라우저에 열리지만, 내가 제출해야만 전송된다.
지도 구석의 이메일 카드
설치 전에 알아 둘 동작이 하나 더 있다. 지도를 연 지 2분쯤 지나면 왼쪽 아래에 “Floorplan Cloud가 나오면 메일로 알려 줄까요?“라는 카드가 뜬다. Floorplan Cloud는 팀마다 지도 하나를 GitHub와 동기화해 쓰는 호스팅 버전으로 소개돼 있다. 문서에 따르면 아래와 같다.
- Notify me를 누르기 전에는 아무것도 전송되지 않는다. 보내는 값은 이메일과 “혼자 쓰기/팀과 쓰기” 선택뿐이다.
- “Use my Claude email” 버튼은 로그인된 Claude 계정의 이메일을 칸에 채워 준다. 버튼을 누를 때만 Claude Code에 묻고, 보내기 전에 주소를 보여 준다.
- “Not now”를 고르면 2주 뒤에 다시 묻고, “Don’t ask again”을 고르거나 가입하면 모든 프로젝트에서 다시 묻지 않는다.
- 환경 변수
FLOORPLAN_NO_PROMPTS=1을 주면 이 카드를 끌 수 있다.
실제로 코드에서 확인한 것은 앞서 말한 전송 한 줄(serve.mjs 267행)과 그 주소가 floorplan-waitlist-...run.app이라는 점이다. 이메일을 모을 의도가 아니라면 카드를 무시하거나 끄면 된다.
처음 20분은 이렇게 써 보자
- 작은 프로젝트에서 시작한다. 지도는 에이전트가 파일마다 설명을 써서 만든다. 파일이 수백 개인 프로젝트는 시간이 걸리고 요금제 사용량도 쓴다. 코드가 수십 개 파일인 사이드 프로젝트가 첫 시험에 맞다.
- 회사 코드라면 먼저 허락을 받는다. 파일 내용이 에이전트를 통해 나가는 도구라서, 그 에이전트를 회사 코드에 써도 되는지가 선행 질문이다.
- 설치 뒤
SKILL.md의 허락 목록을 한 번 본다. 앞 절에서 말한 대로 여덟 스크립트로 한정돼 있는지, 내 설치본이 내려받은 것과 같은지 확인하면 된다. 위의CHECKSUMS.txt비교가 가장 확실한 방법이다. - “Make me a floorplan of this app.“을 입력하고 지도를 연다. 처음에는 짧은 안내(tour)가 시작한다.
- 모르는 부분 하나를 골라 질문창에 묻는다. “로그인은 어느 파일이 처리해?“처럼 구체적으로 묻는다. 답과 함께 나오는 작은 지도의 연결선이 실제 코드와 맞는지 한두 군데는 직접 열어 본다.
- 건강 점검을 열어 보되 결과를 감사로 믿지 않는다. 찾아낸 항목은 고치기 전에 해당 파일을 직접 확인한다.
- 다 쓰고 나면 서버를 끈다. 두 시간 뒤 저절로 꺼지지만
node floorplan/serve.mjs --stop으로 바로 끌 수 있다. 쓰지 않는다면claude plugin uninstall floorplan@floorplan과floorplan/폴더 삭제로 정리한다.
문제가 생기면 docs/troubleshooting.md에 대부분 답이 있다. node를 못 찾을 때는 Node.js 18 이상을 설치하고 새 세션을 열라고 하고, 4378번 포트가 쓰이고 있으면 서버가 다음 빈 포트로 옮겨 가니 출력된 주소를 쓰면 된다. 지도가 낡아 보일 때는 “Update the floorplan”으로 다시 읽게 한다.
이럴 때는 다른 길이 낫다
- 코드를 에이전트에게 보여 주면 안 되는 환경. 이름과 설명을 쓰는 과정에서 파일 내용이 에이전트 쪽으로 간다. 이 도구는 그 전제 위에서만 쓸 수 있다.
- 지도가 아니라 정확한 의존 관계가 필요할 때. 지도의 연결은 import와 웹 요청을 정적으로 읽어 맞춘 것이고, 이름과 설명은 에이전트가 쓴 해석이다. 감사나 보안 심사 자료로 내밀 수 있는 수준의 정밀도를 문서도 약속하지 않는다.
- 이미 구조 문서가 잘 되어 있는 팀. 문서를 사람이 관리하는 곳이라면 지도 한 장이 큰 도움이 되지 않을 수 있다.
- 큰 코드베이스를 함수 단위로 파고들고 싶을 때. README의 비교표는 Floorplan을 “내가 만든 앱이 어떻게 돌아가나, 무엇을 조심해야 하나”에 답하는 도구로, 함수 수준으로 읽는 도구는 별도 프로젝트(Understand Anything)로 구분한다. 표현을 다듬는 도구(Archify)도 있다. 이 비교표는 저장소 소유자가 쓴 것이라 중립 평가로 받아들이면 안 된다.
- 확장 설치 자체가 불안할 때. 지난달 Claude Code 확장 마켓플레이스 백도어 사례처럼 확장은 설치만으로도 위험이 될 수 있다. 이 도구가 훅과 MCP가 없는 구조라는 건 그 위험을 줄여 주는 설계이지 0으로 만드는 보증은 아니다. 스킬 형식이 어디까지 표준이 되고 있는지는 에이전트 스킬 표준 재단 이관 소식에서 정리했다.
이 글이 확인하지 못한 것
- 설치도 실행도 안 했다. 저장소를 읽은 것이 전부라서, 지도가 실제로 얼마나 정확한지, 몇 분 걸리는지, 요금제 사용량을 얼마나 쓰는지는 모른다.
- 보호 장치의 동작. 토큰, 출처 검사, DNS 리바인딩 방어, 두 시간 뒤 자동 종료는 문서와 코드 설명으로만 읽었다. 직접 공격해 보거나 실행한 적이 없다.
- 릴리스 지문 비교.
CHECKSUMS.txt를 설치본과 대조하지 않았다. - 테스트 통과 여부. 문서는 공급망 검사(
tests/supply-chain.test.mjs)가 모든 변경마다 돈다고 말한다. 이 테스트를 돌려 보지 않았다. - 별 4,167개의 질. 별은 관심의 숫자다. 사용 후기나 독립 평가는 확인하지 못했다.
- Codex 쪽 동작. 문서의 Codex 절만 읽었고 Codex에서는 어떤 점이 다른지 재현하지 않았다.
그래도 판단은 단순하다. 개인 개발자가 만든 3주 된 저장소이므로 기본 태도는 신중해야 한다. 그 위에서 이 저장소는 훅·MCP·의존성·설치 스크립트가 없고, 바깥 요청 한 곳을 문서가 정직하게 밝혔다는 점에서 확장치고는 확인하기 쉬운 편이다. 작은 개인 프로젝트에서 먼저 써 보고, 회사 코드에는 그 에이전트 사용 허락을 받은 뒤에 쓰기를 권한다.
이 글의 근거 페이지
모두 2026년 11월 14일에 열어 본 페이지다.
- Floorplan 저장소와 README: 기능, 설치 명령, 개인정보 항목, 별·포크·라이선스·마지막 커밋
- Is it safe to install?: 훅·MCP·의존성 없음, 네트워크 요청, 실행하는 프로그램
- Privacy and security: 데이터 흐름 표, 로컬 서버 보호, 대기자 명단
- What’s in your project:
floorplan/폴더와CLAUDE.local.md동작 - Getting started와 Troubleshooting: 설치·업데이트·삭제, 문제 해결
- SKILL.md:
allowed-tools허락 목록 - 라이브 데모: Brewline 샘플 앱의 지도