gh-robbyt-claude-skills-plugins-claude-md-reflect/skills/claude-md-reflect/references/anti-patterns.md

# CLAUDE.md Anti-Patterns

Common mistakes to avoid when writing or improving CLAUDE.md files. You should AVOID the following:

## Vague or Subjective Instructions

**Bad:**
- Write proper code
- Use best practices
- Make it simple
- Write robust error handling
- Create clean functions

**Why:** These are subjective and provide no actionable guidance.

**Good:**
- Use 2-space indentation
- Prefix test files with `test_`
- Return errors instead of panicking
- Functions should not exceed 50 lines

## Hyperbolic or Fluff Language

**Bad:**
- The API client plays a crucial role in our architecture
- It's very important to follow these guidelines
- Make sure to write excellent documentation
- Always use proper naming conventions

**Why:** Words like "crucial", "very important", "excellent", "proper" add noise without meaning.

**Good:**
- Use the API client in `pkg/client` for all external requests
- Document all exported functions
- Use snake_case for variable names

## Long Narrative Paragraphs

**Bad:**
```
When you're working on this project, you should be aware that we have a
specific way of handling errors. In the past, we used to just return nil
and log errors, but we've since moved to a better approach where we return
the actual error values so that callers can handle them appropriately.
```

**Good:**
```
# Error handling
- Return errors to callers, don't just log them
- Use errors.Join for multiple errors
```

## Redundant Information

**Bad:**
```
# Build commands
- npm run build: This command builds the project
- npm run test: This command runs the tests
- npm run lint: This command runs the linter

# Building
To build the project, run `npm run build`
```

**Why:** Information appears multiple times.

**Good:**
```
# Commands
- npm run build: Build the project
- npm run test: Run test suite
- npm run lint: Check code style
```

## Outdated Instructions

**Bad:**
```
# Database
- Use MySQL 5.7
- Run migrations with migrate.sh (NOTE: This script was removed, use db-migrate now)
```

**Why:** Contains outdated information and historical comments.

**Good:**
```
# Database
- Use PostgreSQL 15+
- Run migrations with `npm run db:migrate`
```

## Unclear Scope

**Bad:**
```
Don't use global variables
```

**Why:** Unclear if this applies to all files, tests, or specific contexts.

**Good:**
```
# Code style
- Avoid global variables in src/ (tests can use them for fixtures)
```

## Missing Context for Commands

**Bad:**
```
Run: make proto
```

**Why:** No explanation of when or why to run this.

**Good:**
```
# After editing .proto files
- make proto: Regenerate protobuf code
```

## Over-Capitalization for Emphasis

**Bad:**
```
NEVER EVER USE VAR IN JAVASCRIPT CODE!!!
YOU MUST ALWAYS USE CONST OR LET!!!
```

**Why:** Excessive caps and punctuation create noise.

**Good:**
```
# JavaScript style
- NEVER use var, use const or let
```

## Instructions That Should Be Code

**Bad:**
```
When rotating PDFs, make sure to:
1. Load the PDF using pdfplumber
2. Iterate through each page
3. Rotate each page by the specified degrees
4. Save the output
```

**Why:** Repetitive procedural code should be in a script, not instructions.

**Good:**
```
# PDF manipulation
- Rotate PDFs: python scripts/rotate_pdf.py <input> <degrees> <output>
```

## Mixing Different Concerns

**Bad:**
```
# Instructions
- Use ES modules
- The build takes about 5 minutes
- John prefers arrow functions
- Run tests before committing
- I fixed a bug last week where...
```

**Why:** Mixes style guidelines, historical notes, timing info, and personal preferences.

**Good:**
```
# Code style
- Use ES modules
- Prefer arrow functions

# Development workflow
- Run `npm test` before committing
```