Floorplan: AI로 만든 앱을 지도 한 장으로 읽기
Claude Code나 Codex에 「이 앱의 floorplan을 만들어 줘」라고 하면, 몇 분 뒤 앱 전체 지도가 브라우저에 열려요
- 누가
- Hayden Smith(haydenschmitty)가 만든 Claude Code·Codex 플러그인이에요. AI와 앱을 만들었지만 코드를 직접 읽지는 않는 사람을 위해서요.
- 언제
- 2026년 10월 27일에 공개됐고, 11월 1일 v0.6.1까지 나왔어요.
- 어디서
- Claude Code와 Codex에서 돌아요. 스캔, 지도, 지도의 작은 서버는 모두 내 컴퓨터에서 돌아요.
이게 불편했어요
AI 도움을 많이 받아 앱을 만들었고, 잘 돌아가요. 그런데 「누가 결제하면 무슨 일이 일어나지?」, 「이걸 바꾸면 뭐가 깨지지?」라고 물으면 솔직한 답은 「모르겠다」예요. 코드를 한 줄씩 읽지 않고는 앱의 모양을 볼 방법이 없었어요.
그래서 이렇게 풀어요
Floorplan은 아무도 그리지 않은 설계도를 대신 그려 줘요. 파일과 import를 따라가고, 프런트엔드의 요청을 그 요청에 답하는 서버 엔드포인트와 짝짓는 기계적인 일은 스크립트가 맡아요. 부품이 무엇인지 정하고 쉬운 말로 설명하는 일만 Claude나 Codex가 해요. 지도에서는 화면 하나를 골라 그 뒤의 모든 걸 보거나, 질문을 던지거나, Health 점검으로 코드에 박힌 키를 찾을 수 있어요.




이걸로 만든 사람들
자기 사이트에 Health 점검을 돌려 본 결과를 이슈로 올렸어요. 「중요」로 잡힌 비밀 키가 알고 보니 페이지에 꼭 보여야 하는 Cloudflare 웹 분석 토큰이었다며, 이런 토큰은 빼 달라고 요청했어요.
Upon investigation, the access token identified is my beacon token for Cloudflare Web Analytics
안에서는 이렇게 돌아가요
- 1
사용자 → Claude Code / Codex
「이 앱의 floorplan을 만들어 줘」Floorplan 스킬이 지도가 이미 있는지 보고, 없으면 처음부터 만들어요.skills/floorplan/SKILL.md - 2
Claude Code / Codex → scan.mjs
저장소, 파일, import, 엔드포인트, 요청git으로 파일을 나열하고 import를 실제 파일로 풀며, 서버 엔드포인트와 코드가 보내는 요청을 찾아요.skills/floorplan/scripts/scan.mjs - 3
Claude Code / Codex → architecture.json
앱의 부품, 외부 서비스, 흐름, 둘러보기AI가 스캔 요약과 README를 읽고 앱을 부품으로 나눠 쉬운 말로 적어요.skills/floorplan/references/schema.md - 4
architecture.json → build.mjs
파일 배정, 요청과 엔드포인트 연결AI가 쓴 내용을 검증하고, 파일을 부품에 넣고, import와 짝지은 요청으로 카드를 이어요.skills/floorplan/scripts/build.mjs - 5
Claude Code / Codex → build.mjs
파일, 엔드포인트마다 이름과 설명부품별 작업지를 받아 AI가 하나하나 쉬운 이름과 설명을 채워요. 큰 프로젝트는 여러 도우미가 나눠 맡아요.skills/floorplan/scripts/describe.mjs - 6
build.mjs → floorplan/index.html
Health: 코드 속 키, 로그인 없는 엔드포인트흔한 실수를 찾아 고칠 프롬프트와 함께 지도에 올려요. 비밀 값 자체는 저장하거나 보여 주지 않아요.skills/floorplan/scripts/lib/health.mjs - 7
Claude Code / Codex → floorplan/index.html
로컬 서버로 지도 열기내 컴퓨터에서만 받는 작은 서버를 띄워 브라우저에 지도를 열고, 이미 열린 탭은 제자리에서 새로 고쳐요.skills/floorplan/scripts/open.mjs
넣으면 이렇게 나와요
나한테 맞을까요
이럴 때 좋아요
- AI와 만든 앱을 코드를 읽지 않고 이해하고 싶을 때
- 새 팀원에게 앱 구조를 큰 그림부터 파일까지 보여 줄 때
- AI가 방금 무엇을 왜 바꿨는지 카드로 확인하고 싶을 때
- 배포 전에 코드 속 키나 아무나 읽는 Supabase 테이블 같은 흔한 실수를 점검할 때
- 코드를 쓰기 전에 PRD로 필요한 부품부터 그려 보고 싶을 때
이건 안 돼요
- 첫 지도는 작은 앱도 몇 분 걸리고 큰 앱은 더 걸려요. 쓰는 Claude나 ChatGPT 요금제 사용량을 써요.
- 요청과 엔드포인트 연결은 컴파일러가 아니라 패턴 매칭이라 모든 연결을 잡지는 못해요.
- Health는 감사가 아니라 점검이라고 README가 밝혀요. 공개돼야 하는 토큰을 키로 잡았다는 보고도 이슈에 올라왔어요.
- Claude Code와 Codex에서만 돌아요.
발행 전에 Devalley 편집자가 검토했어요. 칼럼은 어떻게 만드나요