The Habitat Hypothesis
Why every AI (and human) coding failure is an environment problem
This is Part 1 of a 6 part series on Harness Engineering as part of Habitat Thinking to accompany the open source AI Literacy Superpowers plugin
(docs, repo).
It’s Tuesday afternoon. You’re pairing with your AI coding assistant, and you ask it to add a new endpoint to your API.
It comes back with code that:
Uses CamelCase when your entire codebase is snake_case
Puts the route handler in a file called
utils.py(your team has a strict controller pattern)Skips input validation entirely
Uses a database connection pattern you deprecated six months ago
You stare at the diff. You highlight the whole thing and delete it. You mutter something unprintable. And then you do what everyone does: you open a new chat, write a longer prompt, and try again.
What you did next was wrong.
Not the deleting part. That was fine. The trying again with a better prompt part. That’s the wrong fix, and it’s the wrong fix almost every time.
The Wrong Diagnosis
When AI produces bad output, we reach for one of three responses:
Write a better prompt. More detail. More examples. A twelve-paragraph system message that reads like a legal contract.
Switch to a better model. Maybe GPT-4 will get it. Maybe Claude will get it. Maybe the next release will get it.
Give up on AI for “real work.” Use it for boilerplate and throwaway scripts, but keep it away from anything that matters.
All three treat the AI as the variable. The model is too dumb. The prompt wasn’t specific enough. The technology isn’t ready yet.
We sometimes treat humans the same way…
The AI is not the lever. The environment is the lever.
Brain check: Before you read the next section, ask yourself — when a new developer joins your team and writes code that doesn’t follow your conventions, do you blame the developer? Or do you look at your onboarding materials, your code review process, and your documentation?
The Hypothesis
Here it is, the claim this entire series, and the AI Literacy Superpowers plugin, is built on:
The quality of AI-generated code is a function of the environment, not the model.
A mid-tier model operating inside a well-designed environment — one with clear conventions, enforced constraints, and architectural context — will consistently outperform a frontier model dropped into a bare repository with nothing but a README that says “TODO.”
You just read that and your brain filed it under “obvious.” It is not obvious. If it were obvious, you wouldn’t be writing twelve-paragraph prompts. You’d be fixing your repo. So let me say it differently:
The environment is the product. Not the model. Not the prompt. The environment.
When you invest in prompt engineering, you’re optimising a single interaction. When you invest in environment engineering, you’re optimising every interaction from now on.
One of those compounds. The other doesn’t.
But What IS an “Environment”?
When most people hear “environment,” they think of their IDE, their terminal, maybe their .env file. That’s not what we mean.
The development environment is the total context available to your AI agents and humans when working in your codebase:
Conventions — naming patterns, file structure, preferred and banned patterns
Constraints — rules that are enforced, not just documented. Linting rules. Pre-commit hooks. CI checks that reject non-conforming code before it merges
Architectural decisions — the why behind your code structure. Why you chose this database. Why that function exists even though it looks redundant
Accumulated knowledge — what mistakes were made and corrected. What patterns emerged over time
Feedback loops — mechanisms that catch problems and prevent the same mistake from happening twice
Most teams have none of it explicitly available to their people or AI tools.
They have it in their heads. They have it in Slack threads from 2023. They have it in PR comments that nobody will ever read again. But they don’t have it anywhere the AI can see.
And then they wonder why the AI doesn’t know their conventions.
The Sceptic: “This sounds like a lot of overhead. I just want the AI to write code faster. Now you’re telling me I need to build an entire knowledge base first?”
The Pragmatist: “You already have the knowledge base. It’s in your head. The overhead is making it explicit. Which, by the way, also helps every new human teammate you’ll ever onboard.”
The Sceptic: “...”
The Pragmatist: “Yeah. It’s the same problem.”
The Kitchen That Cooks For You
Christopher Alexander spent his career studying how environments shape behaviour. His central insight: a well-designed environment makes the right behaviour natural and the wrong behaviour difficult.
Think about a well-designed kitchen. The knives are where you reach for them. The spices are at eye level near the stove. The rubbish bin opens with a foot pedal so you can use it with full hands. You don’t need a manual for this kitchen. The design teaches you.
Now think about a badly designed kitchen. The knives are in a drawer across the room from the chopping board. The salt is in a cupboard above the fridge. The bin is behind a door. Every meal requires more effort, more mistakes, and more frustration. Not because you’re a bad cook, but because the environment is fighting you.
Your codebase is a kitchen. Your AI agents are some of your cooks. And right now, most of us have the salt above the fridge.
When your AI writes code that doesn’t follow your conventions, it’s not because the AI is stupid. It’s because your conventions aren’t in the environment. They’re in your head, in a wiki nobody reads, in tribal knowledge passed down through code review.
The AI can’t read your mind. But it can read your environment.
Exercise — A two-minute audit: Open the root of your main project right now. Pretend you’re an AI assistant that’s just been dropped into this codebase for the first time. What do you know? What conventions are written down? What architectural decisions are documented? What constraints are enforced automatically versus relying on human reviewers to catch?
If the answer is “not much” you’ve just diagnosed why your AI output isn’t great.
A Fireside Chat: The Model vs. The Environment
The Model: Look, I’m doing my best here. You dropped me into a repository with 400 files, no documentation, and a prompt that says “add a payment endpoint.” What do you expect?
The Environment: That’s exactly my point. You’re a pattern-completion engine. You complete patterns based on context. When the context is thin, you fall back on generic patterns from your training data.
The Model: Which is pretty good! I’ve seen millions of codebases.
The Environment: You’ve seen millions of average, other codebases. So when you get no specific guidance, you produce average code. That’s not a flaw. That’s exactly what pattern completion should do. But this team doesn’t want average. They want their patterns.
The Model: So tell me what they are!
The Environment: That’s what I’m for. When I’m well designed, I give you conventions, constraints, and feedback loops. I turn you from a generic code generator into a teammate that understands this project.
The Model: And when you’re not well designed?
The Environment: Then people blame you. They upgrade to a more expensive version of you. They get the same generic output with slightly better grammar. And they never question whether the bottleneck was me all along.
There Are No Dumb Questions
Q: Does this mean prompting doesn’t matter at all?
A: Prompting matters. But it’s single-use. A great prompt helps one interaction. A great environment helps every interaction. Prompting is giving directions to a taxi driver. Environment design is building the roads.
Q: Won’t better models eventually solve this?
A: Better models will get better at working with whatever context they’re given. A better model in a great environment will be extraordinary. A better model in a bare repo will still produce generic code. The environment advantage doesn’t disappear as models improve. It compounds.
Q: Isn’t this just “documentation”?
A: Documentation is one input. But documentation that isn’t enforced is a suggestion. The environment includes enforcement. Constraints that catch violations automatically, feedback loops that learn from mistakes, and context structured so the AI can actually use it. A wiki page about naming conventions is documentation. A pre-commit hook that rejects bad names is environment.
What’s Coming
Over the next five articles, we’ll build up what a well-designed AI development environment actually looks like. From making your conventions machine-readable (Article 2), to constraints that enforce themselves without human reviewers (Article 3), to multi-agent pipelines that create defence in depth (Article 4), to environments that get smarter with every session (Article 5), and finally the full integrated system (Article 6).
Each article moves from concept to practice. No theory without action.
But for now, you have the hypothesis. And you have the two-minute audit. That’s enough to start.
The Bullet Points
For us humans, here’s a summary.
The common instinct — when AI writes bad code, we blame the model, write longer prompts, or give up on AI for serious work.
The wrong diagnosis — all three responses treat the AI as the variable, but the AI is a pattern-completion engine working with whatever context it has.
The environment hypothesis — the quality of AI output is a function of the environment, not the model. A well-designed environment with a cheaper model beats a bare repo with a frontier model.
What “environment” means — conventions, constraints, architectural context, accumulated knowledge, and feedback loops.
The key shift — stop investing in single prompts. Start investing in the environment. One compounds. The other doesn’t.
Next in the series: “Engineering Context: Teaching Your AI What You Know” where we get specific about making your conventions and context available to your AI assistant.