Concise Rule Writing

Examples:

Never commit .env files                     # 4 words
Use snake_case for Python variables         # 5 words
Run tests before commit                     # 4 words

Writing Techniques

1. Remove Filler Words

Remove: actually, basically, essentially, really, very, definitely, certainly, obviously, simply, just

2. Use Imperative Form

Start with verb. No "you should", "make sure to", "always remember to".

3. Eliminate Redundancy

4. Use Standard Terms

Replace verbose descriptions with known terms:

5. Scope Implicitly

Don't over-specify when context makes it clear:

Rule Patterns

Security Rules

Never commit secrets
Never log passwords
Sanitize all user input
Parameterized queries only
Validate auth on all endpoints

Code Style Rules

snake_case for Python
camelCase for TypeScript
Max 100 chars per line
One class per file

Git Rules

Feature branches only
Run tests before commit
Conventional commit messages
No force push to main

Architecture Rules

Services in /services
Components in /components
No business logic in controllers
Dependency injection for testing

Placement Decision

Optimization Process

Step 1: Draft

Write the rule naturally:

"When working with the database, you should always make sure to use
parameterized queries to prevent SQL injection attacks"

Step 2: Extract Core

Identify the essential constraint:

Use parameterized queries

Step 3: Add Minimal Context

Only if ambiguity exists:

Parameterized queries for all DB access

Step 4: Verify

• Is it clear? ✓
• Is it actionable? ✓
• Is it <50 words? ✓ (6 words)
• Could it be shorter without losing meaning? No

Step 5: Final

Parameterized queries for all DB access

Anti-Patterns

Avoid: Explanatory Rules

# Bad - includes explanation
Never commit .env files because they contain sensitive information
that could be exposed if the repository is public

# Good - just the rule
Never commit .env files

Avoid: Conditional Chains

# Bad - too many conditions
If working on frontend, use React, and if using React, use hooks,
and if using hooks, prefer useCallback for functions

# Good - separate rules
Use React hooks
Prefer useCallback for callback functions

Avoid: Vague Rules

# Bad - not actionable
Write good code
Be careful with security
Think about performance

# Good - specific and actionable
Max cyclomatic complexity: 10
Sanitize all user input
Index foreign keys

Avoid: Duplicate Intent

# Bad - same intent, different words
Never expose secrets
Don't commit API keys
Keep credentials out of code

# Good - one comprehensive rule
Never commit secrets (keys, tokens, passwords)

Context File Rules

Rules in .claude/rules/*.md can be slightly longer since they load on-demand. Still aim for brevity:

# .claude/rules/python.md

## Patterns

- Pydantic for API validation
- AsyncIO for I/O operations
- Type hints on public functions
- Pytest for testing

## Avoid

- Global mutable state
- Bare except clauses
- String concatenation for SQL

Measuring Success

Before Optimization

# CLAUDE.md - 847 words

You should always make sure that whenever you're working with this
project, you remember to never commit any files that contain secrets,
API keys, passwords, or any other sensitive information...

[continues for pages]

After Optimization

# CLAUDE.md - 127 words

## Security
- Never commit secrets
- Sanitize user input
- Hash passwords

## Git
- Feature branches only
- Run tests before commit

## Code
- snake_case (Python)
- camelCase (TypeScript)
- Max 100 chars/line

## Context
| Task | Read |
|------|------|
| Python | .claude/rules/python.md |
| React | .claude/rules/react.md |

Result: 85% token reduction, same coverage.

Quick Reference

Rule Checklist

• <50 words
• Starts with verb (imperative)
• No filler words
• Specific and actionable
• Not duplicating existing rule
• Correct placement (critical vs context)

Word Budget Guide