The Solutions Architect AI Playbook: Architecting the System Your Team's Agents Operate In

You still get asked for the diagram. The component boxes, the arrows, the service boundaries, the data model. That work is real and it still matters. But if you are a Solutions Architect on a team that has gone agentic, you have probably felt a quieter shift that the diagram request hides. The most consequential thing you shipped last quarter was not a design document. It was the configuration that decided how every developer's coding agent reads the codebase, what it is allowed to touch, and what gets blocked before it merges. Nobody asked you for that artifact by name. It does not have a box on an org chart. And it is now the highest-leverage thing your role produces.

That is the part of the job that has no name yet, and the absence of a name is the problem. When the work has no name, nobody owns it, and when nobody owns it, every developer improvises their own version of it. You end up with ten private setups instead of one designed system, and the team wonders why AI adoption looks busy but delivery does not move. The architect is the role best positioned to own the coherence of that system, the boundaries, standards, and trade-offs that make it more than a pile of private setups, because architecting a system that other people build inside is already the job. Operating the individual layers can be shared with Platform Engineering, DevEx, Security, and team leads. What cannot be shared is the coherence: without someone owning it, the framework fragments. The system just changed shape.

Quick answer: In an agentic-development team, the Solutions Architect's highest-leverage deliverable is no longer the architecture document. It is the configured AI development framework, the CLAUDE.md hierarchy, the MCP integrations, the agent chains, the quality gates, the hooks, and the agent permission boundaries that every other role's agents operate inside. The shift has three moves. First, treat the framework as architecture, with the same rigor you bring to a service boundary. Second, design agent chains and quality gates as the team's new operating diagram, not a folder of config. Third, build governance into the framework through agent permission boundaries, rather than bolting it on as a review gate later.

This is the fifth piece in a per-role series on what AI actually changes inside delivery teams. The earlier pieces walk through what shifts for the developer, the QA engineer, the business analyst, and the project manager. If you want the overview of how every role's playbook fits together, the role-based AI playbooks for delivery teams piece is the parent reference. The architect's piece is the one that ties the others together, for a specific reason: the other four roles redesign how their own work gets done. The architect builds the system that all four of their agents run inside. When the developer's agent reads the right context, when the QA agent knows the coverage target, when the analyst's agent uses the project's requirements conventions, that is not luck. That is someone having architected the framework underneath all of it.

I find it useful to hold the architect's progression as a ladder, because it separates "the SA uses AI to draw faster" from "the SA's value moved up a layer." The four levels below match the maturity model I work from. The point of the ladder is not the labels. It is the rightmost column: where the architect's value actually sits at each level.

At L1, the value is the architect's own output. Structured architecture prompting replaces vague requests. A custom architecture-reviewer agent checks changes for pattern consistency and NFR adherence. An ADR-template skill generates standardized decision records. This is real, and it is the floor, not the ceiling. An architect who stops here has bought themselves a faster way to produce the same artifacts. The leverage shift starts at L2 and is the whole argument of this piece. By L2 the architect is no longer the person who writes the design doc. The architect is the person who designed the system the design doc, and every other artifact, now gets produced inside.

The architect's deliverable is not the diagram, it is the framework the team's agents run inside

Start with what changed underneath the work. An architecture diagram describes a system that humans will build. An agentic framework configures a system that agents will build inside. Those are different objects with different rigor requirements, and most teams are still treating the second one like a folder of dotfiles somebody set up once. The repo-level agent instruction system is the clearest example. CLAUDE.md is one implementation of it; AGENTS.md, the open format Codex reads and increasingly a cross-tool convention, is another, as are Cursor rules, JetBrains AI Assistant configurations, and custom agent frameworks. Treated casually, any of them is a README the agent happens to read. Treated as architecture, it is a designed multi-layer context system, and the design decisions in it are as load-bearing as the ones in a service boundary.

The mechanism is layered context loading, and it has three logical layers worth designing deliberately, even if each tool implements them differently. Layer one is the always-loaded root context, the project-wide conventions every agent needs on every task: the directory map, the naming rules, the constraints that never change. Layer two is subsystem-scoped context, the per-directory instruction files (a root CLAUDE.md with src/api/CLAUDE.md and src/services/CLAUDE.md beneath it, nested AGENTS.md files, or the equivalent) that load only when an agent works in that part of the tree, so the agent sees API conventions when it touches the API and persistence rules when it touches the database, and is not drowning in both the rest of the time. Layer three is path-scoped enforcement, the targeted guidance that applies to a glob of files regardless of which agent is working. Tools differ in how they implement it: some support nested instruction files, some use glob-based rule files, and some lean on the harness layer, pre-commit hooks and CI, to carry the third layer. Context engineering, the discipline Anthropic's engineering guidance named in 2025, is the practice of curating the right information for an AI system to act on, and nothing more. The architect's job at this layer is precisely that, applied to a team: deciding what every agent should always know, what it should know only in context, and what it should never have to reason about because a rule already settled it.

Get that design wrong in the obvious direction and you stuff everything into the root file. Now every agent on every task carries the entire project's rules in its working context, the signal-to-noise ratio collapses, and the agents start ignoring the parts that matter because they are buried. Get it wrong in the other direction and the context is so thin the agents reconstruct conventions from scratch on every task, inconsistently, and you are back to ten private setups. The architect who designs this well is making the same trade-off they have always made between coupling and cohesion. It is the same skill. It is pointed at a new artifact.

This is why context architecture is not documentation. Documentation is for humans who can fill gaps with judgment. Context architecture is the operating instructions for systems that will act on them repeatedly and at volume, but not perfectly. When an architect designs the CLAUDE.md hierarchy as a real system, with deliberate decisions about what loads when, the whole team's AI-assisted work inherits that structure. When nobody designs it, the team inherits entropy, one improvised context file at a time.

Agent chains and quality gates are the operating diagram for agentic delivery

Picture the artifact a senior architect is proud of: a clean diagram showing how a feature flows through the system, what each component owns, where the boundaries are. Now move that exact instinct one layer up. On an agentic team, the equivalent artifact is the agent chain: which agent handles which phase of delivery, what files each one owns, and what quality gate sits between them. The architect who can design a service topology can design this. It is boundary design and ownership design, the core architectural skills, applied to a workflow of agents instead of a graph of services.

A concrete chain makes it real. A feature moves Requirements to Architect to Developer to Tester to Reviewer, and each agent owns specific files. The requirements agent owns the requirements doc and the API contract. The architect agent owns the design. The developer agent owns the implementation. The tester agent owns the tests and the coverage matrix. The reviewer agent checks compliance. The design decision is not "which agents exist." It is where the boundaries sit and who is allowed to write what. Hooks enforce those boundaries: a PreToolUse hook that blocks an agent from writing files outside its ownership, a phase gate that refuses to let work move from development to review until the build passes. This is the harness, the surrounding system of agents, checks, and standards the team's work moves through, and it is what lets agents and developers work at speed without the speed becoming risk.

There is a new document class hiding in here that is worth naming: the agentic ADR. A classic architecture decision record captures a choice about the system being built, the options, the decision, the trade-offs. An agentic ADR captures a choice about the framework the team builds inside. Why the agent chain has five stages and not three. Why the reviewer agent runs on a different model than the developer agent. Why a given hook blocks rather than warns. These are architecture decisions in the full sense, with consequences that compound, and writing them down is how the framework stays a designed system instead of drifting into accumulated habit. Compounding engineering, the discipline taking shape in current agentic-development practice, is building so each AI-assisted increment makes the next one cheaper and safer rather than adding entropy. The agentic ADR is one of the mechanisms that makes a framework compound instead of rot.

The quality gates are the other half of the diagram. Pre-write hooks stop agents from editing the wrong files in the wrong phase. Post-write hooks run the linter and parse test results after every code change. Phase-transition gates verify the build before work advances. PR-level gates run AI code review and architectural-compliance checks. None of these are the architect doing the review personally. They are the architect designing the system that does the review every time, on every change, whether or not anyone is watching. That distinction, between doing the check and architecting the check, is the difference between an architect who scales and one who becomes a bottleneck.

Agent permission boundaries are where governance gets built in, not bolted on

The fastest way to watch governance fail is to add it after the framework already shaped behavior. A security review that arrives at the end of delivery finds problems that are expensive to fix and easy to argue about. The architect has a better option, available precisely because the framework is a designed system: encode the governance into the system itself, as rules and hooks the agents cannot route around. Governance stops being a gate the work has to pass and becomes a property the work has by construction.

Concretely, this is agent permission boundaries and security rules expressed as part of the framework. Secrets detection as a pre-commit hook that blocks any commit carrying an API key or token, so a leaked credential never reaches the history in the first place. Dependency vulnerability scanning wired into the pipeline so a known CVE blocks the merge or opens a remediation PR automatically. OWASP checks on AI-generated code, because code an agent produced at volume needs the same scrutiny as code a human wrote, and more, since the agent will reproduce a vulnerable pattern as cheerfully as a safe one. The OWASP Top 10 for LLM applications lists prompt injection as LLM01, the top risk, which in operational terms means any input that becomes part of an agent's context window is an attack surface: a retrieved document, an issue comment, a file the agent was told to read. An architect setting agent permission boundaries is deciding which of those surfaces an agent is allowed to act on without a human in the loop, and that decision is a governance decision made at the framework layer, not a policy memo made after the fact.

MCP integrations are where this gets sharpest, because they are a privileged execution surface, not neutral connectors. An MCP server gives an agent the ability to call external tools and read external data, which means the framework has to treat each one the way it treats any other action surface. The known risks are specific. Tool poisoning, where malicious instructions are embedded in a tool's metadata or description that the agent reads and acts on. Capability attestation gaps, where there is no reliable way to verify that a server does only what it claims. Implicit trust propagation, where adding one server to a multi-server configuration extends trust across the whole set without anyone deciding to. The framework posture that answers these is explicit ownership of which servers are approved, scoped least-privilege permissions per server, logging of what each server is invoked to do, version control of the server configuration, and removal criteria for servers that are no longer needed. Treating MCP servers like convenience plugins rather than privileged integrations is how an action surface becomes an attack surface.

This is the bridge between making AI delivery work and keeping it safe, and the architect stands on both sides of it. The permission boundary that stops an agent from running a destructive command is a delivery-enablement decision and a security decision at the same time. Built into the framework, it is continuous and invisible and it holds under pressure. Bolted on as a review step, it is intermittent, resented, and the first thing skipped when a deadline looms. Governance that lives in the development system is governance that survives a busy quarter. Governance that lives in a checklist is governance that depends on nobody being in a hurry.

At L4, the framework becomes a product the SA operates

Most architects will spend their highest-leverage years at L2 and L3, and that is the right place to be. L4 is platform territory, not a natural SA progression. In most orgs it is shared with or owned by DevEx, Platform Engineering, AI Enablement, and Security. Some SAs grow into platform roles and own it directly; others stay at L2 and L3 by design, and that is the correct call for most. Make L2 and L3 boring and reliable before productizing the framework across projects. But the ceiling is worth seeing, because it reframes what the framework actually is. At L4, the architect stops configuring a framework per project and starts building a cross-project platform: a modular set of agents, skills, hooks, context templates, and CI integrations that deploys to a new project through configuration rather than from-scratch setup. The platform becomes a product, and the architect helps define its standards, boundaries, and evolution loop. New teams become productive in days instead of weeks because the framework they need already exists and only has to be pointed at their stack.

What changes at this level is that the architect is now operating a system with economics. Token budgets per project. Model selection as a cost lever, where moving code review from a frontier model to a cheaper one that is sufficient for review drops cost meaningfully with no quality loss. Agent success rates tracked across projects so the architect can see which framework components deliver value and which generate friction. The evolution loop runs on aggregate data: the hook that blocks the most wrong-phase edits across every project stays mandatory, the agent nobody uses moves from core to optional, the request that shows up on every team becomes the next core component. This is platform operation, and it is the same feedback discipline a good architect already applies to a production system, pointed at the development system instead.

The failure mode at every level below L4 is the same one, and it is worth stating plainly because it is the quiet default. The default is no owned framework at all. Each developer configures their own agent context, their own rules, their own sense of what good looks like, and the team calls that AI adoption. It is activity. It is ten people getting individually faster at producing artifacts inside no shared system, which means the artifacts do not compose, the quality varies by whoever configured their setup that week, and the org cannot tell why high tool usage produced flat delivery. The architect is the answer to that question. The shared framework is the thing that was missing.

A framework is not finished when the files exist

It needs lifecycle ownership. Who reviews new context rules, who removes stale ones, who approves new MCP servers, who watches false-positive rates on hooks, who tracks agent cost and success rate per project, and who decides when a rule moves from advisory to enforced. The architect designs the framework. Lifecycle ownership of it, design, adoption, maintenance, security review, metrics, evolution, is the work that keeps it from drifting into a stale wiki with shell access. Without that lifecycle, the framework decays the same way any system decays when nobody owns its evolution.

Pitfalls: how the architect's AI framework goes wrong

The failure modes here are specific, and naming them is cheaper than rediscovering them.

Treating the framework as a folder of config. The CLAUDE.md files, the agents, the hooks get set up once and then never revisited as a system. They drift. New conventions never make it into the context layers, retired rules keep firing, and the framework slowly stops matching the project. A framework is a designed system with failure modes, and like any system it needs an owner who treats its structure as architecture, not a one-time setup task.

A framework nobody uses. The architect builds a beautiful agent chain, writes the onboarding guide, and the team keeps working the way it always did. Adoption is not configuration. A framework that exists but is not used is worth exactly nothing, and the architect's L3 job is explicitly the adoption work: the live demos, the troubleshooting, the iteration based on what actually trips people up. The hook that triggers thirty false positives a week does not get defended. It gets fixed, or the team routes around the whole framework.

Permission boundaries decided per developer. When each engineer sets their own agent permissions, the team's actual security posture is the loosest setting anyone chose. One person's agent allowed to run shell commands without confirmation is the team's risk, not that person's. Permission boundaries are a framework-level decision precisely because they only work when they are consistent, and consistency is something a designed system provides and improvisation does not.

The unowned shared framework where everyone improvises. This is the meta-pitfall, the one the whole article circles. When nobody owns the framework, it does not cease to exist. It exists in ten incompatible private versions, and the cost surfaces later as inconsistent quality, work that does not compose, and an adoption story that cannot explain why the numbers stayed flat. The fix is not more tools. It is naming the role that owns the system, and that role is the architect.

Key takeaways

• The architect's highest-leverage deliverable on an agentic team is the configured AI development framework, not the architecture document. The framework is what every other role's agents operate inside.
• The CLAUDE.md hierarchy is context architecture, a designed multi-layer system, not a folder of config. Root context loads always, directory-scoped context loads in place, path-scoped rules settle what agents should never have to reason about.
• Agent chains and quality gates are the operating diagram for agentic delivery. Designing which agent owns which files, with hooks enforcing the boundaries, is boundary-and-ownership design pointed at a workflow of agents.
• Governance built into the framework through agent permission boundaries and security hooks is continuous and survives a busy quarter. Governance bolted on as a review gate is the first thing skipped under deadline.
• The default failure mode is no owned framework at all: ten private setups, flat delivery, and an adoption story that cannot explain itself. The architect is the role that closes that gap.

What this means for how the architect's role is designed

The redesign is not a new tool to learn. It is a relocation of where the architect's value sits. The work that used to be the deliverable, the diagram, the design doc, the ADR, is still produced, but it is increasingly produced inside a system, and designing that system is the work that now compounds. An architect who keeps measuring their value by the artifacts they personally author will look busy and feel the leverage drain away. An architect who claims the framework as their architecture, and treats the CLAUDE.md hierarchy, the agent chains, the quality gates, and the permission boundaries with the rigor they have always brought to a service boundary, becomes the person who makes the whole team's AI-assisted work cohere.

Concretely, that ownership reads like four expectations for the role, the way a job description would name them. Context architecture: deciding what belongs in the root instructions, what belongs in subsystem context, what must never be trusted to a model instruction, and what has to be enforced by CI, hooks, permissions, or tests. Agentic workflow boundaries: which agent owns which phase, which files each phase may touch, what a human must review, which gates block and which only warn, and where an agent's output becomes the source of truth. Quality gates: the architectural checks the framework runs by default, from NFR, security, and dependency scanning to API-contract validation, data-boundary rules, and do-not-touch-this-layer constraints. And governance by design: not "please remember the rule" but a framework that blocks or flags the violation, so compliance is a property of the system rather than a hope pinned on late review. None of these is new to the architect. Each is a discipline the role already owns, pointed at the delivery system and not only the product system.

That is also where this connects back to the operating model. A team's AI-development operating model is not real until someone has architected the system it runs on. The other roles redesign their own work. The architect owns the coherence of the shared framework, the quality infrastructure, and the agent boundaries that all of them run inside, even where building and operating individual pieces is shared with Platform, DevEx, and Security. When a CTO asks whether the AI rollout actually changed how the team delivers, the honest answer depends on whether anyone owned that framework, or whether the team just got individually faster inside no system at all. The architect is the role that determines which of those two stories the org gets to tell.

Frequently Asked Questions