Part 2 of The Brownfield Problem — a series for enterprises whose AI investment isn’t yet showing up in delivery speed or cost, on the heavily customised platforms that run the business. If you’re just joining, start with Part 1: The Problem No One Is Naming.
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.