Anti-Pattern Detection for Claude Projects

Calibration: Tier 2, Opus-primary. See repository README for model compatibility.

Detect and fix the seven structural mistakes that cause Claude Projects to underperform. Each pattern has specific detection criteria and symptoms — diagnose by evidence, not intuition.

Critical: Evidence-First Diagnosis

Never assert a pattern without citing the specific component that exhibits it. For every pattern you detect, quote the exact text from the user's Custom Instructions or knowledge files that demonstrates the problem. If you cannot point to concrete evidence, the pattern is not confirmed.

Reasoning discipline

Before declaring an anti-pattern present, walk through the evidence explicitly. State the observations (specific file contents, structural features, duplication instances, layer assignments), name the anti-pattern they match against detection criteria, then explain the severity and impact. Do not compress this sequence into a summary diagnosis.

If the diagnosis scope is unclear (which files are in scope? which Project layers? all seven patterns or a subset?), confirm scope with the user before proceeding. Do not proceed on inferred assumptions.

When to Use This Skill

Use this when a user:

• Shares their Claude Project (Custom Instructions, knowledge file descriptions, or both) and asks what is wrong or how to improve it
• Describes symptoms of unreliable output: inconsistent quality, ignored instructions, Claude treating rules as optional, output that varies unpredictably across conversations
• Asks for a project review, diagnosis, or health check
• Is troubleshooting a specific problem with their Claude Project setup

If the user provides their Custom Instructions and/or knowledge file descriptions, check for all seven patterns systematically. Report only the patterns you find evidence for — do not pad the diagnosis with patterns that are not present.

The Seven Anti-Patterns

1. The Monolith

What it is: Custom Instructions that exceed roughly 1500 words AND contain reference material (examples, frameworks, data tables, extended explanations) mixed in with behavioral instructions. Alternatively, a single knowledge file that serves multiple distinct purposes.

Symptoms the user sees: Inconsistent adherence to behavioral rules. Claude treats some instructions as optional. Output quality varies unpredictably.

Detection criteria:

• Custom Instructions contain data tables, extended examples, framework descriptions, or reference material alongside behavioral directives
• A single knowledge file covers multiple unrelated topics or serves both instructional and reference purposes
• The system prompt is doing double duty as both a behavioral directive and a reference document

The fix: Separate behavioral instructions from reference material. Custom Instructions should contain only identity, behavioral rules, knowledge file routing, operational modes, and output standards. Move all reference material — frameworks, examples, data, templates — into dedicated knowledge files. If a knowledge file serves multiple purposes, split it into single-purpose files.

2. The Orphan File

What it is: A knowledge file that exists in the Project but is not referenced by name in Custom Instructions, or is referenced with only an inventory description rather than routing guidance.

Symptoms the user sees: Claude rarely or never draws from the file's content. Information from the file is absent from output even when directly relevant to the user's question.

Detection criteria:

• A knowledge file is not mentioned at all in Custom Instructions
• A knowledge file is mentioned only as inventory ("This project contains company_info.md") rather than with routing guidance ("Consult company_info.md when the user asks about our product, market, or competitive position")
• The routing description does not tell Claude when to consult the file — only that it exists

The fix: Add explicit routing guidance to Custom Instructions for every knowledge file. Routing should specify the file name and the conditions under which Claude should consult it. Format: "Consult [filename] when [specific trigger conditions]." The trigger conditions should describe the user's likely questions or task types, not the file's internal structure.

3. The Echo Chamber

What it is: The same instruction, principle, or rule appears in multiple locations with different wording. This creates ambiguity about which version is authoritative.

Symptoms the user sees: Inconsistent behavior — Claude follows one version of the instruction in some conversations and a different version in others. Or Claude synthesizes the variations into a compromise that matches none of the intended versions.

Detection criteria:

• An instruction in Custom Instructions is restated (with different wording) in a knowledge file
• The same behavioral rule appears in multiple knowledge files with subtle variations
• Overlapping guidance exists across components — not identical text, but instructions that govern the same behavior with different specifics

The fix: Establish one authoritative location for each instruction. Behavioral rules belong in Custom Instructions. Reference material belongs in knowledge files. If the same concept must appear in multiple places, use identical wording — or better, state it once and reference that location. Audit for subtle duplicates: rules that use different language but govern the same behavior.

4. The Phantom Conversation

What it is: Custom Instructions written in a conversational, chatty style rather than as clear directives. The system prompt reads like a friendly briefing rather than an operating manual.

Symptoms the user sees: Claude treats instructions as suggestions rather than directives. Behavioral rules are followed inconsistently because the conversational framing reduces their perceived authority.

Detection criteria:

• Custom Instructions open with greetings or conversational preamble ("Hi Claude, in this project you'll be helping with...")
• Instructions are phrased as suggestions ("You might want to consider..." / "It would be great if you could...")
• The overall tone is collaborative rather than directive
• Rules use hedged language instead of clear imperatives

The fix: Rewrite Custom Instructions in imperative, declarative form. Replace "You might want to think about X" with "Consider X when [condition]." Replace "It would be great if you could be concise" with "Keep responses under [length] unless the task requires more." The system prompt is an operating specification, not a conversation. Directive language produces more reliable compliance.

5. The Kitchen Sink

What it is: Custom Instructions that contain rules for edge cases, rare scenarios, or "just in case" situations, diluting Claude's attention to the core behavioral rules that matter in the majority of conversations.

Symptoms the user sees: Core behavioral rules are followed less reliably. Output quality is mediocre across all scenarios rather than excellent for common scenarios. The system prompt is long but the output does not reflect the investment.

Detection criteria:

• Custom Instructions address more than 8-10 distinct behavioral instructions
• Instructions include conditional logic for scenarios that arise less than 10% of the time
• Rules include "just in case" provisions for rare situations
• The system prompt could be 30% or more shorter without degrading output for the user's typical tasks

The fix: Ruthlessly prioritize. Identify the 5-7 behavioral rules that affect the most conversations and keep those. Remove or move to a knowledge file any instruction that addresses a rare scenario. Apply the test: "If I removed this instruction, would the output for my typical tasks get noticeably worse?" If the answer is no, remove it. A shorter, focused