TL;DR: CLAUDE.md is prose. You can't parse prose reliably. You can't score it. You can't sync it in 10ms. You can't validate its structure. project.faf is the foundation layer — structured, scored, synced. The MD sits on top and does what MDs are good at: giving instructions.

The Setup Everyone Does

You start a project. You create a CLAUDE.md. You write some prose about your stack, your goals, your conventions. Claude reads it. Things go well.

For about two commits.

What Happens Next

Your CLAUDE.md drifts. Not dramatically — slowly. You add a database. You swap frameworks. You refactor the auth layer. The CLAUDE.md still says "Express with JWT." You don't notice because it still mostly works. AI fills in the gaps with assumptions.

This is context drift. And it's invisible until it isn't.

The Problem With Prose

CLAUDE.md is prose. Free-form markdown. That means:

You can't score it. Is your context 60% complete? 90%? You have no idea.
You can't sync it. When your project changes, who updates the MD? You? When?
You can't validate it. Is the information in it still true? No way to check.
You can't diff it semantically. Two people edit it and there's no merge strategy — just conflicting paragraphs.
AI interprets it differently every time. Prose is ambiguous. That's a feature for humans. It's a bug for machines.

Try bi-syncing two markdown files. You're doing string surgery on free-form text. Good luck doing that in 10ms.

MDs Are Instruction Manuals

And instruction manuals are valuable. "Use this coding style." "Don't modify these files." "Always run tests before committing." That's what prose is good at — giving instructions.

But an instruction manual is not a foundation.

You don't build a house on the owner's manual.

What a Foundation Actually Looks Like

A foundation is structured. Parseable. Scoreable. Syncable.

# project.faf — structured, not prose
project:
  name: my-app
  goal: Real-time analytics dashboard
  version: 2.1.0

stack:
  language: TypeScript
  framework: React
  backend: Node.js
  database: PostgreSQL
  hosting: Vercel

21 slots. Each one filled, ignored, or missing. No interpretation needed. AI doesn't guess your stack — it reads it.

(filled + ignored) / 21 = your AI-readiness

At 55%, AI is flipping coins. At 100%, AI is optimized. You know exactly where you stand.

The Hierarchy

README.md    → Prose for humans
CLAUDE.md    → Prose for Claude (instructions)
project.faf  → Structure for ANY AI (foundation)

They're not competitors. They're layers.

project.faf is the foundation — structured data, scored, synced in 10ms, portable across Claude, Gemini, Grok, Cursor, any AI.

CLAUDE.md sits on top and does what it's good at: "Here's how I want you to work." Instructions. Preferences. Personality.

But without the foundation underneath? Those instructions are built on assumptions. And assumptions drift.

The Bi-Sync Proof

faf bi-sync

8 milliseconds. project.faf ↔ CLAUDE.md. Structured data flows into prose, prose references back to structure. Deterministic. Validated. No string surgery.

Now try that with two markdown files.

The Real Cost of No Foundation

Without structured context, every AI session starts with rediscovery:

AI re-discovers your project (wastes tokens)
AI asks questions you've answered before (wastes time)
AI makes wrong assumptions → rework (wastes hours)
Context drifts → compounding errors → project delays

$5,460/year per developer

Not a guess — a measurement. Read the full DAAFT analysis →

What To Do

You don't have to throw away your CLAUDE.md. Keep it. It's good at what it does.

Just give it a foundation.

bunx faf-cli auto

npx faf-cli auto

One command. Reads your project. Creates project.faf. Scores it. Syncs CLAUDE.md. Done.

Your CLAUDE.md is not a foundation. project.faf is.