{"slug": "the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself", "title": "The AI Coding Workflow That Finally Stopped Making Me Repeat Myself", "summary": "A developer has created a reusable system of Markdown files to help AI coding agents retain project context across sessions. The system splits guidance into four files—AGENTS.md, OVERVIEW.md, MEMORY.md, and ERRORS.md—each answering a different question about how to work, how the project works, why it is built that way, and what has failed. The developer reports that this separation has significantly improved agent performance and has released a cleaned-up version as a reusable repository.", "body_md": "I use AI coding agents a lot.\n\nAnd for a while, one of the most annoying parts had nothing to do with whether they could write code.\n\nIt was that every new session felt like working with someone who had technically read the project but had absolutely no idea what had happened before.\n\nThe code tells an agent a lot.\n\nIt can see the structure, inspect the functions, trace the data flow, read the package.json, and figure out what the application does.\n\nWhat it usually cannot see is everything around the code.\n\nWhy did I choose this approach instead of that one?\n\nDid I already try that library?\n\nWas this weird-looking piece of code deliberate?\n\nDid another agent already spend two hours debugging this exact problem?\n\nDid I specifically say three sessions ago that I do **not** want that abstraction added?\n\nThat information tends to disappear between sessions unless you deliberately give it somewhere to live.\n\nSo over time, I ended up building a little system around that problem.\n\nAnd because it has been working really well for me, I cleaned it up, removed anything project-specific, made some fictional examples, and put the whole thing into a reusable repo.\n\nI already had an `AGENTS.md`\n\nfile with the usual project rules.\n\nThings like:\n\nBasically, all the stuff I got tired of repeating.\n\nThat helped a lot.\n\nBut eventually I realized I was trying to make `AGENTS.md`\n\ndo too many jobs.\n\nThere is a difference between:\n\nHere is how I want you to work.\n\nand:\n\nHere is why this project works the way it does.\n\nAnd there is another difference between both of those and:\n\nWe already tried this. It exploded. Please do not make us learn this lesson again.\n\nSo I split them apart.\n\nThe system ended up with four Markdown files, each answering a different question.\n\n| File | What it answers |\n|---|---|\n`AGENTS.md` |\nHow should the agent behave while working here? |\n`OVERVIEW.md` |\nHow does the project work right now? |\n`MEMORY.md` |\nWhy is it built this way, and what alternatives did we reject? |\n`ERRORS.md` |\nWhat already failed, and what worked instead? |\n\n`AGENTS.md`\n\nstays at the root.\n\nThe other three live in `/DOCS`\n\n.\n\nAnd that separation turned out to matter a lot more than I expected.\n\n`OVERVIEW.md`\n\nis basically the technical map.\n\nIt can contain things like:\n\nThe important part is that it describes **now**.\n\nIt is not a development diary.\n\nIf the project stops using one database and starts using another, I do not append:\n\nUpdate: we no longer do this.\n\nI change the documentation so it reflects what is currently true.\n\nThat gives an agent somewhere to start before it starts wandering through the codebase trying to reconstruct the entire application from scratch.\n\nThis is where things got much more useful for me.\n\n`MEMORY.md`\n\nis not a list of everything that happened.\n\nIt is specifically for decisions where the reasoning might otherwise disappear.\n\nSomething like:\n\nWe save the record before doing metadata extraction because the user's primary action should succeed even if the remote site times out.\n\nAnd then I can record the alternative that was rejected and why.\n\nNow a future agent does not look at that flow and decide:\n\nHuh. This seems backwards. I'll clean it up.\n\nIt knows that the order is deliberate.\n\nThat is the kind of context code usually cannot give you.\n\nA good test I use is:\n\n**Could a competent developer look at this code later and reasonably change it back because they do not know why we chose it?**\n\nIf yes, it probably belongs in `MEMORY.md`\n\n.\n\nIf it is just:\n\nAdded the settings page.\n\nThat is a changelog entry. It does not need memory.\n\nThis one is probably self-explanatory.\n\nBut I also did not want it turning into a bug tracker.\n\nNormal bugs happen. You find them, fix them, move on.\n\n`ERRORS.md`\n\nis for the ones that cost enough time that I really do not want the next agent repeating the whole adventure.\n\nThings like:\n\nThe entry records:\n\nThen the next time something similar happens, the agent can check that before starting from zero.\n\nAt first, I think the obvious temptation with something like this is to document everything.\n\nThat would completely ruin it.\n\nIf `MEMORY.md`\n\nbecomes a changelog, nobody wants to read it.\n\nIf `ERRORS.md`\n\nbecomes Jira in Markdown, the useful failures disappear into hundreds of boring bugs.\n\nIf `OVERVIEW.md`\n\nbecomes a running history of every architecture change, you no longer know which parts describe the current application.\n\nSo I ended up with a pretty high bar for adding things.\n\nFor `OVERVIEW.md`\n\n:\n\n**Did this change make something in the document incorrect or incomplete?**\n\nFor `MEMORY.md`\n\n:\n\n**Was there an actual decision here that someone might reasonably reverse later without knowing the reasoning?**\n\nFor `ERRORS.md`\n\n:\n\n**Was this painful or surprising enough that someone could waste serious time rediscovering it?**\n\nIf not, nothing gets added.\n\nThat might be one of the more important parts of the whole system.\n\nContext is only helpful while there is still a reasonable amount of it.\n\nI tried the giant-instruction-file direction.\n\nI do not love it.\n\n`AGENTS.md`\n\nis usually part of the context every session, whether all of its contents are relevant or not.\n\nIf it contains every project decision, every debugging lesson, every architecture detail, every writing rule, every release procedure, and every random preference I have accumulated over six months, it becomes a giant wall of instructions competing with the actual task.\n\nIt also mixes information that behaves differently.\n\nBehavior rules are fairly stable.\n\nArchitecture changes.\n\nDecision history grows.\n\nDebugging history grows in a completely different way.\n\nSo now `AGENTS.md`\n\nmostly tells the agent **where to look and how to behave**, instead of trying to contain the entire project brain.\n\nThis was the piece that made the system feel more complete.\n\nI created a `project-context`\n\nskill that teaches the agent how to use these files instead of relying on the agent to guess.\n\nIt covers things like:\n\n`MEMORY.md`\n\ninstead of dumping all 700 lines into contextOne rule I especially like is:\n\n**The code wins as a description of what happens. The documentation wins as a description of what was intended.**\n\nIf those two disagree, that is useful information.\n\nThe agent should not blindly trust stale docs, but it also should not assume the current code represents the intended design.\n\nAnd if I ask for something that `MEMORY.md`\n\nsays we already rejected, the agent should not just refuse to do it.\n\nReasons expire.\n\nBut it should tell me:\n\nWe previously rejected this for X reason. Do you still want to change it?\n\nNow the reversal is deliberate instead of accidental.\n\nThis part is slightly separate from the context system, but it fits into how I use coding agents.\n\nI have a `clear-writing`\n\nskill for documentation, READMEs, setup instructions, error messages, release notes, and other project writing.\n\nOne thing that kept bothering me was agents applying the same writing style to everything.\n\nA setup guide should be boringly clear.\n\nA README opening should not sound like a Boeing maintenance manual.\n\nSo the skill first determines what kind of writing it is.\n\nInstructional writing gets stricter rules around sentence structure, terminology, and ambiguity.\n\nWriting that is supposed to have an actual voice gets different rules so it does not turn into the usual polished-but-weird AI prose.\n\nIt is not necessary for the context system itself, but since I use both together, I included it.\n\nBefore an agent changes an existing project:\n\n`OVERVIEW.md`\n\nto understand the current system.`MEMORY.md`\n\nfor decisions related to the thing being changed.`ERRORS.md`\n\nif the task involves debugging or an area that has caused trouble before.Then do the work.\n\nAfterward:\n\n`OVERVIEW.md`\n\nif anything in it became untrue.`MEMORY.md`\n\nonly if a real decision was made.`ERRORS.md`\n\nonly if the failure is actually worth remembering.It is basically:\n\n**Read before changing. Write after learning.**\n\nThere is no vector database.\n\nNo embeddings.\n\nNo background memory agent.\n\nNo separate service.\n\nNo database at all.\n\nIt is Markdown.\n\nThat is kind of the point.\n\nI have built RAG systems and memory layers before, and those absolutely have their uses.\n\nBut I did not need any of that for this problem.\n\nI just needed important project knowledge to survive longer than one coding session.\n\nPlain files are searchable, editable, version controlled, easy for humans to read, and easy for coding agents to use.\n\nGood enough.\n\nA small system for giving AI coding agents the project context they cannot get from reading the code alone.\n\nCode can tell an agent what exists. It usually cannot tell it why something was built that way, what already failed, which alternatives were rejected, or how you want the agent to behave while working in the repository.\n\nThat is what this kit is for.\n\nIt is four Markdown files with separate jobs, plus two skills that teach an agent how to actually use them. Copy the parts that make sense for your workflow, change whatever does not, and ignore the rest.\n\nThis is not an AI memory service, vector database, RAG system, or autonomous memory framework. It is just a lightweight repository convention for keeping useful project context in plain Markdown.\n\nAn agent starts a session knowing nothing about your project except what it can…\n\nOnce I realized how much I was relying on this setup, I figured it might be useful to other people too.\n\nSo I made a generic version of my `AGENTS.md`\n\n, removed my personal project rules, and created templates for the supporting docs.\n\nI also made a fictional project called **Lantern** and filled out example versions of `OVERVIEW.md`\n\n, `MEMORY.md`\n\n, and `ERRORS.md`\n\n.\n\nThat seemed more useful than giving people three completely empty files and saying:\n\nOkay, now document your architecture.\n\nThe examples show what these files can look like after a project has actually been worked on for a while.\n\nThe repo also includes the two skills and their templates/reference material.\n\nYou might only want `MEMORY.md`\n\n.\n\nYou might already have architecture docs and just want the debugging log.\n\nYou might hate my folder structure.\n\nYou might use a completely different agent workflow.\n\nThat is fine.\n\nThe thing I think is useful is the separation:\n\n**behavior**\n\n**current state**\n\n**decisions**\n\n**failures**\n\nOnce I stopped treating all of that as one giant blob of \"context,\" my coding sessions got noticeably less repetitive.\n\nAgents stopped suggesting some of the same rejected ideas.\n\nI had to explain fewer architectural decisions again.\n\nAnd when something ugly had already been debugged once, there was finally somewhere useful to put that knowledge.\n\nMostly, I built this because I was tired of repeating myself.\n\nIt turns out Markdown is pretty good at remembering things.\n\nI find this much more useful than another \"Agent Memory\" MCP server or database.\n\nI'd be interested to hear what you think and if you have suggestions to improve this.", "url": "https://wpnews.pro/news/the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself", "canonical_source": "https://dev.to/sizzlebop/the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself-8ol", "published_at": "2026-09-03 20:56:56+00:00", "updated_at": "2026-09-03 21:54:02.167531+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself", "markdown": "https://wpnews.pro/news/the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself.md", "text": "https://wpnews.pro/news/the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself.txt", "jsonld": "https://wpnews.pro/news/the-ai-coding-workflow-that-finally-stopped-making-me-repeat-myself.jsonld"}}