Filename-as-Specification

A methodology for eliminating AI hallucination in code generation. The specification lives where the AI reads first — the filename itself. No ambiguity, no drift, no mass-deleting at 3am.

The problem

You write a detailed prompt. The AI writes confident code. The code doesn't match what you asked for. You correct it. It introduces new problems. Three hours later, you're mass-deleting and starting over.

The root cause is a tool-use ordering issue. The agent reads the filename first (in a directory listing, or in a tool call response, or in a patch header), then decides what to write into it. If the filename carries no signal, the agent fills the vacuum with a hallucination and commits to it before the file's actual content constrains its behavior.

The insight: put the specification where the AI sees it first — the filename. The AI cannot open the file without absorbing the complete specification. It can't miss it. It can't ignore it. It can't drift.

The anatomy of a FaS filename

user_sv_M0gM0hM0i_D01D04_I+rp0g+E0k+sc0g+E0h_E0m_V010_S2.py

  user       → Entity: User
  sv         → Layer: service
  M0gM0hM0i  → Methods: register, authenticate, get_by_id
  D01D04     → Dependencies: sqlalchemy, jwt
  I+rp0g...  → Internal imports: UserRepository, UserSchema
  E0m        → Export: UserService
  V010       → Version: 0.1.0
  S2         → Status: implemented

One string. Eight orthogonal axes. Parseable both by humans and by a deterministic grammar. The agent reads this filename before writing a single line of the body — and the body it writes is constrained by everything the filename already told it.

The four roles

• ARCH-AGENT — Translates requirements into FaS filenames. Given "a user service with register, authenticate, and lookup", it produces user_sv_M0gM0hM0i_D01D04_E0m_V010_S0.py. Status S0 = unimplemented.
• CODE-AGENT — Reads the filename, implements exactly what it demands, writes the body. Status advances from S0 → S1 (in-progress) → S2 (implemented).
• VALIDATOR — Runs a six-phase pipeline: syntax → completeness → dependency resolution → import chain → export compliance → cross-file consistency. Each phase has to pass before the next runs. Errors are reported with the filename that failed.
• ORCHESTRATOR — Walks a specification tree of FaS filenames and drives the pipeline end-to-end. Hands-off code production from a filetree.yml that only contains names.

Domain matrices

A matrix is a lookup table that maps the compact FaS codes into human-readable concepts for a specific domain. Six matrices ship with the system, and there's a template for building your own.

• REST API — Routes, middleware, controllers, services, repositories. Method codes for CRUD, auth, search, pagination, file upload, webhooks.
• React / Next.js — Components, hooks, providers, pages, layouts. Props, state, effects, context, server actions.
• Python CLI — Commands, arguments, options, subcommands. Click/Typer patterns with validation, prompts, and output formatting.
• Game Development — Entities, systems, components. Physics, input, rendering, AI. ECS architecture expressed in filename form.
• Data pipelines — Sources, transforms, sinks, schedules. DAG edges implied by import codes.
• Infrastructure — Containers, services, volumes, networks. Terraform-style resources as files.

The MCP server

A Model Context Protocol server that gives Claude Desktop native FaS capabilities. Install once and Claude gains permanent access to four tools: parse_fas, generate_architecture, validate_tree, and matrix_lookup. No copy-paste, no context-window pollution, no fragile system prompts.

The server is stateless and reads a local matrices/ directory so you can drop new domain matrices in without restarting it. It streams validation results via MCP's progress protocol so long-running validator phases don't hang the agent.

Why it works

• It exploits token-order attention. The filename is read before the body. By the time the agent sees the body, the filename has already anchored its generation.
• It's deterministic. The grammar is regular. Parse errors fail fast. No "close enough" matches.
• It's human-legible. Once you know the matrix, you can read an entire architecture from a ls -la.
• It composes. Internal-import codes encode the dependency graph as part of the filename, so the validator catches cycles, missing exports, and broken imports without running the code.
• It's portable. Works with any agent that reads filenames — which is all of them.

I built this because I was mass-deleting AI-generated code at 3am one too many times. The insight was stupid-simple: put the spec in the filename. Everything else is refinement of that core insight.

Get it

One package on Gumroad — $100. Everything: the methodology document, all six domain matrices, the three agent prompts, the six-phase validator, the MCP server, the orchestrator, and the matrix-builder template for rolling your own.

→ Get Filename-as-Specification on Gumroad