Skip to main content
Common rules define language-agnostic principles that apply broadly across all projects. Language-specific rules can extend or override these where language idioms differ.

​
Coding Style

​
Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate existing ones.
// Pseudocode
WRONG:  modify(original, field, value) → changes original in-place
CORRECT: update(original, field, value) → returns new copy with change
Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.

​
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:
Never use try-catch blocks that swallow errors without logging or re-throwing.
Error messages shown to users should be clear, actionable, and non-technical.
Include stack traces, request IDs, user context, and other debugging information.
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

  1. Use tdd-guide agent
  2. Check test isolation
  3. Verify mocks are correct
  4. 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

Secrets include API keys, passwords, tokens, private keys, connection strings.
Load secrets from .env files (not committed) or a secret management service.
Fail fast if critical secrets are missing rather than failing later with cryptic errors.
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:
findAll, findById, create, update, delete
Database, API, file, in-memory, etc.
Not the storage mechanism
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

<type>: <description>

<optional body>
Types: feat, fix, refactor, docs, test, chore, perf, ci
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

Use with caution:
  • Enable for trusted, well-defined plans
  • Disable for exploratory work
  • Never use dangerously-skip-permissions flag
  • Configure allowedTools in ~/.claude.json instead

​
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
Todo list reveals:
  • Out of order steps
  • Missing items
  • Extra unnecessary items
  • Wrong granularity
  • Misinterpreted requirements

TypeScript Rules

TypeScript-specific extensions

Python Rules

Python-specific extensions

Go Rules

Go-specific extensions