pulumi
Pulumi Best Practices
Comprehensive performance and reliability guide for Pulumi infrastructure as code, designed for AI agents and LLMs. Contains 46 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- Writing new Pulumi infrastructure code
- Designing component abstractions for reuse
- Configuring secrets and sensitive values
- Organizing stacks and cross-stack references
- Setting up CI/CD pipelines for infrastructure
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | State Management and Backend | CRITICAL | pstate- |
| 2 | Resource Graph Optimization | CRITICAL | graph- |
| 3 | Component Design | HIGH | pcomp- |
| 4 | Secrets and Configuration | HIGH | secrets- |
| 5 | Stack Organization | MEDIUM-HIGH | stack- |
| 6 | Resource Options and Lifecycle | MEDIUM | lifecycle- |
| 7 | Testing and Validation | MEDIUM | test- |
| 8 | Automation and CI/CD | LOW-MEDIUM | auto- |
Quick Reference
1. State Management and Backend (CRITICAL)
pstate-backend-selection- Use managed backend for production stackspstate-checkpoint-skipping- Enable checkpoint skipping for large stackspstate-stack-size- Keep stacks under 500 resourcespstate-refresh-targeting- Use targeted refresh instead of full stackpstate-export-import- Use state export/import for migrationspstate-import-existing- Import existing resources before managing
2. Resource Graph Optimization (CRITICAL)
graph-parallel-resources- Structure resources for maximum parallelismgraph-output-dependencies- Use outputs to express true dependenciesgraph-explicit-depends- Use dependsOn only for external dependenciesgraph-avoid-apply-side-effects- Avoid side effects in apply functionsgraph-conditional-resources- Use conditional logic at resource levelgraph-stack-references-minimal- Minimize stack reference depth
3. Component Design (HIGH)
pcomp-component-resources- Use ComponentResource for reusable abstractionspcomp-parent-child- Pass parent option to child resourcespcomp-unique-naming- Use name prefix pattern for unique resource namespcomp-register-outputs- Register component outputs explicitlypcomp-multi-language- Design components for multi-language consumptionpcomp-transformations- Use transformations for cross-cutting concerns
4. Secrets and Configuration (HIGH)
secrets-use-secret-config- Use secret config for sensitive valuessecrets-avoid-state-exposure- Prevent secret leakage in statesecrets-external-providers- Use external secret managers for productionsecrets-generate-random- Generate secrets with random providersecrets-provider-rotation- Rotate secrets provider when team members leavesecrets-environment-isolation- Isolate secrets by environment
5. Stack Organization (MEDIUM-HIGH)
stack-separation-by-lifecycle- Separate stacks by deployment lifecyclestack-references-parameterized- Parameterize stack referencesstack-output-minimal- Export only required outputsstack-naming-conventions- Use consistent stack naming convention
6. Resource Options and Lifecycle (MEDIUM)
lifecycle-protect-stateful- Protect stateful resourceslifecycle-delete-before-replace- Use deleteBeforeReplace for unique constraintslifecycle-retain-on-delete- Use retainOnDelete for shared resourceslifecycle-ignore-changes- Use ignoreChanges for externally managed propertieslifecycle-replace-on-changes- Use replaceOnChanges for immutable dependencieslifecycle-aliases- Use aliases for safe resource renaminglifecycle-custom-timeouts- Set custom timeouts for long-running resources
7. Testing and Validation (MEDIUM)
test-unit-mocking- Use mocks for fast unit teststest-property-policies- Use policy as code for property testingtest-integration-ephemeral- Use ephemeral stacks for integration teststest-preview-assertions- Assert on preview results before deploymenttest-stack-reference-mocking- Mock stack references in unit tests
8. Automation and CI/CD (LOW-MEDIUM)
auto-automation-api-workflows- Use Automation API for complex workflowsauto-inline-programs- Use inline programs for dynamic infrastructureauto-ci-cd-preview- Run preview in PR checksauto-deployments-api- Use Pulumi Deployments for GitOpsauto-review-stacks- Use review stacks for PR environmentsauto-drift-detection- Enable drift detection for production
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
More from pproenca/dot-skills
zod
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
2.0Kclean-architecture
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
1.4Kemilkowal-animations
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
918vitest
Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
907typescript
This skill should be used when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
821nuqs
nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.
735