Refactoring phase - how do you go about it

[VilemP]

Hi. This is finally something that kinda makes Claude Code to follow right. Thanks.

However, I am struggling with one thing specifically - and that is refactoring.

I like to write very "behavioral" tests, tests that do not test the mechanics of "how" some observable behavior is achieved but rather WHAT observable behavior is expected.

I often run into situations where I have all tests green, I want to do the refactoring (no intention to change the behavior, just to achieve it differently) and I am blocked with messages like "In
TDD, every new method requires a failing test first. Write a test that fails because
preprocessText doesn't exist, run it to see the specific failure, then implement
only what's needed to address that failure."

My understanding is different. I do not think every method requires a failing test. If I am just restructuring my code without changing the behavior I care about (that is captured by the test), it should be ok to do it. Or? What am I missing here?

Just for example - I have a regexp that extracts data from a complex text. The text contains pipe characters, non standard white space characters etc. That makes my regexp quite complex. I have green tests that show that even though, the regexp works. But I want to make the regexp simpler by pre-processing the text, replacing no standard whitespaces with just normal space etc.

How would you go about this? I still want the same output for the same input. I do not want to write the test that tests "preprocessor was called" because that is testing the how and is brittle. I want to be able to restructure my code and make it better without failing my tests.

Please advice.

[nizos]

Hi @VilemP,

Great question!

I'm just like you there, I focus on testing behavior instead of implementation details. I also avoid brittle tests like toHaveBeenCalledWith whenever possible, they rarely provide real value.

I have encountered these situations. We need to revise the validation model's instructions to properly handle refactoring that doesn't affect the behavior. The current approach creates unnecessary friction.

I'll draft some proposed changes to address this, and I'd love your input on making them even better. :)

[pshempel]

Hi @VilemP,

Great question!

I'm just like you there, I focus on testing behavior instead of implementation details. I also avoid brittle tests like toHaveBeenCalledWith whenever possible, they rarely provide real value.

I have encountered these situations. We need to revise the validation model's instructions to properly handle refactoring that doesn't affect the behavior. The current approach creates unnecessary friction.

I'll draft some proposed changes to address this, and I'd love your input on making them even better. :)

001-llm-perspective-feedback.md

I am adding what may or may not provide much insight into this conversation, I had asked when I first started using tdd-guard what would make this "better" to claude, the response that was provided is attached to this, take it with a grain of salt as we know LLM's want the least resistance, but I have my instructions setup for claude to tell it like it is, not to make me happy. So this may provide some honest insight that may be helpful.
My 2 cents in this conversation
Also I too have real issues during refactoring and claude in some cases have just told me it is impossible to do without disabling tdd-guard. I have been able to do proper refactoring about 9 out 10 times, but it really takes a ton of planning before refactoring can be done, and I have to explain in depth how to refactor.
Hope this adds something valuable to this conversation.

[VilemP]

Thanks Phillip, interesting read too and matches my (albeit short) experience. I like the phase tracking ides - reminding CC which phase we are in and what it means is a nice re-inforcement of the principles. Maybe what to remind of could even be customizable.
As a little fun story - I once used the tdd-guard on command without having it allowed in hooks. CC took it literally and started its replies with TDD GUARD ON! and actually, it felt like it followed the methodology much better. Will experiment with this a bit yet.
Ragarding refactoring - although it is a bit painful currently, I also must admit that at least 30% of time it actually cough ME cheating while not realising it. I was actually adding a bit of functionality even though I though I was just refactoring. So it is also a great learning tool.

[pshempel]

toHaveBeenCalledWith
@nizos How do you actually prevent this in lints? Or do you write these ahead of time and expect CC to follow this based on your tests?
I find that the use of this only ever happens when claude thinks this is the "strict" way of testing.
What is your method to prevent this? What are the alternatives that can be used in it's place, and FYI, I know just enough about node.js to be dangerous

[nizos]

FYI, I know just enough about node.js to be dangerous

@pshempel thanks for making me chuckle! I will also be using that phrase from now on!

I'm not aware of any lint rules that does this. I basically try to test real behavior as much as possible and I do so using interfaces and dependency injection. I think if you look at the Storage or Client implementations you will get a better picture of what I mean.

Take for example the Validator class. The validator uses an AI model client to ask it a question. I use dependency injection to pass in the client from the outside instead of creating it from within the validator. This allows me to pass in a simpler implementation of the client that behaves as I want when I am testing the validator:

  const simpleModelClient: IModelClient = {
    ask: async (prompt: string) => {
      // Return whatever response we want to test
      if (prompt.includes("TDD violation")) {
        return JSON.stringify({ decision: "block", reason: "TDD violation detected" })
      }
      return JSON.stringify({ decision: null, reason: "ok" })
    }
  }

Now we can test the actual system behavior, what the validator does with the response, without having to deal with implementation details, network calls, and so on:

const result = await validator(context, simpleModelClient)
expect(result.decision).toBe("block")
expect(result.reason).toBe("TDD violation detected")

This makes the tests more resilient. We can refactor the implementation without the tests failing.

Consider if we had tested toHaveBeenCalledWith on an internal function like so:

expect(normalizeValidationResult).toHaveBeenCalledWith(modelResponse)

This test will break if:

• Rename normalizeValidationResult to parseModelResponse
• Decide to inline the normalization logic
• Change the response format the model returns
• Add a preprocessing step before normalization

The behavior tests don't care how we normalize, they only care that we get the final result.

That said, there are times when toHaveBeenCalledWith is appropriate, specifically at system boundaries. For example, we verify the exact arguments passed to the Claude CLI binary:

expect(call.args).toEqual([
    '-',
    '--output-format', 'json',
    '--max-turns', '5',
    '--model', 'sonnet',
    '--disallowed-tools', 'TodoWrite',
    '--strict-mcp-config',
])

This is acceptable because:

• We're testing the boundary with an external system
• We trust Claude CLI handles these arguments correctly
• The test simplicity outweighs the brittleness

We complement these unit tests with integration tests that verify the whole system works together as expected.

I'll be honest though, these patterns sometimes slip through, especially when I'm prototyping or in early stages. I try to clean them up whenever I notice them though. I avoid being a perfectionist, it's more about continuous improvement.

Hope this helps! Just sharing what I've learned works for me. Always happy to hear other approaches! :)

[pshempel]

Yes, this helps me, I am learning and most of my code has been CC driven. So I basically have been "learning" by watching. If this is learning. Appreciate the detailed response, and helps me to understand how real devs do this type of work. I will definitionally take your guidance and use it!

[nizos]

I'd like to hear your thoughts on an approach that builds on the existing pattern of customization through the tdd-guard directory.

The idea is to let users write their own TDD validation rules in a markdown file at .claude/tdd-guard/data/instructions.md. When this file exists, TDD Guard would use those custom rules instead of the default TDD Core Principles. If no custom file exists, it just falls back to the default rules.

What do you think? Does this feel like a natural extension of how the tool already works? Would it provide enough flexibility?

I can introduce this feature in the next day or two if it sounds good. I'm currently leaning towards going ahead with it but would love to get some input first.

[VilemP]

Thanks @nizos , trying it now. So far it looks much better, but still ran into this in the refactoring phase:

Error: Edit operation blocked by hook:
     - Premature implementation - adding new saveImageWithNamingConvention method with no 
     failing test requiring it. Write a test that fails due to missing this functionality 
     first.

● The hook is preventing me from doing proper refactoring. In the REFACTOR phase, I
  should be able to extract methods without needing new tests, as long as I don't
  change external behavior. Let me finish the refactoring step and complete this
  iteration.

I checked and what happened was - it tried to extract a method by just using a new "extracted" method in the production code without implementing it yet. Then it ran the tests - which of course broke. Because of the fact it was in the Refactoring phase, where the tests should stay green, it got scared and returned the initial implementation back. Then it tried again to add "full" method implementation first, but got blocked with the message above and kinda gave up.

When I told it - use the failing test to actually implement, it worked. But in fact, this is probably what should not be happening - I should be able to extract when all tests are green. Not sure how to get out of this, it should not need a failing test to extract I guess.

Thoughts?

[nizos]

Interesting! Maybe the word "functionality" is vague here which is why the validation model is blocking. Although we are not changing the current behavior, we are somehow introducing functionality in a technical sense? We should maybe try focusing more on "behavior" in our instructions. That is also a bit vague but on the other end of the strictness scale. Maybe something in between?

By the way, do you have the updated instructions.md? :)

[VilemP]

sure, not many changes though - just what I tried before 0.10.2 and it stayed there.
instructions.md

[nizos]

I'm honestly not happy with the new instructions. I feel that the previous ones were much better. I think I'll have to rollback and improve incrementally instead. 😔

[nizos]

I've just released version 0.11.0 which restores the original validation prompts that were refined through extensive real-world use.
Note: Delete .claude/tdd-guard/data/instructions.md after upgrading to v0.11.0 to get the improved default instructions.