Imagine hiring an exceptionally capable colleague who forgets everything overnight. Every morning starts with the same explanations: business terminology, approval workflows, and product logic. This is effectively how most companies work with AI today, repeatedly rebuilding context instead of reusing it.
Context engineering offers a different approach by treating business knowledge as reusable infrastructure. In this article I will explore what context engineering is, where organizational context should live. Also, I will show how to test the approach on a real project in less than an hour.
What Context Engineering Actually Means
Context engineering is the discipline of preparing everything an AI model needs to understand a business before it receives a task. The focus is on building the knowledge foundation that makes those prompts meaningful — and building it once, in a form that any assistant can read. GitHub Copilot, Claude Code, and whatever the team adopts next all draw on the same foundation.
This distinction is critical because most AI initiatives begin with prompt engineering. While prompts define the request, they do not provide the organizational knowledge required to answer it correctly. They cannot capture:
- approval workflows;
- internal terminology;
- architectural decisions made years ago;
- the company-specific meaning of concepts.
Even a perfectly written prompt cannot produce an accurate outcome if the model lacks the necessary business context. But the issue is rarely the model itself. Instead, it operates without access to the information that distinguishes a generic answer from one that is correct for a specific business.
Context engineering approaches this data as an engineering asset rather than documentation. Business glossaries, operating rules, architectural decision records, unresolved questions, and institutional knowledge are structured, versioned, reviewed, and maintained alongside the rest of the technology stack. As a result, every AI interaction begins with a complete and consistent understanding of how the organization works.
Once established, this shared context becomes reusable infrastructure. Every team, as well as new employee, can rely on the same knowledge base instead of recreating organizational context from scratch.
Your Documentation Is Written for People, Not Machines
Most companies store their organizational knowledge in internal platforms such as Confluence, Notion, or similar tools. These systems are effective for people because they have specific and thoughtful UX/UI, which is built with human readers in mind. So, employees can search for information, follow links between documents, and use them to onboard new team members. A person navigates through pages, decides which links to open, and extracts only the information relevant to the task.
But do you know that it’s a flaw for automation? Large language models work differently than human perception. They do not browse documentation or decide where to click next. Instead, they process only the context they receive. Knowledge bases, by design, are optimized for navigation rather than for machine consumption.
This gap can be bridged through an integration layer such as the Model Context Protocol (MCP), which connects AI models to external knowledge sources and retrieves relevant documentation when needed. While this approach is effective, it introduces additional infrastructure that must be deployed, maintained, and monitored. Like any software component, it can fail, drift from the underlying systems, or retrieve incomplete or outdated information.
An even greater challenge emerges over time. Documentation and production systems evolve independently. An engineering team may update approval logic, modify a business rule, or redesign a workflow, while the corresponding documentation remains unchanged for months. This is not necessarily the result of poor documentation practices, but a consequence of maintaining two separate artifacts that follow different update cycles. As a result, AI models may rely on documentation that no longer reflects how the system actually works.
This is the main bottleneck in enterprise AI adoption. The limiting factor here is the growing disconnect between operational systems and the knowledge repositories intended to describe them.
Context as a Repository Artifact
How to solve that issue? An alternative approach is to treat business context as part of the codebase by storing it in the same repository as the application itself. Typically, it’s a collection of Markdown files.
Markdown is a lightweight, plain-text format, which can be:
- edited in any code editor;
- reviewed through pull requests;
- versioned alongside source code;
- maintained without relying on proprietary platforms.
More importantly, documentation follows the same lifecycle as the application. When business logic changes, the documentation describing that logic is updated in the same commit, making it significantly less likely to fall out of sync.
The repository should contain the business knowledge that AI systems need to perform reliably rather than implementation details. In practice, a small set of documents is often sufficient to capture the majority of organizational context. Let’s take a basic kit:
- a glossary defines domain-specific terminology whose meaning is unique to the organization. Moreover, it cannot be inferred from general knowledge alone.
- a general context document explains what the product does, who its users are, and how its core components relate to one another. It provides the high-level understanding that individual documents often assume but rarely explain.
- an open questions document records unresolved decisions, competing assumptions, and areas that remain under discussion. Unlike traditional documentation, which typically captures only final decisions, this document makes uncertainty explicit. Also, it prevents AI systems from presenting unresolved topics as settled facts.
- Architecture Decision Records (ADRs) document why specific technical decisions were made, including the alternatives that were considered and the trade-offs involved. This context often disappears over time as teams change and implementation discussions become difficult to reconstruct from issue trackers or commit history.
- finally, Mermaid diagrams describe workflows, system interactions, and business processes in a text-based format. Because they are written as code, they remain version-controlled, easy to review, and readable by both humans and machines. Their role in context engineering is discussed in more detail later in this article.
Every AI-powered tool connected to that codebase begins with a shared understanding of the product, its terminology, and its decision history. Instead of repeatedly reconstructing organizational knowledge through prompts or conversations, teams can rely on a consistent context that is available from the very beginning of every task.
Why Feeding the AI Everything Doesn’t Work
Once organizational context is stored in a repository, the natural assumption is that an AI model should receive all available information. For example, every meeting transcript, Slack conversation, specification, and internal document. But in practice, this approach reduces rather than improves the quality of the output.
The challenge is distinguishing authoritative knowledge from outdated or irrelevant content. When documentation consists of an undifferentiated collection of documents, the model has no reliable way to determine whether a business rule is current. As well, LMM cannot process whether the documentation reflects a proposal that was abandoned months ago.
As the volume of information grows, context becomes less informative rather than more. The quality of AI output depends not on the amount of information available, but on how well that information is organized. A structured set of documents, each with a clearly defined purpose and maintained over time, provides far more value than an exhaustive archive of everything the organization has ever produced.
This leads to a more fundamental challenge: keeping that context up to date.
Why Documentation Projects Usually Fail
What are the fundamental problems? First, maintaining documentation becomes a separate responsibility that competes with routine. Engineers are measured by the features they deliver and the systems they improve. Asking them to maintain a parallel knowledge base inevitably turns documentation into a secondary task. As development accelerates, documentation updates become less frequent until they eventually stop. Within a few months, the repository reflects a system that no longer exists.
For AI systems, outdated documentation is more harmful than missing documentation. An obsolete document appears authoritative while describing a reality that has already changed. It makes incorrect responses difficult to detect. For this reason, the cost of maintaining organizational context must be as close to zero as possible.
Here are the approaches that help your process smoothly.
Automating Context Maintenance
The most effective way to reduce that cost is to automate documentation generation instead of relying on manual updates. Rather than asking someone to summarize every meeting, organizations can use AI to transform transcripts into structured documentation. A single discussion can automatically update the business glossary, product overview, architecture records, or open questions file, depending on the decisions made during the conversation.
The conversational nature of meeting transcripts is not a significant obstacle. Technical discussions frequently include interruptions, incomplete thoughts, multiple languages within the same conversation, and domain-specific shorthand. Modern language models are generally capable of interpreting this type of communication and extracting the information that should become part of the organization's shared context.
But remember: automation takes real time. Setting up an extraction step, tuning the instruction, and checking the output costs hours of its own. So, task that a person finishes by hand in a few minutes doesn't repay that.
Making Uncertainty Part of the Context
One of the most valuable capabilities of AI-generated documentation is its ability to capture uncertainty alongside decisions. Traditional documentation records conclusions, but rarely documents the topics that were discussed but left unresolved.
By explicitly instructing a model to identify open questions, organizations can maintain a living record of pending decisions. A meeting may conclude with agreement on one policy while postponing another because additional information is required. Instead of disappearing into participants' memories, unresolved issues become visible, searchable, and actionable. So, teams not only no longer preserve only what they know, but also track what they still need to decide.
The Cost of Supplying Context
Providing a structured context to every AI request may appear computationally expensive, particularly when that context contains hundreds or thousands of lines of documentation. In practice, the cost is lower than many organizations expect. Modern AI inference systems optimize repeated requests by caching stable portions of the input. Anthropic charges cached reads at one tenth of the base input token rate, with a cache write costing 1.25 times base. OpenAI, which applies caching automatically, documents reductions of up to 90 percent on input token cost and up to 80 percent on time to first token.
When the same context is supplied across multiple interactions, the model does not repeatedly process it from scratch. Instead, previously processed context can be reused, reducing both latency and computational cost. As a result, supplying a comprehensive and consistent business context is significantly more practical than it may initially seem.
How to Create Workflows the Machine Can Read
Most organizational logic is procedural: one action triggers another, conditions are evaluated, and different actors make decisions at different stages. Traditional workflow diagrams are poorly suited for this purpose. Diagrams created in tools such as Excalidraw or shared as images are easy for people to understand but inaccessible to language models. While a human can interpret arrows and decision nodes, an AI model receives only an image with no structured representation of the underlying process.
Mermaid addresses this limitation by representing diagrams as text. Workflows, decision trees, sequence diagrams, and system architectures are written in a lightweight syntax that can be stored alongside source code. Modern development environments —including GitHub, GitLab, VS Code, and JetBrains IDEs — render these files as visual diagrams while preserving them as plain text within the repository.
This dual representation makes Mermaid particularly well suited for context engineering. Humans interact with visual diagrams, while AI systems consume the same information as structured text. Both rely on a single source of truth that can be version-controlled, reviewed, and maintained together with the codebase.
Beyond simple flowcharts, Mermaid supports a broad range of documentation formats commonly used in software development, including sequence diagrams, state diagrams, mind maps, and C4 diagrams for software architecture. Together, these formats describe both how a business process works and how the supporting systems are organized.
What It Looks Like in Practice
Let’s take a simple case. Consider a typical vacation request workflow implemented in an HR platform such as PeopleForce. An employee submits a leave request. The system verifies the remaining leave balance and determines the request type — for example, annual leave, sick leave, or a public holiday.
From a business perspective, this is a straightforward workflow consisting of several sequential steps and a small number of decision points. In Mermaid, the entire process can be expressed in a few lines of structured text.
Because the process is machine-readable, AI systems can reason about its execution rather than merely explain it. For example, a model can generate an end-to-end integration test that follows the complete business scenario:
- authenticating a user;
- submitting a leave request;
- validating available balance;
- routing the request for approval;
- verifying the final outcome.
Once business logic is expressed in a structured format, AI can transform documentation into executable artifacts, including test cases, implementation plans, validation scenarios, or process simulations.
Most companies already hold the raw material for this. Onboarding sessions, customer calls, and technical brainstorms are recorded and sitting on a shared drive, usually unwatched after the week they happened. But that’s enough for a model to produce the diagram. Transcript in, structured notation out, committed alongside the code.
The same route keeps it current. When the process changes, the change gets discussed in a meeting, and that meeting is recorded too. Documentation stops being a task somebody owes the project and becomes a by-product of work the team already does.
What to Do in the Next 30 Minutes
Context engineering does not need to start with a company-wide documentation initiative. In fact, small experiments are often more valuable than large transformation projects. A single workflow is enough to validate whether the approach fits your organization.
To get started:
- Choose one integration or business process that your team is actively working on.
- Record the next discussion instead of assigning someone to write meeting notes.
- Generate three documents from the transcript: a glossary, a general context file, and a list of open questions.
- Describe the workflow in Mermaid and store it alongside the relevant code.
- Ask an AI model to perform a task that would normally require additional business context, and evaluate whether the documentation is sufficient for the model to understand the problem without further explanation.
If the documentation needs to be shared outside the engineering team, the same Markdown repository can be published as a static documentation website without changing its structure. The result is a single knowledge base that remains readable for both people and AI systems.
The objective is to establish a workflow in which business knowledge is continuously captured, maintained, and made available to both humans and AI. As software teams increasingly rely on AI agents, the quality of that shared context will become one of the primary factors determining how effectively those systems can contribute.