Beyond Prompts: Architecting AI's Business Sense from Your Code
An AI assistant can explain what a PHP method does and still misunderstand what your business does. It may see a refund() method and assume every payment can be reversed, while the real rule depends on settlement status, the sales channel, and an exception agreed with a payment provider.
That gap is not usually a prompting problem. It is an architecture problem: business meaning is scattered across code, database conventions, configuration, and the memories of the people who maintain them. Better prompts help an assistant ask useful questions, but they cannot reliably supply rules the system has never made explicit.
Code contains business knowledge, but not all of it is obvious
Backend systems encode decisions in many forms. A database constraint may prevent duplicate invoices. A conditional may distinguish a trial customer from a paying customer. A queue worker may retry a payment notification, while another service decides whether processing that notification twice is safe.
Those details matter, but reading them requires context. A field named status might represent a customer-facing state, an internal workflow step, or a legacy integration flag. Even accurate code summaries can miss why a rule exists or whether it applies to a new feature.
Start by identifying the business concepts that carry the most consequences: money, permissions, customer commitments, inventory, and regulatory obligations. For each one, look for the rules enforced by the application and the assumptions surrounding it. Treat comments and documentation as evidence to check against behavior, not as automatic proof.
Put important rules behind clear boundaries
AI tools work with the material they can find. Developers do too. A rule expressed in one well-named place is easier to discover and evaluate than the same rule repeated across controllers, scheduled jobs, and SQL queries.
Consider an order that can be cancelled only before it has been dispatched. Instead of repeating a status comparison wherever cancellation is offered, give the decision a home in the domain model or an application service:
final class Order
{
public function __construct(
private string $status,
) {}
public function canBeCancelled(): bool
{
return in_array($this->status, ['new', 'confirmed'], true);
}
}
The method name exposes a business question; the implementation gives a concrete answer. This example is intentionally small: a real cancellation flow may also need authorization, a state change, persistence, and coordination with fulfilment. If dispatch and cancellation can happen concurrently, the system must also protect the decision and update together, for example through an appropriate database transaction and locking strategy.
The goal is not to wrap every conditional in a class. It is to make consequential decisions identifiable, consistent, and testable. An assistant asked to change cancellation behavior can then inspect a meaningful boundary rather than guess which of several similar checks is authoritative.
Make the business contract visible
Code shows what a system currently does. A concise contract can explain what it is supposed to guarantee and where that guarantee ends. Keep these notes close enough to the implementation that changes can be reviewed together.
For an API that accepts cancellation requests, a useful contract might explain which order states permit cancellation, who may request it, what response a caller receives when the order is already dispatched, and whether repeating a successful request has the same effect. It should also identify any downstream work, such as notifying a warehouse, and what happens if that work fails.
Examples make these rules easier to interpret. A test named for a business outcome, such as rejecting cancellation after dispatch, provides a concrete scenario that both a developer and an assistant can follow. Tests demonstrate covered behavior; they do not establish that every important scenario has been covered.
Record unresolved questions as well. “Can a confirmed order be cancelled after the warehouse has started packing?” is more useful than silently letting an assistant infer an answer from a partial implementation. Uncertainty is part of the system’s context.
Give AI a path to evidence
Supplying an entire repository to an assistant is rarely a substitute for directing its attention. Large systems contain obsolete paths, competing implementations, and operational details that may not apply to the task.
Give the assistant a scoped question and a map to the relevant evidence. For example:
Explain the current cancellation rules for orders created through the public API. Inspect the endpoint, the application service, relevant persistence constraints, and tests. Identify conflicting behavior and questions that require a product decision. Cite the files and methods behind each conclusion.
This request asks for an investigation, not an invented policy. Review the cited code, especially where a conclusion depends on configuration, feature flags, database state, or behavior in another service. If the assistant proposes a change, ask it to trace the success path and failure paths: what is saved, what may be retried, and what a caller can safely repeat.
Protect the context you share
Useful context does not require handing over every production record or credential. Use representative examples with sensitive values removed, and follow your organization’s rules for the tools and data involved. Database schemas and sanitized fixtures can often explain relationships without exposing customer details.
Close the loop when the system changes
Business knowledge decays when code, tests, and explanations drift apart. Make the relevant contract part of the change: when a cancellation rule changes, review the API behavior, domain logic, tests, and operational consequences together. A pull request can state the rule being changed and point reviewers to the evidence.
This discipline also improves performance work and architectural decisions. Before caching an eligibility decision, for example, establish which facts affect it and how quickly a changed fact must take effect. Otherwise, a technically fast answer can be a business mistake.
AI becomes more useful when it can trace decisions to clear rules and concrete evidence. The lasting investment is not a perfect prompt; it is a codebase that makes its business commitments visible enough for people and tools to question, change, and maintain them.