An AI assistant can explain a PHP class in seconds and still miss the rule that makes the whole system work. It may see a payment method, suggest a cleaner interface, and overlook the fact that an order must never be marked paid before the provider confirms it. The code looks tidier; the system becomes less trustworthy.

Better AI-assisted design starts by making the system's logic visible. Your code already contains clues about its boundaries, assumptions, and failure modes. The engineering task is to turn those clues into context an assistant can reason about, then test its suggestions against the behavior the system must preserve.

Start with the decisions, not the directory tree

A repository tour can tell an assistant where controllers and services live. It rarely explains why a request crosses three boundaries before a database row changes. Before asking for a design, describe the decision the system must make and the consequences of getting it wrong.

Consider an API that accepts an order. A useful description says more than “create an order and charge a card.” It identifies when an order becomes authoritative, whether the client can retry, and what happens if the payment provider responds slowly. Those details shape the architecture more than the names of the classes.

Give the assistant a compact scenario with four kinds of context:

• Inputs and outputs: What does the caller send, and what response can it rely on?
• Invariants: Which conditions must remain true, including during failures?
• Boundaries: Which database, queue, or external service owns each part of the work?
• Constraints: What operational or compatibility requirements are known?

For example, an invariant might be: “A successful retry must return the existing order rather than create a second one.” That is more useful than asking the model to “make the endpoint robust.” It gives both of you something concrete to verify.

Trace one request through the system

Choose a representative request and follow it from the HTTP boundary to its durable effects. In a PHP application, that might mean reading the controller, validation, application service, repository, database transaction, and any code that calls a payment provider or publishes a message.

Record what each step assumes. Does validation depend on mutable database state? Is an external call made while a database transaction is open? Can a queue worker process the same message twice? These questions expose design pressure that a class-by-class summary can miss.

Then ask the assistant to reconstruct the flow from the supplied code. A focused prompt could be:

Trace an order request through these files. Identify where state becomes durable, where an external effect can occur, and what a retry could repeat. Cite the relevant methods from the supplied code and label anything you cannot determine.

The last sentence matters. An assistant should distinguish evidence from inference. If the repository code is missing, it cannot establish whether a database constraint exists. If the queue configuration is absent, it cannot establish delivery behavior. Treat those gaps as questions for the design review, not as permission to fill in the blanks.

Make failure paths first-class design inputs

Happy-path diagrams are easy for people and models to agree with. The useful design work often begins when a process stops between two successful operations.

Retries and idempotency

Suppose a client sends an order request, the server commits the order, and the response is lost. The client cannot know whether the operation succeeded. A retry needs a stable idempotency key and a server-side rule for associating that key with the original operation. The association must be protected against concurrent requests, typically with a database constraint or another atomic mechanism.

That still leaves decisions to make: how long is the key retained, what happens if the same key is reused with a different payload, and what response should a caller receive while the original request is still running? Ask the assistant to enumerate these cases, then choose and document the contract. “Add idempotency” is a goal; these answers make it a design.

Database and external effects

A database transaction can make local changes atomic, but it does not automatically include a payment provider or message broker. If the database commit succeeds and publishing a message fails, downstream work may never start. If a message is published first and the transaction later rolls back, a consumer may act on a change that does not exist.

One possible approach is a transactional outbox: save the business change and a pending event in the same database transaction, then have a separate process publish the event. That process can fail after publishing but before recording success, so consumers still need to handle duplicates. The pattern improves reliability when its operational cost is justified; it is not a substitute for understanding the delivery contract.

Use AI to challenge the architecture

Once the flow and invariants are clear, ask for competing designs and their tradeoffs. For a slow provider call, one option may keep the API synchronous with a bounded timeout. Another may return an accepted status and process the payment asynchronously. Compare what each choice means for client behavior, user feedback, recovery, and operations.

Insist on concrete consequences. “Use a queue for scalability” is incomplete if nobody has specified how failed jobs are retried, how duplicate work is handled, or how an operator finds a stuck order. Equally, a synchronous design needs a plan for timeouts and uncertain provider outcomes.

The assistant can also look for mismatches between layers: an API promises immediate completion while the worker processes later, or application code assumes uniqueness that the database does not enforce. These are valuable review leads, but they remain hypotheses until checked against the code and configuration that actually run.

Turn reasoning into a durable feedback loop

Capture the important findings where future changes can use them: an API contract, a short architecture decision, a database constraint, or a test of an observable behavior. A retry test, for example, can submit the same key twice and verify that the application exposes one logical order. A concurrency test may be needed to exercise the race that a sequential test cannot.

Keep AI context current as the system changes. A stale description of transaction boundaries can produce confident advice for an architecture that no longer exists. Review generated changes as you would any other proposal: trace the flow, check the failure cases, and run the tests and deployment checks appropriate to the change.

AI intuition is not a mysterious property of a model. It emerges from the quality of the evidence and questions you give it. When the code's rules, boundaries, and failure paths are explicit, an assistant becomes a sharper design partner—and the system becomes easier for the next human to understand, too.