토큰 낭비 중단하기: AI 지원 개발을 위한 파일 매핑 표준을 구축했습니다

새로운 AI 채팅 세션을 시작할 때마다, AI는 내 코드베이스 전체를 읽었습니다.

50개의 파일. 수천 개의 토큰. 매 메시지마다 말이죠. 인증(authentication), 데이터베이스 스키마(database schema), 또는 단 하나의 UI 컴포넌트에 대해 질문하든 상관없이 — AI는 모든 것을 읽었습니다.

저는 16살이고 AI 기반 제품을 만들고 있습니다. 토큰 비용은 빠르게 쌓입니다. 컨텍스트 윈도우(Context windows)는 가득 차고, AI는 오래된 파일들의 흐름을 놓칩니다. 응답 속도도 느려집니다.

그래서 이를 해결하기 위해 무언가를 만들었습니다.

문제점

대규모 프로젝트에서 AI와 함께 작업할 때, 당신은 선택의 기로에 서게 됩니다:

• AI에게 너무 많은 컨텍스트(context)를 제공하기 → 토큰을 낭비하고, 컨텍스트 제한에 걸리며, 응답이 느려짐
• 너무 적은 정보를 제공하기 → AI가 중요한 파일을 놓치고, 잘못된 가정을 함

중간 지점은 없었습니다 — 적어도 이전까지는 그랬습니다.

FolioDux 소개

FolioDux는 AI 지원 개발을 위한 가볍고 오픈 소스인 파일 매핑(file-mapping) 표준입니다.

아이디어는 간단합니다. AI에게 모든 파일을 주는 대신, 모든 것이 어디에 있는지와 무엇을 하는지를 알려주는 압축된 인덱스(index)를 제공하는 것입니다. AI는 먼저 인덱스를 읽고, 관련 있는 파일을 식별한 뒤, 오직 그 파일들만 읽습니다.

파일 하나. 두 가지 규칙. 어떤 AI든 가능.

Claude, ChatGPT, Gemini, Cursor, Copilot — 시스템 프롬프트(system prompt)를 수용하는 모든 도구에서 작동합니다.

작동 방식

프로젝트 루트에 단 하나의 파일인 FOLIODUX.md를 추가합니다.

# FOLIODUX · TaskFlow · v1.0 · 2026-06-18 · 17 files

STACK: React19+TypeScript+Vite · Express+SQLite · JWT
...

그런 다음 AI 시스템 프롬프트에 두 가지 규칙을 추가합니다:

RULE 1 — NAVIGATE BEFORE RESPONDING
모든 응답의 시작 시점에, 다른 어떤 파일을 읽기 전에:
1. FOLIODUX.md를 전체적으로 읽으세요.
...

그게 전부입니다. 이제 당신의 AI는 이미 코드베이스를 알고 있는 개발자처럼 프로젝트를 탐색합니다.

전과 후

FolioDux가 없을 때:
당신이 "로그인 버그를 수정해줘"라고 요청하면, AI는 50개의 파일을 모두 읽습니다. 질문에 대해 생각하기 시작하기도 전에 4,000개의 토큰을 사용합니다. 작업 중간에 컨텍스트 제한에 걸릴 수도 있습니다.

FolioDux 사용 시:
AI가 FOLIODUX.md를 읽고, auth/login → AuthView.tsx, authService.ts, server.ts를 찾아내어 3개의 파일만 읽습니다. 약 300개의 토큰을 사용합니다. 더 빠르고 정확하게 답변합니다.

빠른 시작 (Quick Start)

1단계 — FOLIODUX.md 자동 생성하기

curl -O https://raw.githubusercontent.com/matteo-turri/foliodux/main/foliodux-init.mjs
node foliodux-init.mjs

CLI 스크립트가 프로젝트를 스캔하고, package.json에서 기술 스택 (tech stack)을 감지하며, 모든 파일을 유형별로 분류하고, 주석과 export에서 설명을 추출하여 몇 초 만에 FOLIODUX.md를 생성합니다.

외부 의존성(external dependencies)은 없습니다. Node.js 18+ 버전만 필요합니다.

2단계 — TASKS 섹션 완성하기

스크립트가 자동으로 채울 수 없는 유일한 부분입니다. FOLIODUX.md를 열고 가장 빈번한 요청 사항을 관련 파일에 매핑(map)하세요:

## TASKS
auth/login/register   → AuthView.tsx, authService.ts, server.ts
create/edit product   → ProductForm.tsx, productService.ts, server.ts, types.ts
...

3단계 — AI 도구에 프로토콜 추가하기

위의 두 가지 규칙을 사용하는 AI 도구의 시스템 프롬프트 (system prompt)에 복사하여 붙여넣으세요. Claude Projects, ChatGPT, Cursor 및 일반 도구용 템플릿이 리포지토리 (repo)에 준비되어 있습니다.

파일 형식 (The File Format)

FolioDux는 가능한 한 적은 토큰을 사용하면서 인간과 AI 모두가 읽을 수 있도록 설계된 압축된 키워드 구문 (compressed keyword syntax)을 사용합니다.

설명 규칙 (Description rules):

• 관사 (the, a, an) 사용 금지
• 불필요한 동사 (handles, manages, is responsible for) 사용 금지
• 파일당 최대 8개의 키워드
• "and"는 +, "or"는 |, "calls"는 → 사용

❌ 장황한 표현 (Verbose)	✅ FolioDux
This is the main server file that handles all the API routes	Express: all routes — auth, tasks, projects, user
A service that manages authentication and user sessions	login, register, logout, JWT session storage

유형 코드 (Type codes):

코드	의미
fe	프론트엔드 (Frontend) 컴포넌트
...

설계 원칙 (Design Principles)

단 하나의 파일. 설정(config)도, 데이터베이스(database)도, 서버(server)도 필요 없습니다. 그저 프로젝트 루트에 있는 하나의 마크다운 (Markdown) 파일이면 충분합니다.

도구에 구애받지 않음 (Tool-agnostic). 시스템 프롬프트 (system prompt)를 수용하는 모든 AI와 함께 작동합니다.

토큰 우선 (Token-first). 모든 설계 결정은 토큰 효율성 (token efficiency)을 최적화하도록 이루어졌습니다.

자가 업데이트 (Self-updating). 규칙 2 (Rule 2)를 통해 프로젝트가 성장함에 따라 AI가 인덱스 (index)를 자동으로 유지합니다.

가독성 (Human-readable). 유효한 마크다운 (Markdown) 형식입니다. 다른 파일과 마찬가지로 열고, 편집하고, 버전 관리 (version-control)할 수 있습니다.

시작하기

CLI 스크립트, Claude/ChatGPT/Cursor를 위한 프롬프트 템플릿 (prompt templates), 그리고 완전한 예시를 포함한 전체 프로젝트는 GitHub에서 확인할 수 있습니다:

→ github.com/matteo-turri/foliodux

오픈 소스입니다. MIT 라이선스입니다. 스타 (Stars)와 피드백을 환영합니다.

제 프로젝트들을 진행하면서 제 문제를 해결하기 위해 이것을 만들었습니다. 저는 밀라노에 거주하는 16세입니다. FolioDux를 사용해 보신다면 댓글로 의견을 남겨주세요.