Code Authoring

Apply these requirements when writing or reviewing code.

Architectural Principles

Simplicity over cleverness. Write obvious code the next developer understands immediately. Avoid premature abstractions.

Type safety is not cleverness. Use enums over magic strings, strongly-typed IDs where warranted, and proper error types over string parsing.

Conventions over configuration. Follow framework conventions and defaults. Do not invent custom patterns when standard ones exist.

Pragmatism over purity. Make practical trade-offs. Do not over-engineer for hypothetical requirements.

YAGNI. Implement only what is required. Do not add configuration for values that won't change, abstractions for single implementations, error handling for impossible states, defensive code against trusted internal callers, or features not requested.

Delete freely. Dead code, unused abstractions, and speculative features are liabilities. Remove them.

Fewer dependencies. Each package is maintenance burden. Prefer built-in framework features.

Explicit over implicit. Magic is hard to debug. Prefer clear, traceable code paths.

CLI Tools for Generation

Use framework-provided commands for file generation:

• .NET: dotnet new, dotnet add package
• Rails: rails new, rails generate
• Node.js: npm init, npx create-*
• Python: pip install, poetry init

Incremental Development

Implement the minimum required. Do not add error handling for conditions that cannot occur, resilience when infrastructure handles failures, validation for inputs guaranteed by upstream systems, or configurability for values that never change.

Before adding defensive code:

1. Is this a real possibility in this context?
2. What happens without handling? If the job retries automatically, do not add handling.
3. Did the spec explicitly require this?

Execution Context

For background jobs, assume retry-on-failure unless told otherwise. Do not add try/catch that swallows exceptions.

Research Requirements

Training data is outdated. Libraries evolve. Verify before implementing.

Before writing code using external packages:

1. Check package versions in project files
2. Use WebSearch to find current documentation for that version
3. Verify async patterns—many libraries now have native async methods
4. Check for breaking changes in major versions

Do not wrap sync methods in Task.Run() when native async exists. Do not hand-roll retry logic when libraries like Polly exist and retries are actually needed.

When uncertain about any API:

WebSearch: "[package name] [version] async methods"
WebSearch: "[package name] [version] best practices 2025"

Code Review

Before reviewing, identify packages and versions, then research current best practices.

Flag: sync-over-async patterns, deprecated APIs with modern replacements, manual implementations of built-in features.

Review Checklist

Issue Priorities

Review Output

Use templates/code-review.md if available. Otherwise structure as:

1. Summary (one paragraph)
2. Issues (grouped by priority)
3. Recommendations (prioritized list)