Tell AI to Read the Documentation Before Writing the Code

I recently came across an instruction in a Next.js project’s AGENTS.md file that puts this rather well:

This is NOT the Next.js you know

For anyone unfamiliar with it, AGENTS.md is a file used to give coding agents instructions about a project.

In this case, the message is essentially: things have changed, your existing knowledge may be outdated, read the documentation before getting to work. Next.js’s own guidance now explicitly directs agents to documentation bundled with the installed version.

When the framework needs to tell AI to stop assuming it knows the framework, that probably deserves some attention.

Familiar tools can still cause problems

You ask AI to add a feature to your application.

It recognizes the framework, generates some code and explains why this is the recommended approach. Unfortunately, it may have been the recommended approach two versions ago.

Modern development tools change. Functions are renamed, configuration options disappear and previously valid patterns become deprecated or behave differently.

AI can also mix examples from different versions into one implementation. Each piece looks plausible on its own. Together, they do not necessarily belong in the same application.

This is particularly frustrating because the explanation can sound entirely convincing. The AI knows the terminology. It can explain the architecture. It may even tell you that it is following the latest best practices.

Whether it actually checked those practices is another question.

Unfamiliar tools have a different problem

Now imagine asking AI to connect your application to a particular accounting platform, CRM or event-booking service.

It may have limited knowledge of that product. But it knows what an integration usually looks like, so it fills in the gaps.

Perhaps it assumes the service accepts an API key when it requires a different authentication flow. Perhaps it invents a plausible endpoint or sends a field called customerId when the service expects something else entirely.

The result can look organized and professionally implemented while being based on an API that exists mostly in the AI’s imagination.

Even when a request succeeds, assumptions can still cause problems. Does creating a booking confirm a place, or merely create a pending reservation? Does a customer list return every customer, or only the first page?

Those details need to come from the service’s documentation.

Read the right documentation

“Read the latest docs” is a useful start, but it needs one qualification: the documentation should match what your project actually uses.

If your application uses an older version of a library, instructions for the newest release may be just as unsuitable as an outdated tutorial.

Ask AI to check the installed version first. For an external service, it should check the API version and the integration requirements relevant to your account.

It should also read the project’s existing instructions. Files such as AGENTS.md or the README may explain the setup, point to relevant documentation or describe decisions that should not be casually undone.

This does not require reading an entire documentation website before changing a button label. The point is to check the parts that determine how the requested feature should work.

If it cannot find the answer, it should say so

Some services keep their documentation behind a login. Others have incomplete examples or explain important restrictions somewhere you would never think to look.

If the AI cannot access the information it needs, ask it to identify what is missing.

You can provide the relevant documentation, an API specification or a confirmed example.

That is much more useful than discovering, after several rounds of debugging, that the endpoint it has been “fixing” never existed.

A prompt you can reuse

Before implementing this task, read the project's relevant instructions, including AGENTS.md and the README where present. Identify the installed versions of the frameworks and libraries involved. For external integrations, establish the applicable API version. Consult the relevant official documentation for those versions before writing the implementation. Use version-matched documentation bundled with the project or package where available. For integrations, verify the authentication method, endpoints, required fields, response structure and any pagination or workflow rules relevant to the task. Do not invent APIs, configuration options or service behavior. If required documentation is unavailable or unclear, explain what information is missing before implementing the affected part. Do not upgrade dependencies just to match a documentation example. Briefly identify the documentation used and any remaining assumptions. After implementation, run the relevant checks and verify the behavior. Report anything you could not test.

You can keep this in your project instructions so it does not depend on remembering to include it in every conversation.

Reading the documentation will not catch every mistake. The implementation still needs testing, as we covered in the article about AI declaring that everything works.

But before you spend an afternoon asking AI to fix its integration, it is worth checking whether it ever read how the integration was supposed to work.