Data Model First
Get the entities and relationships wrong, and the interface will feel off no matter how you tweak it.
Get the entities and relationships wrong, and the interface will feel off no matter how you tweak it. Changing the interface takes minutes; changing the data model means migrating everything already stored against it. It's the most expensive rework on the whole chain.
What you'll run into:
- The same information shows up inconsistently on two pages because it was stored twice
- You want to add a filter, but the field was originally crammed into a block of text
- You keep adjusting the interface, only to realize the data relationship is what's wrong
If you let the AI build pages directly, it derives data from the surface: when a page needs to show a customer name, it adds a customer-name field to the project table. Looks fine on one page—until a second page also needs the customer name, and the data starts forking. Define the model yourself; don't let the AI improvise it along the way.
How to define it
Write a content list and a scenario first, then walk through four steps:
| Step | What to do |
|---|---|
| Find the nouns | Circle the nouns in the content list and scenario: projects, customers, revision records, statements |
| Judge entities | Anything you can list, create, edit, and delete on its own is an entity; a property of an entity is a field |
| Define relationships | Ask pairwise: how many Bs can one A have, and how many As can one B have |
| Check for duplicates | If the same information appears in two tables, it should probably become its own entity |
Step three is the crux. A many-to-many relationship needs a join table: if one project can have many customers and one customer can have many projects, you need a third table recording which customer is on which project. The later you pin this down, the messier it gets, because it drags already-stored data along with it. er-wiki
The test for step two is the phrase "can be created, edited, and deleted on its own." If customers can be added, changed, and removed independently, they're an entity, not a field on the project table. This is exactly where deriving data from the interface fails: the page shows a customer name, so the name becomes a field on projects; when a second page needs the name too, it has to be stored again. Extract the "customer" entity first, keep only the customer ID on the project table, and both pages reference the same place—change it once, it changes everywhere.
Signals you got it wrong
- The same thing is stored in multiple places. Changing one means syncing several, and sooner or later you miss one. This is the most typical signal.
- Structured content stuffed into a single field. Store "Zhang Ming 138xxxx" as one string, and when you need to search by phone you have to re-parse it.
- A table full of empty fields nobody uses. It means two different kinds of things were forced into one table in the first place.
- Deleting one row triggers a cascade of problems. The relationships weren't defined clearly; after deleting a customer, the projects become orphans.
Soft delete deserves its own note: add a deletion flag instead of actually deleting. Users can recover from mistakes, and linked data won't suddenly break. It's cheap, and it turns deletion from an incident into an everyday operation.
Note for the AI
Keep this in the project docs and attach it every time the AI defines data structures:
Based on the content list and usage scenarios below, design the data model
first. Do not write the interface.
Content list: [paste the list]
Scenario: [who, when, doing what]
Please output:
1. An entity list. For each entity: fields, types, required or not, defaults.
2. Relationships between entities, marked one-to-one, one-to-many,
or many-to-many. Point out explicitly when a join table is needed.
3. A duplicate-storage check: is the same information present in
multiple entities? If so, explain why or suggest how to extract it.
4. A list of uncertainties, e.g. which entity a field belongs to,
which side of a relationship is the "many" side. Ask me one by one;
do not decide on your own.
5. Which fields may need to be searched or filtered later, and explain
why they can't be stuffed into one big text field.
Also: add created_at and a soft-delete flag to every entity.
Only write code after I confirm.
Point five prevents a common pitfall. To make the interface easier to write, the AI happily crams several pieces of information into a single field—and you only find out you can't split them apart when you need to filter. Having it justify this before touching code is far cheaper than reworking it afterward.