gh-cskiro-claudex-claude-code-tools/skills/claude-md-auditor/reference/anti_patterns.md

CLAUDE.md Anti-Patterns and Common Mistakes

Purpose: Catalog of common mistakes, violations, and anti-patterns to avoid when creating CLAUDE.md files

This document identifies problematic patterns frequently found in CLAUDE.md files, explains why they're problematic, and provides better alternatives.

---

Critical Violations (Security & Safety)

🚨 CRITICAL-01: Secrets in Memory Files

Problem

# CLAUDE.md

## API Configuration
- API Key: sk-1234567890abcdefghijklmnop
- Database Password: MySecretPassword123
- AWS Secret: AKIAIOSFODNN7EXAMPLE

Why It's Dangerous

• ❌ CLAUDE.md files are typically committed to source control
• ❌ Exposes credentials to entire team and git history
• ❌ Can leak through PR comments, logs, or backups
• ❌ Violates security best practices

Correct Approach

# CLAUDE.md

## API Configuration
- API keys stored in: .env (see .env.example for template)
- Database credentials: Use AWS Secrets Manager
- AWS credentials: Use IAM roles, never hardcode

## Environment Variables Required
- API_KEY (get from team lead)
- DB_PASSWORD (from 1Password vault)
- AWS_REGION (default: us-east-1)

Severity: CRITICAL Action: Immediate removal + git history cleanup + key rotation

---

🚨 CRITICAL-02: Exposed Internal URLs/IPs

Problem

## Production Servers
- Production Database: postgres://admin:pass@10.0.1.42:5432/proddb
- Internal API: https://internal-api.company.net/v1
- Admin Panel: https://admin.company.net (password: admin123)

Why It's Dangerous

• ❌ Exposes internal infrastructure
• ❌ Provides attack surface information
• ❌ May violate security policies

Correct Approach

## Production Access
- Database: Use connection string from AWS Parameter Store
- API: See deployment documentation (requires VPN)
- Admin Panel: Contact DevOps for access (SSO required)

Severity: CRITICAL Action: Remove immediately + security review

---

High-Severity Issues

⚠️ HIGH-01: Generic Programming Advice

Problem

## React Best Practices

React is a JavaScript library for building user interfaces. It was created
by Facebook in 2013. React uses a virtual DOM for efficient updates.

### What is a Component?
A component is a reusable piece of UI. Components can be class-based or
functional. Functional components are preferred in modern React...

[200 lines of React documentation]

Why It's Problematic

• ❌ Wastes context window space
• ❌ Claude already knows this information
• ❌ Not project-specific
• ❌ Duplicates official documentation

Correct Approach

## React Standards (Project-Specific)

- Use functional components only (no class components)
- Custom hooks in: /src/hooks
- Component co-location pattern: Component + test + styles in same directory
- Props interface naming: [ComponentName]Props

Example:
/src/features/auth/LoginForm/
  ├── LoginForm.tsx
  ├── LoginForm.test.tsx
  ├── LoginForm.styles.ts
  └── index.ts

Severity: HIGH Action: Remove generic content, keep only project-specific standards

---

⚠️ HIGH-02: Excessive Verbosity

Problem

# CLAUDE.md (1,200 lines)

## Introduction
Welcome to our project. This document contains comprehensive information...
[50 lines of introduction]

## History
This project started in 2019 when our founder...
[100 lines of history]

## Git Basics
To use git, first you need to understand version control...
[200 lines of git tutorial]

## TypeScript Fundamentals
TypeScript is a typed superset of JavaScript...
[300 lines of TypeScript basics]

[500 more lines of generic information]

Why It's Problematic

• ❌ Consumes excessive context (> 18,000 tokens ≈ 9% of 200K window)
• ❌ "Lost in the middle" degradation
• ❌ Difficult to maintain
• ❌ Hard to find relevant information

Correct Approach

# CLAUDE.md (250 lines)

## Project: MyApp
Enterprise CRM built with React + TypeScript + PostgreSQL

## CRITICAL STANDARDS
[20 lines of must-follow rules]

## Architecture
[30 lines of project-specific architecture]

## Development Workflow
[40 lines of team process]

## Code Standards
[50 lines of project-specific rules]

## Common Tasks
[40 lines of commands and workflows]

## Detailed Documentation (Imports)
@docs/architecture.md
@docs/git-workflow.md
@docs/typescript-conventions.md

Severity: HIGH Action: Reduce to < 300 lines, use imports for detailed docs

---

⚠️ HIGH-03: Vague or Ambiguous Instructions

Problem

## Code Quality
- Write good code
- Make it clean
- Follow best practices
- Be consistent
- Keep it simple
- Don't be clever

Why It's Problematic

• ❌ Not actionable
• ❌ Subjective interpretation
• ❌ Doesn't provide measurable criteria
• ❌ Claude won't know what "good" means in your context

Correct Approach

## Code Quality Standards (Measurable)

- Function length: Maximum 50 lines (warning) / 100 lines (error)
- Cyclomatic complexity: Maximum 10 (warning) / 20 (error)
- Test coverage: Minimum 80% for new code
- No `console.log` in src/ directory (use /src/lib/logger.ts)
- No `any` types (use `unknown` if type truly unknown)
- TypeScript strict mode: Enabled (no opt-outs)

Severity: HIGH Action: Replace vague advice with specific, measurable standards

---

Medium-Severity Issues

⚠️ MEDIUM-01: Outdated Information

Problem

## Build Process
- Use Webpack 4 for bundling
- Node 12 required
- Run tests with Jest 25

## Deployment
- Deploy to Heroku using git push
- Use MongoDB 3.6

Why It's Problematic

• ❌ Misleads developers
• ❌ May cause build failures
• ❌ Indicates unmaintained documentation
• ❌ Conflicts with actual setup

Correct Approach

## Build Process (Updated 2025-10-26)
- Vite 5.0 for bundling (migrated from Webpack)
- Node 20 LTS required
- Run tests with Vitest 2.0

## Deployment (Updated 2025-10-26)
- Deploy to AWS ECS using GitHub Actions
- Use PostgreSQL 16

## Update History
- 2025-10-26: Migrated to Vite, PostgreSQL
- 2024-05-15: Upgraded to Node 20

Severity: MEDIUM Action: Regular audits, include update dates

---

⚠️ MEDIUM-02: Duplicate or Conflicting Information

Problem

## Code Style (Line 50)
- Use 2-space indentation
- Prefer single quotes

## TypeScript Standards (Line 150)
- Use 4-space indentation
- Prefer double quotes

## React Guidelines (Line 250)
- Indentation: Use tabs
- Quotes: Use backticks for strings

Why It's Problematic

• ❌ Conflicting instructions
• ❌ Claude may follow the wrong standard
• ❌ Team confusion
• ❌ Indicates poor maintenance

Correct Approach

## Code Style (Single Source of Truth)

### Formatting (Enforced by Prettier)
- Indentation: 2 spaces
- Quotes: Single quotes for strings, backticks for templates
- Line length: 100 characters
- Trailing commas: Always

### Config Location
- .prettierrc.json (root directory)
- Auto-format on save (VS Code: editor.formatOnSave)

Severity: MEDIUM Action: Consolidate all style rules in one section

---

⚠️ MEDIUM-03: Missing Context for Standards

Problem

## Standards
- Never use `useState` hook
- All API calls must use POST method
- No files over 200 lines
- Must use Redux for all state

Why It's Problematic

• ❌ Standards seem arbitrary without context
• ❌ May be outdated after architecture changes
• ❌ Hard to question or update
• ❌ New team members don't understand "why"

Correct Approach

## State Management Standards

### useState Hook (Avoid for Complex State)
- ❌ DON'T: Use useState for complex/shared state
- ✅ DO: Use useState for simple local UI state (toggles, input values)
- ✅ DO: Use Zustand for shared application state
- WHY: useState causes prop drilling; Zustand avoids this

### API Call Methods
- Use POST for: Mutations, large request bodies
- Use GET for: Queries, cached responses
- WHY: RESTful conventions, better caching

### File Length (Soft Limit: 200 Lines)
- Preference: Keep files under 200 lines
- Exception: Generated files, large data structures
- WHY: Maintainability, easier code review

Severity: MEDIUM Action: Add context/rationale for standards

---

Low-Severity Issues

⚠️ LOW-01: Poor Organization

Problem

# CLAUDE.md

Random information...
## Testing
More random stuff...
### Security
Back to testing...
## API
### More Security
## Testing Again

Why It's Problematic

• ❌ Hard to navigate
• ❌ Information scattered
• ❌ Difficult to maintain
• ❌ Poor user experience

Correct Approach

# Project Name

## 1. CRITICAL STANDARDS
[Must-follow rules]

## 2. PROJECT OVERVIEW
[Context and architecture]

## 3. DEVELOPMENT WORKFLOW
[Git, PRs, deployment]

## 4. CODE STANDARDS
[Language/framework specific]

## 5. TESTING REQUIREMENTS
[Coverage, strategies]

## 6. SECURITY REQUIREMENTS
[Authentication, data protection]

## 7. COMMON TASKS
[Commands, workflows]

## 8. REFERENCE
[File locations, links]

Severity: LOW Action: Reorganize with clear hierarchy

---

⚠️ LOW-02: Broken Links and Paths

Problem

## Documentation
- See architecture docs: /docs/arch.md (404)
- Import types from: /src/old-types/index.ts (moved)
- Run deploy script: ./scripts/deploy.sh (deleted)

Why It's Problematic

• ❌ Misleads developers
• ❌ Causes frustration
• ❌ Indicates stale documentation

Correct Approach

## Documentation (Verified 2025-10-26)
- Architecture: /docs/architecture/system-design.md ✅
- Types: /src/types/index.ts ✅
- Deployment: npm run deploy (see package.json scripts) ✅

## Validation
Links verified: 2025-10-26
Next check: 2026-01-26

Severity: LOW Action: Periodic validation, date stamps

---

⚠️ LOW-03: Inconsistent Formatting

Problem

## Code Standards
some bullet points without dashes
* Others with asterisks
- Some with dashes
  - Inconsistent indentation
    * Mixed styles

Headers in Title Case
Headers in sentence case
Headers in SCREAMING CASE

Why It's Problematic

• ❌ Unprofessional appearance
• ❌ Harder to parse
• ❌ May affect rendering
• ❌ Poor user experience

Correct Approach

## Code Standards

### Formatting Rules
- Consistent bullet style (dashes)
- 2-space indentation for nested lists
- Title Case for H2 headers
- Sentence case for H3 headers

### Example List
- First item
  - Nested item A
  - Nested item B
- Second item
  - Nested item C

Severity: LOW Action: Adopt consistent markdown style guide

---

Structural Anti-Patterns

📋 STRUCTURE-01: No Section Hierarchy

Problem

# CLAUDE.md
Everything at the top level
No organization
No hierarchy
Just a wall of text

Correct Approach

# Project Name

## Section 1
### Subsection 1.1
### Subsection 1.2

## Section 2
### Subsection 2.1

---

📋 STRUCTURE-02: Circular Imports

Problem

# CLAUDE.md
@docs/standards.md

# docs/standards.md
@docs/guidelines.md

# docs/guidelines.md
@CLAUDE.md

Correct Approach

• Maintain acyclic import graph
• Use unidirectional imports
• CLAUDE.md → detailed docs (not reverse)

---

📋 STRUCTURE-03: Deep Import Nesting

Problem

# CLAUDE.md
@docs/level1.md
  @docs/level2.md
    @docs/level3.md
      @docs/level4.md
        @docs/level5.md
          @docs/level6.md (exceeds 5-hop limit)

Correct Approach

• Maximum 5 import hops
• Flatten structure when possible
• Use fewer, comprehensive documents

---

Detection and Prevention

Automated Checks

## Checklist for CLAUDE.md Quality

### Security (CRITICAL)
- [ ] No API keys, tokens, or passwords
- [ ] No database credentials
- [ ] No internal URLs or IPs
- [ ] No private keys
- [ ] Git history clean

### Content Quality (HIGH)
- [ ] No generic programming tutorials
- [ ] Under 300 lines (or using imports)
- [ ] Specific, actionable instructions
- [ ] No vague advice ("write good code")
- [ ] Project-specific context

### Maintainability (MEDIUM)
- [ ] No outdated information
- [ ] No conflicting instructions
- [ ] Context provided for standards
- [ ] All links functional
- [ ] Last update date present

### Structure (LOW)
- [ ] Clear section hierarchy
- [ ] Consistent formatting
- [ ] No circular imports
- [ ] Import depth ≤ 5 hops
- [ ] Logical organization

---

Anti-Pattern Summary Table

ID	Anti-Pattern	Severity	Impact	Fix Effort
CRITICAL-01	Secrets in memory files	🚨 CRITICAL	Security breach	Immediate
CRITICAL-02	Exposed internal infrastructure	🚨 CRITICAL	Security risk	Immediate
HIGH-01	Generic programming advice	⚠️ HIGH	Context waste	High
HIGH-02	Excessive verbosity	⚠️ HIGH	Context waste	High
HIGH-03	Vague instructions	⚠️ HIGH	Ineffective	Medium
MEDIUM-01	Outdated information	⚠️ MEDIUM	Misleading	Medium
MEDIUM-02	Duplicate/conflicting info	⚠️ MEDIUM	Confusion	Medium
MEDIUM-03	Missing context for standards	⚠️ MEDIUM	Poor adoption	Low
LOW-01	Poor organization	⚠️ LOW	UX issue	Low
LOW-02	Broken links/paths	⚠️ LOW	Frustration	Low
LOW-03	Inconsistent formatting	⚠️ LOW	Unprofessional	Low
STRUCTURE-01	No section hierarchy	📋 STRUCTURAL	Poor navigation	Low
STRUCTURE-02	Circular imports	📋 STRUCTURAL	Load failure	Medium
STRUCTURE-03	Deep import nesting	📋 STRUCTURAL	Complexity	Low

---

Real-World Examples

Example 1: The "Documentation Dump"

Before (Anti-Pattern):

# CLAUDE.md (2,500 lines)

[Complete React documentation copy-pasted]
[Complete TypeScript handbook]
[Complete git tutorial]
[Complete testing library docs]

After (Fixed):

# CLAUDE.md (200 lines)

## Project-Specific React Standards
- Functional components only
- Co-location pattern
- Custom hooks in /src/hooks

## TypeScript Standards
- Strict mode enabled
- No `any` types
- Explicit return types

@docs/react-architecture.md
@docs/typescript-conventions.md

---

Example 2: The "Secret Leaker"

Before (Anti-Pattern):

## API Configuration
API_KEY=sk-1234567890
DB_PASSWORD=MySecret123

After (Fixed):

## API Configuration
- Use .env file (see .env.example)
- API_KEY: Get from team lead
- DB_PASSWORD: In 1Password vault

---

Example 3: The "Vague Advisor"

Before (Anti-Pattern):

## Standards
- Write clean code
- Be professional
- Follow best practices

After (Fixed):

## Code Quality Standards
- Max function length: 50 lines
- Max cyclomatic complexity: 10
- Min test coverage: 80%
- No console.log in production

---

Document Version: 1.0.0 Last Updated: 2025-10-26 Purpose: Anti-pattern catalog for CLAUDE.md auditing Status: Comprehensive reference for audit validation