How I Built a Research Agent That Reads the Docs Before My Coding Agent Ships

The autonomous implementation system the author runs on a Mac mini uses an orchestrator to dispatch tasks to parallel implementation agents built on Claude Code, and a self-healing agent to clean up failures. The most irritating failure mode was when the implementer confidently called a library function that didn't exist, causing tests to fail and the system to block the task. After auditing two weeks of failed tasks, the author found that 60% of failures were due to not checking the library documentation first.

To fix this, the author introduced a read-only research sub-agent that runs before the implementation agent. This research agent reads the relevant documentation and returns a short, structured brief that the orchestrator checks before dispatching the implementation agent. The research agent is given read-only tools like Read, Grep, Glob, WebSearch, and WebFetch, and cannot edit files or run shell commands.

The implementer cannot start working on a task without a completed research brief, and the brief must have a confidence score above a certain threshold.

The research brief format is a short, structured Markdown file with four key fields: Questions, Findings, Verdict, Confidence, and Staleness risk. The implementer reads the Verdict first, and the orchestrator reads the Confidence to decide whether to dispatch the task. If the Confidence is too low, the research agent is run again with the weak questions as new queries.

By introducing this structural change, the hallucinated API bugs dropped from roughly one in five tasks to about one in forty over three months, with an extra cost of less than 10% of tokens.