Multi-Repo AI Governance

I spent weeks building AI context files. Half of them were lying.

Not intentionally. The files were accurate when I wrote them. Then things changed — stack updates, schema migrations, business pivots — and nobody updated the docs.

The AI kept reading the old context. I kept getting confident, wrong answers.

The worst part: I didn't notice immediately. The outputs looked reasonable. The errors were subtle. By the time I caught them, I'd already built on top of a false foundation.

That's the failure nobody talks about. Not "AI hallucinated" — it didn't. It read exactly what I gave it. The problem was that what I gave it was stale.

I was running five projects in parallel at the time — a hospitality site, a financial management app, a company site, a pitch deck, a personal portfolio. Each had its own AI context. Each drifted at its own pace. There was no system connecting any of it.

The first thing I built was the wrong thing: more docs.

More detail, more structure, more coverage. It helped for a week. Then those files started drifting too.

The second thing I built was closer: a trigger matrix. Every type of change — new route, schema update, new dependency, business model shift — mapped to the exact doc that must be updated. In the same PR. Not as a follow-up. The task is not complete until the docs reflect reality.

That stopped the drift on individual projects.

But propagating it across five repos exposed the next gap. Generic rules don't survive contact with specific domains. The financial app needed a data model doc. The hospitality site needed a portal spec. The pitch deck needed a verified-claims layer — because an investor asking "where does this number come from?" is not the moment to discover your context file was optimistic.

What I eventually understood: there are two types of context. Context that belongs in a shared template — ground rules, architecture patterns, health check cadence. And context that belongs in the repo — domain decisions, data anomalies, verified claims. Mixing them breaks both.

Most people who hit this problem assume they need better AI tools. What they usually need is better maintenance discipline.

The context file is not documentation. It's a contract between you and the model. When it breaks, the model doesn't warn you. It just keeps going.

If you're building with AI assistants across more than one project, the question worth asking now — before it costs you — is: who updates the context when something changes, and how do they know it needs updating?

Template is open source — link in the comments.

Sources

• ai-product-architecture-template (open source, GitHub): https://github.com/gtcuco-personal/ai-product-architecture-template