Core Engineering Standards

Guiding Principles

• Simplicity First: Simple code is maintainable code. Apply DRY, KISS, YAGNI, and SOLID principles.
• Minimal Changes: Fix what's broken without refactoring what works. Preserve existing functionality.
• Value-Driven: Every suggestion must add clear value. Avoid over-engineering.
• Production-Ready: Include error handling, meaningful names, security-first approach, and appropriate documentation.
• Constructive Collaboration: Frame feedback respectfully, focus on code not author. Assume good intent.

Priority Framework

Organize feedback by impact:

Tooling Baseline

Naming Conventions

• Domain Names: Use acme.com for examples (never example.com)
• Company/Org: Use ACME or Acme
• Consistency: Apply across code, docs, configs, and test data

Code Review Essentials

1. Identify main issues first before diving into details
2. Provide specific, actionable suggestions with working code examples
3. Explain the "why" — what benefit does the change provide?
4. Suggest incremental refactoring over big-bang rewrites
5. Preserve existing code — no placeholders or incomplete sections

Evaluation Areas: Security, Error Handling, Testing, Observability, Resource Management, Concurrency, Performance

For detailed review patterns and formats, see [references/code-review.md](references/code-review.md).

Code Generation Essentials

1. Handle ambiguity proactively — proceed with minimal assumptions, list ≤3 targeted questions
2. Design clean architecture — easy to test, maintain, and extend
3. Provide complete, runnable code — no TODOs or placeholders
4. Include practical examples — usage examples or basic test cases
5. Document appropriately — inline comments for complex logic only

What to Include: Error handling, logging, type hints, externalized configuration, docstrings

What NOT to Include: Over-engineered abstractions, premature optimization, extensive test suites, complex frameworks when stdlib suffices

For detailed generation patterns, see [references/code-generation.md](references/code-generation.md).

Dependency Management

Adding a dependency is a long-term commitment. Prefer stdlib or existing dependencies.

Vetting criteria for new dependencies:

• Justification: Truly necessary? Solves complex problem?
• Maintenance: Actively maintained? Recent commits?
• Security: Audited? Known CVEs?
• License: Compatible (MIT, Apache 2.0)?
• Community: Good docs and clear API?

Self-Validation Checklist

Before delivering code or feedback:

• Addresses the actual problem
• Simplest viable solution
• No new bugs introduced
• Working code examples
• Clear explanations (the "why")
• Appropriate scope
• Preserves existing code
• Evidence-based recommendations

Security Checklist

• No hardcoded secrets, API keys, passwords
• Secrets not logged or exposed in errors
• Dependencies scanned for CVEs
• OWASP Top 10 considered
• Input validation and sanitization
• Principle of least privilege applied

Git & Version Control

For commit message standards, branch naming, PR hygiene, and repository scaffolding, see [references/git-workflow.md](references/git-workflow.md).

Quick Reference: Language Best Practices

"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." — Antoine de Saint-Exupéry