From an Overloaded AGENTS.md to a Knowledge Layer for Coding Agents

One instruction file only works in the early stage

When I first introduced coding agents into my development workflow, the problem looked straightforward: write one clear instruction file, describe the project's conventions, tell the agent what to read before implementation, and establish a few important guardrails. For Codex, that file was usually AGENTS.md. For Claude Code, CLAUDE.md served a similar purpose.

The approach worked well in the beginning. The repository was small, there were only a few modules, and most technical decisions could still be inferred from the source code. I only needed to document build commands, test commands, naming conventions, forbidden dependencies, and a few directories the agent should avoid changing.

Then the project grew.

In the larger systems I have worked on, a repository that begins with a few services can gradually accumulate frontends, backends, workers, shared libraries, infrastructure code, deployment manifests, event contracts, and several integration paths. Some projects become monorepos. Others remain distributed across repositories while sharing the same architectural principles. Rules that were initially simple become dependent on a particular service, domain, or type of change.

The response was the same one many teams have: keep adding more content to the instruction file.

A document that began with a few dozen lines gradually accumulated:

• A system overview.
• Responsibilities for each service.
• Clean Architecture rules.
• Conventions for .NET, Python, Angular, or React.
• Kafka and Outbox guidance.
• Tenant-isolation rules.
• API contracts.
• Event schemas.
• Migration instructions.
• Operational runbooks.
• A list of mistakes the coding agent had made before.

At some point, the instruction file was no longer an instruction file. It had become a small wiki embedded in the agent's default prompt.

More context did not always make the agent more accurate

When a coding agent produces the wrong implementation, the first assumption is often that it did not receive enough context. More rules are added, explanations become longer, and the agent is required to read more documents before it starts.

That approach has a limit.

When a task only affects a Kafka consumer in one worker service, the agent may still carry frontend conventions, migration rules, retrieval architecture, model-selection policies, and unrelated operational guidance. Important constraints no longer stand out. They are placed beside hundreds of lines of other context.

There have been cases where the agent read the correct file and still missed a rule buried near the bottom. A convention from one service was applied to another, or an old architectural decision was treated as current. More dangerously, conflicts between documentation and source code were silently resolved in favor of the existing implementation.

The problem was no longer a lack of documentation. The codebase lacked an architecture for delivering the right context to the right task.

A coding agent does not need to understand the whole system during every execution. It needs to understand which part of the system is affected, which boundaries must remain intact, which decisions are still active, and which source should be trusted when evidence conflicts.

OKF and a more structured way to organize knowledge

Open Knowledge Format, or OKF, is an open specification for representing knowledge as Markdown files with YAML frontmatter arranged in a directory tree.

OKF was initiated and publicly introduced by Google Cloud on June 12, 2026. It grew out of what Google described as the “LLM-wiki” pattern: small, structured knowledge documents that can be read by both people and agents. The goal was not to create another proprietary knowledge platform, but to formalize that pattern as an open, portable, and interoperable format. The first release focused on packaging concepts in Markdown; OKF v0.2 later added clearer provenance, verification, freshness, and lifecycle signals.

The interesting part is not simply that OKF uses Markdown. Its larger contribution is treating each unit of knowledge as an identifiable concept with metadata, lifecycle state, and links to other concepts. For coding agents, that is a more practical context model than placing everything inside one instruction file.

That model fits coding agents naturally.

Instead of placing the entire architecture inside AGENTS.md, the repository can contain a separate knowledge layer:

repository/
├── AGENTS.md
├── CLAUDE.md
├── .ai/
│   ├── index.md
│   ├── architecture/
│   │   ├── index.md
│   │   ├── system-overview.md
│   │   ├── dependency-rules.md
│   │   └── event-driven-architecture.md
│   ├── services/
│   │   ├── index.md
│   │   ├── agent-service.md
│   │   ├── workflow-service.md
│   │   ├── retrieval-service.md
│   │   └── tool-executor.md
│   ├── standards/
│   │   ├── index.md
│   │   ├── dotnet.md
│   │   ├── python.md
│   │   └── angular.md
│   ├── decisions/
│   │   ├── index.md
│   │   ├── adr-kafka.md
│   │   └── adr-qdrant.md
│   └── runbooks/
│       ├── index.md
│       └── failed-agent-execution.md
├── services/
├── frontend/
└── infrastructure/

The example uses .ai/ because its purpose is immediately visible, but the name itself is not important. A team can use knowledge/, docs/architecture/, or another directory that fits the repository.

The important part is that knowledge is divided into concepts small enough for the agent to discover, load, and compare within the scope of a task.

AGENTS.md should not carry the entire truth

After working with Codex and other coding agents, I found that AGENTS.md is most effective when it acts as a bootstrap instruction rather than a knowledge base.

It should tell the agent:

• Where to start.
• How to determine the affected scope.
• When to read an architecture document.
• When to read a coding standard.
• When to report a conflict.
• When to update knowledge after implementation.

A root instruction can remain as short as this:

## Mandatory knowledge discovery


Before implementation:


1. Read `/.ai/index.md`.
2. Identify the affected service, domain, contract and coding standard.
3. Read only the relevant knowledge documents.
4. Ignore documents with `status: deprecated` except for historical context.
5. Compare documented intent with the current source code.
6. Report material conflicts instead of silently choosing one side.
7. Update affected knowledge documents when architecture, behavior,
   public contracts or operational procedures change.


Do not load the entire `.ai` directory by default.

The same idea applies to CLAUDE.md. It remains Claude Code's project entry point, but it does not need to contain the whole architecture. It only needs to direct Claude into the knowledge tree and establish a mandatory discovery process.

This separation makes two kinds of information much clearer:

AGENTS.md / CLAUDE.md
    = how the agent must work


.ai/**/*.md
    = how the system is designed

One is workflow and guardrails. The other is knowledge.

The agent should not read every document before each task

Some earlier implementation plans used strong instructions such as “read all README, AGENTS.md, and architecture documents before implementation.” The intention was reasonable: reduce hallucination and force the agent to respect the existing design.

That works while the documentation set is small. Once the knowledge base grows, it creates another problem: context dilution.

A better approach is to move through the knowledge base using progressive disclosure:

User requirement
      ↓
AGENTS.md or CLAUDE.md
      ↓
.ai/index.md
      ↓
The relevant domain index
      ↓
A small set of required concepts
      ↓
Source code and tests
      ↓
Plan, implementation, and validation

Suppose Codex receives this task:

Add exponential backoff to the Kafka consumer in Tool Executor without duplicating the execution of non-idempotent tools.

The agent does not need the entire platform architecture. It needs a narrower context set:

.ai/services/tool-executor.md
.ai/infrastructure/kafka.md
.ai/standards/dotnet.md
.ai/decisions/adr-message-retry.md
.ai/runbooks/kafka-consumer-failure.md

Only then should it inspect the actual implementation under services/tool-executor/.

This is close to how an experienced developer works: identify the affected domain, load the relevant rules, inspect the implementation, and return to older decisions when a conflict appears. Very few engineers begin a small change by rereading every architecture document in the company.

A coding agent should be given a similar discovery path.

What a concept document should contain

A common documentation mistake is to repeat the source code: which classes exist, which folders contain repositories, and which controller calls which handler. Those documents become stale quickly because the code already represents that information more precisely.

A coding-agent knowledge layer should prioritize information that the model cannot reliably infer from code alone:

• The service's primary responsibility.
• What the service must not do.
• Dependency boundaries.
• Domain invariants.
• Public contracts that must remain stable.
• Accepted trade-offs.
• Validation required after a change.
• Relationships with other concepts.

A Tool Executor concept may look like this:

---
type: Service Architecture
title: Tool Executor
description: Executes approved tools and streams execution progress.
status: stable
tags:
  - dotnet
  - kafka
  - tool-execution
verified:
  - by: human:solution-architect
    at: 2026-08-01T09:00:00Z
stale_after: 2026-11-01
---


## Responsibilities


- Execute tools selected by the Agent Service.
- Validate tool permissions before execution.
- Stream execution progress to connected clients.
- Publish execution results through Kafka.


## Architecture constraints


- Must not access the Workflow database directly.
- Must not execute tools outside the approved allow-list.
- Must preserve company and user context across asynchronous messages.
- Retry logic must not duplicate non-idempotent tool execution.


## Dependencies


- [Kafka](../infrastructure/kafka.md)
- [Agent Service](agent-service.md)
- [Tool Permission Policy](../policies/tool-permission.md)


## Validation


- Run unit tests for retry and idempotency behavior.
- Run the integration test against the local Kafka container.

The Markdown body communicates design intent to engineers and agents. The YAML frontmatter allows tooling to process lifecycle and trust signals without loading the entire body.

A team does not need every OKF field on day one. An existing codebase can begin with:

type:
title:
description:
status:

Once the workflow stabilizes, the team can add:

verified:
stale_after:
sources:
resource:

A gradual rollout prevents the knowledge layer from becoming a large documentation initiative with no sustainable ownership.

index.md is the map for context discovery

Many index.md and README files attempt to summarize everything below them. Once the index becomes too long, the agent is effectively loading most of the knowledge base at the beginning again.

In an OKF-style knowledge tree, index.md should be treated as a map:

## Architecture


- [System overview](architecture/system-overview.md)
- [Dependency rules](architecture/dependency-rules.md)
- [Event-driven architecture](architecture/event-driven-architecture.md)


## Services


- [Agent Service](services/agent-service.md)
- [Workflow Service](services/workflow-service.md)
- [Tool Executor](services/tool-executor.md)
- [Retrieval Service](services/retrieval-service.md)


## Standards


- [.NET standards](standards/dotnet.md)
- [Python standards](standards/python.md)
- [Angular standards](standards/angular.md)


## Decisions


- [Kafka as the event backbone](decisions/adr-kafka.md)
- [Qdrant for semantic retrieval](decisions/adr-qdrant.md)

Each link description needs enough detail for routing. Vague descriptions such as “information about Tool Executor” add almost no value. A description such as “tool execution boundaries, permission validation, Kafka contracts, and idempotency rules” provides much stronger selection signals.

Large domains can have their own local index.md. The agent moves from the root index to the domain index and only then loads a concept. The knowledge tree can grow without forcing every task to carry the entire documentation set.

Separating intended architecture from current implementation

One important lesson from using coding agents is that source code does not always represent the intended design. It primarily represents the current implementation.

In a long-lived codebase, there may be:

• Temporary workarounds that were never removed.
• Dependencies introduced during an incident.
• Legacy code that violates a newer boundary.
• A refactoring effort that is only half complete.
• Documentation that has not caught up.
• A decision that changed without its ADR being deprecated.

The evidence should therefore be separated into three groups.

Intended architecture

The knowledge layer describes:

• What a service is designed to own.
• Which dependencies are allowed.
• Which boundaries must remain intact.
• Which business invariants must not be broken.

Current implementation

Source code, tests, and configuration show:

• What the system currently does.
• Which dependencies currently exist.
• Which contracts are actually published.
• Which behavior is covered by tests.

Historical reasoning

ADRs, pull requests, and Git history explain:

• Why a decision was made.
• Which trade-offs were accepted.
• Which choices were temporary.
• Which assumptions later changed.

If the knowledge layer says Tool Executor must not access the Workflow database while the source code injects WorkflowDbContext, the agent should not silently choose one side.

The conflict should be stated explicitly:

Documented intent:
Tool Executor must not access the Workflow database directly.


Observed implementation:
Tool Executor currently references WorkflowDbContext.


Impact:
The current implementation violates the documented service boundary.

The implementation may need to be corrected. The architecture may also have changed while the document remained stale. The conflict must be visible before the agent generates more code based on an unverified assumption.

Knowledge must change with the code

Detailed architecture documents are useful during design, but they gradually lose value when they are not part of the pull-request workflow. The code keeps changing, while the documents are updated only when someone remembers.

OKF does not solve that problem automatically. Storing Markdown in Git makes knowledge easier to version and review, but the team still has to include it in the Definition of Done.

A suitable workflow for a coding agent is:

Inspect relevant knowledge
          ↓
Inspect current implementation
          ↓
Plan and implement
          ↓
Run tests and validations
          ↓
Evaluate architecture and contract impact
          ↓
Update affected knowledge
          ↓
Review code and knowledge together

Not every pull request needs to modify .ai/. An internal refactoring that changes no behavior, boundary, or public contract may require no knowledge update.

Knowledge should change when implementation affects:

• Service responsibilities.
• Dependencies between modules or microservices.
• Public APIs or event contracts.
• Business rules.
• Security policies.
• Operational procedures.
• Build, test, or deployment workflows.
• Architectural decisions.

From this perspective, changing a Kafka event without updating its contract knowledge is similar to changing a public API without updating its OpenAPI specification. The implementation may compile, but the engineering artifact is incomplete.

Status, freshness, and verification reduce misplaced trust

A directory of Markdown files without metadata makes every document appear equally trustworthy. That is rarely true in a real repository.

Long-lived repositories often contain documents that remain after they have become historical. Some are drafts. Others were once correct but have not been reviewed for a long time.

Two simple fields can change how an agent uses the document:

status: deprecated
stale_after: 2026-11-01

deprecated means the document should not guide new implementation. stale_after does not prove that the content is wrong, but it requires the agent to compare it with the source before relying on it.

The verified field distinguishes generated knowledge from knowledge confirmed by an engineer:

verified:
  - by: process:architecture-validation
    at: 2026-08-01T07:00:00Z
  - by: human:solution-architect
    at: 2026-08-01T09:00:00Z

A practical policy may be:

• Use stable and non-stale documents normally.
• Treat draft documents as advisory.
• Use deprecated documents only for historical context.
• Compare stale documents with source code.
• Require human verification for significant boundary changes.

Metadata does not make a document absolutely correct. It tells the agent how much caution to apply.

Instruction files are not enforcement

Teams often respond to agent mistakes by adding another “must not” statement to AGENTS.md. That can improve context, but it does not provide enforcement.

However, AGENTS.md and CLAUDE.md remain context. Clear instructions improve compliance, but they are not security boundaries or enforcement mechanisms.

Hard constraints belong in tooling:

• Architecture tests that reject forbidden dependencies.
• Linters that reject convention violations.
• Schema validation for Kafka events.
• Pre-commit hooks for formatting.
• CI checks for broken links and stale concepts.
• Permission systems for dangerous tools.
• Sandboxes or hooks for prohibited operations.

A rule such as “Tool Executor must not reference WorkflowDbContext” should exist in the knowledge layer so the agent understands the design. It should also have an architecture test that fails the build when the dependency appears.

Knowledge and enforcement solve different problems:

Knowledge helps the agent make the right decision.
Automation prevents the system from accepting the wrong one.

Important boundaries usually need both.

OKF does not force me to add a vector database

When knowledge and AI are discussed together, the conversation often moves immediately to embeddings and vector search. That should not be the first step.

For dozens or a few hundred concepts, filesystem navigation, index.md, titles, descriptions, and tags are usually enough. Codex or Claude Code can also use repository search to find relevant concepts.

Vector search becomes useful when the knowledge base grows large enough that navigation and lexical search no longer locate concepts reliably.

Even then, the OKF files should remain the canonical source:

OKF Markdown files
        ↓
Parse metadata and sections
        ↓
Build a full-text or vector index
        ↓
Search returns a concept ID
        ↓
Open the canonical OKF file
        ↓
Check status, freshness, and verification

The vector database is a derived discovery index. It does not replace the file in Git. If the index is rebuilt or the embedding model changes, the original knowledge remains intact.

This separation also matches practical experience with Qdrant-based retrieval pipelines. Vector search is valuable for semantic discovery, but it should not become the only place that holds business truth or architectural truth.

A practical adoption path for an existing codebase

The adoption should not begin by asking Codex to generate hundreds of Markdown files in one run. That often creates documentation that looks complete but lacks trust. The agent may repeat source-code details, duplicate content across files, and turn assumptions into architectural rules.

A staged rollout is safer.

Phase 1: Create the entry points

Add:

AGENTS.md
CLAUDE.md
.ai/index.md

Both instruction files should point to the same discovery workflow. The root index should contain only the high-level map.

Phase 2: Document boundaries that are difficult to infer from code

Start with:

.ai/architecture/system-overview.md
.ai/architecture/dependency-rules.md
.ai/services/<critical-service>.md
.ai/standards/<primary-stack>.md
.ai/decisions/<important-adr>.md

There is no need to document every class. The useful material is responsibilities, invariants, boundaries, and trade-offs.

Phase 3: Add metadata and ownership

Once the tree is stable, add:

type:
description:
status:
verified:
stale_after:

Every important concept needs a real owner or reviewer. Without ownership, stale_after only produces warnings that nobody resolves.

Phase 4: Validate knowledge in CI

CI can check:

• Valid YAML frontmatter.
• Required type fields.
• Internal links.
• Deprecated documents excluded from active indexes.
• A report of stale concepts.
• Corresponding knowledge updates for public contract changes.

Phase 5: Add search when navigation is no longer enough

Full-text search, a graph index, or vector search should be introduced only when there is evidence that filesystem discovery is failing. The search layer should return concept IDs and metadata instead of becoming an independent source of truth.

Common failure modes

Turning the knowledge layer into a copy of the source code

Documentation generators can produce many files describing classes, methods, and folders. The result looks comprehensive, but the value is limited because the code already represents those details better.

The knowledge layer should focus on intent, boundaries, invariants, reasoning, and operational constraints.

Generating all documentation without review

An agent can create a useful skeleton quickly, but architectural statements and business rules require verification. One incorrect rule in .ai/ can influence many later tasks.

Marking everything as stable

If every concept is stable, lifecycle metadata becomes decoration. The team has to use draft, deprecated, and stale_after in practice.

Importing the entire .ai/ tree into every session

That removes the main benefit of progressive disclosure. The entry point should teach the agent how to find context rather than loading all context immediately.

Excluding knowledge from pull requests

A knowledge base is only trustworthy when it changes with the code. Once developers stop trusting the documents because they know they are outdated, the coding agent loses its most valuable context source as well.

The real issue is not Markdown

OKF will not automatically turn Codex or Claude Code into a Solution Architect. A well-organized .ai/ directory cannot compensate for weak architecture, missing tests, or unclear ownership.

What OKF provides is a better mental model for context engineering:

• Knowledge is divided into identifiable concepts.
• The agent begins with a small entry point.
• Context is loaded according to task scope.
• Intended architecture is separated from current implementation.
• Documents carry status, freshness, and verification signals.
• Knowledge participates in the same lifecycle as source code.
• Search indexes remain discovery mechanisms.

At first, I also believed that one sufficiently comprehensive instruction file would be enough for coding agents. After expanding codebases, assigning implementation phases to agents, and resolving mismatches between documentation and source code, the limitation became clear: this approach works well only in the early stages.

Once a project spans several domains, services, and decisions that cannot be inferred directly from code, the coding agent needs a knowledge architecture for the same reason developers need a software architecture.

OKF is not a complete answer to the entire problem. It is, however, simple enough to adopt incrementally, structured enough to scale, and open enough to avoid coupling the engineering knowledge base to one agent or vendor.

References

• Google Cloud introduces the Open Knowledge Format
• Google Cloud announces trust signals in OKF v0.2
• Open Knowledge Format v0.2 specification
• Open Knowledge Format repository and README
• OpenAI Codex: Custom instructions with AGENTS.md
• OpenAI Codex customization overview
• Claude Code best practices
• Claude Code: How Claude remembers your project