An AI agent to review technical specs: why automate what fails when done by hand

A bad technical specification is a time bomb. It doesn't go off right away, but weeks or months later, when the development team discovers that the client meant something completely different, the requirements contradict each other, and half of the critical scenarios aren't described at all. By various estimates, up to 40 percent of rework in IT projects stems from poor documentation at the start. One developer decided something could be done about it, and built an AI agent that checks specs before anyone starts writing code against them.

The story, published on Habr in early March 2026, wins people over with its honesty. The author warns up front that this is not a finished product and not a universal solution. It is an experiment born of personal frustration, from working with documentation in which every second item can be read two ways. The idea is simple and elegant: point a language model at the text of a technical specification and ask it to find contradictions, logical gaps, ambiguous wording and missing edge cases. What takes a human analyst hours of careful reading, an AI agent can do in minutes.

Technically, the approach fits the increasingly popular paradigm of AI agents: autonomous systems built on large language models that don't just answer questions but carry out a sequence of actions to reach a goal. Here, the agent splits the spec into logical blocks, checks each one for internal consistency, then checks the blocks against each other, and finally produces a structured report pointing to specific problem areas. This is not just a prompt in ChatGPT; it is a chain of reasoning with context and memory.

What makes the experiment truly interesting is that it reflects a fundamental shift in how developers think about applying language models. The first wave of enthusiasm centered on code generation: GitHub Copilot, autocompletion, turning descriptions into working functions. The second wave, which we are seeing now, targets the processes around code: documentation review, requirements analysis, checking test cases for completeness, auditing architectural decisions. This is less flashy than "AI writes your code for you," but potentially far more valuable for business.

The quality of technical specifications is one of those problems the industry has tried to solve through methodology for decades. Agile partly sidestepped it by replacing monolithic specs with iterative user stories. But even in agile teams, someone has to write clear acceptance criteria, and someone has to check them. In outsourcing and custom development, where the spec remains a legal document, the stakes are higher still. An imprecise wording in a spec is not just technical debt; it is a potential conflict between client and contractor that can end up in court.

Of course, the approach has limits, and the author doesn't hide them. A language model does not understand a project's business context the way an experienced analyst does. It may flag a formal contradiction where there is none, or miss a problem disguised as a correct wording. The AI agent does not replace human expertise; it amplifies it, acting as a first filter that catches the obvious problems and frees the analyst's time for the non-obvious ones.

It is also notable that such tools are starting to appear not only as enthusiasts' side projects. Major requirements management platforms are already integrating AI features for documentation quality analysis. Jira, Confluence, Notion: all are moving in this direction. But custom agents tailored to a specific team's specific processes may prove more effective than universal solutions. That is why the experience of building such an agent quick and dirty is valuable: it shows that the barrier to entry has dropped so far that one specialist can assemble a working prototype in a few evenings.

This experiment is a small but telling illustration of where applied AI in development is heading. Not replacing programmers, not automatically generating finished products, but targeted reinforcement of people where they traditionally make mistakes. Spec review is only one such node. Next could be automated contract audits, validation of business requirements against regulatory norms, and checking marketing materials for legal risks. The pattern is always the same: let the AI read what a human wrote, and ask it to find the weak spots. Simple, but surprisingly effective.