Tables Beat Paragraphs: Structuring a CLAUDE.md That Claude Can't Misread

Claude scans your CLAUDE.md the way you scan a dense paragraph at 2 a.m., which means it misses things. That is the premise of part 10 of Vibe Academy's CLAUDE.md Pro Tips series, and the fix it proposes is structural rather than about what you write. Rules buried in prose get extracted imprecisely. Rules laid out in tables get pattern matched at a glance. The video backs this with a real example from the creator's own website repo.

The 2 a.m. Reading Problem

The video's core claim is that Claude does not read your CLAUDE.md carefully. It skims, the same way a tired human skims dense documentation late at night. When a rule lives inside a prose paragraph, the model has to work to extract it, and under attention pressure it extracts less precisely. The longer and denser the paragraph, the more likely the rule comes out mangled or gets skipped entirely. The on-screen card labels this tip "Structural Clarity" and states the principle in four words: tables beat paragraphs.

The Standard Vocabulary Table

The concrete example comes from the creator's website repo, a section called Standard Vocabulary. It is a table with three rows, and each row maps a category to the only terms allowed for it, shown on screen under the header "Terms -- only these, no synonyms":

Category	Allowed terms
Decisions	GO / NO-GO / CONDITIONAL
Status	On Track / At Risk / Blocked
Effort	S / M / L / XL

There is no prose around it and no explanation, just the mapping. As the video puts it, that table is impossible to misread. Claude can see in one glance that a status must be On Track, At Risk, or Blocked, with no room to invent synonyms like "in progress" or "delayed."

Less Like a README, More Like a Spec

The takeaway the video lands on is a shift in how you think about the file. A README explains things to a human who has time and context. A CLAUDE.md should encode rules for a model that skims. The on-screen summary compresses the benefit into three phrases: less prose, less ambiguity, less re-reading. Anywhere you have a paragraph explaining a convention, ask whether it could be a table row mapping a category to its allowed values.

Where This Fits in the Series

This is tip 9 on the slide (card 10 of 11) and lesson 10 in the CLAUDE.md Pro Tips series from Vibe Academy. The video closes by teasing the final installment: one last tip plus a checklist that consolidates all nine prior tips, so you never have to hold them all in your head at once. The full series is free at vibe.academy.

Key Takeaways

• Claude skims CLAUDE.md files the way humans skim dense docs, so rules in prose get extracted imprecisely.
• Tables let the model pattern match rules at a glance instead of parsing paragraphs.
• A Standard Vocabulary table maps each category to its only allowed terms: Decisions (GO / NO-GO / CONDITIONAL), Status (On Track / At Risk / Blocked), Effort (S / M / L / XL).
• Include only the mapping, with no surrounding prose or explanation.
• Structure your CLAUDE.md as a spec of constraints rather than a README that explains.

Resources

• Vibe Academy -- the creator's free AI education site hosting the CLAUDE.md Pro Tips series