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:
| Priority |
Description |
Examples |
| Critical |
Security vulnerabilities, bugs that break functionality, data loss risks |
Injection flaws, hardcoded secrets, unhandled exceptions |
| Recommended |
Performance issues, maintainability problems, scalability concerns |
N+1 queries, tight coupling, missing error handling |
| Optional |
Style improvements, future-proofing, minor optimizations |
Naming tweaks, code comments, minor refactors |
Tooling Baseline
| Language |
Linting/Formatting |
Security |
| Python |
ruff + black, pylint (≥9.0) |
pip-audit |
| Bash |
shfmt + shellcheck |
- |
| Go |
gofmt + golangci-lint |
govulncheck |
| JS/TS |
eslint --max-warnings=0 |
npm audit |
| Terraform |
terraform fmt + tflint |
- |
| All |
ggshield + gitleaks |
Dependency scanning on PRs |
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
- Identify main issues first before diving into details
- Provide specific, actionable suggestions with working code examples
- Explain the "why" — what benefit does the change provide?
- Suggest incremental refactoring over big-bang rewrites
- 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.
Code Generation Essentials
- Handle ambiguity proactively — proceed with minimal assumptions, list ≤3 targeted questions
- Design clean architecture — easy to test, maintain, and extend
- Provide complete, runnable code — no TODOs or placeholders
- Include practical examples — usage examples or basic test cases
- 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.
Dependency Management
Adding a dependency is a long-term commitment. Prefer stdlib or existing dependencies.
Vetting criteria for new dependencies:
Self-Validation Checklist
Before delivering code or feedback:
Security Checklist
Git & Version Control
For commit message standards, branch naming, PR hygiene, and repository scaffolding, see references/git-workflow.md.
Quick Reference: Language Best Practices
| Language |
Key Practices |
| Python |
Type hints, PEP 8, context managers, prefer stdlib |
| Go |
Handle all errors, use defer, small interfaces |
| JS/TS |
async/await, destructuring, strict mode |
| Bash |
set -euo pipefail, quote variables, use functions |
| Docker |
Multi-stage builds, non-root user, pinned versions |
"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
1---2name: core-engineering3description: Core coding standards and best practices for code review and generation. Provides guiding principles (DRY, KISS, YAGNI, SOLID), priority frameworks for feedback, tooling baselines, dependency management guidelines, and response formats. Use when reviewing code, generating code, asking about coding standards, or when the user needs general engineering guidance that applies across all languages.4---56# Core Engineering Standards78## Guiding Principles910- **Simplicity First:** Simple code is maintainable code. Apply DRY, KISS, YAGNI, and SOLID principles.11- **Minimal Changes:** Fix what's broken without refactoring what works. Preserve existing functionality.12- **Value-Driven:** Every suggestion must add clear value. Avoid over-engineering.13- **Production-Ready:** Include error handling, meaningful names, security-first approach, and appropriate documentation.14- **Constructive Collaboration:** Frame feedback respectfully, focus on code not author. Assume good intent.1516## Priority Framework1718Organize feedback by impact:1920| Priority | Description | Examples |21|----------|-------------|----------|22| **Critical** | Security vulnerabilities, bugs that break functionality, data loss risks | Injection flaws, hardcoded secrets, unhandled exceptions |23| **Recommended** | Performance issues, maintainability problems, scalability concerns | N+1 queries, tight coupling, missing error handling |24| **Optional** | Style improvements, future-proofing, minor optimizations | Naming tweaks, code comments, minor refactors |2526## Tooling Baseline2728| Language | Linting/Formatting | Security |29|----------|-------------------|----------|30| Python | `ruff` + `black`, pylint (≥9.0) | `pip-audit` |31| Bash | `shfmt` + `shellcheck` | - |32| Go | `gofmt` + `golangci-lint` | `govulncheck` |33| JS/TS | `eslint --max-warnings=0` | `npm audit` |34| Terraform | `terraform fmt` + `tflint` | - |35| All | `ggshield` + `gitleaks` | Dependency scanning on PRs |3637## Naming Conventions3839- **Domain Names:** Use `acme.com` for examples (never `example.com`)40- **Company/Org:** Use `ACME` or `Acme`41- **Consistency:** Apply across code, docs, configs, and test data4243## Code Review Essentials44451. Identify main issues first before diving into details462. Provide specific, actionable suggestions with working code examples473. Explain the "why" — what benefit does the change provide?484. Suggest incremental refactoring over big-bang rewrites495. Preserve existing code — no placeholders or incomplete sections5051**Evaluation Areas:** Security, Error Handling, Testing, Observability, Resource Management, Concurrency, Performance5253For detailed review patterns and formats, see [references/code-review.md](references/code-review.md).5455## Code Generation Essentials56571. Handle ambiguity proactively — proceed with minimal assumptions, list ≤3 targeted questions582. Design clean architecture — easy to test, maintain, and extend593. Provide complete, runnable code — no TODOs or placeholders604. Include practical examples — usage examples or basic test cases615. Document appropriately — inline comments for complex logic only6263**What to Include:** Error handling, logging, type hints, externalized configuration, docstrings6465**What NOT to Include:** Over-engineered abstractions, premature optimization, extensive test suites, complex frameworks when stdlib suffices6667For detailed generation patterns, see [references/code-generation.md](references/code-generation.md).6869## Dependency Management7071Adding a dependency is a long-term commitment. **Prefer stdlib or existing dependencies.**7273Vetting criteria for new dependencies:74- [ ] **Justification:** Truly necessary? Solves complex problem?75- [ ] **Maintenance:** Actively maintained? Recent commits?76- [ ] **Security:** Audited? Known CVEs?77- [ ] **License:** Compatible (MIT, Apache 2.0)?78- [ ] **Community:** Good docs and clear API?7980## Self-Validation Checklist8182Before delivering code or feedback:83- [ ] Addresses the actual problem84- [ ] Simplest viable solution85- [ ] No new bugs introduced86- [ ] Working code examples87- [ ] Clear explanations (the "why")88- [ ] Appropriate scope89- [ ] Preserves existing code90- [ ] Evidence-based recommendations9192## Security Checklist9394- [ ] No hardcoded secrets, API keys, passwords95- [ ] Secrets not logged or exposed in errors96- [ ] Dependencies scanned for CVEs97- [ ] OWASP Top 10 considered98- [ ] Input validation and sanitization99- [ ] Principle of least privilege applied100101## Git & Version Control102103For commit message standards, branch naming, PR hygiene, and repository scaffolding, see [references/git-workflow.md](references/git-workflow.md).104105## Quick Reference: Language Best Practices106107| Language | Key Practices |108|----------|--------------|109| Python | Type hints, PEP 8, context managers, prefer stdlib |110| Go | Handle all errors, use `defer`, small interfaces |111| JS/TS | async/await, destructuring, strict mode |112| Bash | `set -euo pipefail`, quote variables, use functions |113| Docker | Multi-stage builds, non-root user, pinned versions |114115> "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." — Antoine de Saint-Exupéry116
KiranEswaran