How to make your project model agnostic.

1 days ago | By Engineerisaac | Log in to view page count Public

Back to feed

Stop Building Projects That Only One AI Understands

A lot of people are using LLMs without really understanding what they are or how they work.

And, honestly, that hasn't mattered very much yet.

For most people, an LLM is basically an effort box.

You put something you don't want to do into the box, the machine does it, and you take the result.

Boss is happy.
Work gets done.
Nobody complains.

The problem starts when we move from tasks to projects.

Because now you're not asking an AI to write one function, fix one bug, or explain one error.

You're asking it to participate in something that might last weeks or months.

And that creates a very old engineering problem at an absolutely ridiculous speed.

---

We've Seen This Problem Before

Imagine an engineer works on a system for four years.

They know why everything exists.

They know which weird piece of code looks wrong but absolutely cannot be touched.

They remember the failed approach from two years ago.

They know why one service talks to another service in that bizarre way.

Then they leave the company.

Suddenly everyone realizes:

Half the system was stored inside Dave's head.

Now the team is digging through commits, Slack messages, tickets, comments, and ancient documentation trying to reconstruct what Dave knew.

AI-assisted development creates the same problem.

Except instead of happening after four years, it can happen Thursday afternoon.

Your bot has spent three days working through a problem.

It has accumulated context.

It understands what you've tried.

It understands the strange decisions you made.

It understands what you're trying to accomplish.

Then the conversation gets too large.

The model changes.

The service goes down.

You switch tools.

You start a new session.

And suddenly:

Dave left the company.

Except Dave was Claude.

Or ChatGPT.

Or Gemini.

Or whatever you're using next week.

---

The Solution Is a Framework

The answer isn't better prompting.

And it isn't stuffing increasingly ridiculous amounts of context into every conversation.

You need to build a framework around the project that the bots read.

Think of it as a skeletal system.

Before an AI starts doing meaningful work on your project, it should have somewhere it can go to understand:

- What this project is
- What we're trying to accomplish
- How we expect work to be done
- What important decisions have already been made
- Where additional instructions live
- What it should read before touching specific parts of the project

The framework becomes the project's institutional memory.

The conversation doesn't.

---

Start With One Root Markdown File

You don't need to build some enormous documentation system on day one.

Start with one Markdown file at the root of the project.

Call it whatever makes sense:

FRAMEWORK.md

PROJECT.md

AGENTS.md

CONTEXT.md

The filename matters much less than the rule:

Every bot reads this first. Every time.

This is the front door to the project.

It doesn't need to contain everything.

In fact, it shouldn't.

Its job is to give the bot the basic mental model of the project and point it toward additional instructions when they're needed.

A skeletal version might look something like this:

# Project Framework

## What This Project Is

Briefly explain what we're building and why it exists.

## Primary Goal

Explain what we're ultimately trying to accomplish.

## How To Work In This Project

- Read this file before beginning work.
- Understand existing code before replacing it.
- Don't introduce new dependencies without a reason.
- Don't make unrelated changes while completing a task.
- Test your work before declaring it complete.
- Update project documentation when your changes make it inaccurate.

## Project Structure

/src
Main application code.

/tests
Tests and validation.

/docs
Additional project frameworks and documentation.

## Child Frameworks

Additional instructions exist for specific areas.

Before working on architecture:
Read /docs/architecture.md

Before working on the API:
Read /docs/api.md

Before working on the frontend:
Read /docs/frontend.md

Before deployment:
Read /docs/deployment.md

## Current State

Briefly explain where the project currently stands.

## Important Decisions

Record decisions that future developers or agents should not
have to rediscover.

## Before Finishing A Task

- Verify the requested task actually works.
- Check for unintended changes.
- Run the appropriate tests.
- Update documentation if necessary.
- Leave enough context for another agent to continue the work.

That's it.

You now have a skeleton.

And the skeleton can grow with the project.

---

Let The Framework Create Child Frameworks

This is where the idea becomes powerful.

Your root framework doesn't need to explain every detail about everything.

It needs to explain where those details live.

Maybe your project eventually has:

FRAMEWORK.md

docs/
architecture.md
database.md
frontend.md
api.md
testing.md
deployment.md

Now the root framework can tell the bot:

If you're modifying the database, read database.md first.

Or:

If you're touching deployment, you must read deployment.md before making changes.

You are creating a hierarchy of context.

The bot doesn't need the entire history of the company dumped into its context window every time it fixes a button.

It needs the right context for the job it's doing.

The root framework gets it oriented.

The child frameworks teach it how to operate inside specific parts of the system.

---

The Bot Should Help Maintain The Framework

Here's another important part.

You shouldn't have to manually maintain all of this forever.

Make framework maintenance part of the bot's job.

Tell your agents:

If your work changes something described by the framework, update the framework.

Now documentation becomes part of completing the task.

If the bot changes how deployment works, deployment documentation should change with it.

If it introduces an architectural decision that future agents need to understand, that decision should be recorded.

If it discovers that an instruction is wrong, it should flag it.

The project slowly develops its own institutional memory.

---

Leave Breadcrumbs For The Next Bot

The goal is simple.

Where one bot stops, another bot should be able to start.

And it shouldn't have to be the same bot.

You should be able to work in ChatGPT today, Claude tomorrow, Gemini next month, and some local model six months from now.

The project itself should provide enough framing that a competent agent can walk in, read the instructions, inspect the current state, and start becoming useful.

That's what model-agnostic development should mean.

Your project shouldn't depend on the personality, memory, hidden context, or peculiar behavior of one model.

The intelligence required to operate the project should increasingly live with the project.

---

You're Still The Operator

There's a funny contradiction in AI development.

If you want to be lazy, you have to do more preparation.

You can delegate an incredible amount of execution.

But delegation without structure creates chaos.

If you blindly tell an AI:

Make this work.

It probably will.

That's actually part of the danger.

It may produce something that works perfectly on your machine today while being completely unusable by another developer tomorrow.

It may solve the immediate problem while making the larger system worse.

It may introduce dependencies nobody understands.

It may violate decisions another agent made yesterday.

It may build something that cannot survive outside the conversation that created it.

The AI accomplished exactly what you asked.

You just didn't give it enough of a framework to understand what "good" meant.

---

Build The Skeleton Early

Don't wait until your project becomes complicated.

That's when this gets painful.

Build the skeleton while the project is small.

Create the root framework.

Teach the bot to read it first.

Let that framework point toward child frameworks as the project grows.

Make maintaining those frameworks part of completing the work.

Record important decisions where the next agent can find them.

You're basically creating an onboarding system for an engineer who might arrive five minutes from now.

Because that's exactly what a new AI session is.

It's a new engineer walking into the room with absolutely no idea what happened before it got there.

Give it the framework.

Give it the breadcrumbs.

Give it the rules.

Then let it work.

The goal isn't to build a project your current AI understands.

The goal is to build a project the next AI can understand too.

Interactive Lab

Posts