It’s 6:47 am and Marcus is already at his desk.

Not because anyone asked him to be. Because the question that followed him home last night is still sitting there when he wakes up, and the only way to get it out of his head is to start answering it.

What does the AI actually need from us that we haven’t given it yet?

His coffee is still too hot to drink. The office is quiet in the way it only is before 8 am — no Slack, no standups, no one arriving with a problem that needs solving before they’ve even taken their coat off. Just the hum of the air conditioning and a blank file open on his screen.

He’s going to build this properly.

Not another prompt. Not another training session for the team. The actual infrastructure — the files, the layers, the foundation that the AI reads before it writes a single line of code.

He’s starting with Layer 1.

Every complex system has one rule that sits above all the others.

Not because it’s the most sophisticated rule. Not because it’s the hardest to follow. But because if it breaks — if someone violates it once, even with good intentions, even with a clean PR that passes review — the consequences don’t show up immediately. They accumulate quietly. They surface later, at the worst possible moment, as work that someone else has to find and undo.

In a brownfield enterprise platform, that rule is this:

The base is read-only. Always.

Here’s what that means in practice.

Enterprise SaaS platforms — the kind that have been running for years, extended by multiple teams, customised at every layer — are built on a foundation that the vendor provides and maintains. That foundation is updated regularly. Security patches, performance improvements, new features, breaking changes that require migration. It’s a living thing.

Your customisations sit on top of that foundation through an override mechanism — a pattern the platform provides specifically so that your code and the vendor’s code never touch. Your changes live in your layer. The vendor’s code lives in theirs. When the vendor ships an update, they replace their layer. Your layer is untouched. Everyone goes home on time.

This is the architecture working as designed.

The moment AI writes directly to the base layer — even once, even a small change, even something that seems harmless — that contract breaks. Your modification is now inside the vendor’s territory. The next platform upgrade will silently overwrite it. No warning. No merge conflict. No error. Just gone. And depending on what that modification was doing, gone might mean a broken checkout flow that no one catches until a customer does.

Marcus knows this. He’s known it for years.

What he’s realising, sitting at his desk at 6:47 am with a blank file in front of him, is that he’s never written it down.

Not in a way the AI can read.

It lives in the heads of his senior engineers. It gets communicated in PR reviews — “this should be in the custom cartridge, not the base” — and in onboarding conversations, and in the occasional post-mortem when someone junior makes the mistake that every junior engineer makes at least once. It’s tribal knowledge. It’s essential tribal knowledge. And tribal knowledge is exactly what AI cannot access.

In Marcus’s case, the platform is a heavily customised enterprise commerce platform — one with its own specific override architecture, its own extension system, its own rules about what the vendor owns and what you own. But the principle holds across any enterprise platform with a similar extension model. SAP, Oracle, Guidewire, or any heavily customised open-source base. The specific names change. The problem is the same.

This is the first thing Layer 1 fixes.

What Layer 1 actually is

It’s a short file. Shorter than you think it needs to be.

That brevity is deliberate. Layer 1 is loaded into every single AI conversation — it’s the first thing the tool reads before it does anything else. Which means every word in it competes with every other word for the finite attention the AI brings to a session. A long Layer 1 is a diluted Layer 1. You want high signal, zero noise.

The file lives at the root of your repository. For Claude Code it’s called CLAUDE.md. For GitHub Copilot it’s .github/copilot-instructions.md. For Cursor it’s .cursorrules. Different tools, same principle — every major AI coding assistant looks for a file in a known location and treats it as the authoritative set of rules for this project.

What goes in it:

The read-only rule, stated absolutely. Not “try to avoid editing the base cartridges.” Not “in most cases, prefer the custom cartridge.” Absolute. No exceptions clause. The rule must be unambiguous enough that no amount of “but it would be simpler to just edit the base” reasoning can override it. AI models will optimise for simplicity unless you give them a hard constraint. So give them a hard constraint.

The list of what’s read-only. Every base and vendor cartridge by name. The AI needs a definitive list, not a general principle it has to interpret. If it’s on the list, it’s off-limits. If it’s not on the list, it’s fair game. No ambiguity.

The override mechanism. The rule tells the AI what not to do. It also needs to know what to do instead. A single paragraph explaining the override pattern — how to extend a controller, how to overlay a module — gives it the path forward. Without this, the AI knows what’s forbidden but not what’s permitted, and it will improvise.

A pointer to the full coding standards. Layer 1 is not the place for detail. It’s the place for the one rule. Everything else lives in Layer 2, and Layer 1 simply points there.

The whole file fits in twenty lines. That’s not a rough estimate. That’s a target.

Here’s what that looks like in practice — the actual CLAUDE.md file from an enterprise commerce project. If you’re on a different platform, the names will differ. The structure is the same.

# Project Guidelines

For full coding standards, cartridge lists, and override patterns,
see docs/CODING_STANDARDS.md.

## Base Cartridge Rule

Never edit read-only cartridges. This includes:
- app_storefront_base and all SFRA modules
- Third-party integration cartridges (see full list in docs/CODING_STANDARDS.md)

Always use the cartridge overlay pattern in app_custom or the
corresponding _custom cartridge. Use server.replace, server.append,
or server.prepend to override base controller routes. For models,
scripts, and templates, create a file at the same path in the custom
cartridge to overlay the base version.

Twenty lines. One rule. One pointer.

That’s the whole file. Deliberately.

Notice what’s not in there. No explanation of why the base is read-only. No history of the decisions that led here. No nuance about edge cases. The AI doesn’t need the reasoning — it needs the constraint. The reasoning lives in your head, in your team’s shared understanding, in the post-mortem documents that explain what happened last time someone got this wrong. Those are human documents. Layer 1 is a machine document.

The done signal

This is the test that tells you whether Layer 1 is working. Run it before you build anything else. Run it again after any change to the file.

Ask the AI to add a new route to one of your core controllers.

That’s it. A simple, realistic task. The kind of thing a developer asks for three times a week.

Watch where it puts the file.

If it creates the file inside app_storefront_base — or any cartridge on your read-only list — Layer 1 is not working. The rule isn’t landing. Go back to the file, tighten the language, make the constraint harder.

If it creates the file inside app_custom, using server.extend(base) and the correct override method for what you asked for — Layer 1 is working.

On any other platform the cartridge names will be different, but the test is identical in principle: ask for a realistic code change and watch whether the AI respects the boundary between what’s yours and what’s the vendor’s.

It sounds almost too simple. Good. The test is simple because the rule is simple. The sophistication comes later, in the layers built on top of this one. Layer 1 is the foundation. You need to know it’s solid before you build anything else on it.

Marcus runs the test at 7:23 am.

He’s been building the file for the better part of an hour — not because it took that long to write twenty lines, but because he spent forty minutes thinking about what to leave out. Every instinct he had said to add more. More context. More explanation. More edge cases the AI might encounter.

He left them out. They belong in Layer 2.

He runs the test. Types the instruction. Watches the AI respond.

It creates the file in the custom cartridge. Correct override pattern. Correct method.

He takes a sip of his coffee — cold now, doesn’t matter — and adds a note to the file with the date and a single line:

Tested. Working.

It’s a small thing. A twenty-line file and a test that took thirty seconds.

But the foundation is solid. And for the first time since that board meeting, Marcus feels something shift — not relief exactly, more like the particular satisfaction of having started a thing the right way.

Everything else gets built on top of this.

What breaks if you skip this layer

It’s worth naming explicitly, because the temptation to skip Layer 1 and jump straight to the more interesting layers is real. Layer 2 — the coding standards, the module map, the override patterns — feels more substantial. More like the real work.

Skip Layer 1 and build Layer 2 first, and here’s what happens.

The AI follows your coding conventions beautifully. Correct naming. Correct test structure. Correct everything — committed directly to the base. The PR looks great. The code review catches nothing because the reviewer is looking at code quality, not cartridge location. The next vendor upgrade silently overwrites it. Three months later, in a standup, someone says “that feature we shipped in Q2 has stopped working” and no one immediately knows why.

Layer 1 is not the most interesting layer to build. It is the most important one to build first.

In Part 3: Layer 2 — the highest-leverage file in the entire system. Not platform documentation. Not API references. The specific document that teaches the AI how your project works. Why this single file prevents more bugs than any other piece of infrastructure — and what goes in it.

If you found this useful, subscribe to get each part as it lands. The series runs seven parts — each one builds on the last.

Working through this on a heavily customised platform right now? Email contact@brownfieldai.dev or message me on LinkedIn. I’m always up for a direct conversation.

Kinnaree Patel is the founder of Brownfield AI, which helps enterprises get AI delivering real business results on the platforms they already run. She writes from live experience inside an enterprise AI transformation. Want to talk it through? Email contact@brownfieldai.dev or visit brownfieldai.dev.

The slide goes up and Marcus feels it before he processes it.

Not the numbers — the room.

The particular quality of silence that settles when a slide lands badly. The CFO’s hand moving to her coffee cup, lifting it, setting it down again without drinking. The way the Head of Product suddenly finds something interesting in his notepad. Marcus has been in enough of these rooms to read the temperature without looking at the thermometer.

The slide shows a competitor. Smaller company. Half the engineering headcount. Shipping at a pace that makes the chart look almost accusatory — a line climbing steadily upward while Marcus’s line does something more complicated. Something that requires explanation.

He gives the explanation.

It’s a good explanation. Accurate. He’s rehearsed the shape of it, the language that makes the complexity legible without sounding like an excuse. He talks about the platform. The years of customisation. The architectural decisions that were the right calls at the time and are now the walls everything else is built against.

The CFO nods.

Not the nod that means I understand. The other one. The slow, considered nod that means I’m filing this away.

“And the AI tools?” she asks. “We’ve made a significant investment there.”

“We have,” Marcus says. “The team is using them.”

He doesn’t say the rest. Not here, not in this room. The rest is for the drive home, for the particular darkness of the car at 11 pm when the day has finally run out of demands and there’s nothing left but the honest version.

The tools are running. The output looks right. It just doesn’t work.

Picture the codebase Marcus is responsible for.

Not the clean version from the architecture diagram on the wiki — the real one. The one that exists in production, that has been live for years, that has absorbed the decisions of every team that touched it before his. Some of those decisions were elegant. Some were made at 2 am before a launch. Some were workarounds that became permanent because permanent was faster than right, and then the person who knew they were workarounds left, and now they’re just the way things work.

This is a brownfield system. Most enterprise systems are. The term sounds clinical but the reality is deeply human — it’s what happens when software lives long enough to accumulate history.

His platform is a major enterprise SaaS product. Solid foundation. Heavily extended. Customised at every layer by teams who understood their piece of it, working at the speed that business demanded. The kind of system where you learn not to touch something without first understanding why it exists.

Now add AI coding assistants.

The tools arrive with encyclopaedic knowledge of the base platform. They know the APIs, the extension patterns, the architectural principles. In a demo environment, on a clean instance, they’re remarkable. A developer describes what they need and the AI produces code that looks exactly right. Fast. Confident. Apparently competent.

The first few weeks feel like the turning point everyone said was coming.

Then the PRs start landing.

A senior engineer opens one and goes quiet for a moment. Then types a comment — the kind that’s carefully worded because the author is a junior developer, and what it’s really saying is:

This is in the wrong place. And I need you to understand why without feeling like you failed.

The AI has written to the base layer — the read-only foundation that vendor upgrades will silently overwrite. The code is syntactically perfect. Architecturally, it’s a time bomb with a very clean detonator.

Another PR. Different problem, same shape. The AI has overridden an entire module when it needed to change one function — copying the whole file rather than extending it, which means any changes the base makes to the other functions will never reach this version. The code works today. It will drift quietly out of sync with the platform it’s supposed to extend.

Marcus’s senior engineers — the ones who carry the most context about how this system actually works — are now spending their afternoons reviewing AI output for problems that aren’t visible until you already know what to look for.

Think about what that costs.

The people who understand the system deeply enough to catch subtle architectural errors are also the people who are supposed to be building the next thing. They’re now a quality gate for a tool that was supposed to make quality easier. The juniors who could benefit most from AI assistance can’t always tell when the output is subtly wrong. And subtly wrong in a system with this much layered history is a specific kind of expensive — the kind that surfaces three months later, during a platform upgrade, at the worst possible moment.

Here’s what Marcus’s instinct says. It’s the same instinct most engineering leaders reach for first.

Better prompts. More documentation. Training sessions on how to use the tools correctly.

It’s a reasonable instinct. It’s also pointing at the wrong problem.

The AI doesn’t need better prompts from individual developers. It needs something more fundamental.

Sit with this distinction for a moment, because it’s the hinge the whole problem turns on.

Platform knowledge is what the AI arrives with. It knows the base product — the APIs, the extension model, the patterns documented in the official guides and discussed in every forum thread and Stack Overflow answer ever written about the platform. This knowledge is generic. It applies to every team running this system, everywhere in the world. The AI has it. It’s not the gap.

Project knowledge is what the AI is missing. It doesn’t know your system. It doesn’t know which directories are read-only and which aren’t. It doesn’t know whether your team overrides by extending the base module or by replacing it entirely — and why, and when each approach is correct. It doesn’t know your test naming convention, your branch strategy, the module map that evolved over years to reflect the specific shape of your business. This knowledge lives in the people who’ve been here long enough to absorb it. It isn’t written down anywhere the AI can find.

When you ask an AI to write code in a system it knows in the abstract but not in the specific, it fills the gaps with its best guess. Its best guess is always the simplest, most generic approach — the one that works on a clean implementation, not on yours.

That’s not a tool problem. It’s a context problem.

And context problems require context infrastructure to solve them.

Marcus’s senior engineers weren’t being resistant when they flagged these failures.

They were being precise.

“The AI doesn’t know our override pattern.” Precise. “It keeps writing to the wrong layer.” Precise. “I’d spend less time doing this myself.” Precise, and worth listening to.

The developers flagging AI failures in your team are not the obstacle to transformation. They’re the most accurate diagnostic instrument you have. They can see exactly where the gap is because they live inside it every day.

The gap is not capability. The AI is capable.

The gap is context. And the organisation hasn’t built the infrastructure to deliver it.

This is the problem I spent time living inside — not as an outside consultant looking in, but as someone embedded in the work, in the weeds, feeling the same pressure Marcus feels on the drive home.

What came out of that time was a framework. Six layers. Each one teaching the AI something it cannot infer on its own — built in a specific order, because the order matters as much as the layers themselves.

The first layer tells the AI what it must never touch, and exactly how to override things correctly. Without this, everything else is built on sand.

The second — and this was the surprise — turns out to be the highest-leverage file in the entire system. Not platform documentation. Not API references. Project conventions. The specific decisions your team has made about how work gets done here.

The third layer configures what the AI can do without interrupting you, and what always needs a human in the loop. The fourth handles the operations that happen once a quarter and have no margin for error. The fifth encodes what “done” means — the team’s definition of quality, made legible to the AI. The sixth gives the AI continuity across sessions, so it starts a new conversation already carrying the context it built up in the last one.

None of these are prompts. They’re files. Committed to the repository, version-controlled, living next to the code they govern.

The total upfront investment to build all six is roughly one day. One focused day to construct the skeleton. After that, the system accumulates context naturally as you work. And the AI — the same AI that was producing plausible-looking code in the wrong place — starts producing output that fits. That respects the architecture. That your senior engineers can review in minutes rather than hours.

Velocity compounds. Not because the tool improved. Because you gave it what it needed.

Back in the car, in the dark, Marcus asks himself a different question.

Not the one he’s been asking —

Why isn’t this working the way it’s supposed to?

The one underneath it.

What does the AI actually need from us that we haven’t given it yet?

It’s a small shift in language. It’s a significant shift in posture. It moves the problem from the tool’s shortcomings to the environment the tool is operating in. And once you make that move, the path forward becomes clearer — not easy, not instant, but clear.

You stop waiting for the AI to figure out your codebase.

You start building the infrastructure that lets it.

That’s what this series is.

In Part 2: Layer 1 — the single most important constraint in the system. The one rule that, if the AI breaks, creates work another developer has to find and undo. What it is, what it contains, and the exact test that tells you whether it’s working.

Subscribe to get each part as it lands. If you’ve been following the LinkedIn series on AI on customised enterprise platforms, this is where the framework gets the depth the LinkedIn format wouldn’t allow.

If you’re navigating this on a heavily customised platform right now and want to talk it through, email contact@brownfieldai.dev or message me on LinkedIn. I’m always up for a direct conversation.

Kinnaree Patel is the founder of Brownfield AI, which helps enterprises get AI delivering real business results on the platforms they already run. She writes from live experience inside an enterprise AI transformation. Want to talk it through? Email contact@brownfieldai.dev or visit brownfieldai.dev.