Why I trimmed my project’s documentation by 90%

When working remote, my lunch hours have a well-defined purpose: to learn about AI.

In the summer of 2026, I discovered a couple of principal-level engineers from Meta who describe their AI workflow in detail. I’ll leave links to their YouTube channels below.

In one of their videos, I learned about a study made by Anthropic demonstrating that documentation and pre-defined instructions passed to agents are, in many cases, worse than useless—they are harmful to the agent’s output.

How can it be?

The reason is simple: built-in harnesses have become so good so quickly that the well-intended documents created by most engineers can confuse agents, making them more prone to sub-optimal solutions.

I remember dedicating the better part of a Saturday to building my own project’s documentation, including a polished AGENTS.md and CLAUDE.md.

But as usual when working with AI, one must be ready to “kill one’s darlings,” as this dizzyingly-fast technology demands the ability to move on quickly.

So, after hearing about the study, I went to Opus 5.

—Hey, I heard about so-and-so study. Can you verify that it’s real and check my current documentation against it?

[Thinking for about 4 minutes]

—Yes, confirmed: the study is legit, and your docs are 90% useless at this point.

And that was that. I had a few more exchanges with the agent and ended up removing 90% of my documentation in one sweep.

It felt great: there was indeed outdated information and useless instructions, so getting rid of that was liberating.

Additionally, it was another demonstration of how fast progress is happening in this field. Many fear it, but I can only admire it.

Crazy times, exciting times. My dear documentation was hurting the very project it was intended to protect. In a few months, documentation may not be needed at all, who knows?

The important lesson for me is about adaptability: one must not fear changing course if new advances demand it, and you can bet that AI demands it.

As a wise man said: “who doesn’t adapt, doesn’t survive—much less thrives.”

I believe that the ability to adapt and try new things is becoming more crucial than ever before in history, so we must not fear it.

We must embrace it.