There are three common ways to give an agent context about your product: keep instructions alongside the code, connect it to your team's documentation, or connect it directly to the work itself. Each has different benefits and tradeoffs. The bigger challenge is that having the right context available doesn't guarantee the agent will interpret or follow it correctly, so choosing where context lives is only part of the problem.
What can go wrong
A 2026 study, How Coding Agents Fail Their Users, analyzed 20,574 real coding-agent sessions across 1,639 repositories and identified 16,118 episodes where developers visibly pushed back on the agent's work. The sessions included Cursor and Copilot, with CLI logs dominated by Claude-family models. Episodes could receive more than one tag, and three patterns stood out:
38.33% were tagged as developer constraint violations. Of those, 73.68% were attributed to instruction-following failures, where the agent failed to follow an explicit instruction from the developer.
26.95% were tagged as cases where the agent misread what the developer intended.
22.58% were tagged as inaccurate self-reporting, where the agent said work was complete when it wasn't.
Missing context is clearly part of the problem, but these findings complicate the usual advice to simply give AI more context. An agent can have a clear instruction and still not follow it. It can also report that work is complete when it isn't.
Most of what follows focuses on where product context should live so an agent can find it. Later, we'll come back to what happens when the agent doesn't follow that context and how to verify what actually happened.
Why "write a better ticket" isn't the whole answer
Clearer specifications can help when the problem is missing information. In the study, underspecified instructions were identified as a cause in 15.36% of the validated episodes and accounted for 44.10% of cases where the agent misread developer intent.
But instruction-following failures were more common. They were identified as a cause in 36.49% of the episodes, even when the developer had already given the instruction explicitly.
So better tickets help, but they only address part of the problem. Teams still need a reliable way to make product context available to both people and AI. In practice, that usually means deciding where that context should live. The next three options take different approaches to that.
Option 1: Keep context with the code
The simplest approach is to keep context in markdown checked into the repository, such as CLAUDE.md, Cursor's .cursor/rules/ files, or documentation in a /docs directory. The agent can load it automatically, it's version-controlled next to the code, and an engineer can update it in the same pull request that changes the thing it describes.
This shines when the team is small and the context is engineering context. No new tool, no adoption tax, and the guidance sits inches from the code it governs. For one or two repositories and a handful of engineers, it's often genuinely enough. Anything heavier is probably over-engineering.
Where it strains is maintenance. Rules can go stale, and keeping them current tends to fall to the shrinking group of people who still understand the system, while everyone else keeps building against whatever is already there. Repo-level guidance also naturally skews toward engineering context. What a product term actually means, why a flow behaves the way it does, or what decision led to a particular constraint often lives with people who don't spend their days in the repository.
Even a current, explicit instruction can still be ignored. Making it available doesn't guarantee the agent will follow it.
Option 2: Connect the agent to your documentation
The next approach is to use the knowledge base where broader product context already lives, including PRDs, decisions, glossaries, user journeys, research, and other documentation in Notion, Google Drive, Confluence, or a similar system. Connect the agent through MCP, and it can retrieve that information while it works.
This shines because it's cross-functional. PMs, designers, and engineers can all contribute, so the "why" behind a decision lives in human-readable form with history attached. For the narrative side of product context, a well-kept knowledge base is hard to beat, and most teams already have one.
Where it strains is that documentation captures information at a point in time, while product context needs to stay current as the product changes. A stale page can be worse than a missing one because it looks just as authoritative as a current page.
The deeper problem is retrieval. The product context is often there, but it's buried inside documents written for people, not machines. A 2,000-word PRD may contain exactly the definition an agent needs, but the agent still has to find the right passage, determine whether it's authoritative, and interpret it correctly. That's why retrieval isn't the same as structured context.
MCP solves access to the document. It doesn't automatically solve which document is right, which part matters, or whether the agent will follow what it finds.
Option 3: Connect the agent to the work
A third approach is to put product meaning closer to the work itself. Instead of storing all of the context in a separate file or prose document, product meaning can live as structured context, including definitions, acceptance criteria, decisions, business rules, and intent attached to the work the team is already doing.
That changes the job for the agent. Rather than finding a paragraph somewhere and deciding what it means, it can retrieve the structured object or definition directly. Several products are moving in this direction, though what they expose differs:
Productboard gives agents access to product and roadmap context, including features, objectives, releases, and specifications.
Linear gives agents access to planning and delivery context such as issues, projects, and comments.
Jira, through Atlassian's Rovo MCP server, gives agents access to issues and related work across Jira and connected Atlassian tools.
CoreStory builds a persistent model of a codebase's architecture, workflows, business rules, and APIs from the code itself.
Reqode links specifications to implementation through a deliberately read-only connection, and after implementation, checks code changes against specifications and architecture guidelines.
Atono gives agents access to the story itself, its acceptance criteria, AI Context notes, and the Product Glossary through MCP.
This shines when several people and AI tools need the same product answer rather than slightly different copies scattered across repositories, documents, and individual conversations. If a product term has a specific meaning, or a permission rule needs to be interpreted consistently, structured context gives the team one place to manage that meaning.
Where it strains is that it's another system. Consistency doesn't happen automatically just because the context is structured. Someone still has to own it and keep it aligned with reality, and if ownership is fuzzy, a structured source can drift just like a wiki can, with the added danger that it looks authoritative even when it's wrong.
If you're one repo and three people, this is probably more infrastructure than you need, and a simpler rules file may carry you a long way. None of this replaces the agent's judgment either. Better context improves what it has to work from, but it still has to interpret and follow that context correctly.
One more path: build the context layer yourself
Some larger organizations build their own retrieval layer instead, using a vector store or internal MCP server connected to the systems they already use. That can be the most flexible option if you have the engineering capacity. You decide what counts as authoritative, how information is structured, which systems are queried, and what the agent can access.
The tradeoff is ownership. You now own the infrastructure, the integrations, the retrieval quality, and the job of keeping the source material current.
This solves the same problem in a different way, and for some organizations it's the right approach.
Context isn't the last step
Where the context lives answers only part of the problem. In 22.58% of the validated episodes in the coding-agent study, the agent was tagged as inaccurately reporting success. It said work was complete when it wasn't. Checking the implementation itself still matters. Treat an agent's completion message as a claim to verify, not proof that the work is done. Review the changes, run the tests, and check the result against the acceptance criteria.
For product work that reaches users, there's another question after that. Did the change actually roll out, and is anyone using it? Feature flags and usage data can provide evidence about what happened after implementation.
In Atono, the feature flag controlling rollout and the resulting usage data stay connected to the same story as the work. Usage data is available when the application is configured to send usage events to Atono. That isn't a check on the implementation, and it doesn't prevent any kind of agent failure. It gives the team evidence that the work was released, reached users, and – when the right events are instrumented – was actually used.
That's a different problem from supplying context, but it belongs in the same workflow. Give the agent the best context you can, check the work yourself, then see what happened after release.
How to choose
Be honest about where your team actually is:
One or two repositories, a few engineers, mostly engineering context → start with repo-level rules. Don't add a tool for a problem you don't have.
Cross-functional and documentation-heavy, with a knowledge base that's already load-bearing → connecting the agent to that documentation through MCP can get you a long way.
Multiple teams and AI tools need the same product definitions and structured context → connecting the agent directly to the work starts to earn its keep.
You have unusual requirements and the engineering capacity to own the infrastructure → building your own context layer may make sense.
None of these is inherently more mature than another. They work well in different situations and come with different tradeoffs. Pick the lightest system where the answer to "what does this mean?" is the same everywhere it's asked. And whichever one you choose, don't confuse context availability with proof that the agent followed it.
What good looks like
Take a simple example from Atono. "Everything" is the name of a specific screen in the product, not just a common word. Ask an agent to "add a filter to the Everything view" without structured product context, and it has to infer what "Everything" means from the surrounding code. It might build a perfectly reasonable generic catch-all filter that doesn't match the actual product. That's the kind of situation that produces something almost right.
Give it a Product Glossary entry that defines Everything as that specific screen, along with the relevant product rules, and the agent no longer has to infer what the term means from the surrounding code. That solves the ambiguity problem, but it doesn't solve the compliance problem. Making the definition reachable doesn't guarantee the agent will interpret every instruction correctly or follow every constraint. And implementation isn't the end of the story either. After the filter is built, the team still needs to verify the implementation and see what happens after release.
When the story, rollout controls, and usage data stay connected, the team can answer those questions without relying only on what an agent, an engineer, or a stale document says happened. Checking the work yourself tells you what actually happened.
Atono is the product engineering platform – one system that runs planning, building, feature flags and usage data together – that keeps product context connected to the work, so teams and their AI agents build from the same understanding of the product. Book a walkthrough with our team to see it. Teams of 25 or fewer can start free, with plans and pricing available as they grow.
FAQ
How do I give Claude Code context about my product?
Three common approaches are to keep product instructions alongside the code, connect Claude Code to your documentation through MCP, or connect it directly to the system where the work and its product context live. The right approach depends on where your team already maintains trustworthy context and how many people and tools need the same answer.
Does Cursor read my Jira tickets?
Not by default. Cursor can access Jira data when you connect it through Atlassian's Rovo MCP server or another compatible MCP connection. What it can retrieve or update depends on the connection and permissions you configure.
What's the difference between a rules file and an MCP server?
A rules file such as CLAUDE.md or Cursor's .cursor/rules/ stores instructions with your code so the agent can load them automatically. An MCP server gives the agent a connection to another system so it can retrieve information when needed. Neither guarantees the information itself is current or that the agent will follow it correctly.
Why does AI write code that looks right but isn't?
Sometimes the agent is missing important product context or has to guess what an underspecified request means. But agents can also fail to follow instructions they already have. A large study of real coding-agent sessions found explicit constraint violations were the most common category of observed mismatch between agent behavior and developer intent. Good context reduces ambiguity, but the resulting work still needs to be checked.
Make your product work flow
Shared context from first decision to feature usage