How to Stop Writing Code by Hand and Start Designing Harnesses for Neural Networks

Recently I caught myself feeling strange. You're sitting in an editor, launching an agent like Claude Code or Cursor, giving it a task, and ten minutes later you're sorting through a mess of made-up functions and broken types. Trying to dictate a five-page system prompt usually makes things worse: the model forgets the beginning of the instruction by the third step.

It turns out that in the engineering community around OpenAI, Anthropic and Cursor, this problem has already been formalized into a separate discipline. It's called Harness Engineering, which can be translated as designing harnesses or bridles for agents.

Repository deusyu/harness-engineering has gathered an extensive knowledge base on this topic in one place: analyses of concepts, translations of dozens of English-language articles from engineers like Martin Fowler, LangChain and the creators of Bun, as well as ready-made templates for implementing this approach in your own projects.

Where the Idea Came From

If in classical development a person writes code and the machine executes it, then with the arrival of autonomous agents the chain changes. A person formulates constraints and rules of the game, the neural network writes code, and the environment runs checks and returns feedback to the agent.

The point is that the engineer stops being the author of every line. The engineer's main product becomes a system of constraints: configuration files AGENTS.md, custom linters, structural tests, and strict gates in CI.

The repository cites data from a real experiment by one of the teams: over 5 months, a team of 3-7 people merged about 15,000 pull requests totaling nearly a million lines of code, closing an average of 3.5 PRs per person per day. Most of the generation ran overnight in six-hour sessions.

Main Principles of Harness Engineering

The repository author deconstructs the approach into several applied concepts.

Repository as the Single Source of Truth

Everything that isn't inside a git repository doesn't exist for the agent. Your Zoom calls, architecture discussions in Slack, or drafts in Google Docs don't make it into the model's context.

If you decided to change an API signature or agreed on a folder structure, this should live in the repository as versioned files. Any specifications and task plans are immediately committed to a branch.

A Map Instead of an Encyclopedia

A common mistake when setting up agentic development is creating a massive system file with all project instructions. Models get overwhelmed by lengthy prompts.

Instead, a AGENTS.md file of about 100 lines is used. It works as a table of contents or map of the terrain, pointing the agent to which subdirectories to look at for details depending on the task. Each subdirectory contains its own local AGENTS.md. This principle is called progressive context disclosure.

Mechanical Control Instead of Verbal Persuasion

Text rules in documentation quickly become outdated, and agents tend to ignore or misinterpret them. Linters and unit tests don't become outdated.

Instead of lengthy architecture style descriptions, custom linters are written. The most interesting part: error messages in such linters immediately contain clear instructions for fixing the issue. The agent runs the check, catches the linter error, reads the hint text, and rewrites the problematic code section itself.

Code readability for agents and entropy management

When choosing libraries, priority is given to stable, well-documented technologies with predictable behavior. If a library is too complex or uses dark metaprogramming magic, the agent will constantly stumble. Sometimes it's easier to implement a simple internal module from scratch than to make the neural network guess the behavior of an opaque external package.

Additionally, agents love copying bad patterns if they find them in the existing codebase. To prevent the repository from rotting, special refactoring agents run in the background, whose task is reduced to finding deviations from standards and creating corrective PRs.

Self-Referential Repository

What makes project deusyu/harness-engineering compelling is that it's built on the very principles it describes.

Inside the repository, a strict scripts/check-consistency.sh script runs, triggered via pre-commit hooks and GitHub Actions. The script checks thirteen levels of integrity:

• Verifies the exact number of articles mentioned in badges and documentation
• Monitors that the directory structure matches the declared file tree
• Validates all links and tables
• Controls image audits in article translations so that no diagrams from the originals are lost

The process of adding new materials is automated through a specialized Claude skill, where agents perform initial parsing and formatting of articles, while a human acts only as the final censor.

Who This Project Is For

If you're writing pet projects solo or want to set up efficient work with Cursor, Claude Code, Aider, or local models in your team, this repository is worth bookmarking.

There are no magic buttons or ready-made binaries here. This is a handbook and a collection of engineering experience, explaining why your prompts stop working over distance and how to configure the repository so that neural networks bring benefits instead of turning the codebase into a dump.

The easiest way to start learning is with the files in the concepts/ directory, then look at the implementation of AGENTS.md at the project root and try on a similar structure for your own working repositories.