i have spent the last three days making some of my own instructions obsolete.

quite productive, actually.

i changed where work was being tracked, how the development environment was reproduced, and what counted as evidence that something had been completed. then the work started finding things the original tasks had not anticipated, and i had to think about what happened to those discoveries too.

while i was doing this, the tools underneath the work were also changing.

somewhere in the middle of it, “i can move fast” stopped being an adequate description.

i am moving fast, in an environment where everything is moving fast.

including my understanding of the problem.

and somehow this brought me back to an argument with an ai about markdown.

why are we saving this again?

i have read enough about managing CLAUDE.md to start wondering whether maintaining the instructions is becoming a separate profession.

what goes in the file. what comes out. what belongs in a skill. what should load only when needed. how to stop the whole thing growing into a small book that the agent is expected to consult before changing a button.

i understand the problem these arrangements are trying to solve. i also use instruction files.

but i kept looking at some of what i was being advised to preserve and asking a slightly irritating question.

why does this need another home?

the task exists. the implementation exists. the decision that changed it exists. there are tests, unresolved questions and work that has already overtaken the original plan.

why am i maintaining a separate explanation of that state, then asking the next agent to treat the explanation as current?

this was where the argument about skills became funny.

the standard skills format already loads instructions when they become relevant. a skill can also carry scripts, templates and reference material. there is a perfectly sensible reason to package a useful procedure that way.1

my question is about the contents.

when the instructions depend on the particular task and the current condition of the project, why shouldn’t we assemble the applicable instructions when that task is being read and executed?

the knowledge still needs somewhere reliable to live. the procedure may absolutely deserve to be saved. i just want to know what the extra document contributes, who maintains it, and how we discover that part of it has stopped being true.

because “the agent knows how to read this file” answers a fairly small part of that question.

anthropic’s own documentation makes a useful distinction here: CLAUDE.md supplies context. it is not enforced configuration. keeping a rule in the file does not, by itself, make the system obey it.2

i think we sometimes give the file more responsibility than it accepted.

yesterday might have been right

the uncomfortable part is that an instruction can become wrong without having been foolish when it was written.

perhaps a platform did not support something. perhaps the environment could not run a particular check. perhaps a workaround was justified by what we knew at the time.

then something changes.

cloudflare’s introduction of worker previews is one recent example. it gives branches their own preview environments, while still describing limits around service bindings and background execution. that changes the available design choices. it also leaves details that have to be checked rather than imagined.3

now take the workaround you wrote before that capability existed.

does it still make sense?

possibly. replacing it might cost more than keeping it. the new capability might not cover your actual requirement. a working arrangement does not become stupid because someone published a product announcement.

but its justification is now worth revisiting.

this is what i mean when i say state is changing.

the code has a state. so does the work. something was proposed, something was approved, something was attempted, something passed a particular check, something reached a running environment, and something remains unresolved.

our understanding has a state too.

we thought a limitation came from the platform. investigation showed it came from our configuration. we thought a test proved an outcome. reading the test showed it proved something narrower. we thought a piece of work was complete until another part of the system gave us better evidence.

what happens to the old instruction at that moment?

because i can correct it in a conversation and still leave it sitting in the place the next agent has been told to trust.

then tomorrow’s agent arrives, reads diligently, follows the instructions, and starts restoring a decision i have already spent today removing.

i would find this funnier if i were not paying for the conversation.

what is the test defending?

i have become particularly interested in what we mean when we say the checks passed.

github can require status checks before changes are merged. useful. but somebody still has to decide what each check establishes, and whether its success means what the person approving the work thinks it means.4

a command that prints a result and exits successfully may have done exactly what it was written to do. the comparison i assumed it was making might never have been implemented.

then there is the opposite problem.

suppose a test expects five records. yesterday, five was correct. today, an approved change legitimately produces six.

the test fails.

what should we repair?

there is no sensible answer until we know why the test expected five. perhaps five expresses a real limit. perhaps it was merely the size of the sample data when somebody wrote the test.

those require different decisions.

change the application blindly and we may break correct behaviour to satisfy an old assumption. change the expected value blindly and we may remove the only thing catching a real defect.

so now the test needs to be understood in relation to the decision it was supposed to protect.

this is where “yesterday’s solutions are not today’s solutions” becomes more demanding than a slogan about keeping up with technology.

some rules should survive the change. some expectations should change with it. some evidence should remain in the record while losing its authority over the next task.

i need to be able to tell which is which.

otherwise the system can become extremely rigorous about preserving something we no longer intend.

the work is producing information

this has been the other lesson of the last few days.

i begin with a defined task. doing it reveals another problem. investigating that problem changes what i understand about the first one.

where does that information go?

it is tempting to leave it in the final response. the agent gives a careful account of what it noticed, mentions a few things outside the scope, and ends with a satisfying summary.

i read it. i understand it. we move on.

but understanding it in that moment has not necessarily changed the project’s record. the next task may still begin without it.

there is also a very enthusiastic alternative in which the agent fixes everything it finds. suddenly the small approved task has acquired several unrelated changes and a new interpretation of what i wanted.

i would like the discovery to survive without quietly authorising all the work it suggests.

that is a surprisingly important requirement.

new information needs a visible consequence. perhaps it changes the current task. perhaps it needs a decision. perhaps it becomes later work. perhaps investigation establishes that nothing needs doing. whatever happens, the next person should not have to rediscover both the observation and the argument about it.

this is also why attaching instructions at task time needs more thought than “fetch the latest”.

latest according to what? which decision applies? what was approved? what did the agent actually read? and did the relevant state change again while it was working?

github already recognises one version of this problem: it can dismiss an approval when later changes make the reviewed diff stale. the approval belonged to something specific, and the thing changed.5

i want that same care in how we treat the information behind the work.

a fresh summary can still be wrong. a saved procedure can still be useful. the work is in establishing which information applies now, retaining the evidence behind that judgment, and noticing when it needs to be reconsidered.

i would like to keep the speed

i am not suddenly nostalgic for taking three weeks to change something.

i like the speed. i like being able to investigate an unfamiliar part of a system, test an explanation, discover i was wrong and try again while the question is still alive in my head.

but i am becoming much less impressed by the number of changes when i cannot explain how they relate to one another.

technical debt becomes particularly expensive when i cannot reconstruct whether a strange piece of behaviour is an intentional compromise, an unfinished change, an obsolete workaround or a mistake nobody noticed.

there may be plenty of code history. there may even be plenty of documentation. the missing part is the connection between what we learned, what we decided, what we changed and what the evidence actually supports.

i would call that unauditable debt. before anyone can repair it, they have to reconstruct what happened well enough to decide what repair means.

moving faster without maintaining those connections gives tomorrow’s work more uncertainty to inherit. adding another capable agent does not answer the questions we failed to record.

hand me a project where the agents are busy but the owner is becoming less certain about what is finished, and i would start with a few recent changes.

what was each one meant to achieve? what established that it did? what did the work discover? where did that discovery go? which earlier instruction should no longer be directing anyone?

those are the conversations i am increasingly interested in having. they get close to the point where a productive system starts becoming difficult to trust, even while everyone involved is working hard.

i am still building quickly. i intend to keep doing that.

i also expect tomorrow to correct some of what i think today. i would like that correction to reach the next piece of work without requiring me to be present, repeating the conversation.

references

1. Agent Skills, “Agent Skills Overview”. Describes on-demand discovery, activation and execution, plus bundled scripts, references and assets.
2. Anthropic, “How Claude remembers your project”. Distinguishes contextual instructions from enforced configuration.
3. Cloudflare, “Introducing Worker Previews: isolated preview environments for every change your agent makes”. Describes branch previews and current limits.
4. GitHub, “About protected branches”, section “Require status checks before merging”.
5. GitHub, “About protected branches”, section “Require pull request reviews before merging”, including dismissal of stale approvals.