# 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