When Prompts Become the New Build System
Harness engineering is a discipline where developers write natural-language prompts to build features, and a convention-driven automation layer handles everything else: branching, environments, deployments, reviews, releases, and cleanup.
What problem does this solve?
Modern software development involves a crushing amount of ceremony. Shipping a single feature typically means:
- 1Creating a feature branch with the right naming convention
- 2Setting up a working (local) environment for the feature (dependencies, env vars, seed data)
- 3Writing the code (the actual creative work)
- 4Writing or updating tests
- 5Running linters, type checks, and tests locally before pushing
- 6Debugging CI failures that passed locally
- 7Writing or updating documentation (tech docs, inline comments)
- 8Creating a pull request with a meaningful description
- 9Waiting for, and chasing, code review
- 10Responding to review comments, pushing fixes, re-requesting review
- 11Updating the ticket in Jira/Linear/whatever team tracker
- 12Getting approval, merging, verifying the deploy
- 13Cleaning up the branch
- 14Writing changelog or release note entries
Steps 1-2 and 4-14 are pure overhead. They are repetitive, error-prone, and distract from the only step that actually creates value: writing the code.
Now add AI coding agents to the picture. Tools like Claude Code, Codex, Gemini, and others can write code from natural-language descriptions. But they still need all the surrounding infrastructure to function. An AI can write code, but it cannot (by default) create its own branch, provision its own database, generate its own PR, and tear down its own environment when done.
Harness engineering bridges that gap. It provides the convention layer and automation that turns an AI coding agent into a full development workflow, not just a code generator.
How it works
Convention over configuration
The core insight is that naming conventions can drive an entire CI/CD pipeline. No registry, no config files for each feature, no manual orchestration. Just a naming pattern:
The developer (or AI agent) pushes to a claude/ branch. The harness derives the feature name by stripping the prefix and session suffix. Everything else is automatic.
What gets automated
The harness eliminates manual work at every stage of the development lifecycle:
| Stage | Without harness | With harness |
|---|---|---|
| Start a feature | Create branch, set up environment | Push to claude/ branch. Branch, environment, database, and file storage are provisioned automatically |
| Iterate on code | Manual deploys to test | Every push auto-deploys to an isolated preview URL |
| Submit for review | Create PR manually, write description | Say /review. PR is created with description, preview URL, and reviewers assigned |
| Merge to dev | Manual merge, manual cleanup | Say /mergedev. PR is created, auto-merged, branch deleted, environment torn down |
| Release to production | Manual tagging, changelog, release notes | Say /release. Version tagged, changelog generated, GitHub Release created, production deployed |
| Emergency fix | Scramble to branch from main, hotfix, deploy | Say /hotfix. Branch from main, fix, PR to main, auto-tag patch release, back-merge to dev |
| Roll back | Panic, find the right commit, force push | Say /rollback. Safe revert (no force push), tracking issue created |
| Dependency updates | Review Dependabot PRs one by one | Say /deps. Patches batch-merged, breaking changes flagged |
| Resume work | Remember where you left off, checkout branch | Say /continue. Lists active features with preview URLs, picks up where you stopped |
| Team visibility | Ask around, check GitHub manually | Say /status. Dashboard of active features, pending PRs, preview URLs, unreleased changes |
Skills: the prompt-driven command set
Skills are the harness's command vocabulary. Each skill is a markdown file that teaches the AI agent how to perform a specific workflow operation. They are not code in the traditional sense; they are structured instructions that the AI follows.
/feature-Start a new feature (now optional; session start auto-initializes)/mergedev-Merge feature to dev with auto-merge/review-Submit PR for human review (without auto-merge)/release-Ship dev to production with version tagging/hotfix-Emergency production fix bypassing normal flow/rollback-Revert production to a previous release/changelog-Auto-generate changelog from merged PRs/deps-Batch-handle Dependabot dependency updates/continue-Resume an in-progress feature/status-Team dashboard with features, PRs, and preview URLs/harness-upgrade-Upgrade the harness itself to the latest versionUsers can add their own custom skills by creating new markdown files. The harness never touches custom skills during upgrades.
Signal files: how the AI talks to CI/CD
The harness uses a clever pattern: signal files that the AI commits to the repo, which trigger specific GitHub Actions:
- +
.pr-description.md- Triggers PR creation. Contains frontmatter flags like review: true (don't auto-merge) or hotfix: true (use hotfix workflow) - +
.release-description.md- Triggers the release workflow to create a versioned release - +
.railway-url- Written by GitHub Actions back to the branch, containing the preview URL
This means the AI agent communicates its intent through files, and the CI/CD system responds. No API tokens in the agent's hands, no direct GitHub API calls. The AI just writes a file and pushes.
The two variants
The harness comes in two tiers. Pick the one that matches whether your project needs a live deploy:
Feature branch automation and auto-merge. For libraries, CLI tools, scripts, and projects deployed elsewhere.
Adds Railway preview environments per feature, an isolated PostgreSQL database, and an S3-compatible bucket. Use what you need; ignore what you don't.
Web App is a superset of Code Only. Pick the one that matches your project's infrastructure needs, and everything is pre-configured.
Traits: composable best practices for AI agents
One of the harness's most distinctive features is its trait system. Traits are markdown files containing stack-specific best practices that the AI agent reads before writing code.
Instead of hoping the AI knows the latest conventions for your stack, you give it curated, version-specific guidance:
traits: nodejs, typescript, express, vitest, eslint, pnpmTraits are composable, meaning you pick one from each relevant category and they work together. Presetsbundle common combinations (e.g., "Next.js 15" = TypeScript + Node.js + React + Next.js App Router + Vitest + ESLint + pnpm).
Critically, traits are managed and upgradable. When a framework ships a new major version, the upstream trait is updated, and /harness-upgrade shows you the diff and lets you adopt the changes.
The customization principle
A core design philosophy of harness engineering is that everything is adjustable. The harness provides opinionated defaults, but developers own their configuration:
- +Skills are markdown files. You can edit existing skills or add new ones. Custom skills are never overwritten during upgrades.
- +Workflows are YAML files. You can add new workflows alongside the harness-managed ones.
- +Traits are composable. Pick only the ones relevant to your stack.
- +Settings are mergeable. The harness provides starting points; you add your own hooks, permissions, and tool configurations.
- +CLAUDE.md is yours. The harness provides a snippet to copy; your project instructions are never touched.
The upgrade system respects this boundary. Harness-managed files are replaced on upgrade (with clear documentation of which files those are). Project-owned files are diffed, and you choose what to accept.
The migration and versioning system
The harness versions itself using semver. Each feature merge to dev auto-bumps the patch version and generates a structured migration file (YAML) describing:
- +What changed (scope: infrastructure, config, skill, trait, docs)
- +Who it affects (which variants, which traits)
- +Which files were modified
- +Priority level (REQUIRED, RECOMMENDED, INFORMATIONAL)
When a developer runs /harness-upgrade, the skill reads these migration files, filters by their variant and installed traits, and presents a smart upgrade plan. This means a project using only the "Code Only" variant with TypeScript and Vitest traits never sees changes about Railway environments or Prisma best practices.
What makes this different
Harness engineering is not just "CI/CD templates" or "AI coding tools." It is the combination of several ideas into a coherent discipline:
Prompts as the primary interface
The developer's main interaction is natural language. "Add dark mode." "Merge to dev." "Roll back production." The harness translates intent into infrastructure operations.
Convention-driven automation
No configuration per feature. A naming convention (claude/<name>-<session>) drives the entire pipeline. This means zero setup cost per feature and zero cleanup burden.
Full environment isolation
Every feature gets its own branch, preview URL, database, and file storage. There is no "it works on my machine" and no "I accidentally wrote to production."
AI-native workflow design
The harness is designed from the ground up for AI coding agents. Signal files, skill files, session hooks, and managed traits are all patterns that emerge from treating AI as a first-class development participant, not a bolt-on.
Composable and upgradable
The trait system, migration files, and managed/project-owned file distinction mean the harness evolves independently of your project. You get improvements without losing customizations.
Team-scale operations
Skills like /status, /review, /deps, and /continue are designed for teams where multiple people (or multiple AI sessions) work on different features simultaneously, each with isolated environments.
Who is this for?
- +Solo developers who want to focus on describing what to build, not managing infrastructure
- +Small teams (2-5 people) who need preview environments, code review workflows, and release management without a dedicated DevOps person
- +AI-first development shops that use AI coding agents as their primary development method and need the surrounding workflow to match
- +Rapid prototypers who want to go from idea to deployed feature with a single conversation
The bigger picture
Harness engineering represents a shift in how we think about software development infrastructure. Traditionally, CI/CD pipelines are configured once and maintained by specialists. Developers interact with them indirectly through git operations and hope things work.
In the harness engineering model, the CI/CD infrastructure is conversational. The developer (or AI) expresses intent through natural language and naming conventions. The infrastructure responds, provisions, deploys, and cleans up. The entire lifecycle, from "I want to build X" to "X is live in production," happens through a series of prompts and conventions.
This is not about replacing DevOps. It is about making the 90% of common development workflows so automated that teams can focus their DevOps energy on the 10% that is genuinely unique to their project.
The conventions are the harness. The prompts are the interface. The automation is the engineering.