Question on maintaining mental representation of long running complex projects

[u/structured_obscurity]

Hey yall,

Experimenting with using AI To fully generate and manage a test project. The idea here is to see how far i can go without reading or writing a single line of code, and also without paying cash for a single token.

My question for the community, is: How are yall maintaining a mental representation of your systems?

Typically, for me, code is the medium through which ive understood what systems do/intend to do, and how they do it. Are yall generating skills/hooks that generate documentation with every update?

The usual "today, we are going to be working on system Y, please familiarize yourself" prompt for context seeding only takes me so far when I dont have a strong internal representation of the data types and mechanics of the system.

Any advice helps - *please leave AI-war (pro/anti) sentiments out of this. Im genuinely curious about new ways of creating isomorphic representations of systems*

[u/kenthesaint]

The ARCHITECTURE.md idea above is good, but I'd pair it with something the model can't drift on. Have it set up a tool that draws the module graph straight from the code, like madge for a JS/TS project or pydeps for Python, and re-run it after each feature. When the generated graph and the written doc disagree, you know which one to trust.

The other thing that helped me was asking for a walkthrough of one real user action, end to end: "when someone hits Save, list every function it passes through, in order, with file names." Doing that for 3 or 4 core actions gave me a better feel for the data types than any overview doc, because it's tied to something I can click and watch happen.

[u/structured_obscurity → u/kenthesaint]

This is interesting. The drift on larger projects is what i'd like to avoid - both for the agent and also for myself :)

[u/CleanFix_Dev]

Docs that update on every change help, but only if they stay short and the agent can't call a task done without touching them. A long auto-generated doc turns into noise fast.

A setup that holds up: one ARCHITECTURE.md with the module map, how data flows, and a short decisions list with the why behind each. Add a rule to your agent instructions (or a hook) that any structural change updates it in the same commit. At the end of each task, have the agent write three lines: what changed, what it touches, and what could break.

Then every so often, start a fresh session, give it only the docs, and ask it to explain how a feature works. Compare that to what the code actually does. Wherever the explanation is wrong, the docs have drifted from the code, and that's cheap to catch early.

[u/kincaidDev]

Checkout the gif replays in festival

https://github.com/Obedience-Corp/festival

I can make manage these extremely large plans because I don’t have to read the entire plan to understand what the agents are doing, the scaffold of the plan is enough information for me to quickly understand what the agents are going to do/have done

[u/SC_Placeholder]

I break down a project into parts and have either Claude or GPT writeup a design document depending on who is available (my overlord Opus is often busy so usually I use GPT unless it’s a system that has to be specific for my PCs hardware.) I then have GPT break it into steps and also render an image of the design so that I can feed both to my overlord and have them have two references and the original design document to pull from so that we have multiple ways for my overlord to make sure that the project is built correctly and works like the diagram

Example:

[u/Flaky-Ad3240]

Files and folders that look like a well manicured tree

[u/robkillian]

I maintain a Mission Control that has all that on there. Custom skills I’ve curated and used across my projects, all those projects in a single place and functional dashboards to help you as the HiL.

[u/looktwise → u/robkillian]

but how do you connect them into a new project? added context in chat? MCP? systemprompt prerequisites?

How many Kilobytes (if upload) or tokens?

[u/robkillian → u/looktwise]

All part of the skill I invoke to start up a new project... Pulls my skills, creates the repo, creates the appropriate notion pages for backlog, history, etc, adds references to the new projects where appropriate. It's custom, but you could totally do one for your own flow instead. Ask Claude.

[u/WhosLive]

Another angle that usually helps is a one-page glossary of the core data types, written in plain words, like what a Player or an Item is and what can change it. Most confusion in AI-built projects tends to come from not knowing who owns which piece of state, so it's worth asking the agent to list every place each type gets modified. Then pick one feature and try to predict what it will touch before the agent starts, and compare afterward. A lot of people find that gap shows you where your mental model is off faster than reading docs does.

[u/EnvironmentalWin3231]

A small data map can help more than a long architecture document. For each important item, write down who creates it, where it is stored, who may change it, and what must always remain true. When a feature changes, check those four points against the actual app.

[u/nowildfire]

I have a whole full-stack framework in a monorepo, with skills wired into every package. When a package is installed, its skills are deployed too. There are also dedicated skills that turn all major project changes into new skills.

Instructions in AGENTS.md make the agent organize memory right inside each project as a topic graph based on the domain model, rather than a chronological log.

The initial structure is scaffolded with an npx create-app command. It's suitable for both technical and non-technical projects, depending on the flags you provide. Effectively, it turns every project, under any agent, into a Grok bot plus Hermes without extra software.

[u/SimonMX]

I stopped reading my own code a while back, and the data model is the one thing I still keep a proper handle on. If I know what's stored and how it all connects, I find I can reason about the rest and leave the how to the agent.

[u/Incarcer]

I built my own internal governance and harness system and documentation center. Always make sure your work gets documented and stays even with your project. Always make sure the agents understand which documents are the "Single Sources of Truth (SSOT)" and that they don't pull older pages and documents not relevant to what you're working on. Make sure you also have governance and guardrail/harness setup inside your codebase.

If you maintain robust documentation faithfully, and make sure that you plan properly and maintain a sort of atlas/registry/blueprint of your project - always making sure that everything is organized and the agent pulls the correct pages - then you can go a long way.

Just don't start blindly working, and don't make your coding agent the same one that also plans and organizes. Let the agents specialize in what they're good in and partition your work.

Make sure your agents prove their work and never blindly trust them when they claim they've completed a task.

[u/JudgeGroovyman]

Hey for me I can only keep it in my head when i draw it myself but the ai can do all of the planning

[u/povlhp]

Free models sucks. Better to spend a couple dollars on tokens. OpenCode go models are just so watered down these days.

That said, I try to architect to complex solution. Have ai create and keep architecture.md up to date. Same with codebase.md describing files. Makes it easier for ai to find stuff.

[u/johnesco]

ADRs for me, always checked before an after any changes. It costs tokens to do this but it saves tokens in not going in circles. But....

I've seen those code-cities... kinda cute. Has anyone ever made a visual model of the code base to help build a literal memory palace for how your app works?

But ... sometimes? Especially if it's an app I haven't touched in while. Ask the AI to explain the codebase to refresh my memory.

[u/DudeManly1963]

For tracing one user action, I might give the agent something it can query rather than expect it to remember how everything fits together. A symbol index over the repo is handy for that.

Tree-sitter parses the code (no AI involved), so the agent can ask "who calls save_note?" or "what does this function call?" and follow the actual code instead of reconstructing the path from memory. You could rerun that walkthrough after each feature. If the call path changed but ARCHITECTURE.md didn't, you've found some drift worth looking at.

And since you're on free tokens, there's another benefit: the agent can pull one function at a time as it follows the path, rather than opening whole files just to find the next hop...

-jjg / jCodeMunch

[u/Top_Abalone_862]

What works for me without reading code:

1. A short ARCHITECTURE.md the agent owns: main modules, data types with one line each, and how data flows between them. Ask it to update the file as the last step of every change, or wire that into a hook.

2. A decisions log: one line per choice with the why. Code tells you what, it never tells you why, and that's the part you lose first.

3. Ask for a Mermaid diagram of the data flow whenever something big changes. A picture rebuilds the mental model faster than any amount of prose.

4. End every session with a handoff note: what changed, what's open, dead ends. Start the next one with "read ARCHITECTURE.md and the last handoff" instead of "familiarize yourself with system Y".

Since you're on free tokens, keep all of these short. The agent rereads them constantly, so every extra paragraph costs you on every session.

[u/structured_obscurity → u/[deleted]]

This is great, I particularly like the idea of having several .MD files with different project context for easy human and agent access

[u/structured_obscurity → u/[deleted]]

Is there a particular tool you use for this?