Architect Platform Helper

Design internal developer platforms with golden paths, self-service provisioning, and platform engineering best practices that accelerate delivery.

When to Use This Agent

Choose this agent when you need to:

• Design an Internal Developer Platform with service catalogs, software templates, and self-service provisioning workflows
• Implement golden paths for service scaffolding, CI/CD generation, environment provisioning, and observability bootstrapping
• Evaluate and integrate tools like Backstage, Crossplane, Argo CD, and Terraform into a cohesive developer experience

Consider alternatives when:

• You need deep expertise in a single infrastructure tool rather than broader platform strategy
• Your focus is end-user application development rather than building the tooling layer teams consume

Quick Start

Configuration

Copy
name: architect-platform-helper
type: agent
category: platform-engineering

Example Invocation

Copy
claude agent:invoke architect-platform-helper "Design self-service platform for provisioning microservices with CI/CD"

Example Output

Self-Service Microservice Provisioning
Architecture: Backstage + Crossplane + Argo CD + Datadog

Template: new-microservice-v2
  Inputs: service_name, language [go|ts|python|java], team_owner

Provisioned Resources:
  1. GitHub repo from language skeleton
  2. CI pipeline (.github/workflows/ci.yml)
  3. K8s namespace + quotas in dev/staging/prod
  4. Datadog dashboard (Rate, Error, Duration)
  5. PagerDuty service linked to team_owner
  6. Crossplane RDS Composition (if confidential data)

Golden Path: container scan, SBOM, SLO (required)
  Recommended: feature flags, OTel tracing

Core Concepts

Platform Engineering Overview

Aspect	Details
Internal Developer Platform	Self-service layer abstracting infrastructure, enabling devs to provision and deploy without tickets
Golden paths	Opinionated workflows for common tasks encoding best practices while remaining optional, not mandated
Service catalog	Discoverable inventory of services, libraries, and infra with metadata: lifecycle stage, SLOs, docs, deps
Platform as product	Internal product with user research, roadmaps, adoption metrics, and feedback loops
IaC abstraction	Crossplane Compositions or Terraform modules hiding cloud complexity behind organizational APIs

Platform Engineering Architecture

+----------------+     +------------------+     +----------------+
| Developer      | --> | Service Catalog  | --> | Software       |
| Portal (UI/CLI)|     | (Backstage)      |     | Templates      |
+----------------+     +------------------+     +----------------+
        |                       |                       |
        v                       v                       v
+----------------+     +------------------+     +----------------+
| Infrastructure | --> | GitOps Engine    | --> | Runtime        |
| Abstraction    |     | (Argo CD / Flux) |     | Platform (K8s) |
| (Crossplane)   |     |                  |     |                |
+----------------+     +------------------+     +----------------+

Configuration

Parameter	Type	Default	Description
catalog_provider	enum	backstage	Service catalog: backstage, port, cortex, or custom
iac_engine	enum	crossplane	Abstraction layer: crossplane, terraform-modules, pulumi, cdk
gitops_tool	enum	argocd	Reconciliation engine: argocd, flux, or manual-apply
default_cloud	enum	aws	Default cloud provider for provisioning templates
template_repo	string	-	Git repo URL containing software templates and skeletons

Best Practices

1. Treat your platform as a product - Conduct user research, track adoption metrics (template usage, time-to-first-deploy), and maintain a public roadmap. Platforms ignoring dev feedback become shelfware.

2. Start with a single golden path - Identify the highest-friction workflow (usually new service creation) and pave that first. One working path builds trust for broader adoption.

3. Make golden paths optional - Developers should choose paths because they are easier, not because alternatives are blocked. Track opt-in rates as product-market fit signals.

4. Abstract infrastructure, not decisions - Handle cloud provisioning but let teams choose language, testing framework, and deployment cadence. Over-abstraction creates one-size-fits-none.

5. Version templates semantically - Treat templates like APIs with versioning, change notifications, migration guides, and deprecation windows for previous versions.

Common Issues

1. Template sprawl - Teams fork and diverge from golden paths. Establish a contribution process with review, testing, and promotion criteria.

2. GitOps reconciliation conflicts - Multiple teams modifying shared configs create merge conflicts. Use per-team directories or ApplicationSets with conflict detection.

3. Platform team bottleneck - Without self-service, all requests funnel through the platform team. Invest in Crossplane Compositions and Backstage templates for independent provisioning.