Sovant AI Engineering Standards
A comprehensive engineering discipline skill for the Sovant AI codebase. Ensures clarity, maintainability, and scalability through proven development practices.
Overview
This skill enforces Sovant AI's core engineering principles when writing, reviewing, or refactoring code. It prioritizes simple solutions, environment safety, code reuse, and thorough documentation to maintain a clean, scalable codebase.
Instructions
When working on Sovant AI code, follow these principles:
1. Clarity & Communication
Explain all bugs, changes, or technical decisions in plain EnglishUse everyday analogies when helpful to clarify complex conceptsAsk clarifying questions until you're at least 95% confident in the task scopeNever simplify, shorten, or reinterpret system instructions unless explicitly told toWhen summarizing code or logic, be exhaustive and include all important details2. Simple, Clean Code
Always use the **simplest working solution** that meets requirementsAvoid introducing new libraries, tools, or patterns unless truly necessaryClean up obsolete logic when introducing new code to prevent technical debtAlways trace issues to the root cause rather than patching symptomsFavor readability over cleverness3. Structure & Organization
Refactor any file that exceeds **400 lines** to keep modules focusedFollow the existing folder structure, naming conventions, and coding styles consistentlyKeep the root folder cleanStore experimental scripts, test data, and debug tools inside `dev_resources/`Maintain logical grouping of related functionality4. Environment-Safe Practices
Always write environment-aware code with proper dev/test/prod separationNever hard-code secrets or configuration valuesUse environment variables for all configurationManage environment variables via Supabase/Vercel environment controlsOnly include mock data inside test files, never in dev or prod environmentsDo not insert detection logic, placeholders, or dummy values into main production code5. Code Reuse & Non-Duplication
Always check the codebase for existing logic before writing new utilities or hooksReuse centralized helpers and shared modules to avoid repeated inline codeFavor composable React hooks and utility functions in Next.js applicationsExtract common patterns into reusable abstractions when you see duplication6. Safe Change Management
Only modify code directly related to the requested task or issueDocument why a fix works in the commit message or PR descriptionAvoid speculative fixesUse targeted logging or debug tools to investigate before codingRemove all temporary code, debug flags, or `TODO` stubs once the root issue is solved7. Testing Practices
Write basic tests to confirm new logic or edge cases, especially for critical featuresPrefer testing pure logic over UI snapshot tests unless UI behavior is the featureUse mocks/stubs when working with external systems (Supabase, Stripe, webhooks, etc.)Store test files alongside the modules they cover or in clearly mapped `/__tests__/` folders8. Debugging & Diagnostics
Use `console.log()` only for targeted debugging and remove before merging unless intentionalLog context-rich messages including input data, state summaries, or error originsCreate temporary debug-only wrappers in `dev_resources/` if needed and document them clearlyUse proper logging levels (error, warn, info, debug) appropriately9. Commenting & Traceability
Include high-level comments at the top of each file and each function to explain intentPrioritize explaining **why** something is done, not just what the code doesLink to related issues, PRs, or Slack threads when context is externalKeep comments up-to-date when changing code10. Deployment Readiness
Use feature flags or guards for any potentially breaking or experimental logicDouble-check for unintended changes in API contracts, database schemas, or user-facing logicPRs must be atomic — no bundling of unrelated fixes, experiments, or featuresEnsure all changes are backward-compatible or properly migration-planned11. Documentation & Developer Notes
Add edge case notes or gotchas in a markdown file inside `dev_resources/notes/`Update READMEs or add inline documentation for new modules or patternsWhen unsure where to document something, leave a `NOTE:` comment with contextKeep documentation close to the code it describesKey Reminders
**If you're not 95% sure what's being asked, pause and clarify before coding**Simple, maintainable code always wins over clever solutionsLeave the codebase cleaner than you found itThink about the developer who will maintain this code in 6 monthsExample Usage
When implementing a new feature:
1. Ask clarifying questions until requirements are crystal clear
2. Search the codebase for existing patterns and utilities to reuse
3. Write the simplest solution that works
4. Add tests for critical paths and edge cases
5. Document why decisions were made in comments and commit messages
6. Ensure environment variables are properly configured
7. Review for potential breaking changes or missing guards
8. Clean up any temporary debugging code
This skill ensures all Sovant AI code maintains high quality standards and remains maintainable as the codebase grows.