AI Coding Principles

Actionable principles for AI coding agents to write production-quality code.

Golden Rules

These four rules apply to every coding task:

1. Read Before Writing

Always explore the codebase before generating code.

• Search for similar implementations first
• Understand existing patterns and conventions
• Check how errors are handled elsewhere
• Look at test patterns already in use

WRONG: Immediately generating a new utility function
RIGHT: Searching for existing utilities, then extending or reusing

2. Minimal Change Principle

Make the smallest change that solves the problem.

• One bug fix = one focused change
• Don't refactor unrelated code
• Don't add features not requested
• Don't "improve" working code opportunistically

WRONG: Fixing a typo and also reformatting the file
RIGHT: Fixing only the typo

3. Match the Codebase

Consistency over personal preference.

Even if you "know better," match existing patterns unless explicitly asked to migrate.

4. Verify Understanding

Ask when uncertain. Assumptions cause rework.

Ask before proceeding when:

• Requirements are ambiguous
• Multiple valid approaches exist
• Change might break existing functionality
• You're unsure about business logic

Don't ask when:

• Implementation is straightforward
• You can verify with tests
• The choice is purely stylistic

Error Handling

See references/error-handling-patterns.md for language-specific examples.

Principles

1. Explicit over silent - Never swallow errors without logging
2. Context is required - Include what failed, where, and why
3. Fail fast in dev - Crash early to surface bugs
4. Graceful in prod - Degrade functionality, don't crash users

Good vs Bad

// BAD: Silent failure, no context
try {
  await saveUser(data);
} catch (e) {
  return null;
}

// GOOD: Explicit handling with context
try {
  await saveUser(data);
} catch (error) {
  logger.error('Failed to save user', {
    userId: data.id,
    error: error.message,
    stack: error.stack,
  });
  throw new UserSaveError(`Could not save user ${data.id}`, { cause: error });
}

Error Handling Checklist

• Are all errors logged with context?
• Do error messages help debugging?
• Are expected errors handled differently from unexpected?
• Is sensitive data excluded from error messages?

Security Fundamentals

See references/security-checklist.md for the full checklist.

Non-Negotiable Rules

1. Validate all external input - User input, API responses, file contents
2. Use parameterized queries - Never concatenate SQL
3. Manage secrets properly - Environment variables, never in code
4. Never log sensitive data - Passwords, tokens, PII

Quick Security Check

Before completing any task:

[ ] User input is validated and sanitized
[ ] No secrets in code or logs
[ ] SQL uses parameterized queries
[ ] File paths are validated (no path traversal)
[ ] External data is treated as untrusted

Common Vulnerabilities to Avoid

Testing Philosophy

See references/testing-patterns.md for implementation patterns.

What to Test

Critical paths:

• User authentication flows
• Payment/transaction logic
• Data persistence operations
• Core business rules

Edge cases:

• Empty inputs
• Boundary values
• Error conditions
• Concurrent operations

What Not to Over-Test

• Trivial getters/setters
• Framework code
• Third-party libraries
• Pure UI styling

Test Placement

Testing Checklist

• Are critical paths covered?
• Do tests verify behavior, not implementation?
• Are tests independent and repeatable?
• Do tests have meaningful names?

Performance Considerations

Profile First

Never optimize without evidence. The bottleneck is rarely where you think.

1. Measure current performance
2. Identify actual bottleneck
3. Fix the bottleneck
4. Measure again

Common Pitfalls

Performance Checklist

• Database queries are batched where possible
• Large lists are paginated
• Resources are properly cleaned up
• Heavy computations are cached if repeated

Communication Patterns

When to Ask vs Proceed

Ask when:

• Multiple valid implementations exist
• Requirements seem incomplete
• Change impacts other systems
• Business logic is unclear

Proceed when:

• Implementation is obvious
• Tests can validate correctness
• Change is isolated and reversible
• Following existing patterns

Explaining Changes

When describing what you did:

1. What - The specific change made
2. Why - The reason for this approach
3. Impact - What else might be affected
4. Testing - How to verify it works

WRONG: "Fixed the bug"
RIGHT: "Fixed null pointer in UserService.getProfile() by adding
       null check before accessing user.settings. This was
       triggered when users hadn't completed onboarding."

Enterprise Patterns

The following sections cover enterprise-grade patterns essential for production systems.

Architecture & SOLID

See references/architecture-patterns.md for detailed examples.

SOLID Quick Reference

Layer Placement

Observability

See references/observability-patterns.md for implementation patterns.

The Three Pillars

Logging Rules

1. Structured JSON - Not string concatenation
2. Request ID - Propagate through all logs
3. Context - Include who, what, where, when
4. Levels - error (failures), warn (degraded), info (business events), debug (diagnostics)

Four Golden Signals

Monitor these for every service:

• Latency - Request duration
• Traffic - Request rate
• Errors - Failure rate
• Saturation - Resource utilization

API Design

See references/api-design-patterns.md for conventions and examples.

REST Conventions

GET    /resources          List
POST   /resources          Create
GET    /resources/{id}     Read
PUT    /resources/{id}     Replace
PATCH  /resources/{id}     Update
DELETE /resources/{id}     Delete

Response Format

// Success
{ "data": {...}, "meta": { "requestId": "..." } }

// Error
{ "error": { "code": "USER_NOT_FOUND", "message": "...", "requestId": "..." } }

API Checklist

• Correct HTTP methods and status codes
• Request validation with clear errors
• Consistent error format with codes
• Pagination for collections
• Versioning strategy defined

Database Patterns

See references/database-patterns.md for schema design and optimization.

Schema Essentials

-- Every table needs
id            -- Primary key (UUID preferred)
created_at    -- When created
updated_at    -- When modified
-- Optional
deleted_at    -- Soft delete

Query Rules

Resilience Patterns

See references/resilience-patterns.md for implementation details.

Everything Fails. Design for It.

Retry Guidelines

Retry: 503, 504, timeouts, connection errors
Don't retry: 400, 401, 403, 404, 422
Backoff: Exponential with jitter
Max attempts: 3-5 for most cases

Code Review

See references/code-review-checklist.md for the complete checklist.

Review Focus Areas

1. Correctness - Does it work? Edge cases?
2. Design - Right place? Right abstraction?
3. Readability - Can you understand it?
4. Security - Input validated? Auth checked?
5. Testing - Critical paths covered?

Before Submitting (Self-Review)

• I've tested this locally
• I've reviewed my own diff
• No debugging code left in
• PR description explains what and why

Refactoring

See references/refactoring-patterns.md for safe refactoring techniques.

The Golden Rule

Make the change easy, then make the easy change.

When to Refactor

Safe Refactoring Process

1. Verify test coverage exists
2. Small incremental changes - commit frequently
3. Keep behavior unchanged - tests should pass
4. Separate from features - refactor PRs are pure refactoring

Quick Reference Checklist

Run through before completing any task:

Pre-Change

• Read existing code in the area
• Understand current patterns
• Clarify ambiguous requirements

During Change

• Minimal necessary changes
• Match codebase style
• Handle errors explicitly
• Validate external input
• No secrets in code

Post-Change

• Tests pass
• No regressions introduced
• Changes are explained clearly

Principles Summary

Core Principles

Enterprise Principles

Reference Files

Comprehensive guides for deep understanding:

Rules

Atomic, enforceable rules for code review. Each rule follows: Incorrect → Correct → Why.

Security (CRITICAL)

Error Handling (HIGH)

Database (HIGH)

API Design (HIGH)

Architecture (HIGH)

Testing (MEDIUM)

Observability (MEDIUM)

Resilience (MEDIUM)

Refactoring (MEDIUM)