Instructions as Architecture: How I Give Claude Long-Term Context That Sticks
Most instruction docs are written like a to-do list. The ones that hold up are designed like a building.
CLAUDE.md (or AGENTS.md if you’re working in ChatGPT/Codex) is one of the most important files in your system. It’s critical for you to understand what to put in there vs. what not to put in that file.
Dheeraj explains it really well as to why it’s important to set it up properly. Best thing is - he goes a layer deeper. Yes, rules are important, but Dheeraj says that there is another layer underneath the rules that can set you up for success.
Most instruction docs never have it.
Just a pile of corrections on top of older corrections. No foundation. No way to tell what was load-bearing and what was leftovers from a project that ended months ago.
I really like how Dheeraj compares this to the infrastructure of a house. Foundation, load-bearing walls, wiring, rooms you renovate. Once you see it that way, the mistake is obvious:
Most people are decorating a building with no structure underneath.
That's what he's writing about. And it changes how you think about every instruction document you'll ever write for Claude or ChatGPT.
Dheeraj Sharma runs GenAI Unplugged, where solopreneurs and small teams learn to build real AI systems.
This is Dheeraj’s 2nd guest post for Prosper, his first one is here:
It's the most useful one for anyone who's ever written a system prompt, a CLAUDE.md, or a set of custom instructions.
Now let's dive in!
Hey all, Dheeraj is here!
Every AI system has one document that nobody respects until the day it fails.
It goes by different names. A project’s context file. A system prompt. A set of custom instructions. The onboarding doc you paste at the top of a new chat.
Whatever you call it, it is the closest thing an AI system has to institutional memory. It is the only place where “how we do things here“ gets written down once instead of re-explained every session.
And most people write it like a grocery list. A flat pile of rules.
Always use this format.
Never do that.
Keep the tone friendly.It works in the demo. Then the work gets real, the rules pile up, they start to contradict each other, and the quality quietly drifts. The document that was supposed to be your memory becomes the thing you stop trusting.
Why it matters
I have written a lot of these. Across 75-plus articles and several agents that run my content operation, the instruction document is the single most valuable thing I maintain.
When it is good, Claude makes decisions I would have made. When it is bad, I spend my day correcting output that technically followed the rules and still missed the point.
The difference is not better rules. It is treating the document as architecture instead of a to-do list.
Rules versus architecture
A to-do list tells you what to do in cases someone already thought of. Architecture tells you how the whole thing is supposed to hold together, so you can make a good call in a case nobody listed.
Think about an actual building.
The architecture is not a list of “put a chair here, a lamp there.“ It is the foundation, the load-bearing walls, the way the rooms connect, the wiring that makes it all work.
Those decisions determine what the building can become. You can rearrange furniture forever, but if the structure is wrong, no amount of decorating saves it. Instruction documents work the same way.
The people getting generic, drifting output are decorating. They keep adding rules, tweaking phrasing, bolting on one more “always remember to.“
The people getting output that sounds like them, session after session, have built a structure underneath the rules.
Here is the structure I think in terms of:
Foundation: identity and principles. Who this is for, what we value, how we decide. This rarely changes.
Load-bearing walls: the non-negotiable constraints. Remove one and quality collapses.
Rooms: task-specific guidance. Added and remodeled as the work changes.
Wiring: examples of good and bad that make everything else usable.
Once you see the Claude.md or Agents.md document this way, the common mistakes become obvious. They are all structural failures, not wording problems.
The five mistakes most people make
1. They write rules instead of principles.
A rule covers one case. A principle covers the cases you did not foresee. Side by side:
RULES (brittle) PRINCIPLES (general)
- Never start a sentence with - Write the way you talk. Prefer
“However”. plain connectors over formal ones.
- Always use “we”, not “I”. - Speak from the team’s voice unless
a story is explicitly personal.
- Headers must be sentence case. - Headers describe what the section
delivers, not what it covers.The right column survives cases you never thought to write a rule for. The left column breaks the moment the real work is one inch off your examples. Lead with the principle, then use a rule or two as illustration. Not the other way around.
2. They mix permanent context with temporary context.
This is the most common rot I see. The foundation (who you are, what you value) gets written in the same place as this week’s task notes (”we are currently focused on the launch, ignore the older drafts“).
Three weeks later the launch is over, the note is stale, and it is sitting two lines above the principles that are supposed to be permanent. Now the whole document is suspect, because you cannot tell at a glance what is load-bearing and what is leftover.
Keep the things that never change far away from the things that change weekly. They have different lifespans and they do not belong in the same room.
3. They describe instead of demonstrate.
“Use a confident, concrete tone“ means nothing on its own. Confident to whom? Concrete compared to what?
An instruction document without examples is asking Claude to guess at your taste, and it will guess wrong in exactly the ways that are hardest to correct.
One short “here is good, here is bad, here is why“ does more than a paragraph of adjectives. Like this:
DESCRIBE (does not work)
“Write in a confident, concrete tone.”
DEMONSTRATE (works)
“Write in a confident, concrete tone.
- Bad: This can help leaders unlock their potential.
- Good: This cuts your weekly review prep from 3 hours to 30 minutes.
- Why: A measurable change anchors the claim. ‘Potential’ anchors nothing.”Examples are the wiring. They are what turn a description into something the model can actually act on.
4. They overbuild.
More context feels safer. It is not. Every line you add is a line Claude has to weigh, and past a certain point you are not adding signal, you are adding noise that competes with the signal.
I have watched a context document get worse because someone kept feeding it everything they could think of, until the three decisions that mattered were buried under forty that did not.
The discipline of deciding what Claude truly needs to know, and cutting the rest, is harder than adding more. It is also where most of the quality lives.
5. They pour it once and abandon it.
People treat the document like concrete. Write it at the start of a project, never look at it again. But architecture that is never maintained is how you get a building with rooms nobody uses and wiring nobody understands.
The instruction document should change as you learn what Claude keeps getting wrong. Every time I catch myself giving the same correction twice, that correction is a missing wall, and it goes into the document.
The doc is a living structure, not a launch artifact.
The structure I use
You do not need my exact layout. You need the shape. Mine has four parts, and they map directly onto the architecture.
1. Identity and principles (the foundation).
A few sentences on who this is for and what we are trying to do, then the principles that drive decisions. Not rules. The reasoning behind the rules. This is the part that lets Claude handle a situation I never anticipated, because it can reason from the same place I would.
2. Non-negotiables (the load-bearing walls).
The short list of things that are never up for debate. For me that includes hard voice constraints and a few format rules that protect the brand. These are deliberately few. If everything is load-bearing, nothing is, and the model cannot tell what to protect when there is a tradeoff.
3. How I work, with examples (the wiring).
The patterns, each paired with a concrete demonstration. This is the largest section and the one that does the most work, because it is where abstract principles become things Claude can copy.
4. A living section (the rooms).
Current focus, what is active right now, what changed recently. This is the only part I expect to edit often, and because it is fenced off in its own section, editing it never threatens the foundation.
The whole point of separating these is lifespan. The foundation should look almost the same in six months. The living section should look different next week. When they live in different rooms, you can renovate one without bringing down the other.
Here is what that looks like in skeleton form. Four labeled parts, real text, ready to fork:
# Project: Acme content operation
## Identity and principles (the foundation)
This document directs Claude on every piece of content for Acme. We write for
content-led solopreneurs. Decisions favor specificity over cleverness, evidence
over claims, and the reader’s next action over impressive prose.
## Non-negotiables (the load-bearing walls)
- No em-dashes. Use periods, commas, or line breaks.
- Every quantified claim cites its source on the same line.
- Never promise an outcome we cannot show.
## How we work, with examples (the wiring)
### Voice
- Bad: This revolutionary tool will transform your workflow.
- Good: This cuts the weekly digest from 3 hours to 30 minutes.
- Why: concrete change with a number; no superlatives.
## Living section (the rooms)
Last edited: 2026-05-28
Current focus: Q2 launch sequence
Recent corrections:
- 2026-05-12: stopped using “unlock” as a verb. It signals hype without content.Each section has a clear lifespan, a clear job, and at least one concrete example wherever there is a claim about taste. Drop this into a CLAUDE.md, a system prompt, or a Claude Project’s custom instructions box. Same shape, any tool.
The test
Here is the single question I use to tell whether a document is architecture or a to-do list.
Could a brand-new collaborator, someone who has never worked with you, make a decision you would be happy with on a case that is not explicitly covered, using only this document?
If yes, you built architecture. You encoded how you think, not only what you want, and that generalizes.
If they would freeze the moment they hit something you did not list, you wrote a to-do list. It will work right up until the work surprises you, which it always does.
Here is the test in action.
The scaffold above never mentions writing for kids. A new collaborator gets the brief: a one-pager aimed at 10-year-olds.
The foundation says decisions favor specificity over cleverness and the reader’s next action over impressive prose. The non-negotiables ban superlatives and require evidence on the same line.
From those two principles alone, the collaborator knows: avoid hype words a 10-year-old will skim, anchor every claim in something a child can picture, end with one thing they can do today.
The doc never said “for kids,” but the principles produced a good call. That is architecture working.
That test is also why this matters more for AI than for humans. A new human hire fills the gaps with judgment and asks you when they are unsure. Claude fills the gaps with whatever the document implies.
So the quality of your implied structure is the quality of your output on every case you did not foresee, which is most of them.
Build the structure once, decorate forever
The instruction document is not the boring setup step before the real work. For anything you do repeatedly with Claude, it is the real work. It is where you decide, once, how good your output is allowed to be when you are not watching.
Write it like architecture. A foundation that rarely moves. A few walls that hold everything up. Wiring made of real examples. Rooms you renovate as you learn. Then maintain it like a building you live in, because you do.
If you want the take-home version, the scaffold I use as the starting point for every new project’s instruction document is here.
About eighty lines, four labeled parts, principles instead of rules, examples for every claim about taste, ready to fork into a CLAUDE.md, a system prompt, or a Claude Projects custom-instructions box.
Get the Instruction Document Scaffold
The system-level version of this thinking, how a set of instruction documents and small single-job agents run a real content operation end to end, is what I document at GenAI Unplugged.
 | A guest post by
|
Thank you Ilia for giving me this opportunity to share it with audience of Prosper. The article has come out well and I hope everyone learn to put this in practice.
This is so helpful, Dheeraj. Thank you 🙏 Very generous of you and Ilia!