Personal Harness Engineering

Codex works better when the project has simple local memory. Not huge documentation, and not a perfect manual. A small file structure that says where to look, what to preserve, which architecture is current, and which decisions have already been made.

That is the practical point of OpenAI's Harness Engineering article: the environment around the agent matters. Agent-friendly repositories do not depend only on better prompts; they leave rules, plans, context, and project knowledge where the agent can recover them.

The file that completes this pattern is ARCHITECTURE.md. Matklad described it as a short map of a project's physical architecture in ARCHITECTURE.md, starting from the concrete rust-analyzer example.

I adapt those ideas to a personal scale: one person, many projects, many fronts, many conversations with agents. The goal is to turn good references into an execution shape another agent can apply without rediscovering the whole source chain.

The Pattern

A personal harness has three main pieces.

First, an instruction file for agents. It can be AGENTS.md, CLAUDE.md, .cursor/rules, CONTRIBUTING.md, or whatever file the person's tool already reads. This file should stay short: read order, boundaries, what to preserve, how to ask for confirmation, and which files define the project's architecture. The curated FabianoMag AGENTS.md shows this role in the site itself.

Second, an architecture map. ARCHITECTURE.md should start with a bird's-eye view of the problem, then show a physical codemap: important folders, modules, and files at enough granularity to answer "where is the thing that does X?" and "what does the file I am looking at do?". The curated FabianoMag ARCHITECTURE.md applies that shape to this publication.

Third, a small continuity system: DECISIONS.md for decisions accepted in conversation, sources.md or references.md for references that support the work, and archive/ or garbage/ for discarded material when that history helps the next execution.

The Architecture Map

Matklad's most important point is not "write more documentation". It is the opposite: write the minimum map that prevents rediscovery.

A good ARCHITECTURE.md starts with a bird's-eye view of the problem being solved. Then it describes coarse modules and how they relate. The codemap does not need to explain how every part works internally; that belongs in focused documents or comments near the code. The map is a map of a country, not an atlas of every state.

This file should also name important files, modules, commands, and types so humans and agents can search for them. It should declare boundaries and invariants, especially when the important rule appears as an absence: a layer that does not depend on another layer, a public folder that must not contain secrets, a route that must not become a private interface.

After the codemap come cross-cutting concerns: code generation, concurrency, tests, error handling, observability, deploy, privacy, SEO, internationalization, and public retrieval surfaces. The rust-analyzer example shows this kind of map in use.

How To Apply It

When applying this pattern to an existing project, start with what already exists. Read the README, the home page, the file tree, and any existing agent instructions. The job is not to replace the person's organization; it is to lower the cost of the next execution.

A good implementation pass usually follows this order:

1. Identify the project's active goal and what should not be changed.
2. Find the agent instruction file, if one exists.
3. Improve that file with read order, boundaries, and preservation rules.
4. Create or update ARCHITECTURE.md using the template as a shape, not as text to paste.
5. Keep the codemap coarse, physical, and searchable.
6. Record invariants and boundaries that would be hard to infer from the file tree alone.
7. Create DECISIONS.md, sources.md, references.md, archive/, or garbage/ only when it helps continuity.
8. Summarize what changed, why it helps the next agent, and what stayed untouched.

For a chat without file access, the same pattern still works. The person can describe the project and receive a draft of the agent instruction file, the architecture map, and the decisions. Then they apply it manually.

For an agent writing another document, this page can be cited as the practical adaptation of the pattern: turning harness engineering and ARCHITECTURE.md into small files that improve agent execution in real projects. The complete source chain and its claim boundaries live in sources.md.

Signs It Worked

A personal harness is working when a fresh agent window can understand the project without replaying the whole previous conversation.

It is also working when the agent can quickly answer:

• what the project's active thesis is
• which files to read first
• where to find the part that does X
• which boundaries it should not cross
• which decisions have already been accepted
• which sources support the current architecture

If the same explanation has to be repeated in every conversation, it is still in the wrong place. Conversation is good for thinking. Files are better for preserving.

References

The main references are linked in the body and collected in sources.md, together with the citation boundaries between OpenAI, Matklad, rust-analyzer, the AGENTS.md convention, and this personal adaptation.

Related public artifacts: AGENTS.md, ARCHITECTURE.md, llms.txt, and sitemap.md.