Think Inside the Box: Co-packaging documentation for AI coding agents
In this article...
- Why AI coding assistants struggle with software libraries, even when extensive documentation already exists.
- How the Amadeus's internal design system is a reference for a practical solution by packaging documentation alongside code.
- Why co-packaged documentation could become a new industry standard for AI-ready software libraries.
Editor’s note: This article was developed jointly by Andres Igea Oviedo, Software Engineer; and Andrea Scorti, Architect, at Amadeus.
AI coding assistants have fundamentally changed how developers build software. Whether using GitHub Copilot, Claude Code, Codex, or another agent-based tool, developers increasingly begin with a prompt to seek out information across documentation and other resources. Yet many of the assumptions that underpin modern software distribution were established long before AI became part of the development workflow.
Documentation is one of the clearest examples.
Today, when developers install a library through npm, PyPI, Maven, NuGet, or another package manager, they receive the code but very rarely the documentation needed to use that code effectively. The documentation usually exists, but it lives elsewhere: a website, a wiki, a documentation portal, or a generated reference site. The package contains the implementation while the instructions are delivered separately.
For decades, this separation worked because documentation was written primarily for humans. Developers could browse websites, search pages, and navigate rich interfaces. However, documentation is now increasingly being consumed by AI agents that read and reason over local files inside development environments.
That shift exposes a growing mismatch between how software is packaged and how it is used.
The documentation gap facing AI agents
Modern coding agents are highly effective when working with local information. They can read source code, follow references between files, traverse repositories, and process large amounts of markdowns. Their main limitation is access to external documentation during code generation: Internet access may be unavailable, authentication may block retrieval, and corporate environments may restrict external connections. Even when online access is possible, agents may fail to find documentation that matches the installed version or is structured for AI consumption. In these cases, they must rely on prior knowledge derived from potentially outdated training data rather than authoritative, version-specific sources.
When an AI agent encounters an unfamiliar library, it typically has three choices:
- Rely on training data.
- Search external documentation sites.
- Read files available locally.
Only the third option guarantees access to authoritative information that matches the exact version installed in the project. Yet most libraries provide little agent-friendly documentation beyond a README file.
The consequences are familiar to many developers:
- Hallucinated APIs and nonexistent methods.
- Recommendations based on deprecated patterns.
- Missing guidance on best practices and design intent.
- Repeated correction cycles that reduce productivity gains.
These issues are often viewed as model weaknesses. However, many are actually packaging weaknesses, which are not catering to the new consumer: the AI agent.
Applying the Think Inside the Box principle
The proposed solution is described as the “Think Inside the Box Principle.”
The idea is simple: a software package should contain everything needed to use it correctly, including the documentation.
The inspiration comes from physical products. When someone buys furniture, the assembly instructions arrive in the same box as the components. The instructions match the product version, require no additional search effort, and are designed for the person assembling the item. Software packages can follow the same pattern.
Here’s a simple analogy that summarizes this approach:
| Physical Goods Company | Software Library |
|---|---|
| Product (panels, shelves) | Source code, compiled artifacts |
| Assembly and usage instructions | API docs, usage guides, examples |
| The box | The package (npm tarball, wheel, JAR) |
| The customer | The AI coding agent |
| The store | The package registry (npm, PyPI, Maven Central) |
As with assembly instructions for physical products, the documentation should be designed for the consumer of the package, increasingly an AI agent, rather than for the people who created it.
Also, this does not replace human-facing documentation websites. It is meant to complement them by making the same information available to AI agents, directly alongside the code.
Amadeus’ internal design system as a reference implementation
An implementation of this concept can already be seen in Amadeus’ internal design system which provides a shared foundation for designing and building user interfaces across the company.
This design system's package demonstrates how structured, AI-consumable documentation can be versioned and distributed alongside the code it describes.
Rather than shipping only source code and build artifacts, the package includes APIs, accessibility guidance, implementation examples, design tokens, and usage guidelines, generated from the same source as the human-facing documentation and updated with every release to avoid separate "AI-only" content and reduce documentation drift.
With this in mind, the design system currently publishes the following structure inside its npm package:
Rather than loading all documentation into context simultaneously, agents begin with an index and selectively retrieve the information needed for a specific task.
This way, future AI tools could automatically detect packaged documentation, while existing tools can be directed to it through standard instruction files.
Why simple files may outperform additional infrastructure
One of the more interesting aspects of the proposal is what it intentionally avoids.
While alternatives such as MCP servers, skills, prompt templates, and specialized retrieval systems may be useful for operational workflows, documentation retrieval is fundamentally an information-access problem rather than an execution problem.
Agents already know how to read files.
Introducing additional infrastructure often creates operational overhead, configuration requirements, runtime dependencies, and maintenance costs. Markdown files packaged within the dependency require none of these. They work offline, require no authentication, and remain available wherever the package is installed.
This boils down to a simple principle:
Don't add infrastructure when the agent's existing capabilities already solve the problem.
From idea to standard
To encourage broader adoption of this standard, we could rely on Co-packaged Documentation (CoDoc), a specification for packaging version-specific, AI-consumable documentation alongside library code. The aim is not to create a new technology stack, but to establish a lightweight and ecosystem-agnostic packaging convention.
CoDoc also introduces an optional machine-readable manifest:
To make implementation practical across ecosystems, it also outlines how a docs/ directory could be included in existing package formats:
| Ecosystem | Include docs/ via |
|---|---|
| npm | files field in package.json or .npmignore exclusion removal |
| PyPI | package_data or data_files in setup.py / pyproject.toml |
| Maven | Resource directory inclusion in pom.xml |
| NuGet | Content files in .nuspec or <Content> items in .csproj |
| Crates.io | include field in Cargo.toml |
Learning from TypeScript
The software industry has seen a similar transition before.
In the early days of TypeScript, type definitions were often maintained separately from the libraries they described. Over time, the ecosystem moved toward shipping type definitions directly with packages because maintaining them externally created duplication, version drift, and unnecessary complexity.
Documentation for AI agents may be on a similar path.
Today, AI-oriented guidance often exists as prompts, templates, repositories, or disconnected documentation.
Tomorrow, developers may simply expect that information to arrive with the package itself.
Looking ahead to measuring the impact of co-packaged documentation
The central proposal of the paper to co-package AI-optimized documentation with library code can make a significant contribution to producing more accurate AI-generated code.
Preliminary observations from the Amadeus design system's internal adoption suggest that co-packaged documentation reduces API hallucinations and implementations with deprecated patterns. Therefore, rigorous benchmarking across a diverse range of libraries remains an open research direction.
To address this evidence gap, the aim is to develop CoDocBench, a public evaluation suite that will measure AI-agent performance on library-usage tasks with and without co-packaged documentation across multiple libraries and package ecosystems.
By defining measurable success criteria, CoDocBench will test the proposed standard and allow the wider community to validate its impact.
Ultimately, the results will show whether thinking inside the box could become a practical standard for AI-ready software libraries, so stay tuned for updates.
If you'd like to contribute to the discussion and share ideas, join the conversation on GitHub.
Read the full Think Inside the Box white paper: https://amadeusitgroup.github.io/Think-Inside-the-Box-White-Paper/
TO TOP