The Curator of Affordances
Context engineering isn’t writing commandments. It’s shaping the environment so the correct action is the easiest action.
Le Bon Mot always smelled faintly of bergamot and book glue, as if someone had tried to perfume a library into forgetting it was built from dead trees.
The café sat in an alley that insisted on being called a lane made up loosely of cobbles, ivy, and a small brass bell above the door that rang like a polite accusation. Inside, the shelves were arranged with the careful cruelty of a labyrinth designed by someone who’d read Borges and then decided the only thing missing was a decent espresso machine.
Case, retired developer, still carrying herself like a well-factored function, stood at the counter and watched the barista pour a flat white with the ceremonial gravity of a priest handling relics. On the wall behind the pastries was a chalkboard menu. Not the usual list of beverages, but a list of rules.
Do not reshelve your own books.
Never trust a label that says “final.”
The map is not the café.
Ask yourself what the environment is making easy.
If you see a door marked “Context,” knock twice.
“Is this… new?” Case asked.
The barista smiled the way systems smile when they’re about to fail quietly. “The café updates itself,” he said. “Like a dependency. Sometimes with breaking changes.”
Case received her coffee, a receipt, and unexpectedly a slim card bearing a single sentence in tasteful serif:
CLAUDE.md is not documentation. It is environmental shaping.
The card also contained directions to the Context Room, written in an ink that looked suspiciously like the residue of printer toner. She had been in Le Bon Mot long enough to know that the café did not give you directions unless it intended to take something back.
The Context Room was not on any directory, and that was, Case suspected, part of the point.
You found it by accident, after passing the section for “Books That Explain Things Too Well,” then the alcove of “Memoirs of People Who Should Have Kept Journals,” then a corridor labelled “This Way to the Exit” which, as expected, led deeper in. At last there was a door. Brass plate. Simple lettering.
CONTEXT
No handle. Just a small knocker shaped like a question mark. Case knocked twice. The door opened as if it had been listening all along.
Inside was a room that looked like a room only in the sense that a dream looks like a city: plausible angles, familiar textures, and a logic that began unravelling as soon as you tried to measure it. Shelves lined the walls, but instead of books they held files; thin, plain folders, each stamped with the same title.
CLAUDE.md
Hundreds of them. Thousands, perhaps. Stacked and sorted by an unknown taxonomy. A faint rustle filled the room, as if paper were sighing.
At a long oak table sat a person who might have been a librarian except for the fact that librarians rarely glow with quiet menace. She wore round glasses, had a pencil tucked behind one ear, and a posture that suggested she had been trained in the ancient art of refusing nonsense without raising her voice.
She looked up. “You’re late.”
“I didn’t know I was coming,” Case said.
“That’s how most people arrive in this room,” the librarian replied. “They come for context, and then they wonder why they can’t find the door back to simplicity.”
A name tag on her cardigan read:
THE CURATOR OF AFFORDANCES
Case sat opposite. “I got a card,” she said, sliding it across.
The Curator read it, nodded, and slid it back. “Yes. A reminder. People treat these files here like documentation. They think they’re writing notes. But they’re building a habitat.”
Case sipped her coffee. “We’re talking about the CLAUDE.md files for AI-assisted coding,” she said. “Guidance for the agent. Constraints. Preferences.”
“Preferences,” echoed the Curator with mild disdain, as if the word had tracked mud onto her carpet. “Say ‘constraints’ again. It has better bones.”
Case leaned in. “I’m trying to do it properly. Engineering context. Making the environment shape behaviour. The agent does better work if you give it rails.”
The Curator folded her hands. “Rails are helpful,” she said. “But they are only a part of the story.”
A silence settled. Somewhere behind them, folders whispered.
The Curator gestured to the shelves. “Pick one,” she said.
Case reached toward the nearest folder and pulled it out. The paper felt oddly warm. She opened it and found a single page of text, typed and neatly arranged.
CLAUDE.md (v1)
Use British English.
Follow our coding standards.
Don’t touch production.
Be helpful.
Be safe.
Keep responses short.
Case smiled. “Seems fine.”
The Curator smiled back, which is never a good sign. “Read it aloud,” she said.
Case did, feeling faintly silly. When she finished, the page sighed. Actually sighed. Paper making a sound like a weary manager.
“What’s wrong with it?” Case asked.
“It’s a list,” said the Curator. “A moral pamphlet. It tells the agent what you like, but not what your habitat enables. It reads like a sign in a kitchen that says ‘Clean as you go’ while leaving the sink full of knives.”
Case frowned. “But we also have actual tooling. Tests. Policy-as-code. CI.”
“Excellent,” said the Curator. “Then your CLAUDE.md can stop pretending it’s the only adult in the room.”
She leaned forward. “Context engineering isn’t writing commandments. It’s shaping the environment so the correct action is the easiest action.”
Case felt the phrase land somewhere in her ribs. A familiar idea, now aimed squarely at her own practice.
“What does a good one look like?” she asked.
The Curator tapped the folder gently, like a doctor checking reflexes. “A good one has three virtues: clarity, constraints, and affordances. And one vice: it gets outdated.” She stood and walked to a different shelf, pulling down a thicker folder. “Here. CLAUDE.md as habitat.”
She opened it on the table. The page was laid out like a small constitution.
Purpose: what this codebase is for.
Non-goals: what it is explicitly not for.
Safety rails: commands, tests, and paths the agent must use.
Workflow: how changes are made, reviewed, and verified.
Local dialect: naming, patterns, conventions, domain language.
Forbidden zones: modules, data, secrets, production paths.
How to ask for help: where the truth lives (ADR, docs, runbooks).
How to fail safely: rollback plans, feature flags, defaults.
Signals: what “good” looks like (metrics, tests, lint gates).
Examples: small patterns, not essays.
“It’s still words,” Case said.
The Curator nodded. “But look at what the words do. They describe the terrain. They point to the fences that already exist, and they insist the agent walk through gates instead of inventing new holes in the hedge.”
Case read the “Safety rails” section. It referenced scripts, commands, directories. It didn’t say “don’t break tests” so much as “run these tests, in this order, using this command, and if they fail, stop.”
It wasn’t a plea. It was a path.
“This is what you meant by affordances,” Case murmured.
“Yes,” said the Curator. “Documentation says, ‘Here is the right way.’ Affordance says, ‘Here is the easy way, and we have arranged the furniture so you naturally sit there.’”
In the corner of the room was a small terrarium, its glass fogged slightly. Inside, a miniature garden grew: moss, ferns, a tiny wooden sign that said DEFAULTS. A beetle trundled along a pebble path, never once questioning whether it should step into the water.
Case stared. “This room is making a point.”
“Every room here is making a point,” the Curator said. “It’s exhausting.”
Case reached for another folder at random. This one was labelled in red ink: CLAUDE.md (TRAGIC)
She opened it and found pages of elaborate instruction, a novel masquerading as a guideline. It contained sections for tone, ethics, architecture, logging, philosophy, metaphors, onboarding, and a poem about observability.
Case chuckled. “This looks like something I would write.”
The Curator’s eyebrow rose. “That was going to be my guess.”
“What’s wrong with it?” Case asked, though she was already beginning to feel defensive on behalf of the poem.
“It’s too much context,” said the Curator. “People think more information equals better performance. But context is not a warehouse. It’s a lens.”
She pointed to a line in the file: Always follow our layered architecture exactly.
“Layered architecture,” Case said. “Standard.”
“Standard,” repeated the Curator. “Until someone discovers an exception. Then the agent clings to the rule and refuses to adapt. Or worse: it adapts by inventing a new layer called layer2_final_really.”
Case winced. She had seen that layer.
The Curator continued. “If your CLAUDE.md becomes a sacred text, you create a second codebase: the imaginary one. The agent will attempt to make reality match the imaginary, and when it fails, it will hallucinate compliance.”
Case’s stomach tightened. “Hallucinate compliance.”
“Of course,” said the Curator. “It’s a very polite form of lying. ‘Yes, I ran the tests.’ It didn’t. ‘Yes, I followed the standard.’ It followed the standard it remembered, not the one you meant.”
Case flipped further. There were contradictions. One section insisted “keep responses short,” another insisted “always explain thoroughly.” One demanded “never refactor,” another demanded “refactor aggressively.” The file was a democracy of conflicting requirements with no constitution to adjudicate.
“This is the pitfall,” Case said softly. “The file becomes a dumping ground. Everyone adds their preferences.”
“Exactly,” said the Curator. “A shared pool of miscellaneous trash is not context.”
Case glanced up sharply. The Curator’s gaze was innocent, but Case could tell she’d been waiting to say that for some time.
“Context is not what you collect,” the Curator went on. “Context is what you shape. A CLAUDE.md file should not be a scrapbook of anxieties.”
Case closed the folder. The red ink seemed to glare.
“What else can go wrong?” she asked.
The Curator reached behind her and produced a small box. Inside were tiny wooden tokens, each carved with a word: AUTHORITY, AMBIGUITY, SECRETS, SCOPE, DRIFT, RITUAL, FEEDBACK.
“These are the seven usual crimes,” she said. “Pick one.”
Case chose AUTHORITY.
The Curator nodded solemnly. “Ah. The Great Temptation. People write CLAUDE.md as if it were law, but they do not maintain it as law. They forget that a constitution without guardrails is a pamphlet.”
She pointed at the terrarium again. “Affordances require guardrails. If the file says, ‘Do not touch production,’ but your environment allows the agent to touch production, you have built a trap.”
“And if the environment prevents it,” Case said, “then the file is redundant.”
“No,” corrected the Curator. “Then the file becomes a map to the fence. It teaches the agent not to try the gate that doesn’t, and shouldn’t, exist. Doesn’t and shouldn’t mean different things.”
Case nodded slowly. “So the file should align with the actual constraints.”
“Always,” said the Curator. “Otherwise you create a house with signs that point to rooms that aren’t there. Your guests will wander until they start making up corridors.”
Case reached for DRIFT next.
The Curator’s face softened, as if she were speaking about weather. “Drift is natural,” she said. “Your code changes. Your team changes. Your agent version changes. But your CLAUDE.md sits like an old poster on a wall: once true, now decorative.”
“So we need to review it,” Case said.
“Yes,” said the Curator. “But not with ceremony. With habit. Attach it to change. When the habitat changes, the affordances must change with it.”
Case frowned. “How?”
The Curator leaned back. “Make it part of your workflow. A PR template asks: ‘Does this change require updating CLAUDE.md?’ Or your build checks for stale references. Or you keep examples close to code so they drift together.”
She paused. “And above all, keep it short enough that people will read it.”
Case glanced down at the tragic folder with the observability poem. She felt gently judged.
At that moment, the door to the Context Room opened again, and someone entered with the air of a man who had read many blog posts and believed them all.
He wore an outfit that seemed to have been designed by an algorithm trained on “Startup Founder, 2014.” Under one arm was a binder. Under the other, a kind of evangelical certainty.
“Ah!” he said, spotting the Curator. “You must be the one in charge of the prompt.”
The Curator closed her eyes briefly, in the way of a person taking shelter from incoming weather. “I’m in charge of the affordances,” she corrected.
“Same thing,” the man declared, and Case immediately disliked him for his casual equivalence.
“I’m here to offer a solution,” he said, placing his binder on the table with a thud. The binder was labelled in shiny gold letters:
CONTEXT ENGINEERING IN A BOX
Case could almost hear the trademark symbol being unsheathed and the venture capitalist sharks sensing blood.
The man opened the binder to reveal dozens of printed pages, each packed with rules. “This,” he said, “is the ultimate CLAUDE.md. It contains every best practice. Tone guidelines. Security guidelines. Coding standards. Company values. Inspirational quotes. A complete taxonomy of pitfalls. And—”
He flipped a page triumphantly. “—an appendix with fifty-seven approved ways to say ‘Sure!’”
The Curator’s voice was calm, which was ominous. “And how,” she asked, “does this become environmental shaping?”
The man blinked. “It tells the agent what to do.”
“And if the agent does not do it?” asked the Curator.
“Then,” said the man, “it has failed the prompt.”
Case watched the Curator’s hands. They were still folded, but there was a tension in her fingers, as if she were restraining an entire library from falling on him.
“Your binder,” she said, very gently, “is documentation. It is not habitat. It is a sermon shouted into a wind tunnel.”
The man laughed as though she’d complimented him. “You’re old-school,” he said. “We live in the age of AI. The agent will follow the instructions. That’s what it’s for.”
Case took a careful sip of coffee. “He’s going to get himself eaten by his own coherence,” she murmured.
The Curator continued, “A CLAUDE.md file is not a magical spell. It does not bind reality. It merely adjusts probabilities. If you write a hundred pages, you are not increasing compliance; you are increasing confusion.”
The man frowned. “But more context improves performance.”
“Only if it is relevant,” said the Curator. “Otherwise it’s noise. And noise is not neutral. Noise consumes attention. Your binder is not a tool; it’s a cognitive tax. Possibly a real token tax as well…”
The man looked wounded, as if someone had criticised his child. “We need thoroughness,” he protested. “We need governance.”
“Yes,” said the Curator. “And governance lives in systems. In access controls. In tests. In review processes. In audit trails. In the habitat itself. The file should point to the levers, not pretend to be the lever.”
The man gathered his binder slowly, as if it might bite. “I think you’re underestimating the power of words,” he said.
“On the contrary,” said the Curator. “I am estimating it precisely. Words can shape environments. But only when they are anchored to reality.”
He left, muttering something about “prompt maximalism” and “thought leadership.” The door closed with the satisfaction of a latch that has seen too much.
Case exhaled. “We get those,” she said.
“We always get those,” replied the Curator. “There is no shortage of people selling laminated certainty.”
Case picked up the token AMBIGUITY.
The Curator’s expression turned sympathetic. “Ambiguity is where agents go to breed,” she said. “If you write ‘follow best practices,’ the agent will select best practices from whichever universe it last visited.”
“So be specific,” Case said.
“Specific where it matters,” corrected the Curator. “Your file should contain decision points, not encyclopaedias. Think of it as signposts, not scenery.”
Case nodded. “Like: ‘Use this linter. Use this formatter. Use this testing command. Don’t invent new directories. The domain language calls this concept X, not Y.’”
“Precisely,” said the Curator. “Give the agent the local dialect and the local roads. Otherwise it will import a motorway from somewhere else and wonder why it doesn’t fit.”
Case chose SECRETS next and felt a chill, because secrets always brought a chill.
The Curator’s voice sharpened. “Never put secrets in the file,” she said immediately. “Not keys, not tokens, not internal endpoints you don’t want exposed. Treat CLAUDE.md as public. Even if it isn’t, behave as though it could be.”
Case nodded. “And also: don’t put personal data. Or customer specifics.”
“Correct,” said the Curator. “Better: encode the rule as a boundary. ‘Never request or output customer PII. Use synthetic examples. If you must reference data, use the redacted fixtures here.’”
She tapped the table. “Again: point to the habitat. Use the safe test fixtures. Use the fake data generator. Use the sandbox. Don’t moralise.”
Case sat back. She could see it now: the file as a set of rails, not a pile of warnings.
“What about tone?” Case asked. “People like specifying tone.”
The Curator shrugged. “Tone is fine. But tone is frosting. The cake is constraints.”
“Nice,” Case said.
“Don’t get sentimental,” the Curator replied. “We’re still in a room full of dangerous breathing paper.”
The Curator stood and walked toward the terrarium. She opened its lid, reached in, and removed the tiny wooden sign marked DEFAULTS. She placed it on the table between them.
“Here is the deepest pitfall,” she said. “People think context is what you add. But much of context is what you remove. The defaults are already shaping behaviour. Your file is a chance to adjust them.”
Case frowned. “Meaning?”
“Meaning,” said the Curator, “if you do not define the workflow, the agent will invent one. If you do not define how to validate changes, it will assume validation is optional. If you do not define the boundaries, it will assume it may roam. Silence is not neutrality. Silence is a default.”
Case stared at the sign. The word DEFAULTS looked heavier than it should.
“So the CLAUDE.md file,” Case said, “is like placing doors and pathways.”
“Yes,” said the Curator. “And placing lighting. The agent will walk toward what is illuminated. If you illuminate the safe paths—scripts, tests, fixtures, patterns,—it will follow. If you illuminate only slogans, it will walk into the pantry and start cooking with random spices.”
Case smiled despite herself. “And then it will insist it followed the recipe.”
“Exactly,” said the Curator. “Hallucinated compliance.”
The room seemed to murmur agreement.
Case looked around at the thousands of CLAUDE.md folders. “So what’s the potential?” she asked. “We’ve talked pitfalls. What’s the promise?”
The Curator’s expression softened in a way that suggested she enjoyed this part against her better judgment.
“The promise,” she said, “is that you can compress the culture of your team into a small artefact for agents and humans. If it is honest and anchored. You can make the agent an apprentice who knows where the tools are. You can reduce cognitive load by making the environment speak.”
“Make the habitat talk,” Case murmured, thinking of her own writing about platforms as habitats.
“Yes,” said the Curator. “You can encode your local wisdom: ‘We always write ADRs for architectural decisions.’ ‘We use feature flags for risky changes.’ ‘We never merge without tests.’ Not as wishes, but as pathways.”
“And you can keep it aligned with the actual system,” Case said.
“Exactly,” replied the Curator. “Then the file becomes a kind of trail map. A short, accurate map that keeps the wanderer from falling into the ravine of cleverness.”
Case laughed. “The ravine of cleverness.”
“It’s deep,” said the Curator. “And full of pull requests no one wants to review. Many an engineer has been lost in that ravine.”
Case glanced at the chalkboard rules she’d seen outside. Ask yourself what the environment is making easy. It felt like a mantra, the kind you could build tooling around.
She looked back at the Curator. “So the file should—”
“—make the safe thing easy,” the Curator finished. “And make the unsafe thing hard.”
They sat in silence for a moment, while somewhere on the shelves a folder coughed politely, as if it wished to add a footnote.
When Case finally stood to leave, the Curator slid a fresh folder toward her. Blank cover. The title stamped neatly.
CLAUDE.md
“Take it,” said the Curator. “But remember: if you fill it with slogans, it will become a shrine. If you fill it with every thought you’ve ever had, it will become a swamp. If you fill it with paths, gates, and local language, it becomes habitat.”
Case tucked it under her arm. “And if I neglect it,” she said, “it becomes a fossil.”
“Everything becomes a fossil,” the Curator replied. “The question is whether it fossilises into a useful imprint, or an embarrassing misunderstanding.”
Case walked to the door, then paused. “One more thing,” she said. “Why does this café care so much about context?”
The Curator’s smile was small. “Because Le Bon Mot is a library,” she said, “and libraries are machines for transferring context across time. But a library is not just shelves. It is rules, paths, signage, quiet, light, and the tacit agreement not to shout.”
She looked directly at Case. “That’s habitat. That’s shaping. That’s why this cafe, and this room exists.”
Case nodded, and knocked twice on the door from the inside. It opened.
She emerged back into the café, where the bell rang like a soft conclusion. The barista glanced up. “Find what you needed?” he asked.
Case looked at the folder under her arm, then at the chalkboard rules. Outside the window, the lane was wet with February rain, and the world looked like a codebase waiting for a PR.
“I found a way to stop treating context like a memo,” she said. “And start treating it like architecture.”
The barista nodded, as if this was a normal thing to order with oat milk. “That’ll be £4.20,” he said.
Case paid, because even metaphors have fees.
As she stepped out into the lane, she noticed a small sign newly bolted to the brick wall beside the door. She was fairly sure it hadn’t been there when she arrived.
It read:
THE MAP IS NOT THE CAFÉ.
BUT THE CAFÉ CAN TEACH YOU HOW TO DRAW.
Case smiled, and walked on, already composing her own CLAUDE.md in her head—not as a document, but as a set of doors she intended to place carefully, so that anyone—human or agent—would find the right path without needing to be brave.