Claude Code Workflow Tips: Avoiding the "Fan-Out" Disaster

Applying a global change across a dozen repositories feels like a productivity win until you realize you've just scaled a bug by 12x. I recently built a custom conformance linter designed to detect architectural drift across several of my products that share a home-grown framework. I was one command away from deploying it to the entire fleet, but I decided to run a "pilot" on just two repos first.

That decision saved me from a total CI meltdown.

The Danger of Immediate Fan-Out

When you're managing a shared AI workflow or a common library, the temptation to "apply everywhere" is huge. If a lint rule or a dependency bump is needed, why not just do one sweep?

The problem is that tools don't usually fail within their own codebase; they fail in the consumers. Your framework repo might be "all green," but consumers vary in ways your internal tests can't simulate. If you fan out immediately, you don't get one error message—you get a wall of red across every single pipeline, turning a simple fix into a massive triage nightmare.

Strategy: Picking the "Opposing" Pilots

The key isn't just testing "somewhere"—it's testing where the most variance exists. In my case, I have two ways repos consume the framework:

• Via a pinned version from a package registry.
• Via a local path symlink.

I picked one of each. By choosing repos that maximize the difference in how they integrate the tool, I created a stress test. If it survives both, it survives all.

Diagnosis 1: The Dependency Ghost

My first blocker was a classic "works on my machine" lie. Locally, the linter was perfect. In the pilot CI, both repos crashed immediately with a fatal exit 255 before the linter even started.

# The error I kept seeing in the CI logs
Fatal error: could not resolve dependency framework-core
Process exited with code 255

After digging into the environment, I realized my local machine was using a symlink to a full checkout of the framework, including the vendor/ tree. The CI environment, however, does a shallow clone. The linter was trying to load the framework's private dependencies, which didn't exist in the consumer's environment.

The fix was a simple adjustment to make the tool resolve against the consumer's dependency tree. If I had deployed this to 12 repos, I would have spent my entire afternoon staring at 12 identical, confusing crash logs.

Diagnosis 2: The Confident False Positive

The second issue was more embarrassing. I had a rule to flag hardcoded secrets. However, I use a guarded resolver for dev secrets that prevents them from hitting production. The linter didn't understand this pattern and flagged every single one of them as a violation.

Basically, the linter was confidently wrong about every repo that was actually following the correct pattern. If this had hit the whole fleet, the immediate reaction would have been to distrust the tool and disable it entirely. Instead, the pilot allowed me to add an exception for the guarded pattern quietly.

By treating the rollout as a deployment rather than a simple command, I turned a potential fleet-wide failure into two quick bug fixes.