Skip to main content
Drafted and last reviewed July 24, 2026. Maintained by the Plannotator documentation team. As AI models improve, getting better results can require less prompt scaffolding and better context. Instead of writing a longer rulebook, give the agent concrete material that shows what you want it to build and what good work looks like. Anthropic calls these materials rich references. They can include repositories, existing code, reference websites, wireframes, HTML prototypes, specifications, test suites, reference implementations, and rubrics that describe your team’s standards.
A central AI coding task connects to rich references including an HTML prototype, code example, tests, and a rubric.

​
Why better models can need fewer instructions

The message you type is only one part of an agent’s context. The model may also receive a system prompt, repository instructions, skills, memory, tool definitions, and files it opens while working. In The new rules of context engineering for Claude 5 generation models, Anthropic reports that it removed more than 80 percent of Claude Code’s system prompt for newer Claude models with no measurable loss on its coding evaluations. The team found that many older instructions were now overconstraining the model or conflicting with one another. The article describes several related changes:
  • Replace rigid rules with guidance that lets the model use judgment.
  • Design clear tools and interfaces instead of teaching every use through examples.
  • Load detailed guidance when it becomes relevant instead of putting everything up front.
  • Keep repository instruction files lightweight.
  • Give the model richer references instead of relying only on written plans and specifications.
This is a report about Anthropic’s experience with newer Claude models, not proof that every model or task needs fewer instructions. Safety boundaries and important constraints still belong in the context. Do not assume that more prompt technique produces a better result when the model could learn more from the work itself.

​
What is a rich reference?

A rich reference is concrete material that an agent can inspect and use while it works. The word rich does not mean long, complicated, or heavily structured. It means the reference contains more useful information than a prose description alone. A Markdown plan can still be a good reference. Anthropic’s point is not that plans or specifications are obsolete. Newer models can also work from more expressive material.

​
Why richer references can beat longer prompts

Prose tells the agent about the work. A reference can show the work. Suppose you want an agent to build a settings page. You could spend several paragraphs describing the page’s hierarchy, spacing, controls, error states, and interaction flow. You could instead give it:
  • an HTML wireframe showing the layout;
  • an existing settings page that demonstrates the product’s conventions;
  • the specification for the new behavior;
  • tests for the important states; and
  • a design rubric describing what your team accepts.
Each reference answers a different question. The HTML shows where things go. Existing code shows how this repository builds similar features. The specification explains the required behavior. The tests define cases that must work. The rubric gives the agent a way to judge the result. Anthropic specifically recommends code when possible because it gives the model high-fidelity instructions in a form it understands well. The article also says that an HTML mockup will generally communicate a design better than a prose description or screenshot.

​
Examples of rich references

​
Building a user interface

The agent still receives a clear task. The references provide the detail that would otherwise turn the prompt into a small design document.

​
Porting existing behavior

The source function communicates the algorithm. The target repository communicates local conventions. The tests and rubric make the acceptance bar visible.

​
Designing an API

An API task might use a product specification, an existing API with similar behavior, a test suite, and a team rubric for API design. The specification states the outcome. The existing API demonstrates conventions. The tests define observable behavior. The rubric helps the agent evaluate naming, errors, pagination, and compatibility.

​
How to give an agent rich references

  1. State the outcome. Tell the agent what it needs to build, change, or decide.
  2. Choose a small set of useful references. Include only the material that helps with this task.
  3. Explain each reference’s role when it is not obvious. Say whether it defines behavior, demonstrates style, provides an example, or sets the quality bar.
  4. Let the agent inspect the material. Do not rewrite the entire reference into the prompt.
  5. Verify the result against the references. Run the tests, compare the implementation with the prototype, and apply the rubric.
Keep the set small. Too many references can recreate the same problem as an oversized prompt. Give the model the right context, not all available context.

​
What to avoid

Rich references do not fix an unclear task. The agent still needs to know the intended outcome. Avoid:
  • attaching a whole repository when one package or implementation is the useful example;
  • providing several references that disagree without saying which one controls;
  • treating example code as a requirement when the agent is only meant to learn from it;
  • writing a rubric with generic advice such as “make it high quality”;
  • using references to hide a decision the team has not made; and
  • removing safety rules or hard product constraints just because the model has better judgment.

​
Where Plannotator fits

Open-source Plannotator lets you review plans, Markdown, HTML, local code changes, pull requests, and merge requests with the coding agent that produced them. A team can review an HTML prototype or implementation plan before the agent builds from it, then review the resulting change against the same material. Plannotator Workspaces is the separate commercial product for sharing plans and technical documents across teammates and agents. A workspace can keep a main plan beside specifications, HTML prototypes, wireframes, and team guidance. Plannotator does not decide which context an agent needs. It gives people and agents a shared place to inspect and discuss the material they are using.

​
Frequently asked questions

No. The useful part is the material the agent can inspect. A link may be how the agent reaches a repository, prototype, specification, test suite, or rubric.

​
Do rich references replace prompts?

No. The prompt should still state the task, outcome, and important constraints. References carry the detailed context that is easier to show than describe.

​
Do I need every type of reference?

No. Use the smallest useful set. A code change might need only the target file, a similar implementation, and its tests. A user-interface task may benefit from an HTML prototype and a design rubric.

​
Are Markdown plans and specifications no longer useful?

They are still useful. Rich references expand the available formats. They do not require teams to stop writing plans or specifications.

​
Is “rich references” an industry standard?

No. Anthropic used the phrase in its July 2026 article and the accompanying X article. It is a useful description, not a formal protocol or specification.

Compare HTML and Markdown for agent work

See when a visual HTML artifact communicates more than a text-only document.
Last modified on July 25, 2026