Decisions That Stick
The Scenario
You're building a multi-tenant app. Early on, you and your AI weigh Postgres against MySQL and pick Postgres, for one reason that matters a lot: row-level security, so every query is scoped to its tenant by the database itself.
Decisions like that are easy to make once and expensive to make twice. Weeks later, in a fresh conversation, an agent that doesn't know why you chose Postgres will happily suggest something else.
The Decision, in Claude Code
fai is running in the repo. In Claude Code:
You:
"Postgres or MySQL for this? Tenants must never see each other's rows."
Your AI:
"Postgres. Row-level security lets the database enforce tenant isolation on
every query, so a missed WHERE clause can't leak data. MySQL has no
equivalent; you'd enforce it in application code."
You:
"Postgres it is. And JWTs for auth, so sessions stay stateless."
Where It Lands
fAI captured the conversation. After synthesis, your FAI-PROJECT.md has entries
like these (illustrative):
## Key Decisions
### Postgres over MySQL
- **Decision:** Use Postgres for all tenant data.
- **Rationale:** Row-level security enforces tenant isolation in the database,
so a missing filter in application code can't leak another tenant's rows.
### JWT for auth
- **Decision:** Authenticate with JWTs.
- **Rationale:** Sessions stay stateless.
The rationale is kept with the decision. That's what makes it useful later: the next agent gets the reason, not just the answer.
Weeks Later, in Cursor
You're adding a reporting service. You're in Cursor, in the same repo. Its rules
file already points at the same FAI-PROJECT.md.
You:
"Set up the data layer for the reporting service."
Your AI:
"Using Postgres to match the rest of the project, with row-level security
policies on the reporting tables so tenant isolation holds here too. Auth
reads the existing JWT. Want the policies in a migration?"
Without that entry, a reasonable agent might have reached for whatever it considers a sensible default. With it, the new service starts from the decision, and from the reason for it.
What fAI Did, and Didn't
- Did: capture the decision and its reason, file them under Key Decisions, and point every detected agent at them, in whichever tool you opened next.
- Didn't: make the choice, or stop you changing it. If you move off Postgres later, that conversation is captured too, and the next synthesis pass rewrites the entry.