Harness Engineering

Harness engineering

Turn repeated coding-agent mistakes into durable repository artifacts by combining instructions, constraints, feedback, memory, evaluation, and governance into a small, evidence-backed harness.

When to invoke

• "Make this repository more reliable for GitHub Copilot."
• "Add durable agent instructions and guardrails."
• "Prevent this coding-agent mistake from happening again."
• "Add drift checks for our project rules."
• "Review or refresh our existing agent harness."

Harness model

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

Discovery evidence

Read these files and folders when they exist, then summarize the stack, entry points, commands, conventions, failures, and unenforced rules:

• README.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/
• .github/workflows/
• CONTRIBUTING.md
• package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, or build.gradle
• docs/
• scripts/
• existing tests and CI checks

Adoption workflow

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.

Agent instructions must cover project purpose, ownership boundaries, setup, test, lint, build, verification commands, package manager rules, dependency rules, safe editing rules, generated file rules, forbidden paths, testing expectations, PR or commit conventions, and how to record new failures or decisions. Avoid broad personality guidance and rules that cannot be checked or reviewed.

Enforceable checks and failure memory

Good checks are narrow, fast, named clearly, documented with the rule they protect, and runnable locally or in CI.

Rule: Do not edit generated API clients.
Check: script scans diffs for generated paths and fails with a clear message.

Rule: Every failure memory note names a regression check.
Check: script validates docs/failures/*.md for a "Detection" section.

Rule: Profile docs and templates must stay aligned.
Check: test compares profile README files to expected template files.

Create docs/failures/<slug>.md for user-visible, high-risk, or recurring failures unless an existing note already covers the root cause:

# Short Failure Title

## Summary
What failed, who saw it, and why it matters.

## Root Cause
The technical or process cause. Avoid blame.

## Prevention
Instruction, test, drift check, CI gate, fixture, or manual review point that prevents or detects recurrence.

## Evidence
Links to issue, PR, test, log, command output, or file paths.

If automation is unsafe, record the manual review point and why automation would mislead.

Drift checks and review criteria

Use drift checks when guidance can silently become stale: docs mention removed commands, profile snippets diverge from generated examples, failure notes omit regression checks, decision records are missing for structural changes, or CI references stale scripts or package commands. Prefer the repository's existing language; if there is no convention, Python with only the standard library is a portable default.

When reviewing harness changes, take an opposing perspective and report findings first, ordered by severity, with file and line references when available. Look for generic copied rules, duplicate or conflicting instruction files, broad checks with false positives, unenforced high-risk rules, missing failure memory, generated docs not refreshed, CI gates that skip relevant checks, and harness defaults overwriting target conventions. Do not modify files during review unless explicitly asked.

Limits

• Do not use this skill for ordinary feature implementation unless the user asks to improve the repository's agent operating environment.
• Do not copy generic templates without repository evidence.
• Do not create duplicate harness surfaces when an equivalent location already exists.

Optional external reference use

The prompt-first harness workflow at https://github.com/baskduf/harness-starter-kit is optional reference material only when the user asks for it or the target repository already uses it. Do not let that reference override repository evidence.

Output template

## Harness engineering report

**Status:** adopted | reviewed | blocked
**Repository inspected:** <path or repository>

### Evidence reviewed
- <file or folder>: <fact learned>

### Harness changes or findings
| Area | Artifact | Rule or finding | Enforcement |
| --- | --- | --- | --- |
| Instructions | `<path>` | <target-specific rule> | <check, CI, or manual review point> |

### Validation
- `<command or review>`: <pass, fail, or not run with reason>

### Follow-up
- <assumption, skipped failure memory reason, or next check>

Quality gate

• The target repository was inspected before edits or review conclusions.
• New or changed guidance is specific to repository evidence.
• High-value rules have checks, CI gates, or documented manual review points.
• Failure memory was created when required, or the report explains why it was skipped.
• Generated docs or indexes were refreshed when affected.
• The final report names every command run and its result.
• Review output lists findings by severity and does not edit files unless requested.

References

• Harness starter kit