Stopping Replit Agent from re-engineering your app every session (what worked for me)

Agent & Assistant
1

One important thing I learned early:

:backhand_index_pointing_right: By default, Replit will overwrite and summarize its own generated documentation over time.

That’s useful for keeping things concise, but it also means:

  • important details can get compressed away

  • subtle but critical facts can disappear

  • the agent may lose context across sessions

So if you want stable, long-lived reference context, you need to create documentation that the agent does not rewrite without your intent.

The problem I kept running into

Each new agent session would try to reconstruct the system from code:

:backhand_index_pointing_right: sometimes correctly
:backhand_index_pointing_right: sometimes subtly wrong

Example from one app:

It would always assume LocalMusicX.com dev and prod shared the same database
They don’t (separate Neon DBs)

Another example (even trickier)

In my other app, http://WordsYouKnow.app, the system supports:

:backhand_index_pointing_right: 5 Romance languages
:backhand_index_pointing_right: bidirectional learning (native → target AND target → native)

So the UI, lesson content, and prompts all depend on:

  • the learner’s native language

  • the target language they’re learning

Without context, the agent would repeatedly try to re-derive:

  • which language each part of the UI should be in

  • how lessons are localized

  • which direction the translation flow should go

That’s a lot of hidden logic to “rediscover” from code.

The fix: give the agent a persistent source of truth

Instead of relying on prompts or auto-generated docs, I built a small set of stable reference files.

Now I can say:

:backhand_index_pointing_right: “Please refer to the application localization documentation and implement…”

…and the agent stays aligned.

This has been an enormous productivity multiplier.

What I’m using for LocalMusicX.com

1. AGENT_NOTES.md (append-only, project root)

The most critical file.

Captures facts that are easy to get wrong and expensive to rediscover, like:

  • dev vs prod DB separation

  • venue calendars are the ONLY authoritative source for events

  • venue → event city cascade behavior

  • communication / coding preferences

Rule: append-only (never rewrite history)

2. docs/project-history.md

A full system snapshot:

  • tech stack

  • DB schema

  • frontend routes

  • backend services

  • major development phases

Gives a new session a map of the system before touching code.

3. docs/testing-reference.md

Keeps testing consistent:

  • test procedures

  • data-testid conventions

  • DB references

Helps the agent write reliable tests instead of guessing.

4. docs/future-development-goals.md

Prevents accidental conflicts with the roadmap.

Without this, the agent may:

  • implement features in the wrong way

  • or conflict with planned architecture

5. Session scratchpad (in conversation context)

For temporary but critical knowledge:

  • in-flight bugs

  • edge cases

  • implementation quirks

  • ordering rules / gotchas

Examples:

  • route shadowing rules

  • early-return ordering

  • specific React warnings

Doesn’t belong in permanent docs—but essential during multi-session work.

The result

  • far fewer incorrect assumptions

  • less re-explaining context

  • more consistent changes across sessions

  • fewer regressions

My takeaway

AI agents don’t maintain a stable mental model of your system.

:backhand_index_pointing_right: If you don’t provide one, they will keep rebuilding it
:backhand_index_pointing_right: And sometimes rebuilding it wrong

And if your docs are being auto-summarized, that model can drift even faster.

Curious how others are handling this

  • Are you maintaining an AGENT_NOTES.md or similar?

  • How do you protect critical context from being overwritten?

  • Do you rely on prompts or persistent docs?

Feels like this is becoming a core discipline for AI-assisted development.

1 Like
2

Wrote about this exact problem back in January. Same conclusion, different implementation.

Here’s the actual prompt I run to generate the /docs layer: Notion

The enforcement block in replit.md is the part most people skip. Docs are useless if Agent doesn’t read them on session start.

1 Like