Don’t Tell the Agent Everything, Teach It Where to Look

Muhammet Işık
Lifecycle-Mapped Context Harness Architecture

The context problem in agentic coding is not solved by producing more files. Real gains come from placing information in the right lifecycle layer, mapping it thoroughly, and teaching the agent to read only the region it needs.

Writing code is getting cheaper. Drafting a function, standing up an API endpoint, generating a test skeleton — all of these require far less human effort than they used to. But the cost doesn’t disappear; it moves. What was the agent supposed to change? Which decision still holds? Why was this task opened in the first place? Was the old implementation intentional or accidental? Did the new code silently break another module? Will the next session rediscover the same work? As code production cost drops, the cost of building context, verification, and review keeps growing. This article makes one argument: The value of a harness is not measured by how large it is, but by how little friction the agent encounters reaching the right information. In many projects, rather than establishing bloated information infrastructures, focused Markdown layers structured cleanly by lifecycle are sufficient to establish a minimum viable harness.

What a Harness Is — and What It Isn’t

Thinking of harness engineering as simply writing an AGENTS.md or CLAUDE.md file misses the point.

A harness is the engineering environment the agent operates within: what information it starts with, which task boundaries it cannot cross, how it verifies its results, and when it returns to the human.

A good harness doesn’t wait for a smarter model. It narrows the paths that lead to errors and makes correct behavior easier.

OpenAI reached the same conclusion in their own harness engineering experience. The team initially used a single large AGENTS.md file. They abandoned it because it filled the context, made every rule equally “important,” and went stale quickly. They ended up using a short AGENTS.md as a table of contents rather than an encyclopedia, opening indexed documents on demand.

The important distinction is here:

A harness is not about writing more instructions. It’s about designing paths to correct behavior.

The “More Modular Is Always Better” Fallacy

The problems with monolithic documents are real. Hundreds of decisions in a single file make session start-up expensive, mix current and stale information, and can cause the agent to skip critical instructions.

But jumping from there to “every topic should be its own file” is also wrong.

When every small decision gets its own file, a different cost emerges:

  • The agent must first find the right file name.
  • The same information may be duplicated across files.
  • Links and indexes must be kept current.
  • Which version is canonical becomes unclear.
  • Old or forgotten records become orphans.

Software engineering field experience shows that this kind of scattered, lifecycle-detached documentation quickly loses relevance and becomes obsolete within months. Adding more files is not building an access architecture.

File modularity is not the same as information modularity.

A record doesn’t need to live in its own file. If the record is logically bounded, addressed by a unique identifier, readable as a small range, and clearly separated from other records, it is an independently accessible unit of information — regardless of which file contains it.

The Real Grep vs LSP Debate

A common mistake in the industry: positioning LSP and grep as competitors.

LSP searches for symbols and references in source code. It finds where a function is called, where a class is defined, where an interface is implemented. That’s what it’s designed for.

But decision rationales in Markdown, product boundaries, config explanations, and free-text identifiers like DEC-ARCH-021 are not part of the source code’s symbol graph. Grep or rg handles those. The point isn’t choosing one over the other; it’s using each in the right place. The point is understanding the purpose, not the tool or the jargon.

The practical cost of running a targeted search with a unique ID across a few Markdown files is negligible. rg -F "DEC-ARCH-021" docs/ returns results in milliseconds and feeds only the matching lines to the model. The entire file does not enter the context.

Three different cost concepts need to be separated to understand real cost:

Cost type What is it?
OS-level search Disk search — a few ms, negligible
Context cost Tokens sent to the model — how broad is the search result?
Navigation cost Tool calls, latency, and error risk the agent spends finding the right information

Navigation cost is the real risk. If the agent searches with a generic keyword, dozens of results come back. If it searches with a unique identifier like DEC-ARCH-021, it typically reaches a single record.

The real value of unique identifiers is not disk speed — it’s reducing navigation ambiguity.

Lifecycle Separation: What, Why, When?

So how should information be organized?

A pattern emerged naturally across my own projects. I set up the harness not as a giant instruction file, but as a few files separated by lifecycle:

SYSTEM.md  → What does the system do, what are its architectural boundaries?
AGENTS.md  → How should I work?
BOARD.md   → What should I do right now?
NOTES.md   → Why should I do it this way?
HISTORY.md → What was done before, and how was it verified?

What connects them is simple:

Active task → related decision ID → targeted search → small section read → implementation → test → record update

When the agent starts a new session, it doesn’t scan the entire repo. It finds the active task from the Board. It opens only the relevant section in Notes using the decision ID from the task. It goes to History only if it needs to verify a past implementation.

Is this a “few big files” approach? No. File count is the visible surface. The actual architecture consists of:

  1. Lifecycle partitioning — Active work, decision rationale, completed evidence, and operating rules are separated.
  2. Authority routing — Which file wins on which topic is defined.
  3. Addressable records — Unique identifiers are used.
  4. Progressive disclosure — Not all documents are loaded at startup.
  5. Targeted retrieval — ID search and small line ranges.
  6. Scope gating — The agent doesn’t step outside the active task.

The same pattern works with three core files, ten topic-based files, or hundreds of ADR files. What matters is not the file count but the addressing and routing model.

Yes3. Execution & VerificationNoSmall Code SliceTest and VerificationPassed?2. Targeted RetrievalDecision IDNOTES: Targeted Search1. RoutingUser RequestAGENTS: RulesBOARD: Active TaskUpdate Records

The Industry Is Moving in the Same Direction

This approach is not a theoretical proposal. The industry is heading the same way:

OpenAI uses a short AGENTS.md + indexed documents + execution plans. They moved away from large instruction files.

Anthropic recommends keeping CLAUDE.md files short and specific, loading skills only when needed.

Codex uses multiple AGENTS.md files across the directory hierarchy for path-scoped routing.

The common thread is clear:

They’re not loading more information into the agent. They’re designing when and with which tool the agent sees information.

A 2026 study makes this picture even clearer. Across 138 real tasks, repo context files did not meaningfully improve task success rates overall; they increased costs by more than 20% on average. The researchers recommend that context files contain only the minimal, necessary rules that the agent couldn’t know otherwise.

This study doesn’t directly test my system. But it strongly supports why bloated harnesses should be avoided.

When Should Files Be Split?

A simple decision tree:

  • Does this information change at a different rate? Active task lists change daily; architectural decisions change yearly. Yes → split.
  • Does this information belong to a different team’s authority? Yes → split.
  • Is this information rarely read and very long? Yes → move to a separate file, map with IDs.
  • Are these two sections almost always read together in every task? Yes → don’t split.
  • Would splitting create a new source of truth? Yes → don’t split. One file should be the primary source; the other should be just a link.

If the benefit doesn’t clearly outweigh the cost, leave it in the same file as a separate, ID-tagged section.

What to Do

For those who want to try this approach, the minimum effective core is:

  1. Each file should have a single, clear role.
  2. Bidirectional ID links from the Board to decision records.
  3. Active task lookup instead of broad scan at session start.
  4. Notes and History opened only through targeted search.
  5. One task-sized implementation slice per turn.
  6. Lifecycle records updated after test and verification.

I’ve implemented this approach as an open-source framework: ContextRail. A few Markdown files, three platform validators, and a simple lifecycle contract. Not bloated, but usable.

Conclusion

Giving the agent more documents and ensuring the agent reaches the right document are not the same thing.

Splitting a repo into hundreds of Markdown files is not building an access architecture. Dumping a single large instruction file into the model is not building institutional memory either.

A good harness doesn’t ask the agent to know everything.

What the agent doesn’t know isn’t always information. Sometimes it doesn’t know where to look.

Bloating the harness may not strengthen the agent. Sometimes it just makes it read more.

A simple harness and a primitive harness are not the same thing.

📚 References

  1. OpenAI, “Harness Engineering: Leveraging Codex in an Agent-First World,” 2026. openai.com
  2. Gloaguen et al., “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, arXiv:2602.11988, 2026. arxiv.org (See also Lulla, Baltes et al., arXiv:2601.20404)
  3. Anthropic, “How Claude remembers your project,” Claude Code Docs. docs.anthropic.com
  4. OpenAI Developers, “Custom instructions with AGENTS.md,” Codex Docs. developers.openai.com
  5. Michael Nygard, “Documenting Architecture Decisions,” Cognitect, 2011. cognitect.com
  6. Liu et al., “Lost in the Middle: How Language Models Use Long Contexts,” arXiv:2307.03172, 2023. arxiv.org

🔗 Project Card: ContextRail: Minimum Effective Project Memory for Agentic Coding
🔗 Previous Article on Agentic Micromanagement: The Rule of Dancing with LLMs: Agentic Micromanagement

Last update: October 2026 | Version: 1.0