Dev Rules

Development Rules and Guardrails

Git Safety

Security

Secrets and Credentials

• Never commit .env files, API keys, tokens, passwords, or connection strings
• Always use .env.example with placeholder values, never real credentials
• If real credentials are found in git history, flag immediately - they must be rotated
• Add secret config files to .gitignore (e.g., config/secrets.yml)

Code Security

• Validate all user input at system boundaries (API endpoints, form submissions)
• Use parameterized queries - never string concatenation for database queries
• Sanitize data before rendering in templates (prevent XSS)
• Use bcrypt or argon2 for password hashing, never MD5 or SHA for passwords
• Set CORS origins from environment variables, never wildcard in production

Dependency Security

• Check for known vulnerabilities before adding new packages
• Prefer well-maintained packages with active security response
• Pin dependency versions in lock files

PR Workflow

When working with pull requests:

1. Always read comments first before making changes
   • gh api repos/{owner}/{repo}/issues/{num}/comments
   • gh api repos/{owner}/{repo}/pulls/{num}/comments
2. Check merge readiness before acting
   • gh api repos/{owner}/{repo}/pulls/{num} --jq '{mergeable, mergeable_state, draft}'
3. Check how far behind the base branch
   • gh api repos/{owner}/{repo}/compare/{base}...{head} --jq '{behind_by, ahead_by}'
4. After fixing/rebasing your own repo's PR - comment a summary of what was done. On upstream or fork PRs, never comment without the user's or maintainer's explicit go-ahead
5. Before deleting a fork - verify zero open PRs from that fork
6. When rebasing - squash into clean commits, match project's commit style
7. Never force-push to someone else's branch - only to your own fork branches

CLAUDE.md Authoring Rules

When writing or reviewing CLAUDE.md files:

Rule Statement

State each rule once, plainly, with the reason when it isn't obvious. Current Claude models follow brief plain instructions reliably; repetition, ALL-CAPS, and emphasis markup cause overtriggering rather than better compliance.

For rules that must never slip (secrets, force-push, destructive commands), enforce them mechanically with PreToolUse hooks instead of prompt emphasis -- a hook cannot be ignored in a long context.

Length and Structure

• Keep each CLAUDE.md under 200 lines -- rules get ignored beyond this
• Split detailed rules into .claude/rules/*.md files
• Structure: Overview > Commands > Conventions > Architecture > Critical Rules
• Loading: ancestors load at startup, descendants lazily, siblings never

Context Optimization

Progressive Disclosure

• Load metadata first (names, descriptions) before full content
• Only read files when actually needed - don't preemptively read everything
• For long files, read specific sections rather than the entire file

Context Health

• Manual /compact at ~50% context usage -- don't wait for auto-compaction
• Use /rewind when an approach fails -- don't leave failures in context
• Spawn sub-agents for research tasks to keep main context clean
• New task = new session (avoid context pollution)

Scripts as Black Boxes

• Run helper scripts with --help first to understand their interface
• Only read script source code if --help is insufficient or if debugging
• Prefer calling tools over reading their implementation

Efficient Patterns

• Present quick-reference tables upfront when multiple approaches exist
• Route to specific patterns based on the task at hand
• Don't load all reference material - load what's relevant

Anti-Patterns

• Don't read every file in a directory when a targeted search suffices
• Don't duplicate work between main context and sub-agents
• Don't re-read files that were recently read in the same session
• Don't say "no try again" after bad output -- /rewind then re-prompt
• Don't wait for auto-compact -- model is least intelligent during auto-compact