What is Harness Engineering?

Harness Engineering is the discipline of steering AI coding agents to produce reliable, maintainable software. Rather than writing every line by hand, engineers design the environments, specify intent, and build the feedback loops that enable an agent to ship at scale.

The central insight: the quality of AI-generated code is a function of the harness that surrounds the model, not the model alone. This repository is the Harness Engineering framework specialized for GitHub Copilot in VS Code — the surfaces are different from Claude Code or Cursor, but the discipline is the same.

The Copilot Harness Stack

GitHub Copilot reads customization from a small set of well-defined files. A complete Copilot harness layers all of them:

| Layer | File(s) | Purpose | |-------|---------|---------| | Repository instructions | .github/copilot-instructions.md | Loaded on every Copilot Chat request in this repo. Short, high-signal context. | | Scoped instructions | .github/instructions/*.instructions.md | Per-pattern rules, activated via applyTo globs. | | Reusable prompts | .github/prompts/*.prompt.md | Slash-command prompts invoked as /<name> in chat. | | Custom agents | .github/agents/*.md | Specialized Copilot personas (planner, reviewer, refactorer) with tool restrictions. | | Universal config | AGENTS.md | Read by Copilot Coding Agent and most other coding agents. | | Tool wiring | .vscode/mcp.json | MCP servers exposed to Copilot Chat. |

A weak harness limits even a great model. The model is the commodity; the harness is the craft.

Quick Start

Install with npx (recommended)

# Inside the repo you want to harness
npx harness-copilot init

This scaffolds .github/copilot-instructions.md, .github/instructions/, .github/prompts/harness-*.prompt.md, .github/agents/, AGENTS.md, and .vscode/mcp.json into the current project.

Install with the bundled script

git clone https://github.com/harness-engineering/harness-copilot.git
cd harness-copilot && ./setup

Run Your First Audit

After installing, open Copilot Chat in VS Code and run:

/harness-audit

This triggers a 5-phase workflow: Discovery (detect stack), Assessment (score 10 components), Gap Report (structured output), Plan (prioritized actions), Execution (apply fixes).

Available Skills

Each skill is a .github/prompts/harness-<name>.prompt.md you invoke from Copilot Chat with a slash command.

| Command | Description | |---------|-------------| | /harness-audit | Full 5-phase harness engineering audit | | /harness-copilot-instructions | Generate .github/copilot-instructions.md | | /harness-instructions | Generate scoped .github/instructions/*.instructions.md files | | /harness-prompts | Generate reusable .github/prompts/*.prompt.md slash commands | | /harness-agents | Generate custom .github/agents/*.md agent profiles (planner, reviewer, etc.) | | /harness-agents-md | Generate universal AGENTS.md | | /harness-architecture | Generate ARCHITECTURE.md (matklad pattern) | | /harness-verify | Set up test/lint/type-check verification loops | | /harness-hooks | Set up pre-commit hooks | | /harness-ci | Set up GitHub Actions CI/CD pipeline | | /harness-linters | Create custom lint rules + structural tests | | /harness-entropy | Set up quality grades + drift detection | | /harness-sdd | Set up Specification-Driven Development workflow | | /harness-long-running | Set up multi-session agent workflow | | /harness-maintain | Update harness docs after code changes | | /harness-help | List all commands and project status |

CLI flags

npx harness-copilot init                  # Interactive
npx harness-copilot init --yes            # Non-interactive defaults
npx harness-copilot init --global         # User-level VS Code prompts folder
npx harness-copilot init --skills harness-audit,harness-verify
npx harness-copilot list                  # List all skills
npx harness-copilot update                # Re-sync skills in-place

The Three Pillars

1. Context Engineering

Curating and delivering knowledge to Copilot so it makes informed decisions. In a Copilot harness this means .github/copilot-instructions.md, scoped .instructions.md files with applyTo globs, AGENTS.md, and structured docs (ARCHITECTURE.md, ADRs, glossaries).

2. Architectural Constraints

Guardrails that prevent Copilot from producing structurally invalid output. Custom linters, structural tests, enforced module boundaries, strict type configs, and schema validators — each delivering machine-readable, actionable error messages so Copilot can self-remediate.

3. Entropy Management

The ongoing effort to fight decay that accumulates at AI-generated velocity. Quality grades, doc freshness checks, dead-code sweeps, and scheduled drift detection. Includes instruction-rot detection for .github/copilot-instructions.md itself.

Learn More

1. Read the docs — docs/ covers Copilot customization surfaces, harness principles, and anti-patterns.
2. Follow a guide — guides/ walks you through your first Copilot harness.
3. Browse templates — templates/ has ready-to-use Copilot configuration files.
4. Use checklists — checklists/ give step-by-step audit verification.

Supported Stacks

Skills and instruction templates are tuned for the Microsoft stack: C# / .NET 8+, F#, ASP.NET Core, Blazor, .NET MAUI, Entity Framework Core, Azure Functions, TypeScript / React (TypeScript is Microsoft), and PowerShell. Generic-language detection still works — the rubrics travel — but starter templates and examples target this stack.

Who Is This For?

Individual engineers who want dramatically more leverage from Copilot. Learn the patterns that separate productive Copilot-assisted development from frustrating prompt-and-pray workflows.

Engineering teams adopting Copilot across a shared codebase. Establish shared .github/copilot-instructions.md, .github/instructions/ rules, and entropy budgets so every developer's Copilot produces consistent output.

Engineering leaders building organization-wide Copilot strategies. Understand the investment areas — context infrastructure, constraint pipelines, entropy budgets — that determine whether Copilot adoption accelerates delivery or creates technical debt.

Repository Structure

harness-copilot/
|-- skills/                       Pluggable skills (SKILL.md + bundled templates)
|   |-- harness-audit/            Full harness audit (primary entry point)
|   |-- harness-copilot-instructions/  Generate .github/copilot-instructions.md
|   |-- harness-instructions/     Generate scoped .instructions.md files
|   |-- harness-prompts/          Generate reusable .prompt.md slash commands
|   |-- harness-agents/           Generate custom .github/agents/*.md profiles
|   |-- harness-agents-md/        Generate AGENTS.md
|   |-- harness-architecture/     Generate ARCHITECTURE.md
|   |-- harness-verify/           Set up verification loops
|   |-- harness-hooks/            Set up pre-commit hooks
|   |-- harness-ci/               Set up CI/CD pipeline
|   |-- harness-linters/          Custom lint rules
|   |-- harness-entropy/          Entropy management
|   |-- harness-sdd/              Specification-Driven Development
|   |-- harness-long-running/     Multi-session workflow
|   |-- harness-maintain/         Maintain harness docs
|   |-- harness-help/             Help and status
|-- agent/                        Reference playbooks and specs
|-- docs/                         Concepts: Copilot surfaces, principles, anti-patterns
|-- guides/                       Step-by-step walkthroughs
|-- templates/                    Canonical Copilot template files
|-- checklists/                   Audit checklists
|-- bin/                          CLI (npx harness-copilot)
|-- tests/                        Test suite
|-- project/                      Roadmap, decisions, progress
|-- setup                         Bundled bash setup script
|-- package.json                  npm manifest

Key Resources

| Resource | Description | |---|---| | Skills | 16 pluggable slash commands for auditing and improving Copilot harnesses | | Docs | Concepts: Copilot customization surfaces, principles, anti-patterns | | Guides | Getting started, pillar deep-dives, migration playbooks | | Templates | Canonical templates for .github/copilot-instructions.md, instructions, prompts, custom agents, MCP | | Checklists | Audit your harness against best practices |

Acknowledgments

This framework builds on the work and ideas of many people:

• Mitchell Hashimoto — for coining and popularizing the term Harness Engineering and articulating the distinction between the model and the harness.
• The GitHub Copilot team — for building the customization surfaces (copilot-instructions.md, .instructions.md, .prompt.md, custom agents) that this framework targets.
• Martin Fowler, Birgitta Bockeler, and Chad Fowler — for their writing on AI-assisted software delivery.
• The Spotify, Microsoft, and GitHub engineering blogs — for sharing real-world experiences scaling AI coding agents.
• The NinjaCodeTurtle / harness-engineering project — the upstream multi-tool framework this repository is derived from. Concepts and rubrics are inherited; surfaces are rewritten for Copilot.

Contributing

We welcome contributions of all kinds: new guides, templates, corrections, and improvements. Please read the Contributing Guide before submitting a pull request.

Every contributor is expected to follow our Code of Conduct.

Security

If you believe this repository contains a security issue, please follow the private reporting guidance in SECURITY.md. Do not open a public issue for suspected vulnerabilities.

License

This project is licensed under the Apache License 2.0.

Copyright 2025 Harness Engineering Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.