AI coding agents can generate entire services, reason about architectures, and scaffold applications in minutes. But ask one to build a service for your organization and you'll quickly notice the gap: it doesn't know your rules. It doesn't know which messaging broker your compliance team mandates, which services already exist in adjacent domains, or which project template is the golden path for your team.

These aren't knowledge gaps that more training data will solve. They're organization-specific, constantly evolving, and already documented somewhere most agents never look: your internal developer portal (IDP).

This post walks through a demo that connects an AI coding agent to a Backstage-based developer portal—specifically Red Hat Developer Hub—and shows what happens when the agent can query the software catalog, read TechDocs, and inspect software templates before making a single architectural decision. Keep reading to see how the catalog prevents a Payment Card Industry Data Security Standard (PCI-DSS) compliance violation, resolves a cross-domain governance conflict, and produces a traceable decision record—all before any code is written.

The setup

The RHDH Agentic project provides the tooling for this demo. It connects an AI coding agent/harness (in this case, Claude Code) to a Red Hat Developer Hub instance using the Backstage command-line interface (CLI) to execute catalog query actions.

The demo uses a simulated enterprise catalog for a fictional insurance company called Parasol Insurance. The catalog contains more than 500 entities across 14 business domains, each with its own engineering team, approved technology stack, governance rules, and TechDocs handbooks.

The scenario: a developer joins the Claims team, needs to build a payment reconciliation service, and asks the agent for assistance. The agent has access to a single skill, catalog-explore, that lets it run Backstage CLI (Model Context Protocol (MCP) is supported too) actions against the catalog. Here's what the query commands look like:

# List all domains
npx @backstage/cli actions execute catalog:query-catalog-entities \
  --query '{"kind":"Domain"}' \
  --fields '["metadata.name","metadata.description","spec.owner"]' \
  --backendUrl http://localhost:7007

# Get a specific entity
npx @backstage/cli actions execute catalog:get-catalog-entity \
  --kind Component --name claims-settlement-service --namespace default \
  --backendUrl http://localhost:7007

# Read TechDocs for a domain
npx @backstage/cli actions execute techdocs-mcp-extras:retrieve-techdocs-content \
  --entityRef "domain:default/claims" \
  --backendUrl http://localhost:7007

The agent decides which queries to run, exploring the catalog the same way a new developer would, but faster.

Phase 1: Map existing domain architecture

To start, the developer might say: "I joined the Claims team. I need to build a payment reconciliation service. What domains and systems exist in our catalog?"

The agent queries for all (business) domain entities and gets back 14 of them:

claims, billing-payments, underwriting, policy-administration,

platform-engineering, customer-portal, data-analytics, reinsurance,

commercial-lines, personal-auto, personal-property, life-annuities,

specialty-lines, compliance-regulatory

Continuing its exploration, it investigates the Claims domain, finding 6 systems. The one that matters is the claims-payment-system, which already contains 5 production services. The agent searches for existing reconciliation services (component entities in Backstage) and finds 1: payment-reconciliation-service, but its catalog entry tells a different story:

{
  "spec": {
    "owner": "group:default/billing-payments-engineering",
    "system": "payment-processing-system",
    "dependsOn": [
      "component:default/billing-account-ledger-service",
      "component:default/payment-gateway-service"
    ]
  }
}

A quick catalog check reveals this service belongs to Billing and Payments. It handles incoming premium payments—not the outbound claim settlements our developer needs. Without the catalog, a developer (or agent) might have assumed the job was already done!

Phase 2: Learn the rules

The developer continues the interaction with another question:

Are there any governance rules or technology requirements for payment-related services? 

Check the domain handbooks.

Following the prompt, the agent reads multiple layers of TechDocs to understand the governance landscape. What's impressive is that the agent doesn't read the Claims handbook and move on; it discovers governance is hierarchical and reads across organizational boundaries.

Layer 1: Org-wide standards (from Platform Engineering TechDocs)

The agent discovers org-wide engineering standards: API design conventions, observability requirements, and security patterns. These apply to every domain:

• All APIs must use OpenAPI 3.0.3 with URL-based major versioning.
• All services must expose Prometheus /metrics endpoints with Rate, Errors, and Duration (RED) metrics.
• Service-to-service auth uses mutual Transport Layer Security (mTLS) via Istio; user-facing auth uses Keycloak.
• Data at rest must use Advanced Encryption Standard (AES)-256 encryption for confidential or restricted data.
• Customer-facing services must meet a p99 < 500 ms latency service level objective (SLO).

Layer 2: Domain handbooks (from Claims and Billing TechDocs)

The Claims domain handbook specifies:

• Java with Quarkus is required for all transactional services (Python is only for machine learning workloads).
• AMQ Streams (Kafka) is preferred for all async domain events.
• All services processing Personally Identifiable Information (PII) must register with the General Data Protection Regulation (GDPR) Compliance System.
• All claim state transitions must emit Kafka events.

The Billing and Payments domain handbook specifies:

• IBM MQ is required for all payment transaction messaging. Kafka is explicitly not approved for payment-critical paths.
• Components in PCI-DSS scope must have Guardium database activity monitoring.
• All services must deploy using Parasol Helm charts with PCI-hardened base images.

Layer 3: Cross-domain conflicts

Things get interesting now. The Billing and Payments domain handbook is unambiguous:

Mandatory Rule: All payment transaction messaging MUST use IBM MQ with guaranteed delivery. Kafka is not approved for payment-critical paths due to at-least-once semantics.

However, the Claims domain states that Kafka is preferred for asynchronous events. Our new reconciliation service sits at the intersection; it consumes claim settlement events (Claims domain, Kafka) and processes payment transaction data (Billing domain, IBM MQ). A generic agent or a developer unfamiliar with the Billing domain might have defaulted to Kafka. Using the information hosted in the catalog prevented a PCI-DSS compliance violation before anyone wrote a single line of code.

The agent proposes a resolution: a bridge pattern that consumes bank settlement files from the Billing domain's IBM MQ channel at the cross-domain boundary, then publishes reconciliation events to Claims Kafka topics internally. It cites the Billing handbook's own exception clause:

Reconciliation batch jobs that do not handle cardholder data may use relaxed messaging requirements (AMQ Streams instead of IBM MQ) with approval.

By citing official governance docs, the agent presents a ready-to-approve solution that unblocks the developer while satisfying compliance rules

Phase 3: Identify integration points

Now the developer is ready with a follow-up question:

What existing services and APIs should my reconciliation service integrate with?

This is where the catalog's dependsOn relations and inline API specs become valuable. The agent traces the dependency graph within claims-payment-system. It also reads full OpenAPI specs directly from catalog entities. For example, the Claims Status API includes this endpoint:

paths:
  /claims/{claimReference}/payments:
    get:
      summary: List payments made against a claim
      operationId: getClaimPayments
      parameters:
        - name: claimReference
          in: path
          required: true
          schema:
            type: string

These are machine-readable contracts embedded directly (or referenced by URL) in catalog entities. The agent builds a complete integration map—with actual endpoint URLs, operation IDs, and schemas—without reading a single line of source code.

The end result is an integration checklist for the developer:

Phase 4: Scaffold with the right template

Our developer has seen the software templates available in the IDP, and asks:

Which software template should I use? Show me what parameters it needs.

The agent fetches the available templates, evaluates each against the Claims domain requirements, and selects the Quarkus template. It carries Parasol's golden path tag, targets the Claims domain, and applies the Quarkus framework required by domain governance.

The template's parameter schema tells the agent exactly what to supply. Every parameter value suggested by the agent comes from the catalog research:

• The service name follows the domain's kebab-case convention.
• The owner is claims-engineering.
• The system is claims-payment-system.
• The Java package follows the com.parasol.claims.\* pattern established by the 17 other Java services in the domain.

Phase 5: Produce a traceable decision record

The final output is something no ungrounded agent could produce: a Technology Decision Summary that traces every architectural choice back to its catalog source. The developer asks:

Give me a Technology Decision Summary—every choice, which catalog source informed it,
and any cross-domain conflicts.

This shifts the agent's output from "here's my recommendation" to "here's my recommendation and the organizational evidence behind it." A tech lead reviewing this summary can verify each citation and an auditor can trace compliance decisions to their source.

You can view the agent's detailed response on GitHub. We captured this using a real test run with Claude Code—it's too large to share inline!

Beyond individual decisions: The agentic SDLC

This catalog-grounded approach is one part of a broader pattern the RHDH Agentic project calls the agentic software development lifecycle (SDLC). Instead of burying software standards in static wiki pages, each SDLC role gets an executable agent skill that enforces governance directly in the workflow

The product manager skill writes and guards Product Requirement Documents (PRDs). The architect skill captures decisions in Architecture Decision Records (ADRs) and reviews pull requests (PRs) for structural soundness. OpenSpec handles change management, decomposing work through a structured artifact workflow: proposal, specs, design, tasks, and implementation.

Because skills are version-controlled alongside the code, the team's process evolves with the codebase. A new contributor (human or agent) picks up the current process by cloning the repo. Skills are portable across projects and can be shared as Claude Code plug-ins across repositories and organizations.

Without organizational context, agent skills produce generic output. With it, they produce output that respects domain boundaries, integrates with existing services, and follows governance rules specific to each business domain.

What this means for your organization

While this is a demo scenario for Parasol Insurance, the pattern is real. If your organization runs Backstage or Red Hat Developer Hub, you already have the knowledge graph that agents need. Domains, systems, components, APIs, TechDocs, and templates are the context layer that agents need to understand your organization.

The investment isn't necessarily in more AI infrastructure; it's in the catalog you're already building. Is your enterprise software catalog ready to serve as the context layer for your next AI agent?

AI coding agents are here. The question is whether they build in a vacuum or within the guardrails your organization has already defined in your software catalog.

Try it yourself

Ready to give your AI agents enterprise context? Explore the open source RHDH Agentic repository on GitHub to see how software catalog data transforms agent output.

1. Set up a local RHDH instance with the Parasol Insurance catalog loaded. The project includes detailed setup instructions using rhdh-local and Podman Compose.
2. Run the demo script from the repository. Alternatively, open the demo/catalog-agent/ directory in Claude Code and explore interactively. The CLAUDE.md file in that directory configures the agent persona, and the catalog-explore skill handles catalog queries.
3. Browse the recorded transcripts from previous demo runs at demo/recordings/ in the repository to see the full agent reasoning without setting up infrastructure.

The project also includes a demo walkthrough document with full command outputs showing each phase of the catalog exploration.