Developer Experience
Standardized tooling and environments that make developing and iterating on platform infrastructure consistent and reproducible.
- pt-techne-opentofu-codespace: A GitHub Codespace pre-configured with OpenTofu, pre-commit, and all platform tooling — ready to use without local setup
- pt-techne-pre-commit-hooks: Custom pre-commit hooks written in Go that enforce IaC formatting (
tofu fmt), configuration validation (tofu validate), and automated testing (tofu test) before every commit - pt-techne-development-setup: Local development environment setup for engineers who prefer working outside of Codespaces
This page includes Architecture Decision Records documenting the key design decisions.
Components
Codespace
A GitHub Codespace pre-configured with OpenTofu, pre-commit, gcloud, kubectl, and all platform tooling. Defined as code in pt-techne-opentofu-codespace, version-controlled, and updated alongside the platform.
Pre-commit Toolchain
The primary resource is pre-commit-config — a .pre-commit-config.yaml file pinned to specific hook versions, enforcing tofu fmt, tofu validate, tofu test, YAML lint, and trailing whitespace. Identical in local and CI environments.
| Component | Description |
|---|---|
pre-commit-hook | A custom hook (written in Go) in pt-techne-pre-commit-hooks implementing platform-specific IaC checks beyond what stock hooks provide |
Local Development Setup
A local setup guide and script in pt-techne-development-setup for engineers who prefer native tooling over Codespaces.
Core Invariant
pre-commit run -a must pass before any commit. The CI pipeline enforces the same checks — local and CI are identical environments.
Architecture Decision Records
GitHub Codespace as the Standard Development Environment
| Status | Date | Deciders |
|---|---|---|
| Accepted ✅ | April 2026 | Techne |
Context and Problem Statement
Platform engineers need OpenTofu, gcloud, kubectl, pre-commit, and a set of custom hooks available in a consistent, reproducible environment. Without a standardized environment, engineers spend time debugging toolchain differences rather than building infrastructure. Version mismatches between local tools and CI are a common source of failures that are hard to diagnose.
The platform has a small team (1-2 engineers). Onboarding time is a meaningful cost. Any new engineer should be productive within hours, not days.
Decision
Provide a GitHub Codespace (pt-techne-opentofu-codespace) as the primary development environment, pre-configured with the full platform toolchain. The Codespace is defined as code, version-controlled, and updated alongside the platform.
A local setup guide (pt-techne-development-setup) is maintained for engineers who prefer native tooling, but the Codespace is the supported default. Pre-commit hooks (pt-techne-pre-commit-hooks) enforce the same checks locally and in CI — the environment a developer uses does not change what passes or fails.
Alternatives Considered
- Document required tools and let engineers install them manually — Rejected. Leads to version drift across machines and between local and CI. Debugging environment-specific failures is expensive and opaque.
- Self-hosted runner with a fixed Docker image — Rejected. Adds infrastructure to manage and does not improve the local development experience. The Codespace serves both purposes.
- Devcontainer without Codespace (local Docker only) — Rejected. Requires Docker to be running locally and adds setup steps. The Codespace works immediately from any browser or VS Code instance without local Docker.
Consequences
- New engineers are productive within hours of repository access
- Local and CI environments enforce identical pre-commit checks — no environment-specific failures
- Toolchain updates are applied once in the Codespace definition and inherited by all engineers on next rebuild
- Engineers on restricted machines (no local Docker, managed endpoints) can still contribute via browser-based Codespace