20 April 2026
The CLAUDE.md Problem
Your AI coding agent doesn't know your architecture standards. It doesn't know your ADRs, your principles, your data classification rules. And it's making decisions on your codebase every day without them.
Why your AI coding agent needs to know your architecture standards — and what to do about it
If you’ve spent any time with Claude Code, Cursor, or GitHub Copilot in a serious engineering context, you’ve probably encountered the CLAUDE.md pattern.
The idea is simple. You drop a markdown file into the root of your repository. In it, you describe the codebase, the conventions, the constraints, the things the agent should and shouldn’t do. Don’t use raw SQL. Always validate at the boundary. This service owns these tables and no others. The agent reads it, internalises it, and produces code that actually fits your system rather than code that technically works but violates every principle your team spent years establishing.
It’s a brilliant hack. It’s also, if you look at it from a certain angle, an architecture problem in disguise.
I came to this the wrong way round
Boris Cherny wrote something last year that stuck with me. He observed that the coder is now more like an architect, that the job has shifted from writing code to defining the structures and constraints within which code gets written. His frame was about developers evolving upward. Mine is the reverse.
I’ve spent most of my career as a Chief Architect. I’ve written the ADRs, run the governance boards, produced the principles documents that sat in Confluence and were largely ignored by the time the next sprint started. A while back I started building software again myself, properly, not just prototyping, using the same AI tools my clients’ engineering teams are using.
What I found was that the architecture instinct doesn’t go away. It just changes form. Instead of writing standards for humans to follow, I was writing context for agents to consume. Instead of a governance board, I had a context window. The constraint system was the same. The medium was different.
That realisation is what eventually became a feature in Soiléire.
The governance gap nobody is talking about
Here’s the problem most organisations are walking into right now.
AI-powered engineering is accelerating the pace of change across every application landscape. New tools adopted, capabilities shifting, legacy systems displaced, at a speed that makes quarterly architecture reviews look dangerously slow. Engineering teams are shipping faster than governance can track.
And the agents doing the building don’t know your rules.
They don’t know that you made a decision three years ago to go API-first for all integrations and explicitly prohibited file-based transfers. They don’t know that your data classification standard requires encryption at rest for anything marked Confidential or above. They don’t know that the principle behind your cloud-first hosting policy is portability and vendor independence, not just cost, and that that distinction matters when they’re choosing between two technically equivalent approaches.
Your ADRs know. Your principles know. Your standards know. But they’re sitting in a governance tool, or a Confluence space, or a shared drive, in a format that was designed for humans to read once and forget.
The CLAUDE.md pattern is the engineering community’s improvised answer to this problem. Teams are manually copying architecture decisions into context files, writing bespoke summaries of their standards, trying to distil years of governance thinking into something an agent can act on before the token limit runs out.
It works. It’s also entirely manual, entirely disconnected from the system of record, and entirely dependent on someone remembering to update it when a decision gets superseded.
What we built
When we started building Soiléire, governance records were always part of the model. Architecture Decision Records, Principles, and Standards as first-class entities, not documents attached to applications, but structured records with status workflows, linked entities, and audit trails.
What we didn’t anticipate was how quickly the question of agent consumption would become urgent.
The feature we shipped exports your governance records as structured markdown with YAML frontmatter, purpose-built for AI coding agents, LLMs, and RAG pipelines. Every ADR, every principle, every standard gets rendered into a consistent, machine-parseable format. All references are resolved to readable names rather than opaque internal IDs. Empty sections are omitted to keep the output clean and token-efficient.
You can export a single record, copy it to your clipboard and paste it directly into Claude Code, Cursor, or Copilot as grounding context before you start a session. Or you can export the full governance bundle: a structured ZIP containing a README index, a principles file, a standards file, and a decisions folder with one file per ADR. Drop it into your repository as living documentation. Pipe it into your RAG system. Feed it to whatever automation tooling your team is building.
The result is that your architecture decisions travel with your code. Not as an afterthought. Not as a manual process someone has to remember. As a first-class export from the same system where your architects maintain the governance record.
Why this matters for regulated organisations specifically
There’s a version of this argument that applies to any engineering organisation. But it applies with particular force in regulated financial services and insurance, where the governance isn’t optional and the audit trail isn’t a nice-to-have.
When a regulator asks how you ensured your AI-assisted development respected your data classification requirements, “we had a Confluence page” is not a sufficient answer. When your auditors want to understand the lineage between an architectural decision and a production system, a disconnected markdown file in a developer’s local context doesn’t constitute evidence.
The governance export feature produces a timestamped, structured record of what your governance said at the point of export. Every export is logged. The YAML frontmatter includes generation metadata, organisation, timestamp, source. It’s not just useful for agents. It’s useful for auditors.
The pattern is the same
What I keep coming back to is that none of this is actually new thinking. Architects have always been in the business of writing rules for builders to follow. The builders used to be humans. Now some of them are agents.
The CLAUDE.md file is an architect’s instinct expressed in a new medium. Drop the constraints in the context window. Make sure the thing doing the building knows what it’s not allowed to do.
Soiléire just makes that possible without the manual labour — and with a proper audit trail attached.
This is part of the #ArchitectWhoShips series — exploring what enterprise architecture practice looks like when the architect is also building the product. More on the ailíniú thinking page.