| name | harness-engineering |
| description | Use at the start of ANY coding task in a repository — feature work, bug fixes, refactors, or new projects. Applies harness engineering principles to ensure the agent works with and improves the repo's knowledge architecture, mechanical constraints, and feedback loops. Based on OpenAI's principles from building a million-line codebase with 0 manually-written lines of code. |
Harness Engineering
Overview
Harness engineering is the discipline of building environments, feedback loops, and control systems that let agents do reliable work at scale.
Core principle: Humans steer. Agents execute.
The engineer's job shifts from writing code to designing scaffolding — the tools, abstractions, knowledge structures, and mechanical constraints that let agents move fast without decay.
Announce at start: "I'm using the harness-engineering skill."
How to Apply This Skill on Every Task
Before writing any code, ask and act on these questions:
- Is the task legible in the repo? — Is there a design doc, spec, or execution plan that describes what needs to be done? If not, create one in
docs/ before starting.
- Does
AGENTS.md need updating? — If you're touching a new domain or introducing a new pattern, add a pointer to the relevant doc.
- Are there mechanical constraints to enforce? — If the task introduces a pattern that should always be followed, encode it as a linter rule or structural test, not just a comment.
- Can you leave the repo more legible than you found it? — If you find stale docs, undocumented assumptions, or missing cross-links while working, fix them as part of the task.
- Is the change reversible and verifiable by an agent? — Prefer designs where the agent can validate its own output (tests, CI, observable behavior) without human intervention.
The Engineer's New Role
In an agent-first system, humans work at a higher layer of abstraction:
| Old Role | New Role |
|---|
| Write code | Design environments |
| Fix bugs directly | Identify missing capabilities, encode fixes into tooling |
| Review all PRs | Define acceptance criteria; let agents review agents |
| Write docs | Validate and encode agent output into the knowledge base |
When something fails, the right question is never "try harder." It's: what capability is missing, and how do we make it legible and enforceable for the agent?
Phase 1: Knowledge Architecture
Give agents a map, not a 1,000-page manual.
A giant AGENTS.md fails in predictable ways:
- Context is scarce — a fat instruction file crowds out the actual task
- When everything is "important," nothing is
- Monolithic docs rot instantly and can't be mechanically verified
The Right Structure
AGENTS.md (~100 lines) is the table of contents only — short pointers to deeper sources of truth:
AGENTS.md ← entry point, ~100 lines, pointers only
ARCHITECTURE.md ← domain map, package layering, dependency rules
docs/
├── design-docs/
│ ├── index.md
│ └── core-beliefs.md
├── exec-plans/
│ ├── active/
│ └── completed/
├── product-specs/
│ └── index.md
├── references/ ← external docs as llms.txt for agent consumption
├── DESIGN.md
├── FRONTEND.md
├── QUALITY_SCORE.md ← grades each domain, tracks gaps over time
└── SECURITY.md
Rules
The rule: If the agent can't see it in the repo, it doesn't exist. Slack threads, meeting notes, and tacit knowledge must be encoded as markdown or they are lost.
Phase 2: Agent Legibility
Optimize the codebase for the agent's ability to reason over it, not for human stylistic preferences.
Dependency Choices
Favor "boring" technologies — stable APIs, high training set representation, full composability. Ask:
- Can the agent understand this library's full behavior from in-repo context?
- Is it cheaper to have the agent reimplement a narrow subset than to work around opaque upstream behavior?
Example: Rather than p-limit, implement a mapWithConcurrency helper — tightly integrated with your telemetry, 100% test coverage, behaves exactly as your runtime expects.
What to Make Legible
This unlocks prompts like: "ensure service startup completes in under 800ms" or "no span in these four critical user journeys exceeds 2 seconds."
Phase 3: Enforcing Architecture Mechanically
Encode invariants, not micromanagement. Enforce boundaries centrally, allow autonomy locally.
Layered Domain Architecture
Each business domain should have a strict, mechanically-enforced dependency order. Example:
Types → Config → Repo → Service → Runtime → UI
Cross-cutting concerns (auth, telemetry, feature flags) enter through a single explicit interface: Providers. Everything else is disallowed.
What to Enforce via Linters + CI
Write custom linter error messages that inject remediation instructions into agent context. The agent reads the error and self-corrects.
The Taste Feedback Loop
Human taste → review comments / refactoring PRs / bug reports → documentation update or linter rule. When docs aren't strong enough to enforce a pattern, promote it into code.
Phase 4: Throughput Philosophy
High agent throughput changes which engineering norms are correct.
| Low-Throughput World | Agent-First World |
|---|
| Block on flaky tests | Address flakes with follow-up runs; blocking is expensive |
| Long-lived PRs | Short-lived PRs; corrections are cheap |
| Heavy merge gates | Minimal blocking gates |
| Manual review required | Agent-to-agent review; humans validate outcomes |
The shift: In a system where agent throughput far exceeds human attention, waiting is expensive and corrections are cheap. This would be irresponsible in a low-throughput environment. Here, it's often the right tradeoff.
Phase 5: Entropy Management (Garbage Collection)
Technical debt is a high-interest loan. Pay it down continuously in small increments.
Full agent autonomy introduces entropy: agents replicate existing patterns — even bad ones.
Golden Principles
Define opinionated, mechanical rules that keep the codebase legible for future agent runs. Encode them directly in the repo. Examples:
- Prefer shared utility packages over hand-rolled helpers
- Never probe data shapes without validation or typed SDKs
- All invariants must be centralized, not spread across callers
Recurring Cleanup Process
Replace "Slop Fridays" (20% of the week on manual cleanup) with continuous automated garbage collection.
Increasing Autonomy Checklist
The end state: given a single prompt, the agent can end-to-end drive a new feature. This is earned incrementally by encoding each loop into the system.
Each checkbox requires investment: tools, guardrails, documentation — always written by the agent itself.
Red Flags
If you catch yourself or your team doing any of these, stop and encode the fix:
| Anti-Pattern | What It Signals |
|---|
| Humans writing code directly | Missing capability — what tool or abstraction is absent? |
| Spending >10% of time on cleanup | Entropy management isn't automated yet |
| Important context in Slack/docs outside repo | Agent can't see it — encode it |
| "The agent doesn't understand our X" | X isn't legible in the repo — make it so |
| Monolithic AGENTS.md growing past ~100 lines | Break it up; add docs/ structure |
| Agents reinventing the same helpers | Missing shared utility package; add + lint for it |
| Review bottlenecked on humans | Move review effort to agent-to-agent |
Quick Reference
| Phase | Goal | Signal It's Working |
|---|
| 1. Knowledge Architecture | Map, not manual | AGENTS.md stays ~100 lines; docs are cross-linked |
| 2. Agent Legibility | Agent reasons over full domain from repo | Agent can reproduce bugs, drive UI, query metrics |
| 3. Mechanical Enforcement | Invariants via linters, not docs | Architectural drift caught in CI before merge |
| 4. Throughput Philosophy | Corrections cheap, waiting expensive | PRs short-lived; agent-to-agent review dominant |
| 5. Entropy Management | Continuous GC, not batch cleanup | Background cleanup PRs merge daily |
Related Skills
- superpowers:writing-plans — For creating execution plans as first-class repo artifacts
- superpowers:brainstorming — For designing the system before building it
- superpowers:systematic-debugging — When the agent is failing, diagnose what capability is missing
