𝗧𝗵𝗲 𝗥𝗲𝗽𝗼 𝗜𝘀 𝗧𝗵𝗲 𝗖𝗼𝗻𝘁𝗲𝘅𝘁: 𝗪𝗵𝘆 𝗔𝗴𝗲𝗻𝘁𝘀 𝗗𝗼𝗻’𝘁 𝗡𝗲𝗲𝗱 𝗛𝗶𝘀𝘁𝗼𝗿𝘆

𝗧𝗵𝗲 𝗥𝗲𝗽𝗼 𝗜𝘀 𝗧𝗵𝗲 𝗖𝗼𝗻𝘁𝗲𝘅𝘁: 𝗪𝗵𝘆 𝗔𝗴𝗲𝗻𝘁𝘀 𝗗𝗼𝗻’𝘁 𝗡𝗲𝗲𝗱 𝗛𝗶𝘀𝘁𝗼𝗿𝘆

Coding agents read whatever you give them. This sounds like a strength. Usually, it is a problem.

I used to give agents more documentation. I wrote specs, ADRs, and planning docs. I thought more context was better. Then I saw an agent make a confident mistake. It was not a hallucination. It was simply following an old document that described a system we stopped using months ago. It was obeying history instead of the truth.

History is for humans. It explains why a system exists. It helps you understand trade-offs and old decisions.

Agents are different. They edit the present system. For that task, they do not need historical prose. They need the current source of truth.

They need: • Current schemas • Current module boundaries • Current APIs • Current tests • Current configurations

If you want an agent to understand a database, do not make it replay every migration log. Give it the current schema. If you want it to understand architecture, do not make it read old ADRs. Give it the current module graph.

The danger is context pollution. This happens when a fact lives in two places: the code and a Markdown file. Code changes fast. Prose changes only when someone remembers. When they diverge, the agent trusts the stale document. An agent does not squint or cross-check like a human. It takes the first thing it reads as fact.

Stop writing better docs. Start having fewer places where facts can rot.

Move rules from text into the system structure: • Use directory structures for architecture. • Use naming for intent. • Use package exports for APIs. • Use lint rules for boundaries. • Use schemas for data contracts. • Use tests for behavior.

A rule in a README is a suggestion. A rule in an ESLint config is a wall. The agent cannot ignore a wall.

I have shrunk my instruction files. They no longer restate the architecture. Instead, they point to where the architecture lives.

Keep history for people. Shape the present for agents.

Source: https://dev.to/gyu07/the-repo-is-the-context-why-agents-dont-need-history-4ien

Optional learning community: https://t.me/GyaanSetuAi