Faf Teacher

The Core Explanation

The 32-Minute Problem

Start with the pain point:

Before project.faf: You open a new AI conversation. You drop in a file. AI asks:

• "What does this project do?"
• "What's the architecture?"
• "What framework are you using?"
• "What's the testing strategy?"
• "Where are the main files?"

20 questions. 32 minutes wasted. Every. Single. Session.

With project.faf: AI reads one file. Complete context in <1 second. Zero questions. Ready to work.

That's the difference.

What FAF Actually Is

FAF = Foundational AI-context Format

It's an IANA-registered Internet standard (like PDF, JSON, XML):

• Official Media Type: application/vnd.faf+yaml
• Registration Date: October 31, 2025
• Authority: Internet Assigned Numbers Authority
• Status: Recognized foundational infrastructure

Not a tool. Not documentation. Foundational infrastructure.

The Three Components

1. project.faf (The File)

• Lives in your repository root (next to package.json, README.md)
• Contains your project's "DNA" - architecture, purpose, stack, testing
• Format: YAML (human-readable, machine-readable)
• Size: Typically 50-200 lines
• Updates: Rarely (only when architecture changes)

2. The Reading Order (The Philosophy)

AI reads in optimal order:
1. project.faf     → Project DNA (WHAT it is)
2. CLAUDE.md       → Workflow (HOW to work here)
3. README.md       → Documentation (HOW humans use it)
4. package.json    → Dependencies (WHAT it needs)
5. Config files    → Build settings (HOW to compile)
6. Code            → Implementation (WHAT it does)

Why this order?

• Architecture BEFORE implementation
• Context BEFORE code
• Complete picture BEFORE details

3. AI-Readiness Score (The Measurement)

• 0-100% score showing how well AI understands your project
• Podium tiers: 🏆 Trophy (85%+), 🥇 Gold (70%+), 🥈 Silver (55%+), 🥉 Bronze (40%+)
• Improvement guidance: "Add testing info to reach Gold"
• Measurable progress: 45% → 72% → 89%

Why It Matters

The Cost of No Context:

• Time: 5-30 min per session reconstructing context
• Accuracy: AI guesses wrong, suggests bad patterns
• Frustration: Repeat yourself every conversation
• Money: 10-person team = 2,083 hours/year wasted = $100k+

The Value of project.faf:

• Time: <1 second to complete context
• Accuracy: AI knows your exact architecture
• Persistence: Context survives forever, all tools
• Money: ROI of 6,444% (Anthropic research, Oct 2025)

Real Numbers (Verified)

From Anthropic's research (October 2025):

• 73% reduction in repetitive prompt engineering
• Average ROI: 6,444%
• Payback period: <3 weeks
• Token efficiency: 99%+ savings (30-50 tokens vs tens of thousands)

How It Works

Step 1: Generate

faf init

Creates project.faf in <50ms by detecting:

• Project type (web app, library, API, CLI)
• Language (TypeScript, Python, Rust, Go)
• Framework (React, Next.js, Svelte, Django)
• Dependencies, testing, architecture

Step 2: Score

faf score

Shows AI-readiness: "🥈 Silver (58%) - Good foundation"

Step 3: Enhance

faf enhance

Guided improvements: "Add testing info", "Document architecture"

Step 4: Use

• Drop project.faf into ANY AI conversation
• Claude, Cursor, Gemini, Codex, Windsurf, Warp all read it
• Context loads in <1 second
• Zero questions, instant understanding

Common Questions & Answers

"Isn't README.md enough?"

No. Different jobs:

Example:

• README: "Run npm install to get started"
• project.faf: "TypeScript React app with Next.js 14, uses App Router, targets Node 18+"

README explains usage. project.faf explains architecture.

"What about CLAUDE.md?"

CLAUDE.md is workflow. project.faf is architecture.

They work together:

1. project.faf: "This is a Next.js app with TypeScript strict mode"
2. CLAUDE.md: "Always run tests before committing. No exclamation marks in commits."

The Reading Order: project.faf THEN CLAUDE.md

"Why YAML and not JSON?"

YAML is human-friendly:

# YAML (easy to read and write)