AI Writes Better Software When It Understands the Business

How context documentation and deliberate prompting improve user experience, code quality, and maintainability.

Tony Guinta·2026-09-20

Every time you start a new session with an AI agent, it is like sitting down with a highly capable teammate on their first day.

The agent brings broad expertise across software engineering, finance, accounting, healthcare, legal work, business analysis, user experience, and many other fields. It can examine a problem from several professional perspectives, recognize patterns across industries, and produce working software at remarkable speed.

But it knows nothing about your application.

It has never met your users or watched them work. It does not know the problems your system was built to solve, the value it provides to the organization, or the terminology people use when discussing their work. It does not understand your business rules, workflows, architecture, conventions, or the decisions that shaped the system over time. It starts every new session as a blank slate, without the accumulated knowledge that a human teammate develops after working with your organization for six months, a year, or longer.

That is the gap context engineering needs to close. The practical target is to move a new AI session from a blank slate toward the working knowledge of an experienced teammate within the first few minutes of collaboration. I describe that as giving the agent six months of context in five minutes. Six months is shorthand for the accumulated application knowledge of someone who has been embedded with the team long enough to understand how the business and the system really work. In a mature application, that may represent a year or several years of team knowledge.

You could point the agent at the codebase and tell it to figure everything out. It will inspect the files, identify the frameworks, trace the dependencies, and form a reasonable picture of how the software operates. That picture will still be incomplete.

Source code can show the agent how the current system was implemented. It rarely explains whether the implementation reflects how the business should operate. It may reveal a class named Forecast, but it will not necessarily explain who owns that forecast, where its assumptions come from, how those assumptions change, or why forecast accuracy matters to the organization.

That knowledge changes the software the agent produces.

When an AI agent understands the users, their responsibilities, their vocabulary, and their business practices, it can combine that application-specific context with its broader knowledge of the domain. A finance application benefits from what the model knows about forecasting, accounting controls, reconciliation, auditability, and financial reporting. A healthcare application can draw on its knowledge of clinical workflows, patient experience, privacy, and care coordination. The same principle applies to legal systems, insurance platforms, logistics software, and nearly every other business domain.

The benefits reach beyond the requirements document. Business context helps the agent design workflows that make sense to users. It helps the agent recognize missing rules and edge cases. It improves the language used throughout the product. Models, attributes, methods, services, events, and tests begin to reflect the concepts that people in the business actually use.

That alignment produces better user experiences and a codebase that is easier for humans and future AI sessions to understand.

Reaching the knowledge equivalent of an experienced teammate does not require the agent to read every document or learn everything the team knows. It needs the knowledge relevant to the work about to begin. The first five minutes should give it a reliable mental model of the users, business practices, system behavior, and technical areas involved in that task.

You build that knowledge into the codebase, then use deliberate conversation to make sure the agent finds it, understands it, and applies it correctly. That is how accumulated team knowledge becomes useful within minutes rather than months.

The Codebase Needs More Than Technical Documentation

Most conversations about making a codebase ready for AI begin with technical material. Teams document the architecture, repository structure, frameworks, APIs, data models, coding conventions, and common implementation patterns.

All of that matters. It tells the agent where the code lives and how the pieces fit together. It also helps the agent follow existing patterns instead of inventing new ones every time it makes a change.

In my experience, the larger gap is usually application context.

The agent needs to know why the application exists. It needs to understand the business problems the system addresses, the value it provides, the people who use it, and the work those people perform. It needs the terminology of the business, including the subtle differences between words that may sound interchangeable to an outsider. It needs to understand the workflows, responsibilities, rules, exceptions, and expected behavior that give the software its purpose.

For a financial application, that may include questions such as:

Who owns a forecast?
Who supplies its assumptions?
Which changes require approval?
What does accuracy mean to each role?
Which information must be traceable for audit purposes?
How do users respond when actual spending differs from the plan?

The answers affect far more than screen copy. They influence the domain model, authorization rules, validation, workflow state, reporting, notifications, audit history, and test coverage.

Strong business context also gives the model access to more of what it already knows. Once the agent understands that it is working on a financial forecasting system, and once it understands how forecasting works inside this organization, it can apply its broader knowledge of finance to the problem. It can raise questions about controls, reconciliation, ownership, exceptions, and reporting that a narrowly technical analysis may miss.

The same model can adopt different perspectives when asked. A Product Owner can ask it to think like a financial analyst and identify what that user would need from a feature. A QA Engineer can ask it to think like both a financial analyst and an adversarial tester. A Software Engineer can ask how a proposed design supports the business workflow and where the architecture may work against it.

The application-specific documentation keeps that domain knowledge grounded. General knowledge alone is dangerous because every organization works differently. The agent may understand forecasting, but it still needs to learn what a Budget Owner means in your system, what that person controls, and which assumptions belong to them.

Give the Agent a Map

A new teammate should not have to wander through hundreds of files hoping to discover how the organization works. The agent needs a clear starting point and a path to the information relevant to the current task.

We use an AGENTS.md file as that starting point. Think of it as a map of the repository rather than an encyclopedia. It points the agent toward the available sources of knowledge and explains when each source should be used.

One part of the map leads to material that describes the system:

Application context covers the business problems, users, organizational value, terminology, workflows, rules, and expected behavior.
Technical context covers architecture, repository structure, integrations, data, code navigation, conventions, and implementation patterns.

Another part leads to the documents used to deliver a change:

Product requirements describe what the business needs and why.
Implementation plans describe how the software will change.
QA test plans describe how the team will verify the behavior.

The repository can also contain reusable skills or procedures that teach the agent how the team performs recurring work, such as planning a change, reviewing an implementation, or preparing test coverage.

Each team will organize this differently. The exact filenames matter less than providing a clear route from the task to the knowledge needed to complete it.

Load What Matters to the Work

This body of shared knowledge is the context corpus. A large corpus creates another problem. Loading all of it into every conversation wastes context and can make the agent less effective.

Application and technical context should be divided into focused topics. A document should be small enough for the agent to locate when relevant and complete enough to explain something useful on its own.

Application context might be divided into:

Business concepts and terminology
User personas and responsibilities
Business workflows
Business rules and exceptions
Expected system behavior
Organizational value and outcomes

Technical context might include:

Architecture
Code maps
Data and integrations
Security and authorization
Testing strategy
Operational concerns

The task should drive retrieval. A question about an approval workflow may require the user workflow, authorization rules, and a code map. It probably does not require every document about reporting, integrations, or unrelated business processes.

Focused retrieval leaves room in the context window for conversation, evidence, and decisions. More documentation does not automatically produce better results. The agent needs enough of the right information for the work in front of it.

Context Preloading: Make the Agent Explain What It Understands

Documentation sitting in the repository has no value if the agent fails to retrieve it or misunderstands what it says.

Before beginning a substantial task, I start a discussion that gets the agent searching the context documentation and explaining its understanding. I call this context preloading. This is where the promise of six months of context in five minutes becomes practical. The agent retrieves the accumulated knowledge relevant to the task and brings it into the working conversation before making decisions.

The pattern is simple:

Ask. Search. Explain.

Suppose we are planning a change related to financial forecasts. I might begin with:

Before we start, what do you know about forecast ownership and how assumptions enter the system?

The agent searches the relevant application and technical context, then explains its current model. I ask follow-up questions and continue down a line of reasoning until I am comfortable that it understands the concepts needed for the work.

This requires balance. A discussion that is too broad may pull half the repository into the context window. One that is too narrow may miss an important relationship I did not know to ask about. The conversation usually starts with the central business concept, then follows the dependencies that matter to the task.

The explanation gives me something concrete to inspect. I can confirm what is correct, challenge what sounds incomplete, and identify where the documentation needs work before the agent starts changing the system.

Socratic Questioning: Use Questions to Expose Weak Reasoning

Direct instructions make sense when the work is settled and mechanical. If we have reviewed a plan and agreed to rename a file, the agent does not need a philosophical discussion about it.

Planning and problem solving require a different style of conversation. I use questions to make the agent examine its understanding, challenge my assumptions, and surface concerns before it commits to a solution.

During one discussion, an agent described Budget Owners as people who consume forecast information. That sounded plausible, but it captured only part of their role.

I asked:

Do software license forecasts magically appear in the system?

The question forced the agent to consider where the forecast assumptions originated. It revised its explanation. Budget Owners provide the assumptions and expected changes behind their forecasts, and they are ultimately responsible for forecast accuracy.

That revised understanding can change the requirements, the workflow, the interface, the data model, and the tests. A shallow interpretation might produce a read-only reporting experience. A correct interpretation needs to support ownership, input, accountability, and traceability.

I use this question-led approach throughout the work. Even when I present a specific idea, I often end with “What do you think?” or “What concerns do you have?” That signals that I want analysis rather than agreement.

Human-Paced Collaboration: Keep the Human in the Conversation

AI agents can process information much faster than people can absorb it. That becomes a problem when the agent returns thirty questions, twelve risks, and five competing designs in one response.

The volume creates pressure to keep moving. Faced with a long, polished analysis, people tend to skim it, focus on the few points that stand out, and approve the rest as a package. Each individual recommendation may sound reasonable, so the entire response gets a quick “looks good.” Important assumptions pass without discussion. Decisions build on earlier decisions that nobody fully examined.

That is how human oversight turns into rubber-stamp approval. I think of it as approval by exhaustion.

When this happens, I remind the agent that I am human. I ask it to slow down, present one question or decision at a time, and wait for my response before moving forward.

Working through each point separately changes the quality of the conversation. I can challenge the premise, ask why the agent recommends one approach, consider the tradeoffs, and combine parts of several ideas. The agent can respond to my reasoning before introducing the next decision. We build the plan together instead of reviewing a plan the agent has already completed on its own.

This takes longer than approving a wall of analysis. It also prevents twenty weak assumptions from becoming an implementation plan simply because evaluating them individually felt overwhelming.

The pace should match the kind of work being performed. Exploration, requirements, architecture, and risk analysis benefit from a controlled back-and-forth conversation. Mechanical implementation can move quickly after the decisions are settled and documented.

Human accountability depends on meaningful participation. The Product Owner owns the requirements. The Software Engineer owns the implementation plan and technical decisions. The QA Engineer owns the test strategy. Ownership means understanding and shaping the decisions, not approving a document too large to evaluate carefully.

Use the Same Context Across the Product Team

The greatest value appears when the context supports the whole product development process rather than a single engineer writing code.

A Product Owner can combine application context with the model's domain knowledge to develop a Product Requirements Document. The agent can help identify user goals, business rules, workflow questions, open decisions, and missing edge cases. The Product Owner provides direction, corrects the agent, and owns the final requirements.

A Software Engineer can combine the approved requirements with technical context to develop an implementation plan. The agent can identify affected areas, architecture concerns, delivery phases, risks, and validation needs. The engineer challenges the analysis, resolves technical decisions, and owns the final plan.

A QA Engineer can begin at the same time using the approved requirements along with application and technical context. The agent can examine the feature from the perspective of a domain expert and an adversarial tester, then propose user journeys, edge cases, regression coverage, and exploratory testing.

I prefer having QA perform this analysis independently from the implementation plan. If the engineer or the engineering agent misinterprets a requirement, feeding that interpretation directly into the QA process can reproduce the same mistake. Independent analysis gives the team two views of the approved requirements. Comparing the implementation and test plans often exposes assumptions, contradictions, and missing coverage.

The shared context gives everyone a common language while preserving the judgment of each role.

Context Evaluation: Validate Understanding Before You Trust the Work

An explanation can sound convincing and still be wrong. The agent needs to demonstrate that it can apply the context correctly.

Consider an agent reviewing authorization in a web application. It sees a route guard in the user interface and concludes that the guard controls who can perform an action.

A Software Engineer asks:

What prevents someone from calling the API directly?

That question exposes a gap. Server-side authorization has not been verified.

The team inspects the code and determines what actually happens. If the API enforces the rule but the technical context failed to describe it, the documentation gets updated. If the protection does not exist, the discussion has uncovered a security defect. Either result improves the system.

Then the agent is asked again, in a fresh formulation, to explain and apply the corrected understanding.

The working loop is:

Explain. Challenge. Verify. Document. Retest.

This loop turns mistakes into useful information. A failure may reveal weak documentation, an incorrect assumption, inconsistent code, or a genuine product defect. The finding is captured so the next session begins with better knowledge.

Context documentation needs active maintenance as the work evolves. When a team resolves an ambiguity, discovers an undocumented rule, or learns that the system behaves differently from what everyone assumed, that knowledge belongs in the repository. Otherwise, every new AI session has to rediscover it, and every new human teammate faces the same gap.

Build a Codebase That Carries the Team's Knowledge

A productive AI development environment contains more than source code. It contains a working representation of what the team knows about the business, the users, the product, and the technology. That accumulated knowledge is what allows a blank-slate session to begin operating more like a teammate who has been embedded with the team for six months or longer.

The process forms a continuous loop:

The team captures important knowledge in focused application and technical context.
The agent retrieves the material relevant to the current task.
The human and agent reason through that material together.
The human tests the agent's understanding against code, behavior, and business reality.
New knowledge and corrections return to the repository.

Over time, the codebase becomes easier to work with because more of the team's reasoning survives individual conversations. New sessions start from a stronger foundation. Product decisions connect more clearly to business needs. Technical names reflect the domain. Tests describe meaningful behavior. Documentation and implementation improve together.

This discipline helps experienced engineers who struggle to get reliable results from AI. It also gives vibe coders a path beyond improvisational prompting as their applications grow more complex.

The four practices work together. Context preloading retrieves the knowledge needed for the task. Socratic questioning tests and deepens the agent's model. Human-paced collaboration keeps the person engaged in the decisions. Context evaluation verifies the model against code and business reality, then feeds what the team learns back into the repository.

Both groups can begin with the same step: document the business before asking the agent to build.

Describe who uses the system. Explain the work they perform. Define the language they use. Capture the rules, exceptions, and outcomes that matter. Connect that material to the technical structure of the application. Then ask the agent to explain what it understands, challenge the explanation, verify it against reality, and preserve what the team learns.

A capable AI model already knows a great deal about software and the industries software serves. Give it the knowledge that only your team possesses.

That is how a new AI teammate can arrive as a blank slate and, within the first five minutes, begin working with the application knowledge of someone who has been part of the team for six months or longer.