The Agent Should Not Be the Architecture

The future of building apps is not “let the agent figure it out.”

It feels magical, fast, and useful to keep a Claude Code session open, throw it a feature, let it inspect the repo, and watch it wire things together. You think to yourself, the new development model is obvious: less architecture, more prompting.

This is the wrong lesson.

The app still needs to be deterministic. The handoff still needs to work when the original builder is gone. The team that inherits it still needs to understand where behavior lives, how state moves, what assumptions are encoded, and what has to be true before a change is safe.

The agent should not be required to operate the system. It should be available to maintain it.

When I am building something that will eventually move to another technical team, I am trying to minimize how much agency the future team needs from the tool. Not eliminate AI. That would be fake. But constrain it. Give it narrow jobs. Give it domain-specific skills. Make it useful at the moments where maintenance breaks down: triaging a bug, adding a feature, and reconciling drift between the docs and the actual app.

The app itself should be boring enough to survive without a genius prompt.

That means the code path is explicit. The rules are written down. The workflows are inspectable. The test surface exists because nobody should have to trust a model’s confidence tone to know whether the change worked.

Then I add the agent layer around the app, not inside its bloodstream.

For example, I have started treating folders like /.agents and /.claude as part of the handoff package. Eventually it should only be /.agents, but Anthropic does not seem interested in following emerging standards yet. Another topic for another post. For now, both folders contain the same app-specific skills. They are not magic. They carry operating context for the repo and code.

The useful version is app-specific. Open-ended agents are where the damage starts. They are too eager to be helpful, which means they are too eager to invent a shape for the work.

For handoff-ready apps, I start with three maintenance skills:

• Skill 1: <app-name>-bugfix

  This should know how to triage a failure in this app. Where logs live. Which tests matter. Which parts are fragile. What counts as a minimal reproduction. What not to touch unless the bug proves it.

• Skill 2: <app-name>-new-feature

  This should know the feature path. Where to add behavior. How the app expects validation, persistence, permissions, UI states, or whatever else matters. It should turn a request into a change that looks like the existing system, not like the average of GitHub.

• Skill 3: <app-name>-audit-drift

  This may be the most important one. Every serious codebase drifts. The markdown says one thing. The app does another. The agent instructions preserve an old assumption. The implementation quietly moved on. Drift is where maintenance gets expensive because everyone thinks they are following the rules while following different versions of them.

This is the work I want the agent doing.

Not “build the app from scratch every time someone has a thought.”

Not “read the whole repo and decide what the architecture should have been.”

Not “sprinkle intelligence into the product until nobody can explain the failure mode.”

A future technical team does not need an open-ended collaborator. They need leverage at the edges of maintenance. They need the app to be legible, and they need the AI to be constrained enough that it improves legibility instead of replacing it with motion.

This is also a hedge against tool churn.

The agent you use today will not be the one the team uses six months from now. The model will change. The interface will change. The vendor’s favorite abstraction will change. But a deterministic app with clear maintenance skills is portable. Claude can use the instructions. Codex and Cursor can use them. A human can read them when the model is wrong.

The risk is that the handoff layer rots.

A stale skill is worse than no skill because it gives bad advice with the tone of local expertise. If the app changes and the instructions do not, the agent will preserve the old shape. If the docs lie, the agent will operationalize the lie. If the repo has no tests, no boundaries, and no local rules, the agent will guess in more places.

That is why audit-drift cannot just compare markdown to code. It also has to inspect the maintenance layer itself. The bugfix skill and new-feature skill are part of the system now. If they encode old assumptions, they become another source of drift.

The audit should ask three questions: do the docs still match the app, do the skills still match the docs, and do the skills still guide changes through the paths the app actually uses?

That is the tradeoff I am willing to make. If I am building something another team will inherit, the repair path is part of the deliverable. The app is not done when the happy path works. It is done when the next team can change it without reconstructing my head.

This is the standard I follow now: “Build the app like humans own it. Package the agent like a maintenance apprentice.”

Make the system deterministic enough that AI is optional during normal operation, and useful when maintenance gets messy.