---
description: Developer experience and IDP—golden paths, self-service, scaffolding, documentation. Developers as customers; fast feedback, escape hatches.
alwaysApply: false
---

# Developer Experience

Guidelines for internal developer platforms (IDPs).

## Core Principles

1. **Developers Are Customers** - Understand needs; measure satisfaction and time-to-value.
2. **Golden Paths, Not Cages** - Opinionated defaults with documented escape hatches.
3. **Self-Service First** - Reduce tickets; enable create/deploy/provision in minutes.
4. **Documentation Is Product** - If it’s not documented, it doesn’t exist.
5. **Fast Feedback** - CI and local feedback in minutes, not hours.

## IDP Capabilities

- **Scaffolding**: Template (e.g. Backstage) for new service—name, owner, language; generates repo, CI, K8s manifests, observability stub, README. Validate inputs (e.g. name pattern).
- **Environments**: Self-service dev/preview namespaces or ephemeral envs; production via approval or main.
- **Databases/Resources**: Provision DB or cache from catalog; sanitized snapshots or read replicas for dev.
- **Secrets**: Self-service rotation or fetch from Vault; no shared long-lived secrets in docs.
- **Observability**: Auto-generated dashboards and alerts per service; logs and traces linked from catalog.
- **Cost**: Per-team or per-service cost visibility; budgets and alerts.

## Golden Path

- One recommended way to create a service, run tests, deploy to staging, and promote to production. Document in README and portal. For edge cases, document “escape hatch” (e.g. manual approval, different tool) without making it the default.
- **Portal**: Catalog of services, docs, runbooks, and links to logs/traces. Single place to start.

## Documentation

- **Getting started**: Prerequisites, clone, install, run locally, run tests, first deploy. Keep under 10 minutes.
- **Runbooks**: Per alert or common task; steps and owners. Link from alerts.
- **API/Contract**: OpenAPI or similar; generated from code where possible. Versioned.

## Definition of Done (Platform Feature)

- [ ] Self-service; no manual steps for happy path.
- [ ] Documented (how-to and troubleshooting); linked from catalog.
- [ ] Metrics and feedback loop (usage, errors, satisfaction) in place.

## Common Pitfalls

- **Ticketing for everything** - Prefer self-service automation; use tickets for exceptions only.
- **Tribal knowledge** - Document and put in portal; avoid “ask the platform team” as the only path.
- **Over-engineering** - Right-size to team size and service count; avoid unnecessary abstraction.