Claude Code Gotchas

# Imperfections # As I said, I’ve been using Claude Code for about a month on tasks of various sizes and levels of ambiguity. Some tasks have been bug fixes to existing code. Some tasks have been new features that leverage a small amount of existing code. As I’ve used Claude Code more, I’ve observed some failure modes. Here’s a quick synopsis of each. 1. Claude Code gives up too early. 2. Claude Code runs out of context. After it compacts the context, it’s dumber. 3. Claude Code writes a lot of failing tests and needs to see the tests fail to fix them. 4. Claude Code will change the test to match bad code when it’s way easier to do that than fix the code. 5. Claude Code forgets how to compile, or that it needs to compile to run tests. 6. Claude Code leaves crap around in the working directory. 7. Claude Code uses weird Git commands. 8. Claude Code will decide to rewrite something and leave the old stuff around. Now, I’ll dive into each and explain any workarounds. … For instance, Claude Code really struggled with this feature Pull Request. ... However, even with all these examples, having Claude Code examine existing tests to construct new tests for itself is often fraught with peril. Often, Claude Code will generate tests look right at first glance but fail on first encounter with implemented code. Claude Code will loop until both the code compiles and the tests pass. A poorly defined test can throw Claude Code into a death spiral of bad test, bad code, feature not to specification. Thus, I recommend using Claude Code in a “test driven development” fashion by having it write the tests first. Then, spend a bit more time than usual in review of the generated tests. After this process, as it implements your bug fix or feature, be very wary of changes to your tests. … ## Forgets to Compile # Claude Code will forget how to compile your application. Even if the steps are in `CLAUDE.md`, Claude Code will get confused and may need help with compilation. This is especially true when dealing with dependency changes like those specified in `go.mod`. Claude Code will also forget to compile before it runs your tests. This can be frustrating but I take solace in the fact that I’ve made the mistake myself. If you work on interpreted languages, interspersed with compiled languages, it’s natural to just write the code and run the tests. Claude Code must have a lot of interpreted language data in its training data. Claude Code will be looping saying the tests pass or fail looking for some smoking gun. I often have to press `esc` and tell Claude Code to `go install` so BATS gets the new `dolt`. “You’re absolutely right!” and it’s back on track. Once you know the pattern, you can save yourself a lot of tokens by making sure Claude Code is not stuck in this fashion when tests are passing or failing unexpectedly. … ## Rewrite without a Corresponding Delete # For my large PR described above, at one point, Claude Code decided to make a new implementation from scratch. Instead of deleting what was there, it created parallel functions with the “New” prefix. It ended up making a working implementation which was great. But even after being instructed to clean up the old code, it left a partial implementation that my colleague caught in code review. The dead code was sufficiently interspersed in the file that I did not catch it on review. This was somewhat embarrassing. My colleague asked “There’s a bunch of objects created that are never used. Does Claude Code usually do that?”