Data Shape: The Prerequisite To Good Prompts

Most "the AI made bad code" complaints are actually "I prompted without knowing my own data." The agent did exactly what you asked — on the data shape it imagined. Which wasn't your data shape.

Before any meaningful project, write down:

THE TABLES OR FILES YOU'RE WORKING WITH. Names. Sources. How they're updated.

THE COLUMNS IN EACH. Name, type (text, integer, date, boolean), whether it can be NULL, what the values mean.

RELATIONSHIPS. Which tables link to which other tables, by which keys. Draw it on paper if you have to.

ACTUAL EXAMPLE ROWS. Three to five real rows per important table.

DIRTY DATA. The rows that break your queries. The customer with two spaces in their name. The order with a negative quantity. The date that's "1900-01-01" because someone forgot to fill it in. The notes field that has a JSON blob inside it.

VOLUME. How many rows? Hundreds, thousands, millions? This determines whether you can use simple solutions or whether you need to think about performance.

VELOCITY. How often does the data change? Once a year, once a day, once a second? This determines your refresh strategy.

The deliverable: a one-page data shape document. Tables, columns, relationships, examples, edge cases, volume, velocity. Put it in your repo as data-shape.md. Reference it in your CLAUDE.md. Re-read it before any data-related prompt.

If you don't have this, your prompts are wishes. If you have this, your prompts are specifications.