dev-rules

Development Rules and Guardrails

Git Safety

Rule	Why
Never force push to main/master	Destroys team history, breaks CI
Never git reset --hard without confirmation	Irreversible data loss
Never amend published commits	Creates divergent history for collaborators
Never skip pre-commit hooks (--no-verify)	Hooks catch real issues
Stage specific files by name	git add . risks committing secrets or binaries
Never commit .env, credentials, API keys	Secrets in git history are permanent
Verify current branch before pushing	Avoid pushing to wrong branch

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 - comment back on the PR summarizing what was done
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:

<important> Tags

Wrap must-follow rules in <important> tags so they survive long contexts:

<important>
- Never commit .env files or API keys
- Always run tests before pushing
- Never force push to main/master
</important>

Use <important if="..."> for conditional rules:

<important if="making git commits or pushing code">
- Never add Co-Authored-By trailers
- Use conventional commit format
</important>

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