Coding Style
Immutability (CRITICAL)
File Organization
MANY SMALL FILES > FEW LARGE FILES
- High cohesion, low coupling
- 200-400 lines typical, 800 max
- Extract utilities from large modules
- Organize by feature/domain, not by type
Error Handling
ALWAYS handle errors comprehensively:Handle errors explicitly at every level
Handle errors explicitly at every level
Never use try-catch blocks that swallow errors without logging or re-throwing.
Provide user-friendly error messages in UI-facing code
Provide user-friendly error messages in UI-facing code
Error messages shown to users should be clear, actionable, and non-technical.
Log detailed error context on the server side
Log detailed error context on the server side
Include stack traces, request IDs, user context, and other debugging information.
Never silently swallow errors
Never silently swallow errors
Even if you can’t handle an error, at minimum log it before continuing.
Input Validation
ALWAYS validate at system boundaries:- Validate all user input before processing
- Use schema-based validation where available
- Fail fast with clear error messages
- Never trust external data (API responses, user input, file content)
Code Quality Checklist
Before marking work complete:- Code is readable and well-named
- Functions are small (<50 lines)
- Files are focused (<800 lines)
- No deep nesting (>4 levels)
- Proper error handling
- No hardcoded values (use constants or config)
- No mutation (immutable patterns used)
Testing
Minimum Test Coverage: 80%
Test Types (ALL required):1
Unit Tests
Individual functions, utilities, components
2
Integration Tests
API endpoints, database operations
3
E2E Tests
Critical user flows (framework chosen per language)
Test-Driven Development
MANDATORY workflow:Troubleshooting Test Failures
- Use tdd-guide agent
- Check test isolation
- Verify mocks are correct
- Fix implementation, not tests (unless tests are wrong)
Agent Support
tdd-guide
Use PROACTIVELY for new features, enforces write-tests-first
Security
Mandatory Security Checks
Before ANY commit:- No hardcoded secrets (API keys, passwords, tokens)
- All user inputs validated
- SQL injection prevention (parameterized queries)
- XSS prevention (sanitized HTML)
- CSRF protection enabled
- Authentication/authorization verified
- Rate limiting on all endpoints
- Error messages don’t leak sensitive data
Secret Management
NEVER hardcode secrets in source code
NEVER hardcode secrets in source code
Secrets include API keys, passwords, tokens, private keys, connection strings.
ALWAYS use environment variables or a secret manager
ALWAYS use environment variables or a secret manager
Load secrets from
.env files (not committed) or a secret management service.Validate that required secrets are present at startup
Validate that required secrets are present at startup
Fail fast if critical secrets are missing rather than failing later with cryptic errors.
Rotate any secrets that may have been exposed
Rotate any secrets that may have been exposed
If a secret is accidentally committed, immediately rotate it and invalidate the old one.
Security Response Protocol
If security issue found:1
STOP immediately
Do not continue with feature development
2
Use security-reviewer agent
Get comprehensive security audit
3
Fix CRITICAL issues before continuing
Address all high-severity vulnerabilities
4
Rotate any exposed secrets
Invalidate compromised credentials
5
Review entire codebase for similar issues
Check if the pattern is repeated elsewhere
Patterns
Skeleton Projects
When implementing new functionality:1
Search for battle-tested skeleton projects
Look for well-maintained templates with good documentation
2
Use parallel agents to evaluate options
- Security assessment
- Extensibility analysis
- Relevance scoring
- Implementation planning
3
Clone best match as foundation
Start with proven structure
4
Iterate within proven structure
Customize while maintaining best practices
Repository Pattern
Encapsulate data access behind a consistent interface:Define standard operations
Define standard operations
findAll, findById, create, update, delete
Concrete implementations handle storage details
Concrete implementations handle storage details
Database, API, file, in-memory, etc.
Business logic depends on the abstract interface
Business logic depends on the abstract interface
Not the storage mechanism
Benefits
Benefits
Enables easy swapping of data sources and simplifies testing with mocks
API Response Format
Use a consistent envelope for all API responses:- Include a success/status indicator
- Include the data payload (nullable on error)
- Include an error message field (nullable on success)
- Include metadata for paginated responses (total, page, limit)
Git Workflow
Commit Message Format
Attribution disabled globally via ~/.claude/settings.json.
Pull Request Workflow
When creating PRs:1
Analyze full commit history
Not just latest commit
2
Use git diff [base-branch]...HEAD
See all changes since branch diverged
3
Draft comprehensive PR summary
Explain what changed and why
4
Include test plan with TODOs
Document how changes were tested
5
Push with -u flag if new branch
Set upstream tracking
Hooks
Hook Types
PreToolUse
Before tool execution (validation, parameter modification)
PostToolUse
After tool execution (auto-format, checks)
Stop
When session ends (final verification)
Auto-Accept Permissions
TodoWrite Best Practices
Use TodoWrite tool to:- Track progress on multi-step tasks
- Verify understanding of instructions
- Enable real-time steering
- Show granular implementation steps
- Out of order steps
- Missing items
- Extra unnecessary items
- Wrong granularity
- Misinterpreted requirements
Related
TypeScript Rules
TypeScript-specific extensions
Python Rules
Python-specific extensions
Go Rules
Go-specific extensions