Context
Guidelines written for people don't automatically work for agents
Oracle was building its own agentic app, AI-native software that plans, reasons, and acts on a user's behalf rather than waiting for them to click through forms and pages. As that work progressed, it surfaced a gap in the Redwood UI Text Writing Guidelines: they were written as prose documentation on Confluence, meant for a human writer to read once and apply with judgment. An agent generating text on the fly needed something different.
A guideline written for a human assumes judgment. An agent needs an explicit, structured rule it can reliably follow. That distinction became the starting point for this work.
The shift
Designing for software that acts, not just responds
Traditional enterprise applications are workflow-heavy: a person initiates a task, navigates across pages, gathers data, and makes each decision field by field. Agentic applications flip that model. The system proactively surfaces relevant information, synthesizes it, and proposes decisions with evidence and rationale, often inside a single intelligent workspace instead of a maze of forms and modules.
That shift matters for content because a banner a person writes once, and a designer reviews once, is different from a banner an agent generates repeatedly, in response to conditions no writer ever explicitly anticipated. Writing guidance built for human-authored screens doesn't transfer to agent-generated ones without being rebuilt for how an agent actually reads and applies it.
The work
Rebuilding guidance as structured rule files
I took the existing UI text guidelines, written as narrative documentation, and restructured them as markdown rule files an agent could parse consistently: a stated purpose, explicit decision points, core rules phrased as directives rather than explanations, clear conditions for when the pattern applies, an anatomy breakdown, and paired good and avoid examples the agent can pattern-match against.
A Confluence page is read once by a person who brings context and judgment to filling in the gaps. A rule file is re-read by the agent at generation time, so ambiguity a human reader would resolve automatically has to be resolved explicitly in the rule itself, or the agent has nothing reliable to follow.
Examples
Two rule files, rebuilt from existing guidance
Banner messages and badges were among the first Redwood guidance areas converted into this format.
banner-messages.md: purpose, decision points, core rules, and good writing patterns, structured for an agent to follow.
badges.md: core rules, detail rules, and explicit good and avoid examples for status badges.
Outcomes
Governance that scales with the agentic shift
This work extends content governance to cover AI-generated surfaces, not just human-authored ones, a gap that would otherwise widen as more of the product gets built by agents rather than written by people.
Outcomes
A repeatable conversion template
Established a consistent structure, purpose, decision points, core rules, anatomy, and good/avoid examples, for turning any existing human-facing guideline into an agent-readable rule file.
Governance beyond human-authored text
Closed a gap between how Redwood governs writer-authored UI text and how it governs text an agent generates on its own.
Built for how agents actually read
Wrote rules as explicit directives and paired examples rather than narrative explanation, so the guidance stays reliable when re-read programmatically rather than by a person.