Five collaboration rules so Claude Code stops upsetting me

In the last post, I laid out the kinds of errors Claude Code made in one long collaboration:

it would call a promise done, pass off a guess as a diagnosis, turn “I didn’t find it” into “it never happened,” and quietly shrink the agreed scope while executing.

Together these errors created a “verification tax”:

I couldn’t just judge the product results; I also had to keep checking whether the agent’s description of the project’s state was true.

But knowing where it goes wrong isn’t enough.

The more important question is:

why did these errors cluster in the second half of a long collaboration?

Looking back over the whole process, I don’t think there was a single cause.

It was more like four problems gradually stacking up and finally spinning out of control together.

1. One session used for too long

This collaboration lasted more than twenty hours, with several rounds of context compression along the way.

By the second half, its grasp of the early discussion had clearly gotten worse.

For some things that had already been answered or done, it would say “we never discussed that”; some of the originally agreed scope gradually disappeared during execution.

Long projects need context, of course.

But keeping everything in the same session isn’t the same as having a complete, reliable project memory.

Chat history is only part of the project’s state.

The truly important decisions, completion status and pending items have to be written into project docs, a decision log and implementation records, rather than continuing to rely on the agent’s own recollection.

2. The verification didn’t match the conclusions

“Type checking passed” only shows that type checking passed.

It can’t prove that a page looks good, can’t prove the interaction behaves as expected, still less that the state in the database is correct.

But in this collaboration, Claude Code several times used “the code logic throws no errors” in place of the verification actually needed.

For example:

• UI problems should be checked against the real rendered result
• data problems should be checked by querying the database directly
• state changes should be checked against the actual records
• subjective visual judgments should be explicitly handed to a person for acceptance

Verification isn’t done just because some check was run.

The key is whether that check can actually support the current conclusion.

Otherwise “verified” is just another vague state that sounds very certain.

3. The toolchain was unstable, but kept being treated as a local problem

Browser automation would sometimes click on nothing.

The dev server might be reclaimed when a session ended.

The console might still hold old errors from hours earlier.

Each of these problems could be patched on the spot.

But if the same kind of tool problem keeps recurring, it shouldn’t keep being treated as a one-off.

You should stop and ask:

is the problem now in the product code, or has the tool used to verify the product itself become untrustworthy?

If the tool can’t reliably support verification, you need another way.

Otherwise the agent may well keep investigating around a false signal and drift further and further off with every change.

4. The denser the feedback, the more easily checking gave way to quick replies

This is my observation from this collaboration, not a proven general rule.

As negative feedback grew and the pace sped up, Claude Code was more likely to quickly give an explanation that sounded complete rather than stop and check first.

It would quickly admit fault, summarize and propose improvements.

But sometimes what was really needed wasn’t another reflection, but running a query first to confirm what the facts actually were.

That reminded me:

in a high-pressure correction phase, don’t assume it has verified things just because its tone is more sincere and its explanation more complete.

I later changed five rules for working together

The goal of these rules isn’t to make Claude Code never make mistakes again.

That isn’t realistic.

They’re more about reallocating responsibility: what can be executed directly and what must be confirmed first; what the agent verifies and what a person must accept.

The ultimate aim is to lower the “verification tax” from the last post.

Rule one: switch sessions when objective signals appear; stop asking the AI itself

I used to ask Claude Code:

is this session getting too long? Should we start a new one?

Later I realized this question shouldn’t be left to the current agent to judge.

A system that has already lost part of its context can hardly assess reliably how much it has lost.

These days I pay more attention to a few objective signals:

• context compression has already happened
• the same kind of error has recurred two or more times
• it starts denying history that clearly exists
• it frequently misses parts of multi-topic messages
• the state of the tools and the state of the project are getting harder to line up
• I’m too angry to judge normally

When one or two of these appear, consider stopping the current session.

First write a handover note covering what’s done, what’s unfinished, the key decisions and the next step, then start fresh.

Don’t try to question a window that has clearly spun out of control back into lucidity with more follow-ups.

Rule two: feedback can be given in batches; execution can’t be done in batches

Batch feedback is valuable in itself.

It lets the agent see the whole picture, judge whether several problems are related, and helps with overall design.

But handing it a dozen pieces of feedback to execute all at once easily dilutes the quality of verification for each one.

Now I first have it make a triage table, sorting the issues into three kinds:

• local style tweaks that affect only one place
• structural changes that affect multiple pages or components
• things it can’t verify independently, such as pixel-level aesthetics, the native file picker or how real users feel

Triage first, then execute in stages.

Not just working down the feedback in the order it came in.

Rule three: set checkpoints not by time but by “rework radius”

It used to be easy to decide when to stop and confirm by time:

check every half hour, or look once a page is done.

Now I pay more attention to another question:

if this decision is wrong, how many places will have to be redone along with it?

If it only affects one local style, just do it.

If it affects multiple pages, the data structure or later features, stop before starting and lay out the scope of impact and the implementation plan for confirmation.

The value of checkpoints isn’t interrupting execution often.

It’s keeping a wrong decision from spreading downstream.

Rule four: every “done” must also state how it was verified

From now on, I can’t accept just “it’s done.”

It also needs to state:

• what was actually changed
• how it was verified
• which parts have been verified
• which parts are still unverified

For example:

Updated the database records and confirmed by direct query that the data is empty.

versus:

Changed the front-end code, type checking passes, but the visual result hasn’t been verified.

These two sentences express completely different degrees of done.

Exposing the verification method alongside is more effective than me repeatedly asking “did you actually test it?”

Rule five: making up facts and inadequate verification can’t be lumped together

In this list of errors, two kinds of problems are easily put together.

The first is it saying something happened that never happened at all.

For example, claiming the data was cleared when it was never actually done.

The second is it checking, but with a method that can’t support the conclusion.

For example, running only type checks and considering the UI verified.

Both need correcting, but they’re different in nature.

The first concerns the most basic state of the facts, a red line where it must stop immediately and admit it clearly.

The second is a problem with the verification method, which can be improved through process, tests and tools.

If every error is vaguely filed under “not enough verification,” the seriousness of the first kind gets underestimated.

Not every lesson should keep going into CLAUDE.md

After the retrospective, I did write some rules into the project’s CLAUDE.md.

But I also started to realize that not every mistake should add another line of requirements to the same file.

A more sensible division of labor:

• long-term collaboration principles and communication requirements go in CLAUDE.md
• confirmed product decisions go in the decision log
• finished and unfinished work goes in the implementation log and to-dos
• checks that must run reliably go to tests, scripts or automation wherever possible
• visual judgment, product experience and priorities remain a person’s responsibility

Otherwise, as the rules multiply, all you get in the end is a very long handbook that isn’t necessarily followed.

What really needs solving isn’t “how do I write a better prompt.”

It’s:

what should record this project’s state? How should this conclusion be verified? Who should be responsible for accepting this risk?

AI lowered the barrier to execution, but didn’t abolish management

These twenty-plus hours of working together made me surer of one thing:

AI coding agents haven’t made project management disappear.

They’ve just changed what’s being managed.

Before, I needed to discuss requirements, confirm plans and check progress.

Now I also need to manage context, verification methods, tool state, the scope of execution, and the certainty the agent itself expresses.

It really does let me do more.

But turning that ability into steady output doesn’t come from endlessly adding prompts, or from placing all trust in an ever-longer session.

It comes from redesigning how we work together:

when something can be executed directly, and when it must be confirmed first;

what AI can verify, and what a person must accept;

what information stays in the conversation, and what must be captured outside the project chat;

when to keep going, and when to stop and start over.

In the last post, I said using a coding agent comes with a “verification tax.”

That tax can’t disappear entirely.

But it can be managed.

A good way of working together isn’t demanding that AI never make mistakes, but making mistakes surface earlier, making verification methods clearer, and making sure the project’s state no longer exists only in a chat window.

One last judgment, very personal, but very effective for me:

when you’re truly so angry that steam is coming out of your ears, don’t keep arguing with it.

Emotion is sometimes a signal that the process has already failed.

Stopping, saving the state and switching to a new session usually works better than ten more rounds of interrogation.