Harness Config: A Source-to-Surface Model for AI Tool Config

Omar Aderkaoui — Tue, 02 Jun 2026 12:11:55 +0000

Most repositories were not designed for the number of AI coding tools developers now use side by side.

A repo might have AGENTS.md for Codex-readable instructions, .claude/ for Claude-specific configuration, .cursor/ for Cursor rules, .agents/ for another declared harness surface, plus prompts, skills, hooks, local settings, and tool-specific runtime files.

Each file makes sense on its own. Each tool needs somewhere to read instructions from.

The problem starts when those places become competing sources of truth.

A rule gets copied into multiple folders. One copy changes, another does not. A runtime setting gets written locally and then committed by accident. A team-specific override starts looking like shared project configuration.

The repo still works, but ownership becomes unclear.

That is the drift problem Harness Config is trying to address.

What Harness Config Means by “Harness”

Harness Config uses a few terms carefully.

A harness is an AI agent or developer-facing tool runtime that consumes repository instructions, context, tools, and configuration.

A harness surface is the repo-local file or folder that a harness reads from. Examples include:

AGENTS.md
.agents/
.claude/
.cursor/
another declared output location

The important idea is that these live surfaces do not have to be the durable source.

They can be projected outputs.

The Source-to-Surface Model

Harness Config proposes keeping reviewed configuration in a source layout, commonly under .harness/, and projecting that source into declared harness surfaces.

In plain terms:

.harness/ is the reviewed source.
Projection computes what each declared surface should receive.
AGENTS.md, .agents/, .claude/, .cursor/, and similar locations are the live harness surfaces.

The source is authored and reviewed.

The surfaces are what tools read.

That boundary matters because live tool folders often contain a mix of reviewed config, projected output, local settings, and runtime-owned state.

The CLI Workflow

The CLI follows the same model.

A manifest declares configured sources and declared surfaces. Then the CLI can validate the repo and preview activation before writing anything.

The rough workflow is:

npx harnessc validate
npx harnessc activate
npx harnessc activate --yes

The mental model is simple:

validate checks the configuration
activate previews the projection
activate --yes writes the projection

That preview step is important. It makes changes inspectable before projected files are updated.

This Is Not One Generic Config for Every Tool

Different AI tools need different configuration.

Codex, Claude, Cursor, and other harnesses do not all consume the same files in the same way. A useful standard has to allow those differences instead of hiding them.

Harness Config supports that through shared resources, target-specific overrides, profiles, composable instruction files, and mutable files.

That means:

shared resources can stay shared
tool-specific output can still be projected
profiles can switch configuration for different modes of work
mutable files can be seeded once and then owned by the runtime

The point is not to make every tool identical.

The point is to make ownership visible.

Why This Matters

As teams add more AI coding tools to the same repository, configuration drift becomes easier to miss.

Without a source-to-surface model, every new tool adds another place where instructions can be copied, changed, or forgotten.

Over time, a file may still be technically valid, but no one knows whether it is meant to be edited directly, projected from somewhere else, or owned by the runtime.

With a projection model, the repo can still support multiple harnesses, but the authored configuration has a clearer home.

I have been working on the repo as a collaborator, and this is the part that stands out to me: Harness Config is less about forcing tools to be the same, and more about making configuration ownership explicit.

Different harnesses should have different config when they need it.

But the repo should make it clear which files are reviewed source, which files are projected surfaces, and which files belong to the runtime.

That is the boundary Harness Config is trying to define.

Repo: https://github.com/reachjalil/harness-config