Claude Code Anti-Patterns: Team Adoption Failure Modes

Claude Code anti-patterns are the rollout failure modes that show up after the procurement story is over and the behavioural story begins. Eight of them recur across the engagements we have audited this year — visible in .claude/ directories, in commit history, in the gap between licence telemetry and actual engineering throughput. None of them are bugs in the tool. All of them are failures of curation, governance, or measurement on the team side, and all of them stall rollouts for a quarter or two before anyone names them.

This is the contrarian framing because most rollout retros land on the wrong axis. The team blames the model, the season, the skeptics, the budget. The artefacts in the repo tell a different story: a CLAUDE.md the model has long since stopped reading in full, fifty half-finished skills no one remembers, a permissions allowlist that has been growing for six months without anyone reviewing it, hook configurations that fire on every event and train the team to ignore notifications. Tools do not stall rollouts. The patterns around the tools do.

The structure below is consistent across the eight: a one-line diagnostic signal you can read off the repo in under a minute, the failure shape we see most often, and the corrective pattern we have shipped on at least three engagements. The aim is to give an engineering manager a checklist sharp enough to catch the stall in the first month, not the fourth.

The first anti-pattern is the one that contains all the others: mistaking procurement for adoption. A purchasing team can provision seats inside a week. A licensing dashboard can confirm those seats are active. None of that describes whether the engineering team has changed how it works. The most common failure mode in 2026 rollouts is a leadership team running on licence telemetry while the underlying engineering practice has not budged.

The diagnostic signal is straightforward. Open the team's shared repo. Look for .claude/skills/. Look for .claude/agents/. Look for a hook block in settings.json. If all three are empty or absent and the dashboard says ninety-five percent licence engagement, you are looking at a tool that is being used as autocomplete and being reported as transformation. The gap between those two postures is the gap that stalls rollouts.

The corrective pattern is measurement on the behaviour side. We cover the full framework in the 50-point adoption scorecard, but the minimum-viable version is three numbers tracked weekly: subagent invocations per active user, skill invocations per active user, and CLAUDE.md line count trended over time. Those three signals separate the engaged users from the adopted-but-idle ones inside a fortnight.

The second anti-pattern is the failure mode of the team that took adoption seriously and then over-corrected. A motivated tech lead reads the docs, ships skills enthusiastically, the library grows. Six months in there are forty or fifty entries in .claude/skills/, of which the team actively uses six. The remainder are noise — drafts, experiments, half-finished, near-duplicates of each other, written by engineers who have since rotated off the team.

The diagnostic signal is the ratio between library size and weekly invocations. A healthy library is roughly one skill per two-to-three active users with weekly invocation counts that cluster around the top five entries. A sprawled library has fifty entries and the top five still account for ninety percent of the invocations — the rest sit at zero. The long tail is not dormant capacity; it is overhead.

The skill library is a curated catalogue, not an inbox. Every entry has to earn its slot — same discipline as a design system, same discipline as a public API surface. Teams that apply that discipline keep their libraries small, sharp, and heavily used. Teams that treat it as an inbox watch invocation counts collapse past the twenty-entry mark.

The third anti-pattern is the memory-file equivalent of skill sprawl. CLAUDE.md grows by accretion. Every incident, every convention, every team norm gets added, never removed. By the time the file is two thousand lines long the model is no longer reading it in full — it is sampling, paraphrasing, and on a bad day quietly ignoring sections that no longer match the rest of the repo. The team thinks the memory is comprehensive. The model thinks the memory is noise.

The diagnostic signal is line count plus drift. Two hundred lines is the sweet spot for most repos — the model will read that on every turn without compromise. Five hundred is workable with careful structure and explicit anchors. Past roughly a thousand, behaviour becomes unpredictable. The second half of the signal is drift: when was the file last edited, and does its content still match what the repo actually does. A six-month-old CLAUDE.md telling the model about deprecated patterns is worse than no memory at all.

The corrective pattern has two halves. The first is a prune — move the three sections most likely to be skimmed into linked sub-docs, replace the body with a one-line summary and the link, and re-audit a fortnight later. The second is a cadence — quarterly review, dated entries, a single owner who is accountable for the file's health. Without the cadence the prune is undone within two sprints.

One nuance from the engagements: the orchestrator-style CLAUDE.md (a master file that links out to many relevance-loaded sub-files) consistently outperforms the monolithic version, even at identical total line counts. The model handles small linked context far better than large blocks of inline context, and the linked structure is far easier to keep accurate across a quarter.

Permission drift is the security-side equivalent of skill sprawl. The allow-list in settings.json grows every time an engineer hits a permission prompt during a flow they did not want to interrupt. Two quarters later the list is twice as long, half of it covers tools that nobody on the team actively uses any more, and the gap between intended permissions and granted permissions has widened into something nobody could write down in one go.

The diagnostic signal is age plus turnover. How old are the entries on the list. How many of them were added by engineers who have since left the team. How many of them cover tool surfaces the team has since moved off. A healthy allow-list looks recent and intentional; a drifted one looks like a geological record.

The remediation is calendared review. Once a quarter, an owner walks the allow-list, removes anything that has not been invoked in the previous quarter, and challenges anything that covers a tool surface the team has retired. The work is small. The cost of not doing it accumulates until the quarter the wrong tool fires under the wrong allow-list and the incident review takes a week.

Hooks are the workflow-integration surface — the place where Claude Code becomes a participant in the team's shared workflow rather than a private assistant. They are also the surface most prone to over-eager configuration. A team that grasps the value of hooks tends to wire them to every lifecycle event inside a fortnight, which sounds like enthusiasm and ends up being noise.

The diagnostic signal is alert behaviour. If hook-driven notifications outnumber the team's real-time work events by more than a small multiple, engineers will start filtering them. Once filtering starts the hook is dead — even the important events get ignored alongside the routine ones. The corrective pattern is curation, same as the skill library, applied to lifecycle events.

Hooks are a curation problem dressed as an enthusiasm opportunity. Two well-chosen lifecycle events beat ten indiscriminate ones every time. Teams that take this seriously also build a habit of pruning old hooks alongside new ones — the same quarterly cadence that prunes skills and CLAUDE.md entries.

Three further anti-patterns recur often enough to flag, even though they tend to show up later in the rollout — after the base anti-patterns above have been recognised and partially addressed. Each is a governance failure rather than a curation failure, and the corrective patterns shift accordingly.

All three of these surface later because they require the team to have shipped enough artefacts that governance becomes necessary. A team with zero subagents cannot have a subagent-governance gap; a team with no shared skills cannot have skill orphans. The trade-off is real — the cost of engagement is that you now have artefacts to govern. The payoff is that the governance work is small and the engagement gains are large.

For the operational underpinning of the subagent point, our guide on building a Claude skill from scratch covers the SKILL.md format and the scoping discipline that separates a skill that earns its slot from one that becomes an orphan inside a quarter.

The final anti-pattern is the measurement-side equivalent of install-not-adopt. A team that has corrected the first seven anti-patterns can still stall on this one — measuring the wrong numbers, reporting the wrong success story to leadership, and quietly losing budget two quarters later when the reported metrics turn out not to predict any real engineering outcome.

The diagnostic signal is the gap between reported productivity and felt productivity. If the dashboard claims a meaningful uplift and the engineering managers cannot point to a workflow that has shifted, the dashboard is measuring vanity. The engagement-weighted alternative is harder to compute but is the one that actually compounds.

The pattern from the audit cohort is consistent. Teams that track the top two signals (licence active, sessions per week) report headline numbers that look healthy and predict almost nothing. Teams that track the bottom four (skill and subagent invocation rates, memory hygiene, hook coverage) get smaller numbers, harder to win an executive-review meeting with, but those numbers actually move when the team improves and stay still when the team plateaus. That is the property a productivity metric needs to earn its place on a dashboard.

The remediation is unglamorous: build the engagement-weighted panel, report it weekly to the same audience that sees the vanity panel, watch which numbers people argue about over a quarter. The arguing is the signal. Numbers no one argues about are numbers no one believes in.