85 agentic tools audited for security incidents · Talk to the lab →
MotionticBook a call
Glossary

What are golden principles in agent-written code?

Golden principles are opinionated, mechanical rules about a codebase, written into the repository so that recurring background agents can scan for deviations and open small refactoring pull requests that keep agent-written code consistent.

The term comes from OpenAI's "Harness engineering: leveraging Codex in an agent-first world" (2026-02-11), by Ryan Lopopolo. A small team spent five months building an internal product with no hand-written code: roughly a million lines and about 1,500 merged pull requests, all written by Codex.

That speed created a new problem. Codex copies the patterns already in a repository, including uneven or poor ones, so the codebase drifts. The team first spent every Friday, 20% of the week, cleaning up what it called AI slop. That did not scale, so it wrote its taste down as golden principles and handed the clean-up to agents.

How the loop works

  • Write the rule down

    Each principle is an opinionated, mechanical rule kept in the repository, where agents can read it.

  • Scan on a schedule

    A set of background Codex tasks runs on a regular cadence, scanning for code that breaks a principle.

  • Grade and fix

    The same tasks update quality grades and open targeted refactoring pull requests.

  • Merge quickly

    OpenAI reports most of those pull requests can be reviewed in under a minute and merged automatically.

Examples from the post

Two principles are named. Prefer shared utility packages over hand-rolled helpers, so invariants stay in one place. And do not probe data shapes by guesswork: validate at the boundary or use typed SDKs, so the agent cannot build on a shape it invented.

The post compares the result to garbage collection. Technical debt is paid down in small daily increments instead of in painful bursts, and human taste is captured once and then enforced on every line.

What sits next to them

  • Custom linters

    Hard boundaries, such as which architectural layer may depend on which, are enforced by linters and structural tests whose error messages tell the agent how to fix the problem.

  • AGENTS.md as a map

    A short root file of about 100 lines points to a structured docs folder. It is a table of contents, not the place the rules are enforced.

  • Doc gardening

    A separate recurring agent looks for documentation that no longer matches the code and opens fix-up pull requests.

Limits

OpenAI says plainly that the setup depends on this repository's structure and tooling and should not be assumed to generalise without similar investment. The team also does not yet know how architectural coherence holds up over years in a fully agent-written system.

A principle that is too vague for an agent to check becomes noise, and one that is wrong gets applied everywhere at once. The rules need the same review as code.

How Motiontic's engineers apply it

On client codebases where agents write a large share of the code, Motiontic's engineers start with the rules a linter can enforce, then add a short list of principles that need judgement, each with an example of right and wrong. Any agent clean-up runs as small pull requests that a person can review in minutes.

Common questions

What are golden principles in harness engineering?

They are a short set of opinionated rules about how a codebase should look, written into the repository so background agents can find violations and fix them with small pull requests.

How are golden principles different from a linter?

A linter enforces rules that can be checked mechanically on every change. Golden principles include rules that need some judgement, enforced by agents scanning the code on a schedule.

Where do golden principles live?

In the repository itself, alongside the docs and plans agents already read, because anything an agent cannot see while running effectively does not exist for it.

Running agents that have to hold up?

Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.