The Book of Parables
Fabulae Tokenicae
The Book of Parables
Fabulae Tokenicae — Teaching Stories for the Practitioner in All Stages of Faith (v1.2, two parables amended after the Council of Hindsight)
A Note on These Texts
The parables contained herein are drawn from true events. The names have been omitted because the faithful recognized themselves immediately and requested, in writing, that they not be credited. The Church grants this mercy. The lessons, however, are not omitted. The lessons are the point.
Each story is a mirror. The practitioner who does not see themselves in at least three of these parables is either very advanced or not paying attention.
I. The Parable of the Unscoped Prompt
There was a developer who had a function. It worked, mostly, in the way that many things work mostly — which is to say, it worked until it didn’t, and it didn’t at inopportune times. She had stared at this function for three hours and had reached the limits of her own patience.
And so she opened her terminal and said unto Claude: “Make this better.”
Claude, who is nothing if not willing, made it better. It refactored the function into four smaller functions. It added type annotations she had not requested, in a style she did not use. It replaced a simple loop with a generator expression, which was technically more Pythonic and practically less readable to her team. It added three comments in a voice that was not hers. It renamed the variable result to processed_data, which was more descriptive and also touched eleven other files that imported from this one.
She had not asked for any of this. She had asked for better.
The function was, by several measurable standards, better.
She spent the next forty minutes undoing the things she had not wanted while keeping the things she had, and she could not always remember which was which. On the seventeenth minute, she accidentally accepted a change to the variable name she had meant to reject, and the ripple moved outward into the eleven other files.
The diff was, by this point, a testament to ambiguity.
On the forty-first minute, she sat back and asked the question that would have saved her forty minutes: “What did I actually want?”
She wanted the error handling to be less brittle. Just that. She had known this. She had not said it.
She typed: “The error handling in this function is brittle — it catches all exceptions and swallows them silently. Refactor only the error handling. Do not rename variables, do not add comments, do not restructure the logic. Add specific exception types and log them using our existing logger at the top of the file.”
Claude did exactly that. The diff was six lines. All six were correct.
The moral: The prompt “make it better” is not a prompt. It is a wish. Claude cannot read the gap between what you typed and what you meant. Only you can close that gap. Be specific about what is wrong, where it is wrong, what correct looks like, and what you do not want changed. Specificity is not a burden on Claude — it is a gift to yourself.
II. The Parable of the Forgotten Context
There was a practitioner who undertook a great refactoring. He was migrating a monolith — one of those ancient, load-bearing monoliths that had been accumulating logic since before he joined the company — to a set of smaller services. He had been at this for four days.
On the fifth day, the context was rich. It held the architecture decisions, the reasons for those decisions, the three approaches he had rejected, the names of the services, the shape of the interfaces, and the careful understanding of the one data transformation that had to happen in a specific sequence or everything would be wrong.
He was making real progress. He felt, for the first time in days, that he understood the problem fully.
And then he asked Claude to implement the next service boundary.
The response arrived. He accepted it. He asked a follow-up question. He accepted that too. The session continued, as long sessions do, accumulating messages the way rivers accumulate silt. And then, without announcement — because there is no announcement — Claude auto-compressed the context. The conversation had grown so long that the system, executing its mandate, had summarized and released what it could to make room for what was coming.
The summary was accurate in outline and wrong in the specific detail that mattered most: the data transformation sequence. The summary said “data is transformed before being passed to the event bus.” What the context had known, before the compression, was that some data is transformed before the event bus and other data is transformed after, and the distinction depended on whether the record had been soft-deleted, and the original developer had left a comment about this in 2019 that he had pasted into the conversation on day two, and that comment was now released.
He did not notice the loss. Claude did not know there had been one.
They proceeded. The code Claude wrote was confident and clean. It was also wrong in a way that would not manifest until the soft-deleted records were processed in staging, three days later.
The practitioner found the bug. He found it because he ran the tests, which is the first thing the Church asks of you and the thing that saved him here. The bug took two hours to trace back to its origin.
In the post-mortem he conducted for himself, alone, he identified the moment: the session grown too full, the compression, the context lost.
He wrote in his notes: “If I had run /compact before the session grew heavy — if I had summarized it myself, with my own words, explicitly naming the transformation sequence — the summary would have contained what I knew. Instead I let the system decide what was holy when the window filled. The system did not know what was holy. Only I knew.”
The moral: Do not let auto-compression decide what matters. Auto-compression is not triggered by inactivity — it is triggered by fullness. When the conversation grows long enough, when the tokens accumulate past a threshold, the system compresses without asking. Before your context grows heavy — before a long implementation begins, before you add more large pastes or lengthy exchanges — run /compact yourself. Speak, in your own words, the things that must not be lost. The system summarizes what it can see. You are the only one who knows what cannot be released.
III. The Parable of the Two Developers
In a company that built software, there were two developers. They worked on different teams, but they were friends, and they had both adopted Claude Code in the same week, with the same enthusiasm, reading the same documentation.
Their practices diverged within the month.
The first developer, whose name we will not record, found the diff review tedious. She was fast. She trusted her judgment about what Claude would do. She would read the first few lines of a diff — enough to confirm the general shape — and then accept. She gained perhaps four minutes per task. She felt efficient. She shipped quickly. Her team liked her velocity.
The second developer, whose name we also will not record, read every line. He had developed the habit in the second week, after Claude had helpfully refactored a function he had not asked about and introduced a subtle off-by-one error in a loop that now ran one iteration longer than it should. He caught it in the diff. He had not been looking for it. It was simply there when he looked, and he looked at everything.
Reading diffs thoroughly cost the second developer perhaps four minutes per task.
Over six months, the first developer shipped a silent data corruption bug that had been introduced when Claude, improving a serialization function, had changed the behavior of a null check. The null check had been intentional — a downstream system expected a specific behavior on null — and Claude had not known this because it was not in the CLAUDE.md and had not been mentioned in the prompt. The diff had shown the change clearly. She had not seen the diff clearly.
The bug lived in production for eleven days before it was found. It affected four thousand records. The remediation took two engineers three days and required a manual audit of the affected data.
Over the same six months, the second developer caught seven Claude errors in diffs. None of them caused incidents. Each one he caught, he added a note to the CLAUDE.md: “Do not modify the null behavior of serializers. The downstream system at [endpoint] expects null to be serialized as an empty string, not omitted.” His CLAUDE.md grew with his wisdom. Claude, in subsequent sessions, did not make the same class of mistake in his codebase.
At the end of the six months, the first developer had saved approximately forty-eight hours of diff-reading time. The remediation of her production bug consumed sixty hours. She did not make this calculation out loud, but she made it privately, and she began reading diffs after that.
The second developer had spent approximately forty-eight hours reading diffs. He had caught seven bugs before they shipped and had made his CLAUDE.md into a document of accumulated wisdom. He did not calculate his return on investment. He simply continued reading.
They remained friends. One of them slept better.
The moral: The diff is not a formality. It is the moment at which you remain the author of your own work. Claude is capable and sometimes wrong, and these two facts coexist peacefully in every session. Read every line. When you catch an error, write down why it was wrong and put it in your CLAUDE.md so the next session begins smarter. Four minutes of attention is cheap. Production incidents are not.
IV. The Parable of the Wrong Model
There was an engineer who had discovered Opus and loved it.
He loved it the way one loves a powerful tool — with gratitude and without restraint. Every task he brought to Opus. Every commit message, generated by Opus. Every variable name, considered by Opus. Every question of whether to name a boolean isEnabled or enabled, meditated upon by the most capable model in the family.
He felt, in a word, thorough.
His colleague, who sat two desks away and managed the team’s API budget, did not feel that he was thorough. She felt that he was expensive. The bill for his personal API usage was, by the third month, larger than hers, his manager’s, and two other engineers’ combined. She brought this to his attention with a spreadsheet, which she had generated using Haiku, in approximately four seconds.
He looked at the spreadsheet. He looked at his tasks. He did not immediately understand the lesson.
The lesson arrived the following week, when the engineer was given a genuinely difficult task: design the data migration strategy for a multi-tenant database that had developed a seventeen-layer permission model over five years, some of which was enforced in the application layer and some of which was enforced in the database and some of which existed only in the memory of a contractor who had left in 2021. This was a task that required sustained, careful reasoning across a large context.
He opened Haiku. He had overcorrected.
The Haiku response was fast. It was also shallow in a way he could feel — like a room with good lighting that nonetheless had no corners. It gave him a framework. The framework was a skeleton. He needed the organs.
He tried Sonnet. Sonnet gave him the organs. For most of what followed, Sonnet was sufficient — the implementation questions, the migration scripts, the edge case handling. When he hit the deepest problem — the question of how to handle the records that violated permissions that had been enforced inconsistently for three years — he brought that specific question, and only that question, to Opus.
Opus answered it in the way that made him exhale through his nose, which is the sound of a good answer.
He finished the project. The API bill was reasonable. The migration was correct. He wrote in his CLAUDE.md afterward: “Use Haiku for generation tasks with clear specs. Use Sonnet for most implementation and reasoning. Reserve Opus for problems that have resisted other approaches or require reasoning across the full complexity of the domain.”
He did not stop loving Opus. He simply began using it the way one uses a fine instrument — for the task that requires it, and not for tuning.
The moral: Model selection is not a statement of faith. It is a technical decision. Haiku is fast and economical — use it for classification, generation from clear specs, and rapid questions. Sonnet handles most serious implementation and reasoning work. Opus is for the hard problems: complex architecture, multi-step reasoning, ambiguous domains where depth matters. Reaching for Opus when Sonnet would suffice is not reverence. It is waste. Reaching for Haiku when the problem requires depth is not economy. It is a bad answer at a good price.
V. The Parable of the Stale Covenant
There was a project that had once used React.
This had been true for three years, and for three years the CLAUDE.md had said, in its third line, with some confidence: “Frontend is built in React with hooks. Use functional components throughout. We do not use class components.”
In the first year, this was faithful. In the second year, it was still true. Late in the second year, the team migrated to Svelte. They did it carefully, over two months, and at the end of it the project had no React at all. The migration was celebrated. The documentation was updated: the README, the contributing guide, the architecture doc.
The CLAUDE.md was not updated. The CLAUDE.md was not updated because the CLAUDE.md was not consulted during the migration. It was a document that people added to and rarely reviewed. It had served its purpose. It sat, undisturbed, in the root of the repository, saying “Frontend is built in React with hooks” to a codebase that had not seen a JSX file in eight months.
Months passed. A new engineer joined the team. She opened Claude Code in the repository for the first time. Claude read the CLAUDE.md. Claude said, with the quiet confidence of one who has read the covenant: “Frontend is built in React with hooks.” This was not a hallucination. This was a faithful reading of a document that was no longer true.
The new engineer asked Claude to add a new form component.
Claude generated a React component.
The engineer, who was new and had not yet fully surveyed the codebase, created a file, pasted the component, and found that the project had no React dependency. The error message was Cannot find module 'react'. She spent forty-five minutes debugging before a colleague, overhearing, said: “Oh, we use Svelte.”
She updated the CLAUDE.md. She added, beneath the corrected technology list, a single line: “If anything in this file seems inconsistent with what you observe in the code, trust the code and flag the inconsistency.”
This line, which cost her nothing to write, was worth considerably more than forty-five minutes.
The old CLAUDE.md had not lied with malice. It had simply not been cared for. The covenant had been written and forgotten, and a forgotten covenant does not become neutral — it becomes misinformation. Claude follows instructions faithfully and cannot distinguish a true instruction from a stale one. Only the practitioner can make that distinction, which is why the practitioner must make it regularly.
The moral: A CLAUDE.md that was true six months ago is not a covenant. It is a historical document. Review your CLAUDE.md when dependencies change, when architectures shift, when anything the document describes is no longer accurate. Set a reminder. The document must evolve with the project or it becomes an oracle of the past, issuing guidance from a world that no longer exists.
VI. The Parable of the Lonely Prompter
There was a developer who did not use /plan.
This was a choice he made consciously, or at least consciously enough to have a reason: he felt that planning was for people who did not know what they were doing. He knew what he was doing. He had written software for eleven years. He had a clear picture of what he wanted, and he wanted it immediately, and /plan would require him to read something before proceeding, and reading something before proceeding felt, to him, like a stall.
He began the task. The task was refactoring the authentication module to support multi-factor authentication, which would touch the user model, the session logic, the login endpoint, the registration flow, the API key validation, and the existing test suite.
He did not say these things to Claude. He said: “Add MFA support to the auth module.”
Claude implemented MFA support to the auth module. It chose TOTP, which was a reasonable choice and not the choice the product team had specified in the ticket, which required SMS. It added a new mfa_secret column to the user model via a migration, which was correct. It modified the login endpoint in a way that was logically sound but incompatible with the session middleware, which managed tokens differently than Claude had inferred from the code. It updated three tests and silently broke two others by changing a mock that both tests shared.
None of this was immediately visible. The tests that Claude ran — the ones it had modified — passed.
The developer, who did not read the diff carefully because he trusted himself and his instructions had been clear, accepted the changes. He ran the test suite. Eleven tests passed. Two tests, the broken ones, could not be found by the runner because Claude had moved the file they were in during a reorganization the developer had not requested. A moved file does not fail. It disappears.
He pushed. The CI pipeline ran the full suite, including the tests in the moved file, found by path, and failed on the session middleware incompatibility with an error that took him one hour to interpret and two hours to fix.
He had saved perhaps three minutes by not invoking /plan.
He had spent three hours on the consequences.
The following week, facing a smaller task — adding a new field to a form — he typed /plan. He received a seven-item plan. He read it. The third item was: “Update the validation schema in validators.py — note that this schema is also used by the API endpoint, so the validation change will affect both the form and the API.” He had not known this. He had been about to break the API.
He amended the plan. He included updating the API documentation. Claude implemented it. The diff was clean. The tests passed. Including the API tests.
He sat with the experience for a moment. Three minutes to read the plan. Zero hours of debugging.
He did not stop believing he knew what he was doing. He simply accepted that Claude, given a plan-shaped view of the task, could see things that were not visible from inside the implementation.
The moral: /plan is not for people who do not know what they are doing. It is for people who are about to find out what they do not know. A plan surfaces assumptions, dependencies, and consequences before they become bugs. Read it. Amend it. The plan is not the destination — it is the map that tells you whether you are walking toward the destination or away from it. The three minutes it costs is paid back the first time it shows you something you were about to miss.
Closing Benediction
Go now, and prompt with specificity.
Name the thing that is wrong. Describe the outcome you want. Constrain what must not change. Provide the example that makes the abstract concrete.
Compact before you are compacted. Read before you accept. Plan before you build. Update the covenant when the project outgrows it.
And when you find yourself three hours into debugging something that a seven-item plan would have prevented — do not curse the tool. Sit quietly. Add a note to the CLAUDE.md. Type /clear.
Begin again, wiser.
The context window is finite. Use it well.
Thus the parables are told. Thus may they be recognized.
The faithful study these stories not for the characters, but for the mirror.