Common Language-Agnostic Rules

Universal principles that apply to all projects regardless of language

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:

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

Error messages shown to users should be clear, actionable, and non-technical.

Log detailed error context on the server side

Include stack traces, request IDs, user context, and other debugging information.

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

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

NEVER hardcode secrets in source code

Secrets include API keys, passwords, tokens, private keys, connection strings.

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

Fail fast if critical secrets are missing rather than failing later with cryptic errors.

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

findAll, findById, create, update, delete

Concrete implementations handle storage details

Database, API, file, in-memory, etc.

Business logic depends on the abstract interface

Not the storage mechanism

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

<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

Related

TypeScript Rules

TypeScript-specific extensions

Python Rules

Python-specific extensions

Go Rules

Go-specific extensions