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

CLAUDE.md Anti-Patterns

Catalog of common mistakes organized by severity.

Critical Violations (Fix Immediately)

Exposed Secrets

# BAD - Never do this
API_KEY=sk-abc123...
DATABASE_URL=postgres://user:password@host:5432/db

Detection patterns:

• password, secret, token, api_key
• postgres://, mysql://, mongodb://
• -----BEGIN.*PRIVATE KEY-----
• sk-, pk_, AKIA (API key prefixes)

Fix: Remove immediately, rotate credentials, clean git history

Exposed Infrastructure

# BAD
Internal API: http://192.168.1.100:8080
Database: 10.0.0.50:5432

Fix: Use environment variables or secrets management

High Severity (Fix This Sprint)

Generic Content

# BAD - Claude already knows this
## JavaScript Best Practices
- Use const instead of var
- Prefer arrow functions
- Use async/await over callbacks

Fix: Remove generic content, keep only project-specific deviations

Excessive Verbosity

# BAD - Too wordy
When you are writing code for this project, it is important that you
remember to always consider the implications of your changes and how
they might affect other parts of the system...

Fix: Be direct and concise

# GOOD
Check integration test impacts before modifying shared utilities.

Vague Instructions

# BAD
Write good, clean code following best practices.

Fix: Be specific

# GOOD
- Max function length: 50 lines
- Max file length: 300 lines
- All public functions need JSDoc

Conflicting Guidance

# BAD - Contradictory
## Testing
Always write tests first (TDD).

## Development Speed
Skip tests for quick prototypes.

Fix: Resolve conflicts, specify when each applies

Medium Severity (Schedule for Next Quarter)

Outdated Information

# BAD
Run: npm run test (uses Jest)  # Actually switched to Vitest 6 months ago

Fix: Regular audits, add last-updated dates

Duplicated Content

# BAD - Same info twice
## Build Commands
npm run build

## Getting Started
Run `npm run build` to build the project.

Fix: Single source of truth, reference don't repeat

Missing Context

# BAD - Why this pattern?
Always use repository pattern for data access.

Fix: Explain reasoning

# GOOD
Use repository pattern for data access (enables testing with mocks,
required for our caching layer).

Broken Import Paths

# BAD
@docs/old-standards.md  # File was moved/deleted

Fix: Validate imports exist, update or remove stale references

Low Severity (Backlog)

Poor Organization

# BAD - No structure
Here's how to build. npm run build. Tests use vitest. We use TypeScript.
The API is REST. Database is Postgres. Deploy with Docker.

Fix: Use headers, lists, logical grouping

Inconsistent Formatting

# BAD - Mixed styles
## Build Commands
- npm run build

## Testing
Run `npm test` for unit tests
npm run test:e2e runs e2e tests

Fix: Consistent formatting throughout

Missing Priority Markers

# BAD - What's critical vs nice-to-have?
Use TypeScript strict mode.
Add JSDoc to public functions.
Never use any type.
Format with Prettier.

Fix: Add priority markers

# GOOD
**CRITICAL**: Never use `any` type
**IMPORTANT**: TypeScript strict mode enabled
**RECOMMENDED**: JSDoc on public functions

Structural Anti-Patterns

Circular Imports

CLAUDE.md -> @a.md -> @b.md -> @CLAUDE.md  # Infinite loop

Fix: Flatten structure, avoid circular references

Deep Nesting

CLAUDE.md -> @a.md -> @b.md -> @c.md -> @d.md -> @e.md  # 5 hops max!

Fix: Maximum 3 levels recommended, 5 is hard limit

Monolithic Files

# BAD - 800 lines in one file
[Everything crammed together]

Fix: Split into imports by category

# GOOD
@standards/typescript.md
@standards/testing.md
@patterns/api.md

Detection Commands

# Check for secrets
grep -rE "password|secret|token|api_key" CLAUDE.md

# Check file length
wc -l CLAUDE.md  # Should be < 300

# Check for broken imports
grep "^@" CLAUDE.md | while read import; do
  path="${import#@}"
  [ ! -f "$path" ] && echo "Broken: $import"
done

# Check for vague words
grep -iE "good|clean|proper|best|appropriate" CLAUDE.md