Here's a pattern that'll be familiar if you've coded with an AI agent for more than a week.
Monday, it hits a strange error. It tries six things, finds the real fix, and you move on. Thursday, a new session, the same error. It tries the same six things in the same order.
The model doesn't remember Monday. It never will. Every session starts from zero.
So ParkEase has a file called learnings.md, and the first instruction in the project file is to read it before every task. By the end of the build it had 246 entries across 1,550 lines.
Not documentation. Not "how the system works"; the code and the architecture records cover that. learnings.md holds one specific kind of knowledge: non-obvious fixes that cost real time to find.
Each entry is a heading that states the lesson, then the symptom, the cause and the fix. A few real ones:
React version alignment is mandatory. When workspace packages use different React versions, pnpm hoists the newer one to root. Packages depending on the older version get nested copies in their own node_modules, causing the classic "two React instances" crash at runtime.
A Metro dev server degrades after repeated reloads, and looks exactly like a broken app. A few navigations in, every route rendered an empty root with zero console errors.
That second one is worth its weight in gold. Without it, an AI sees a blank screen with no errors and starts "fixing" code that isn't broken.
pip install --user for a dev tool broke three unrelated tools. It put 47 packages into the shared user site-packages and shadowed the system copies of three libraries.
A tool installer will rewrite your context files — diff before trusting it. One installer wrote into the root CLAUDE.md, created a second context file, registered two hooks and edited .gitattributes.
Read the headings alone and you get a map of every trap the project fell into.
A 1,550-line file could easily become noise. Four habits kept it sharp:
1. Title it as the lesson, not the topic. "Metro" is a topic. "A Metro dev server degrades after repeated reloads, and looks exactly like a broken app" is a lesson; reading the heading alone is enough.
2. Write the symptom the next person will actually see. "Empty root, zero console errors" is what you'd search for in the moment. Nobody searches for the cause; they don't know it yet.
3. Group by surface. pnpm, TypeScript, NestJS, Expo, testing, migrations, the agent harness itself. The AI reads the sections that touch its task.
4. Write it when it happens. Not at the end of the task, when the details are gone. A hook enforces this (post 12): a complex task that never touched the learnings file isn't allowed to finish.
It will figure it out, every time, at full price. A learnings entry turns a 40-minute debugging session into a 4-second read. Across a five-week build, that compounds into days.
There's a second effect I didn't expect: the file made the AI more cautious in the right places. An entry like "the graph answers what calls what, never what we're allowed to do" doesn't fix one bug; it stops a whole class of confident mistakes.
You don't need a framework. A markdown file, one line in your agent's instruction file saying "read learnings.md before every task", and the discipline to add an entry every time something costs you more than fifteen minutes.
Next: Jev, a model that answers with typed judgments instead of prose, and how I put it in front of my own prompts to pick the model and the skill. Honestly, including what it didn't do.
ParkEase is a peer-to-peer parking marketplace for India, built solo with Claude Code.
Code: https://github.com/Deonkar/parkease