Matteo Turri

Posted on Jun 19

Stop Wasting Tokens: I Built a File-Mapping Standard for AI-Assisted Development

#ai #webdev #opensource #tooling

Every time I started a new AI chat session, it read my entire codebase.

50 files. Thousands of tokens. On every single message. Whether I was asking about authentication, database schema, or a single UI component — the AI read everything.

I'm 16 and building AI-powered products. Token costs add up fast. Context windows fill up. The AI loses track of older files. Responses slow down.

So I built something to fix it.

The Problem

When you work with AI on large projects, you face a choice:

Give the AI too much context → burns tokens, hits context limits, slower responses
Give it too little → AI misses important files, makes wrong assumptions

There's no middle ground — or at least there wasn't.

Introducing FolioDux

FolioDux is a lightweight, open-source file-mapping standard for AI-assisted development.

The idea is simple: instead of giving your AI every file, you give it a compact index that tells it where everything is and what it does. The AI reads the index first, identifies the relevant files, and reads only those.

One file. Two rules. Any AI.

It works with Claude, ChatGPT, Gemini, Cursor, Copilot — any tool that accepts a system prompt.

How It Works

You add one file — FOLIODUX.md — to your project root.

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

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

---

## TASKS
auth/login/register   → AuthView.tsx, authService.ts, server.ts
create/edit task      → TaskForm.tsx, taskService.ts, server.ts, types.ts
list/filter tasks     → TaskList.tsx, taskService.ts
database              → db.ts, server.ts

---

## INDEX
App.tsx           | fe  | root: routing, auth state, layout wrapper
AuthView.tsx      | fe  | login + register forms, error display
taskService.ts    | svc | CRUD tasks, local cache, optimistic updates
server.ts         | be  | Express: all routes — auth, tasks, projects, user
db.ts             | be  | SQLite setup, schema creation, migrations on boot
types.ts          | typ | Task, Project, User, Status(todo|in-progress|done)

---

## GROUPS
Frontend:  App.tsx · AuthView.tsx · TaskList.tsx · TaskForm.tsx
Services:  authService.ts · taskService.ts
Backend:   server.ts · db.ts

---

## NOTES
- All routes except /api/auth/* require Authorization: Bearer {JWT}
- Task status values: todo | in-progress | done only

Then you add two rules to your AI system prompt:

RULE 1 — NAVIGATE BEFORE RESPONDING
At the start of every response, before reading any other file:
1. Read FOLIODUX.md in full.
2. Check TASKS — if the request matches a keyword, read ONLY those files.
3. If no match in TASKS, scan INDEX keywords to identify relevant files.
4. Read ONLY the identified files. Never read the full codebase unless asked.

RULE 2 — UPDATE AFTER CREATING
After creating any new file, add one line to FOLIODUX.md INDEX:
{filename} | {type} | {keywords — no articles, no filler verbs, max 8 words}
Update TASKS and GROUPS if needed.

That's it. Your AI now navigates the project like a developer who already knows the codebase.

Before vs After

Without FolioDux:
You ask "fix the login bug". Your AI reads all 50 files. Uses 4,000 tokens before even starting to think about your question. Maybe hits the context limit halfway through.

With FolioDux:
Your AI reads FOLIODUX.md, finds auth/login → AuthView.tsx, authService.ts, server.ts, reads 3 files. Uses ~300 tokens. Answers faster and more accurately.

Quick Start

Step 1 — Generate your FOLIODUX.md automatically

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

The CLI script scans your project, detects the tech stack from package.json, classifies every file by type, extracts descriptions from comments and exports, and generates FOLIODUX.md in seconds.

Zero external dependencies. Node.js 18+ only.

Step 2 — Complete the TASKS section

The only part the script can't fill automatically. Open FOLIODUX.md and map your most common requests to the files they need:

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

Step 3 — Add the protocol to your AI tool

Copy the two rules above into your AI tool's system prompt. Templates for Claude Projects, ChatGPT, Cursor, and generic tools are available in the repo.

The File Format

FolioDux uses a compressed keyword syntax designed to be readable by both humans and AI while using as few tokens as possible.

Description rules:

No articles (the, a, an)
No filler verbs (handles, manages, is responsible for)
Max 8 keywords per file
Use + for "and", | for "or", → for "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:

Code	Meaning
`fe`	Frontend component
`be`	Backend / API
`svc`	Service / logic
`cfg`	Config / build
`typ`	Types / interfaces
`doc`	Documentation
`tst`	Test
`dpl`	Deploy / infra

Design Principles

One file. No config, no database, no server. Just a Markdown file in your project root.

Tool-agnostic. Works with any AI that accepts a system prompt.

Token-first. Every design decision optimizes for token efficiency.

Self-updating. Rule 2 makes the AI maintain the index automatically as the project grows.

Human-readable. Valid Markdown. Open, edit, and version-control it like any other file.

Get Started

The full project — including the CLI script, prompt templates for Claude/ChatGPT/Cursor, and a complete example — is on GitHub:

→ github.com/matteo-turri/foliodux

Open source. MIT license. Stars and feedback welcome.

Built this to solve my own problem while working on my projects. I'm 16 and based in Milan — if you try FolioDux, let me know what you think in the comments.

DEV Community