# Contracts Are Where Context Becomes Visible I have started to think that we sometimes put too much attention on the inside of a bounded context, and too little on the surface where other systems meet it. The internal model matters, of course. If the model inside the context is weak, the system will eventually show it. Rules become scattered. Language becomes inconsistent. Changes become harder than they should be. But from the outside, most of that internal work is invisible. Other teams do not interact with your aggregates. They do not see the private concepts that make your implementation elegant. They do not care much whether the internal code is arranged exactly the way you wanted, as long as the context behaves correctly. What they see is the contract. They see the API. The command. The event. The schema. The field names. The status values. The examples. The errors. That is where the context becomes visible to the rest of the world. That feels more important in the age of AI. AI can generate a lot from a contract. It can create clients, handlers, tests, examples, documentation, mocks, mappings, and explanations. It can help a consumer team move faster without needing to ask the producer team every small question. That is useful. But it also means that whatever is unclear in the contract can spread quickly. ## The outside world builds on the surface A contract is easy to dismiss as a technical artifact. An OpenAPI definition. An AsyncAPI schema. A DTO. A Kafka message format. Something needed so two systems can talk without breaking each other. That view is not wrong, but it is incomplete. A contract is also a published view of the context’s understanding. It says what the context accepts, what it publishes, what it owns, and what other systems are allowed to depend on. It is not the whole domain model, but it is not separate from the domain either. If a context publishes `OrderUpdated`, it has made a very weak statement to the outside world. Something changed. Maybe the payload has enough fields for a consumer to work it out. Maybe the documentation explains the cases. Maybe everyone remembers the discussion from last month. For a while, that may be enough. Then another team consumes the event. A dashboard uses it. A support process starts depending on it. AI is asked to generate a new handler from it. Someone writes documentation based on the schema. Slowly, the vague word becomes part of the system’s shared language. The problem is not the word `updated` itself. The problem is that it avoids saying what is now true. Was the order confirmed? Was payment captured? Was the delivery time selected? Was an item removed? Was the order cancelled by the customer, rejected by the business, or adjusted by an internal process? Those are different facts. Different consumers can rely on them in different ways. If the contract does not make that visible, the meaning has to be recovered somewhere else. Usually it is recovered badly. ## AI reduces the friction around weak contracts Weak contracts were already a problem before AI. Consumers depended on accidental fields. Internal structures leaked into public APIs. Events became generic data notifications. Commands sounded like database updates. AI does not create this problem. It removes some of the friction that used to expose it. If a contract is vague, AI does not necessarily stop. It continues. It infers intent from names, field types, examples, nearby code, and whatever documentation happens to exist. The result can look better than the source material deserves. The code can be readable. The documentation can sound confident. The tests can pass. That is the uncomfortable part. Missing meaning does not always appear as broken software. Sometimes it appears as working software with hidden assumptions. This is why contracts need more attention now, not less. They are one of the main sources AI will use when it builds around a context. If the contract is precise, AI has a narrower and safer space to work in. If the contract is vague, AI will still work, but it may spread the vagueness into more places. The issue is not that AI misunderstands a good contract. The issue is that AI is too willing to work with a bad one. ## Contracts are not exported internals One tempting shortcut is to generate contracts from internal models and call the job done. I understand why that happens. It feels efficient. The data already exists. The fields are already named. The types are already there. Why create another model? Why write mappings? Why duplicate structure? Inside one small application, that may be fine. Across bounded contexts, it is more dangerous. The internal model is designed for the owning context. It should reflect the rules, language, and decisions that make sense inside that boundary. The contract has a different job. It is the part of the model the context deliberately exposes. It should be careful about what it reveals, what it hides, and what it allows others to rely on. Those are not the same design problem. A good internal model can still produce a poor contract if the boundary is treated casually. The outside world does not need every internal distinction. It also may need some external clarity that the internal model does not naturally provide. The contract should be designed for communication across the boundary, not extracted as a side effect of implementation. This is especially important when AI is involved. Generated tools often push toward direct reuse because it is simpler. One schema. One type. One model passed through several layers. Less code. Fewer mappings. That can look clean while quietly removing the boundary. Some duplication is not waste. Sometimes it is the price of keeping meanings separate. ## Commands and events reveal different parts of the context Commands and events are a useful place to see this clearly. A command exposes what the context is willing to be asked to do. It is input language. It should express intent, not just mutation. `UpdateOrder` is usually too broad. It sounds flexible, but often that flexibility means the real business action has not been named yet. `ConfirmOrder`, `SelectDeliveryTime`, `CancelOrder`, or `ApplyRefund` may still need refinement, but they push the conversation closer to the domain. They also say something important about ownership. A command is not a request to change someone else’s data directly. It is a request for the owning context to apply its own rules. Events expose a different kind of language. An event says what the context is prepared to publish as true. That difference matters. `PaymentCaptured` is not the same kind of statement as `PaymentUpdated`. `DeliveryTimeSelected` is not the same kind of statement as `OrderChanged`. An event should give consumers something they can reason about. Not everything about the internal process. Not a dump of all fields that changed. A fact the context owns. This does not mean all events must be grand business milestones. Some events are simple. Some mostly distribute data. But even then, the contract should be honest about what kind of event it is. A data update, a business fact, and a process notification should not all look like the same generic message with a different name. Consumers should not have to guess what kind of truth they are receiving. ## The contract should reduce guessing A good contract does not need to be long. It does need to reduce avoidable guessing. Names matter. Examples matter. Constraints matter. Short notes matter. If a timestamp means business time rather than processing time, say so. If a status is only informational and should not drive consumer behavior, say so. If an event is emitted before the whole process is complete, say so. If a command is idempotent, say what that means in practice. This is not documentation decoration. It is part of the contract. AI makes this more obvious because the contract becomes prompt material whether we intend it or not. A schema with vague names gives AI structure. A schema with clear language, examples, ownership, and constraints gives it a better boundary. I do not think this requires a heavy process. It is more of a review habit. When a contract changes, read it once as an integration artifact and once as language. Ask what the outside world can now see. Ask what the name claims. Ask what consumers are allowed to believe. Ask whether the contract exposes a domain fact or only leaks internal movement. Ask whether someone who was not in the implementation discussion would understand what the context is saying. That last question is useful because most future readers will not have been in the discussion. Neither will the AI tools pointed at the repository six months later. ## The visible part deserves more care I still care deeply about the internal model. A bounded context with poor internals will not stay healthy for long. But the contract is where the context meets the world. It is where other teams form their understanding. It is where consumers build their assumptions. It is where AI tools will often start when asked to generate something useful around the system. That makes contracts one of the most important design artifacts in AI-assisted development. Not because contracts are new. Not because schemas suddenly became architecture. But because the visible part of the context now gets reused, interpreted, and amplified faster than before. If the context speaks clearly through its contracts, AI can help others work with it more safely. If the contract is vague, AI will not fix the missing meaning. It will help us spread it.