[onion2k]

When I started I first had a long discussion with the AI... and made a big Markdown file with a detailed architecture description.

Yep, that's how you get better output from AI. A lot of devs haven't learned that yet. They still see it as 'better autocomplete'.

[tossandthrow]

While this technique works for new projects, it takes no more than a couple of pivots for it to completely fail.

A good AI development framework needs to support a tail of deprecated choices in the codebase.

Skills are considerable better for this than design docs.

[troupo]

"It's just another Markdown file, bro".

LLMs do not learn. So every new session for them will be rebuilding the world from scratch. Bloated Markdown files quickly exhaust context windows, and agents routinely ignore large parts of them.

And then you unleash them on one code base that's more than a couple of days old, and they happily duplicate code, ignore existing code paths, ignore existing conventions etc.

[codebolt]

That's why I'm very careful about how the context is constructed. I make sure all the relevant files are loaded with the prompt, including the project file so it can see the directory structure. Also keep a brief summary of the app functionality and architecture in the AGENTS.md file. For larger tasks, always request a plan and look through it before asking it to start writing code.

[troupo]

Yup, we've become reverse centaurs :) https://doctorow.medium.com/https-pluralistic-net-2025-09-11...