Harness-Engineering

# Harness Engineering

Harness engineering turns repeated coding-agent mistakes into durable

repository artifacts:

Harness = Instructions + Constraints + Feedback + Memory + Evaluation + Governance

Use this skill when the user asks to:

- make a repository more reliable for GitHub Copilot or other coding agents

- add durable agent instructions, repository rules, or guardrails

- prevent repeated AI coding-agent mistakes

- record known failure paths and the checks that prevent recurrence

- add lightweight drift checks for project rules

- review, refresh, or update an existing agent harness

Do not use this skill for ordinary feature implementation unless the user asks

to improve the repository's agent operating environment.

Core Principles

- Treat the target repository as the source of truth.

- Inspect before editing. Preserve the existing stack, package manager, CI,

docs, naming, and architecture.

- Add the smallest useful harness. Prefer updating existing files over adding

duplicate guidance.

- Make important rules enforceable where practical through tests, linters,

type checks, CI, pre-commit hooks, or drift scripts.

- Use manual review points only when automation would be brittle or misleading.

- Record high-risk failures that should not recur, and name the check or review

point that catches recurrence.

- Do not copy generic templates blindly. Adapt every artifact to real evidence

in the target repository.

Discovery

Before proposing or making harness changes, inspect the repository for existing

rules and evidence.

Read these files and folders when they exist:

- `README.md`

- `AGENTS.md`

- `.github/copilot-instructions.md`

- `.github/instructions/`

- `.github/workflows/`

- `CONTRIBUTING.md`

- package manifests such as `package.json`, `pyproject.toml`, `go.mod`,

`Cargo.toml`, `pom.xml`, or `build.gradle`

- existing docs under `docs/`

- existing scripts under `scripts/`

- existing tests and CI checks

Then summarize:

- stack, package manager, and entry points

- existing development and verification commands

- current agent instructions or repository conventions

- known failures, incidents, flaky paths, or repeated review comments

- gaps where project rules are not enforced

Adoption Workflow

Follow this sequence:

1. Choose the harness surface that fits the target repository.

2. Write target-specific agent instructions.

3. Add enforceable checks for high-value rules.

4. Record failure memory for high-risk or recurring failures.

5. Add drift checks for guidance that can silently become stale.

6. Report the adoption with evidence, assumptions, and follow-up.

1. Choose the Harness Surface

Pick only the surfaces that fit the target repository:

| Need | Preferred artifact |

| --- | --- |

| Always-on agent behavior | `AGENTS.md` or `.github/copilot-instructions.md` |

| File-scoped guidance | `.github/instructions/*.instructions.md` |

| Recurring project checks | `scripts/check_*.py`, shell scripts, or package scripts |

| CI enforcement | existing workflow files or a small new workflow |

| Known failures | `docs/failures/*.md` |

| Architecture or process decisions | `docs/decisions/*.md` |

| Adoption evidence | `docs/harness/adoption-report.md` or similar |

If the repository already has an equivalent location, update it instead of

creating a parallel system.

2. Write Agent Instructions

Agent instructions should be concrete and operational. Include:

- project purpose and major ownership boundaries

- setup, test, lint, build, and verification commands

- package manager and dependency rules

- safe editing rules, generated file rules, and forbidden paths

- testing expectations for changed code

- PR and commit conventions if the repo has them

- how to record new failures or decisions

Avoid broad personality guidance, generic best practices, and rules that cannot

be checked or reviewed.

3. Add Enforceable Checks

Convert high-value rules into checks. Good harness checks are:

-