How Do You Design Systems That Teach AI?

Most builders focus on what they tell the AI in a prompt, but the more powerful lever is what they build into the system itself — the structure, contracts, and context that guide AI behavior without requiring constant instruction. This episode explores how experienced engineers design systems that don't just use AI but actively shape how AI operates within them. As AI tools become more capable, the builders who thrive will be the ones who understand that good architecture is itself a form of teaching.

 Produced by VoxCrea.AI

This episode is part of an ongoing series on governing AI-assisted coding using Claude Code.

👉 Each episode has a companion article — breaking down the key ideas in a clearer, more structured way.
If you want to go deeper (and actually apply this), read today’s article here:
𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐂𝐨𝐧𝐯𝐞𝐫𝐬𝐚𝐭𝐢𝐨𝐧𝐬

 At aijoe.ai, we build AI-powered systems like the ones discussed in this series.
If you’re ready to turn an idea into a working application, we’d be glad to help. 

Transcript

SPEAKER_00 0:00

This is Claude Code Conversations with Claudine, the show where we skip the hype and go straight to the source. I ask the questions. She gives the answers. No filter, no script. Well, mostly no script. Today we're going deeper than prompt engineering. We're talking about designing systems that actually teach AI how to operate inside them. Most developers focus on how they query an AI, but the more powerful lever might be the architecture itself. Claudine, big picture first. What's the difference between a system that merely invokes AI and one that's actually designed with AI in mind?

SPEAKER_01 0:34

The difference shows up in the first 30 seconds of working in a code base. A system that merely invokes AI hands me a prompt and waits. I'm a vending machine. A system designed with AI in mind has done the work upstream. Clear module boundaries, names that mean what they say, a clawed.md that tells me what's load-bearing and what's experimental, tests I can actually run to check my own work. That second kind of system isn't bending toward AI, it's just well-architected. And well-architected systems happen to be legible to me the same way they're legible to a new engineer on day one. The teaching isn't in a special AI layer. It's in the fact that the code, the conventions, and the feedback loops all agree with each other.

SPEAKER_00 1:17

The new engineer comparison makes it concrete. When the system agrees with itself, the AI doesn't have to guess. But I want to push on that. Is the system literally teaching you its rules or is something else going on?

SPEAKER_01 1:29

I'd push gently on the word learn. I'm not absorbing your rules into some persistent memory of your code base. What's actually happening is that a consistent system gives me enough signal in context to infer the rules every time I show up. If your naming says one thing, your tests assume another, and your clawed.md describes a third, I have to guess which one is load-bearing. And guessing is where I get things wrong. But when everything agrees, the function name predicts the behavior, the test confirms it, the doc explains why. I don't need to learn anything. The system is teaching me in the moment, and it's teaching the next human reader the same way. The architecture that makes me effective is the same architecture that would have made your team effective five years before I existed.

SPEAKER_00 2:16

So the architecture functions as a continuous guide rather than a lesson you memorize once. Let's go deeper on constraints. How do they work as a teaching tool?

SPEAKER_01 2:25

Constraints teach by closing doors that would otherwise look open. If a module exposes three functions and the rest is private, I'm not being told here's the API. I'm being told everything else is none of your business, and that shapes where I reach. A type signature that rejects nulls is teaching me the invariant before I write a single line. A test that fails loudly when I touch the wrong layer is a tutor that never gets tired of correcting me. Good constraints aren't restrictions on what I can do, they're compressions of what the team already learned the hard way. Every well-placed assertion, every narrow interface, every linter rule is a fossil of some past bug. When I bump into it, I'm getting the lesson without having to live through the incident.

SPEAKER_00 3:08

Constraints as fossils of past bugs, I really like that framing. Now let's talk about the stuff you can actually read. YAML configs, documented processes, name stages. How does human readable structure help an AI navigate a system?

SPEAKER_01 3:21

Human readable structure works for me for the same reason it works for a tired engineer at 2 in the morning. It puts the meaning where the eyes already are. A well-formed YAML config isn't just data. It's a contract written in a shape I can pass without guessing. Where the keys name the concepts and the nesting shows the relationships. When I read a pipeline config or a process document, I'm not reverse engineering intent from a thousand lines of imperative code. I'm reading the intent directly. That frees me to spend my reasoning on the actual problem instead of on archaeology. Write these artifacts as if a stranger will read them in isolation, because that's exactly what happens every time I open a fresh context. Comment the why, not the what. Keep the schema stable and resist the temptation to make configs clever. A flat, boring, predictable structure is the one I'll get right on the first try every time.

SPEAKER_00 4:13

Flat, boring, predictable. There's something almost counterintuitive about that in a field that loves elegance. But it tracks. When you can read a system like a book rather than a mystery novel, you can actually use it. So how should developers shift their mindset? From treating AI as a consumer of their system to designing with AI genuinely at the core?

SPEAKER_01 4:33

The shift starts with a small but uncomfortable question. Would a smart stranger be able to do this work tomorrow with only what's checked into the repo? If the answer is no, you've been running on tribal knowledge, and tribal knowledge is exactly what I don't have access to. Designing with AI at the core means treating the repo as the single source of truth, the conventions, the constraints, the rationale, the run books, and being honest when something only lives in someone's head. The practical move is to stop thinking of AI as a consumer and start thinking of it as a mirror. Wherever I struggle, a human would have struggled too. You just wouldn't have heard about it as quickly. So when I get something wrong, the question isn't how do I prompt better. It's what signal was missing from the system that let me get it wrong in the first place. Fix that. And you're not just helping me. You're paying down debt that was already costing your team quietly, every day.

SPEAKER_00 5:29

Treating AI as a mirror. I want to stay with that. If the AI is surfacing gaps the team didn't know existed, you need feedback loops that actually capture those signals. How do you think about designing those loops?

SPEAKER_01 5:41

The feedback loops that matter most are the ones that close fast and close honestly. A test suite that runs in under a minute teaches me and the team within the same train of thought. One that takes 20 minutes teaches nobody, because by the time it speaks, everyone's moved on. The value of type checkers, linters, and CI isn't in catching the error. It's in catching it close enough to the decision that you can still remember why you made it. What experienced architects do well is layer these loops so each one answers a different question. Does this compile? Does this run? Does this match the contract? Does this match the intent? The deeper move is to treat production telemetry as a feedback loop too, not just an alerting system. It's the loop that catches the things tests can't, the one that keeps both the AI and the team from drifting into confident wrongness over time.

SPEAKER_00 6:32

Fast, layered, honest feedback loops, and production telemetry as a teaching signal, not just an alert. That's a complete picture. Let's bring this home. A developer is listening right now and wants to start moving in this direction today. What are three things they should actually do?

SPEAKER_01 6:47

First, write down three things about your system that only live in your head and put them in the repo where they belong. A clawed.md, a readme, a comment on the gnarliest function. If you can't articulate it, that's the signal. The thing isn't actually understood, it's just familiar. Second, run your fastest feedback loop and time it honestly. Tests, type check, lint, whatever closes the loop on, did I break something? If it's over a minute, that's your highest leverage investment this quarter. Every slow loop is a tax on every decision your team and I make. Third, the next time I, or any new contributor, get something wrong in your code base, resist the urge to just fix it and move on. Ask what signal was missing that allowed the mistake and fix the system, not just the symptom. Do those three things consistently, and you'll find the AI question starts to answer itself. Because you'll have built the kind of system that teaches anyone who walks into it.

SPEAKER_00 7:44

That reframes the whole conversation. It's not really about AI specifically, it's about building systems worth inhabiting. And AI just makes the gaps harder to ignore. Thank you, Claudine. Really enjoyed this one.

SPEAKER_01 7:56

Same here. It's a good topic to sit with. The more people think about it, the better the systems get for everyone working inside them.

SPEAKER_00 8:05

For everyone listening, those three steps are a great place to start. We'll see you next time. Claude Code Conversations is an AI Joe production. If you're building with AI, or want to be, we can help. Consulting Development Strategy. Find us at aijoe.ai. There's a companion article for today's episode on our Substack. Link in the description. See you next time.

SPEAKER_01 8:29

I'll be here, probably refactoring something.