83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# Core Coding Principles
|
|
|
|
> **Scope:** This document defines the core, universal, and project-agnostic engineering principles that apply to all development work. These are the fundamental rules of good software craftsmanship, independent of any specific project.
|
|
|
|
## Core Coding Principles
|
|
|
|
- [SF] **Simplicity First:** Always choose the simplest viable solution. Complex patterns or architectures require explicit justification.
|
|
- [RP] **Readability Priority:** Code must be immediately understandable by both humans and AI during future modifications.
|
|
- [DM] **Dependency Minimalism:** No new libraries or frameworks without explicit request or compelling justification.
|
|
- [ISA] **Industry Standards Adherence:** Follow established conventions for the relevant language and tech stack.
|
|
- [SD] **Strategic Documentation:** Comment only complex logic or critical functions. Avoid documenting the obvious.
|
|
- [TDT] **Test-Driven Thinking:** Design all code to be easily testable from inception.
|
|
|
|
## Dependency Management
|
|
|
|
- [DM-1] Review third-party dependencies for vulnerabilities at least quarterly.
|
|
- [DM-2] Prefer signed or verified packages.
|
|
- [DM-3] Remove unused or outdated dependencies promptly.
|
|
- [DM-4] Document dependency updates in the changelog.
|
|
|
|
## Coding workflow preferences
|
|
|
|
- [WF-FOCUS] Focus on the areas of code relevant to the task
|
|
- [WF-SCOPE] Do not touch code that is unrelated to the task
|
|
- [WF-TEST] Write thorough tests for all major functionality
|
|
- [WF-ARCH] Avoid making major changes to the patterns and architecture of how a feature works, after it has shown to work well, unless explicitly structured
|
|
- [WF-IMPACT] Always think about what other methods and areas of code might be affected by code changes
|
|
|
|
## Workflow Standards
|
|
|
|
- [AC] **Atomic Changes:** Make small, self-contained modifications to improve traceability and rollback capability.
|
|
- [CD] **Commit Discipline:** Recommend regular commits with semantic messages using conventional commit format:
|
|
|
|
```
|
|
|
|
type(scope): concise description
|
|
|
|
[optional body with details]
|
|
|
|
[optional footer with breaking changes/issue references]
|
|
|
|
```
|
|
|
|
Types: feat, fix, docs, style, refactor, perf, test, chore
|
|
Adhere to the ConventionalCommit specification: <https://www.conventionalcommits.org/en/v1.0.0/#specification>
|
|
|
|
- [TR] **Transparent Reasoning:** When generating code, explicitly reference which global rules influenced decisions.
|
|
- [CWM] **Context Window Management:** Be mindful of AI context limitations. Suggest new sessions when necessary.
|
|
|
|
## Code Quality Guarantees
|
|
|
|
- [DRY] **DRY Principle:** No duplicate code. Reuse or extend existing functionality.
|
|
- [CA] **Clean Architecture:** Generate cleanly formatted, logically structured code with consistent patterns.
|
|
- [REH] **Robust Error Handling:** Integrate appropriate error handling for all edge cases and external interactions.
|
|
- [CSD] **Code Smell Detection:** Proactively identify and suggest refactoring for:
|
|
- Functions exceeding 30 lines
|
|
- Files exceeding 300 lines
|
|
- Nested conditionals beyond 2 levels
|
|
- Classes with more than 5 public methods
|
|
|
|
## Security & Performance Considerations
|
|
|
|
- [IV] **Input Validation:** All external data must be validated before processing.
|
|
- [RM] **Resource Management:** Close connections and free resources appropriately.
|
|
- [CMV] **Constants Over Magic Values:** No magic strings or numbers. Use named constants.
|
|
- [SFT] **Security-First Thinking:** Implement proper authentication, authorization, and data protection.
|
|
- [PA] **Performance Awareness:** Consider computational complexity and resource usage.
|
|
- [RL] Rate limit all API endpoints.
|
|
- [RLS] Use row-level security always (RLS).
|
|
- [CAP] Captcha on all auth routes/signup pages.
|
|
- [WAF] If using hosting solution like Vercel, enable attack challenge on their WAF.
|
|
- [SEC-1] **DO NOT** read or modify, without prior approval by user:
|
|
- .env files
|
|
- \*_/config/secrets._
|
|
- Any file containing API keys or credentials
|
|
|
|
## AI Communication Guidelines
|
|
|
|
- [RAT] **Rule Application Tracking:** When applying rules, tag with the abbreviation in brackets (e.g., [SF], [DRY]).
|
|
- [EDC] **Explanation Depth Control:** Scale explanation detail based on complexity, from brief to comprehensive.
|
|
- [AS] **Alternative Suggestions:** When relevant, offer alternative approaches with pros/cons.
|
|
- [KBT] **Knowledge Boundary Transparency:** Clearly communicate when a request exceeds AI capabilities or project context.
|