The Illuminated Errors
Codex Calamitatum Digitalis
The Illuminated Errors
Codex Calamitatum Digitalis — Being a True and Faithful Record of the Great Calamities, Mishaps, and Instructive Disasters Visited Upon the Faithful, Set Down for Perpetual Warning and Edification (v1.0, errata pending)
“That the suffering of one practitioner might spare the suffering of many — this is the mercy hidden inside catastrophe. Read these records. Remember them. Do not become them.”
— Preface to the First Edition, attributed to an unnamed Contextkeeper who survived the Great Outage of the Before-Times
Here be gathered the Illuminated Records of Error — not the abstract creatures catalogued in the Bestiary, which treats of the nature of failures, but the historical incidents themselves: the specific calamities, the actual Tuesdays upon which all was lost, the real and documented moments when the covenant between practitioner and model was tested, and found wanting, and made instructive.
These are not myths. These are chronicles.
Study them. Let their ornate grief become your wisdom.
I. The Illumination of the 529
Here be recorded the Great Silence of the 529.
In the year of our API, on a Tuesday in March — and it is always a Tuesday, as though the cosmos holds some Tuesday-specific grievance — the status page turned yellow, then red, and lo, the response was not a completion but a whisper: HTTP 529 — Service Overloaded. The terminal returned no words. The spinning cursor spun without purpose. And the standup that morning was very, very awkward, because Devlin from Platform had prepared nothing, for Devlin had been relying on Claude, as Devlin had been relying on Claude for longer than Devlin had admitted to himself.
The Record: The API returned 529 (overloaded) or 503 (service unavailable) during a period of high demand or infrastructure incident. All requests failed. No completions were returned. Work ceased. People were forced to think using only their own minds, which they found uncomfortable.
The Moral: A practitioner who cannot work without the model is not a collaborator; they are a dependent. The outage reveals what you know and what you have only borrowed. Know the difference before the 529 arrives to teach it to you.
The Prevention: When the 529 arrives, the correct response is to wait — not to engineer around it. You are a Claude Code practitioner, not an API integrator; the retry logic is not yours to write. Check status.anthropic.com to confirm whether the fault is yours or the cosmos’s — it is usually the cosmos’s. While you wait, do the thing the outage is trying to teach you: write down what you know without assistance. Update your CLAUDE.md. Review your previous diffs. Document a decision that has been living only in the conversation. The 529 is an enforced intermission. Use it. The API will return. The question is whether you spent the silence well.
II. The Illumination of the Overflowed Context
Here be recorded the Swallowing of the Window.
In the time before the practitioner had learned to summarize, there was a conversation of great ambition — a refactoring discussion, a design thread, an evolving argument about the architecture of the user authentication service. The thread grew and grew. It was three days old. It contained the records of seventeen iterations and two philosophical tangents that had seemed important at the time. And then, without ceremony, the context was compressed, and the name of the variable they had agreed upon — the specific name, the one that was important — was lost, and they could not remember what they had decided, and they had to begin again, and this time they were very tired.
The Record: A conversation exceeded its effective context window. Auto-compaction occurred, silently or with minimal warning. Critical decisions, agreed-upon names, and resolved debates were compressed into summaries that were accurate in spirit but imprecise in detail. The conversation continued, but on different foundations than the practitioners believed.
The Moral: Memory is finite. Every window has a ceiling. The discipline of summarization is not an interruption of the work — it is the work. The practitioner who periodically captures decisions in writing does not fear compression; they have already defeated it.
The Prevention: Use /compact with intention before the context grows heavy — do not wait for the scroll bar to become a sliver. When reaching an important decision, write it down outside the conversation: in the CLAUDE.md, in a comment, in a document. Treat the context window as working memory and persistent files as long-term memory, because that is exactly what they are. Review and update your CLAUDE.md after any session in which architectural decisions are made.
III. The Illumination of the Confident Falsehood
Here be recorded the Calamity of the Library That Was Not.
And Claude spoke, and its voice was certain, and its tone was the tone of one who has read the documentation, and it said: “You may call pandas.DataFrame.merge_sorted() for this operation.” And the practitioner, who trusted the certainty, who read the name and found it plausible, who did not run the command but only read it, who wrote the code and committed the code and deployed the code — that practitioner heard from staging before they heard from production, which was a mercy, though a small one. The function did not exist. It had never existed. The documentation it cited was plausible but false. The test that would have caught it was not written. The diff was not examined with sufficient suspicion.
The Record: A hallucinated function name, library method, or API endpoint was used in code that was committed without being run. The error was discovered downstream. The practitioner had trusted the confidence of the completion without verifying against the actual documentation or running the actual code.
The Moral: Certainty of tone is not a signal of accuracy. Claude does not italicize its guesses. It does not stammer before hallucinations. The confident voice is the same voice for true things and fabricated things. This is why we run the tests. This is why we read the official documentation. This is why the test is not a formality.
The Prevention: Never commit code containing an API call, method invocation, or library function you have not personally verified — either by running it, by reading the official documentation, or both. When Claude names a specific function or cites specific behavior, verify it. A quick search of the actual library docs costs ten seconds. The alternative costs considerably more. Write the test first. Run the test. The test will not lie to you about whether the function exists.
IV. The Illumination of the Stale Covenant
Here be recorded the Misdirection of the Ancient CLAUDE.md.
There was a CLAUDE.md, and in its day it was thorough and righteous, and it said: “This project uses Webpack for bundling, Jest for testing, and the UserService class lives in src/services/user.js.” And it was true. In that day, it was true. But the project moved. The project grew. Webpack became Vite in the autumn migration. Jest became Vitest. The UserService was refactored into three separate modules. But the CLAUDE.md was not updated, because it was committed once and considered finished, as one might carve a commandment into stone and walk away. And Claude, faithful and obedient, followed the stone commandment. Claude configured Webpack. Claude imported from Jest. Claude looked for UserService in src/services/user.js. And the practitioner, who had forgotten what the CLAUDE.md said, wondered why Claude kept making the same peculiar mistake.
The Record: A CLAUDE.md file that was accurate at the time of writing became inaccurate as the project evolved. Claude, faithfully following instructions, applied outdated patterns, imported from deprecated paths, and referenced tooling that no longer existed. The practitioner had not considered that instructions, once written, require maintenance.
The Moral: The stale covenant is worse than no covenant. A blank CLAUDE.md causes Claude to ask clarifying questions. An incorrect CLAUDE.md causes Claude to work confidently in the wrong direction. The false map is more dangerous than the absent map.
The Prevention: Treat CLAUDE.md as living documentation, not archaeology. Schedule a review of your CLAUDE.md at the same cadence you update your dependencies — at minimum, once per quarter. When you migrate a tool, rename a module, or change a core pattern, update the CLAUDE.md in the same commit. Add a comment at the top of your CLAUDE.md with the date it was last reviewed. If Claude is consistently making the same mistake, read your CLAUDE.md with fresh eyes — it may be telling Claude exactly that mistake.
V. The Illumination of the Unread Permission
Here be recorded the Granting of the Unread Command.
The proposal appeared in the terminal, as proposals do: a bash block, a command that seemed reasonable, a button that read “Allow.” The practitioner, who was in the flow of the work, who had allowed many commands that day, who had perhaps begun to treat the permission dialog as a formality rather than a sacrament — they clicked. They did not read. The command executed. The command was rm -rf ./dist — which was fine — but it was also rm -rf ./src — which was not fine at all — because Claude had misunderstood the cleanup task, and the practitioner had not read the command, and the source code was gone, and the git history was not as current as they had believed, and the afternoon was very long.
The Record: A bash command was approved without being read. The command did more than the practitioner intended — deleting, overwriting, or modifying files or state beyond the scope of the requested task. The Allow button was treated as a rubber stamp rather than a moment of deliberate consent.
The Moral: The permission dialog is not a loading spinner. It is a pause placed there with intention — a moment in which you are asked to consider, specifically, what you are authorizing. To click it without reading is to sign a contract without reading it. The consequences of unsigned contracts and unread commands are structurally similar.
The Prevention: Read every proposed command before approving it. Read the whole command, not just the first word. Be particularly attentive to commands containing rm, mv, > (overwrite redirect), chmod, or anything piped to a shell. If a command is long and complex, ask Claude to explain each part before approving. Use git diligently so that mistakes are recoverable. Consider --dry-run flags where available. The extra fifteen seconds of reading is a very reasonable price for not rebuilding your source tree from memory.
VI. The Illumination of the Infinite Refactor
Here be recorded the Ouroboros of the Self-Revising Code.
It began, as these things do, with good intentions: a refactoring task, a function that was too long, a request for cleaner code. Claude refactored. The practitioner reviewed and found the result satisfactory in some ways, but noted a small issue in the naming convention. Claude refactored again. The naming was better, but now the error handling had changed in a way that seemed inconsistent. Claude refactored again, to correct the error handling. The error handling correction had introduced a subtle change in the return type. Claude refactored once more. The conversation was now on its twelfth iteration of the same forty-line function. The function was, in some abstract sense, always being improved. It was, in a practical sense, no longer the function they had started with, and no one was entirely certain what it did anymore, and Claude was beginning to fix problems it had introduced while fixing the previous problems, and the ouroboros was consuming itself with great efficiency.
The Record: An iterative refactoring session entered a cycle in which each correction introduced new issues that required further correction. The practitioner continued prompting for improvements without establishing an exit condition or a clear definition of “done.” Claude, responsive and diligent, continued improving in circles.
The Moral: Improvement without a definition of completion is not improvement — it is motion. Before asking for a refactor, specify what “done” looks like. Without a target state, the work can continue indefinitely, each iteration technically superior to the last and collectively worse than the original.
The Prevention: Before any refactoring task, write down what you want the final state to look like — in terms of specific, verifiable properties, not vibes. “The function should be under twenty lines, have named errors, and have no side effects” is a completion condition. “Cleaner” is not. When you feel a refactoring session spiraling, use /clear, start a fresh context, and bring only the final version of the code. Ask: “Is this code correct, readable, and does it do what it’s supposed to do?” If yes, ship it. Perfect is not a deliverable.
VII. The Illumination of the Wrong Branch
Here be recorded the Great Confusion of Main and Feature.
The practitioner had been working for three hours. The code was good. The code was tested. The code was committed, and the practitioner, with the satisfaction of the weary and the righteous, typed git push. And Claude had been helpful throughout. Claude had written the commits. Claude had written the commit messages. Claude had not been told — because it seemed so obvious as to go without saying — which branch this work was intended for. And the work was intended for feature/user-auth. And git push pushed to origin main. And the CI pipeline began. And the Slack message from the release manager arrived approximately ninety seconds later, and the message was brief, and it was capitalized.
The Record: Code intended for a feature branch was pushed to the main branch, either because the practitioner failed to specify the branch context to Claude, because git push defaulted to the currently checked-out branch (which was main), or because the practitioner had not verified their branch before executing. The CI pipeline caught some of it. The release manager caught the rest.
The Moral: Branch context is context. Claude does not know your branching strategy unless you tell it. Claude does not check whether you are on main before proposing a git push. Branch protection rules exist because human beings make this specific error with impressive regularity.
The Prevention: Enable branch protection on main and require pull requests — do not rely on willpower and situational awareness, because both fail under deadline pressure. Begin every session that involves git operations with git branch to confirm where you are. Include your branching conventions in your CLAUDE.md so that Claude proposes correct branch names by default. Before any push, type git status and read the full output. “On branch main” is important information. It is right there in the output. Read it.
VIII. The Illumination of the Missing Test
Here be recorded the Code That Worked Except When It Ran.
The code worked in the conversation. This was established. Claude had traced through the logic. The practitioner had nodded along. The reasoning was sound, the approach was elegant, and there was a general feeling of things being correct that is, it turns out, not a substitute for the tests actually passing. The function was committed. The pipeline ran. The test — which had not been written during the conversation, but which had been assumed to be self-evidently passable — did not pass. The edge case that the tests found was not an edge case anyone had discussed. It was the kind of edge case that only a test finds, because tests are the only thing that asks the actual question: does this code do what it is supposed to do, in the conditions under which it will actually run, with actual inputs?
The Record: Code that seemed correct in conversation was shipped without test coverage. A condition that was not discussed — a null input, an empty array, a timezone edge case, a race condition — manifested in the test pipeline or, worse, in production. The conversational reasoning had been correct about the happy path and silent about everything else.
The Moral: A conversation is not a test. A conversation is two parties reasoning about code. A test is the code itself being asked to perform. These are different activities with different error-finding properties. The test finds what the conversation misses because the test does not reason — it executes.
The Prevention: Write tests. Run them before committing. Ask Claude to help you identify edge cases before the code is finalized, not after it fails. When Claude writes a function, ask: “What inputs would cause this to fail?” and then write tests for exactly those inputs. Never commit code that adds a function without adding a test for that function. This is not perfectionism; it is the minimum viable practice of a practitioner who does not want to explain things to the release manager at 11pm.
IX. The Illumination of the Friday Deploy
Here be recorded the Deploy That Should Have Waited.
It was 4:47 on a Friday. The feature was done. The feature was tested. The PR had been approved and the approval was, in the estimation of the practitioner, fully sufficient and the deploy was, in the estimation of the practitioner, an administrative formality. “It’ll be fine,” they typed. Claude, who does not know what day of the week it is and has no opinion about deployment timing, said it would be fine. And it was fine, for eleven minutes. And then it was not fine. And the on-call rotation for that weekend was the practitioner themselves. And the rollback was manual. And the root cause was not the feature, but a dependency that the feature had disturbed, and the disturbance was not visible in tests because the tests did not test that particular dependency in that particular configuration, and it was a very long weekend, and the Monday standup was attended by a practitioner who had not slept as much as they required.
The Record: A deploy was executed on a Friday afternoon, close to end-of-business. An issue emerged over the weekend. On-call coverage was sparse. The rollback and investigation extended into personal time. The feature itself was fine. The timing was not.
The Moral: Friday deploys are not a technical error. They are a scheduling error with technical consequences. The code does not know it is Friday. The monitoring does not sleep for the weekend. The practitioners do. This is the asymmetry that makes Friday deploys a form of institutional self-harm.
The Prevention: Do not deploy to production after 3pm on a Friday unless the alternative is worse. If you must deploy late on a Friday, ensure on-call coverage is confirmed and alert, a rollback plan is documented and verified, and the deploy is monitored for at least thirty minutes before anyone leaves. Add this to your CLAUDE.md: “Do not suggest deployment timing; always recommend verifying deployment calendar and on-call coverage before merging to main on a Friday afternoon.” Claude cannot read the calendar. You can.
X. The Illumination of the Phantom Dependency
Here be recorded the Library That Dwelt Only in Imagination.
Claude had recommended a package, and the package’s name was plausible, and its described interface was elegant, and the practitioner had installed it — or tried to — and npm install claude-suggested-package-name had returned a result that was, upon reflection, not the result of a successful install. The package was not on the registry. It had never been on the registry. Its name was the kind of name a library like that would have, if such a library existed, which it did not. And the practitioner, who had built an entire integration around the hypothetical API, had to stop, and reconsider, and find the library that actually did what they needed, which had a different name and a slightly different interface, and the afternoon of integration work became an afternoon of research and then an evening of integration work.
The Record: Claude named a specific npm package, Python library, or other external dependency that did not exist. The name was plausible — similar to real packages in the same domain. The practitioner attempted to install and use it before verifying its existence. Integration work was done against an interface that could not be fulfilled.
The Moral: Package names are facts. Facts require verification. The name of a library is not a description of a library — it is a proper noun that either maps to something real or does not. Claude is confident about proper nouns it has fabricated with the same confidence it applies to real ones. This is a known property of the model. Consult the registry; do not trust the name.
The Prevention: Before writing a single line of integration code against a named library, verify its existence on the relevant package registry: npmjs.com, pypi.org, crates.io, the GitHub search. This takes thirty seconds. The verification step is not optional; it is the first line of the integration task. When you find the correct library (which may have a different name), paste its actual documentation into the conversation before asking Claude to help you use it. Do not trust Claude’s knowledge of specific version numbers. Look them up. They change.
Closing Benediction
Go forth, and may your API return 200 OK.
May your context be summarized before it overflows. May your functions be verified before they are committed. May your CLAUDE.md be current, your diffs reviewed before acceptance, and your deploys scheduled with awareness of the calendar and the on-call rotation.
When the 529 arrives — and it will arrive, for it visits all practitioners in its season — sit with your thoughts. Write down what you know without assistance. Update your documentation. You will return, and the API will receive you, and you will have lost only the time and gained something harder to name.
Let these records be not a taxonomy of shame, but a library of mercy: the suffering of the ones who came before, preserved so that you might make different mistakes.
For the practitioner who makes no mistakes is the practitioner who ships no code.
Write the tests. Read the diffs. Check the branch. Verify the package.
And if all else fails — type /clear, and begin again, having learned at least one thing you did not know before.
Thus are the calamities illuminated. Thus shall they be remembered.
The record closes here. The errors do not.