October 29, 2026 · Harness Engineering · Coding Agents · Comparison · EN

Repository Harness vs App Template: They Solve Different Problems

An app template chooses initial code and dependencies. A repository harness defines how coding agents discover authority, stay in scope, verify changes, and maintain the repository over time.

An app template chooses the initial shape of an application. A repository harness defines how humans and coding agents understand, change, verify, and maintain that application after the scaffold exists.

The two are complementary, but confusing them creates brittle repositories.

A template can give you React, Next.js, authentication, linting, tests, CI, and a directory layout in seconds. That is valuable. It reduces blank-page setup cost.

But a coding agent working six months later faces different questions:

• Which document is authoritative for this behavior?
• Is this file generated or safe to edit?
• Which paths are in scope for this task?
• Which command proves the changed contract?
• Which operations need approval?
• What decision must survive the current session?
• How should an upstream update preserve local changes?

Those are repository-operating questions. They belong to a harness, not merely to a starter snapshot.

The short answer

The practical choice is rarely “template or harness.” It is:

1. use a template when you need a starting application shape;
2. use a harness when you need a durable operating contract;
3. use both when starting a new agent-assisted project.

What an app template actually solves

Official scaffolding tools describe their job clearly.

Vite’s guide calls create-vite a tool for quickly starting a project from a basic framework template. Next.js documents create-next-app as a way to create a new application from the default template or a public example.

A mature app template may decide:

• framework and language;
• directory structure;
• dependency versions;
• styling and component conventions;
• authentication or database examples;
• lint, test, build, and deployment configuration;
• sample routes and placeholder domain code.

That is a source-code bootstrap. Its unit of value is the generated application.

The template is strongest at time zero, when the repository has little local history. After generation, the application diverges. Teams change architecture, add constraints, reject patterns, replace tools, and accumulate operational knowledge.

Unless the template includes a safe maintenance mechanism, its relationship with the generated repository ends at creation. Re-running it later risks overwriting local work or creating an unreviewable diff.

What a repository harness solves

A repository harness is an operating layer around the codebase.

It helps a fresh coding-agent session answer six classes of question:

1. Authority: What defines the intended behavior, and which source wins if files disagree?
2. Context: Where should this kind of work begin?
3. Boundaries: What may change, what is generated, and what requires approval?
4. Validation: Which executable checks prove the claims made by this change?
5. Continuity: Which decisions and checkpoints must survive the current session?
6. Evidence: What must the handoff include so another reviewer can reproduce the result?

This is why a useful root AGENTS.md behaves like a router rather than an encyclopedia. OpenAI described the same failure in its harness-engineering write-up: a giant instruction file consumes context, loses prioritization, rots quickly, and is hard to verify. The repository’s structured knowledge should remain the system of record.

A harness therefore connects concise routing to deeper repository-native sources:

AGENTS.md                  operating entry point and global boundaries
docs/README.md             repository map
docs/ARCHITECTURE.md       dependency direction and subsystem seams
docs/decisions/            accepted tradeoffs and reopening conditions
docs/VALIDATION.md         change type to proof command
api/openapi.yaml           authoritative API contract
src/generated/             derived output; do not edit directly
.github/workflows/         executable CI and release behavior

The exact filenames matter less than the contracts. A fresh agent should discover the right source before making the first material decision.

Why “agent-ready template” is not enough by itself

A starter can include AGENTS.md, CLAUDE.md, Cursor rules, or Copilot instructions. That does not automatically make the generated repository agent-ready.

The files can fail in several ways:

1. The instructions describe the template, not the application

The scaffold may say “all API code lives under src/api.” Six months later the team has split the application into services, but the copied instruction still routes agents to the old path.

2. The template guesses product truth

A generic scaffold cannot know which document controls billing behavior, whether a migration is reversible, or which compatibility promise matters to consumers. That authority must come from the actual repository.

3. Validation is generic rather than claim-specific

npm test is useful only when it covers the behavior being changed. A generated command list is not a validation contract unless it maps change types to relevant checks.

4. There is no maintenance boundary

If instructions are copied once, who owns them? How are upstream improvements adopted? What happens when local and upstream edits overlap?

5. Tool files become duplicated policy

Copying the same rules into five vendor-specific files creates drift. A stronger pattern keeps one repository contract and uses thin tool adapters only where discovery requires them.

An agent-ready template can be excellent. But its agent layer must be treated as a maintained subsystem, not as decorative Markdown shipped beside the application.

New project: use both layers deliberately

For a new project, the clean sequence is:

Step 1: scaffold the application

Choose the framework and template that match the product, deployment surface, and team capabilities. Generate the app, install dependencies, and run its baseline checks.

Record the exact source and version of the template. A future reviewer should know where the initial application shape came from.

Step 2: establish repository authority

Replace template placeholders with real product and architecture ownership:

• current product contract;
• architecture and source-of-truth map;
• generated-output rules;
• validation entry points;
• deployment and secret boundaries;
• accepted decisions.

Do not ask the harness to invent this information.

Step 3: install the repository operating layer

Add a concise entry point, scoped instructions at real subsystem boundaries, task envelopes, evidence handoffs, and durable state only where the repository needs them.

repository-harness is designed for this layer. It installs a small repository protocol and safe updater while keeping product documents, decisions, code, tests, CI, and runtime evidence as the system of record.

Step 4: prove the combined repository in a clean session

Give a new agent a representative task without replaying private setup instructions. Check whether it can:

1. find the controlling source;
2. name the editable and generated surfaces;
3. state its authority and stop conditions;
4. select checks that cover the change;
5. return results, omissions, and residual risk.

If the agent succeeds only after a human points it to files, the repository is not yet self-describing.

Existing project: skip the scaffold

An existing repository usually does not need a new app template. It already has the valuable part: real code, real decisions, real failures, real users, and real constraints.

Applying another starter can create more work than value:

• competing directory structures;
• duplicate configuration;
• dependency churn;
• generic examples mixed with production code;
• accidental replacement of local conventions.

Instead, migrate one decision path at a time.

Start with a repeated failure such as:

• an agent edits generated output instead of its source;
• a small request expands into an unrelated refactor;
• the wrong test suite is used as proof;
• a rejected architecture choice is proposed again;
• work is lost across sessions;
• an interrupted update cannot resume safely.

Then add the smallest repository control that prevents the first wrong decision. The existing-repository migration guide gives the full sequence: observe, route, bound, prove, hand off, and rerun cleanly.

A decision framework

Choose an app template when:

• the application does not exist yet;
• framework and dependency defaults are the main open decisions;
• the team wants a working baseline quickly;
• generated example code is genuinely useful;
• the scaffold’s update and ownership model is acceptable.

Choose a repository harness when:

• the repository already exists;
• coding agents repeatedly need human navigation;
• local authority is distributed across code, docs, tests, and CI;
• scope or approval boundaries matter;
• generated files and source files are easy to confuse;
• evidence quality varies across sessions;
• instructions or upstream protocol files need safe maintenance.

Choose both when:

• you are creating a new project that coding agents will maintain;
• you want fast scaffolding without treating the scaffold as permanent authority;
• the team needs both application defaults and durable operating contracts.

Choose neither yet when:

• the product outcome is still undefined;
• the team cannot name an authoritative source;
• there is no representative task to test;
• adding files would only make uncertainty look organized.

In that case, clarify product and repository ownership before automating it.

Keep the layers separable

A strong combined system does not merge template and harness into one indivisible generator.

Keep clear boundaries:

Application layer
  framework, product code, domain policy, runtime, deployment

Repository harness layer
  routing, authority, boundaries, validation, continuity, evidence

Tool adapters
  CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md, etc.

This separation has three benefits.

First, the team can change frameworks without discarding the operating contract.

Second, harness improvements can arrive without replacing application code.

Third, tool-specific adapters can change while the repository’s authority remains stable.

A repository harness should be boring in the best sense: inspectable, versioned, reversible, and subordinate to the repository it serves.

How repository-harness draws the boundary

The current repository-harness contract is intentionally narrow.

It installs:

• a compact AGENTS.md entry point;
• repository context and navigation;
• optional product, decision, plan, runbook, and evidence locations;
• explicit-only skills for discovery, audit, invariant encoding, and harness improvement;
• a versioned maintenance binary with status, doctor, dry-run, update, conflict staging, continuation, and abort paths.

It does not install:

• application architecture;
• product policy;
• validation commands;
• credentials;
• databases or schemas;
• orchestration;
• background processes.

That boundary is the point. The consumer repository owns the application and its workflow. The harness makes those choices legible and safely maintainable; it does not make them on the team’s behalf.

Evaluation checklist

Before adopting an app template, repository harness, or combined starter, test these questions:

Application scaffold

• Does it use a current framework and supported runtime?
• Are dependencies and generated examples minimal enough to own?
• Can the team remove optional pieces cleanly?
• Is the source/version of the scaffold recorded?
• Is there an update strategy, or is generation intentionally one-time?

Repository harness

• Can a fresh agent find the controlling source before editing?
• Are global and scoped rules separated?
• Are source and generated outputs explicit?
• Are local edits preserved during updates?
• Do conflicts stop activation rather than partially overwrite files?
• Do validation commands cover changed claims?
• Are write, deploy, release, secret, and destructive boundaries explicit?
• Does the handoff include commands, results, omissions, and residual risk?

Combined system

• Can the app layer evolve without overwriting the harness?
• Can the harness evolve without replacing application code?
• Is repository truth authoritative over template defaults?
• Are tool-specific instructions thin adapters rather than duplicated policy?
• Does a clean session complete a representative task without hidden guidance?

The practical rule

Use templates to accelerate creation. Use harnesses to improve operation.

A template answers: What application should exist at the start?

A repository harness answers: How should work proceed safely after the repository becomes real?

If you are starting a new agent-assisted project, combine them—but keep the layers independent. If you already have a production repository, preserve its local truth and add the harness incrementally.

Start with the agent-ready repository model, follow the migration workflow, or evaluate the current repository-harness implementation.

FAQ

What is the difference between a repository harness and an app template?

An app template scaffolds initial application code, dependencies, and configuration for a chosen stack. A repository harness defines the operating contracts that help humans and coding agents find authority, respect boundaries, validate changes, preserve continuity, and maintain the repository safely over time.

Can an app template be agent-ready?

Yes, but generated agent files alone are not enough. The template must ship maintained authority, context, boundary, validation, continuity, and evidence contracts. Those contracts must remain correct as the generated application evolves.

Should a new project use both an app template and a repository harness?

Often yes. Use the template for the initial application shape and the harness for future operating discipline. Keep them separable so framework, application, harness, and tool adapters can evolve independently.

Does a repository harness choose my framework or application architecture?

No. Framework choice, architecture, product policy, credentials, schemas, and runtime infrastructure remain consumer-owned. A harness should reveal and enforce the repository’s choices, not invent them.

Can I add a repository harness to an existing codebase?

Yes. Existing repositories are often the strongest use case because they contain real authority, history, tests, and local conventions. Start with one recurring failure and add the smallest control that prevents it.

How do I evaluate an agent-ready starter template?

Run a representative task in a fresh session. Verify that the agent can find authority, distinguish sources from generated output, identify approval boundaries, run covering checks, and return evidence without hidden human correction.

What does repository-harness install?

It installs a compact operating entry point, repository navigation, optional durable templates, explicit-only skills, and a safely maintainable core. It does not install the consumer application’s architecture, policy, validation commands, credentials, database, schemas, orchestration, or background services.