DevEx: Making Developers Productive and Happy
Developer Experience (DevEx) teams focus on: reducing friction in the development workflow, standardizing tooling across the organization, improving documentation quality, automating onboarding for new developers, and measuring developer productivity and satisfaction. The DevEx team's output: developer tools, templates, guides, and standards that make every other team more productive.
AI rules and DevEx are natural allies: AI rules encode the patterns, conventions, and standards that the DevEx team defines. When a developer asks the AI to create a new component, the AI follows the DevEx team's conventions — consistent naming, standard structure, proper documentation. AI rule: 'DevEx team AI rules serve as the encoding layer for organizational developer standards. Every DevEx standard should have a corresponding AI rule that generates compliant code.'
The DevEx team produces two types of AI rules: internal rules (for the DevEx team's own development of tools and templates) and organizational rules (standards that other teams' AI should follow). This article covers both perspectives.
Developer Tooling Standards
Standard development environment: the DevEx team defines what tools every developer uses. Editor/IDE (VS Code with required extensions, or JetBrains with standard plugins), linter configuration (ESLint, Prettier, or equivalent — shared config packages), Git workflow (branch naming, commit message format, PR template), and local development setup (Docker Compose, devcontainers, or Nix flakes). AI rule: 'The AI follows the organization's tooling standards. Linter configuration: use the shared config package (@org/eslint-config). Git commits: follow the conventional commits format. Local setup: use the devcontainer configuration.'
Shared tooling packages: the DevEx team publishes internal packages that standardize common patterns. @org/eslint-config (linter rules), @org/tsconfig (TypeScript configuration), @org/prettier-config (formatting), @org/testing-utils (test helpers and fixtures), and @org/components (shared UI components). AI rule: 'Use organizational packages instead of writing custom configurations. The AI should import from @org/ packages when they exist. Do not duplicate functionality that is already in a shared package.'
CLI tools: the DevEx team may provide CLI tools for common operations (project scaffolding, environment setup, deployment). AI rule: 'When an organizational CLI tool exists for an operation: use it instead of manual commands. The CLI encodes best practices and guardrails. Example: org create-service is preferred over manual project setup because it includes standard configuration, CI/CD, and catalog registration.'
Without shared packages: each repo has its own ESLint config, TypeScript config, and Prettier config. Over time: configs drift. Team A allows any, Team B forbids it. The AI generates different code for each team. With shared @org/ packages: one source of truth. Update the package → all repos get the update. The AI generates consistent code across the entire organization. The DevEx team's most impactful product: shared configuration packages.
Documentation and Onboarding Patterns
Documentation as code: documentation lives alongside the code in the repository (README.md, docs/ directory, inline code comments). The AI should generate documentation as part of feature development, not as an afterthought. AI rule: 'When generating a new API endpoint: generate the API documentation (OpenAPI spec or equivalent). When generating a new component: generate the component documentation (props interface, usage examples). When generating a new service: generate the README with setup instructions, architecture overview, and runbook links.'
Onboarding documentation: every repository should enable a new developer to: understand the project purpose (README overview), set up the development environment (getting started guide), run the application locally (development commands), run tests (test guide), and understand the architecture (architecture decision records). AI rule: 'README.md: include purpose, setup instructions, development commands, testing instructions, and deployment information. Keep READMEs current — update when the setup process changes.'
Architecture Decision Records (ADRs): document significant technical decisions with: context, decision, consequences, and alternatives considered. AI rule: 'When the AI recommends a significant architectural decision (database choice, framework selection, API design): generate an ADR. ADRs live in docs/adr/ with sequential numbering (0001-use-postgresql.md). Future developers can understand why decisions were made.'
Without ADRs: every 6 months, someone proposes switching from PostgreSQL to MongoDB (or vice versa). The team debates for weeks, reaches the same conclusion as last time, and moves on. With ADRs: someone proposes the switch, a team member links to ADR-0001-use-postgresql.md that documents the original reasoning, and the debate is resolved in minutes (unless the context has genuinely changed). ADRs save hours of repeated discussions.
Developer Productivity Metrics
DORA metrics: the four key metrics for software delivery performance. Deployment Frequency (how often code is deployed to production), Lead Time for Changes (time from commit to production), Change Failure Rate (percentage of deployments that cause failures), and Mean Time to Recovery (time to restore service after a failure). AI rule: 'Generate deployment tracking that feeds DORA metrics. Every deployment: record timestamp, commit SHA, outcome (success/failure), and recovery time if applicable. These metrics inform where the DevEx team should invest.'
Developer satisfaction: survey-based metrics (Developer Satisfaction Score, Net Promoter Score for internal tools) and behavioral metrics (time spent waiting for CI, frequency of environment issues, number of support requests). AI rule: 'DevEx tools should minimize: CI wait time (optimize build caching, parallelization), environment setup time (devcontainers, automated provisioning), and context-switching (integrate tools into the IDE, reduce portal-hopping).'
Cognitive load metrics: how much mental effort developers spend on non-coding tasks (understanding the build system, navigating documentation, configuring environments). The DevEx team's goal: reduce cognitive load. AI rules contribute by: generating consistent code that matches existing patterns (developers do not need to learn a new approach for each AI-generated file), following naming conventions (predictable file and function names), and including inline documentation where the logic is not self-evident.
Goodhart's Law: when a measure becomes a target, it ceases to be a good measure. If deployment frequency becomes a target: teams deploy empty commits to increase the number. If lead time becomes a target: teams skip code review to deploy faster. DORA metrics should inform where to invest (slow CI → invest in build optimization), not punish teams or create perverse incentives. The DevEx team uses metrics to find friction, not to grade teams.
DevEx AI Rules Summary
Summary of AI rules for developer experience teams optimizing organizational productivity.
- Tooling: shared config packages (@org/eslint-config, @org/tsconfig). AI uses them, not custom configs
- CLI tools: use organizational CLIs for scaffolding and operations. They encode best practices
- Documentation: generated alongside code. README, API docs, component docs, setup guides
- ADRs: document significant decisions in docs/adr/. Context, decision, consequences
- Onboarding: every repo enables setup in < 30 minutes. Getting started, dev commands, test guide
- DORA metrics: track deployment frequency, lead time, change failure rate, MTTR
- Developer satisfaction: minimize CI wait, environment setup, and context-switching
- Cognitive load: AI generates consistent patterns. Predictable naming. Convention over configuration