Global Standards

Project Standards

This skill provides comprehensive guidance on project-wide coding standards, conventions, and best practices that apply across the entire codebase regardless of language or framework.

When to Use This Skill

Use this skill when:

• Writing code - Ensuring consistency with project standards
• Making architectural decisions - Following established patterns
• Onboarding - Understanding project conventions
• Code review - Checking adherence to standards
• Refactoring - Maintaining consistency during changes
• Setting up new features - Following project conventions

Core Standards Areas

1. Coding Style

When to apply:

• Naming variables, functions, classes, modules, or files
• Structuring code for readability and maintainability
• Deciding on function size and single responsibility
• Removing unused code, commented-out blocks, or dead imports
• Extracting reusable logic to avoid duplication
• Applying consistent formatting and indentation
• Refactoring code for clarity and simplicity

Principles:

• Clear, descriptive names that reveal intent
• DRY (Don't Repeat Yourself) principle
• Single Responsibility Principle
• Self-documenting code through structure
• Consistent formatting across the codebase

Applies to: All code files (.py,.js, .ts,.jsx, .tsx,.vue, .rb,.go, .java,.rs, .cpp,.c, .swift,.kt)

2. Commenting Standards

When to apply:

• Deciding whether code needs a comment
• Documenting complex algorithms or non-obvious business logic
• Writing docstrings or function documentation
• Reviewing existing comments for relevance
• Removing outdated or misleading comments
• Explaining non-obvious code decisions or workarounds

Principles:

• Minimal, helpful comments
• Explain why, not what
• Keep code self-documenting through clear naming
• Comments should explain complex logic or business rules
• Avoid comments that restate what code does
• Keep comments evergreen and relevant

Applies to: All code files across the entire codebase

3. Error Handling

When to apply:

• Wrapping code in try-catch or try-except blocks
• Creating custom exception or error classes
• Implementing error boundaries (React, etc.)
• Handling HTTP errors from API calls
• Displaying user-friendly error messages
• Implementing retry logic with exponential backoff
• Cleaning up resources in finally blocks
• Deciding where to catch versus propagate errors
• Logging errors with appropriate severity levels
• Implementing circuit breakers for external services
• Handling validation errors with structured responses

Principles:

• User-friendly error messages
• Proper exception types and hierarchies
• Graceful degradation
• Comprehensive logging with context
• Resource cleanup in finally blocks
• Appropriate error propagation
• Retry logic for transient failures

Applies to: All code that may throw errors (API handlers, service functions, data processing, file operations, external integrations, network requests, database operations)

4. Input Validation

When to apply:

• Validating form inputs on the frontend
• Validating API request bodies, query parameters, and headers
• Implementing server-side validation logic
• Creating validation schemas (Zod, Yup, Pydantic, Joi)
• Sanitizing user input to prevent XSS, SQL injection
• Validating data types, formats, ranges, and required fields
• Implementing business rule validation
• Displaying validation error messages
• Writing custom validators for domain-specific rules
• Handling file upload validation

Principles:

• Validate on both client and server sides
• Use validation libraries for consistency
• Sanitize input to prevent security vulnerabilities
• Provide clear, actionable error messages
• Validate at system boundaries
• Use allowlists over blocklists

Applies to: Form components, API handlers, request validators, input sanitizers, schema definitions, validation middleware, file uploads, webhooks, external API integrations

5. Tech Stack Consistency

When to apply:

• Choosing libraries or packages for new functionality
• Implementing features using framework-specific patterns
• Setting up new services, integrations, or third-party APIs
• Configuring database connections, ORM settings, or query builders
• Adding authentication, authorization, or security features
• Setting up testing frameworks, tools, or test utilities
• Configuring deployment, CI/CD pipelines, or infrastructure
• Evaluating whether to add a new dependency
• Implementing caching, monitoring, logging, or observability
• Choosing between alternative approaches

Principles:

• Consistency with existing technology choices
• Follow framework-specific patterns and idioms
• Prefer existing tools over adding new dependencies
• Document technology decisions
• Maintain architectural consistency

Applies to: Frontend, backend, database, infrastructure, testing, deployment, third-party integrations

6. Project Conventions

When to apply:

• Organizing files and directory structure
• Writing git commit messages or PR descriptions
• Managing environment variables, configuration, and secrets
• Adding or updating project dependencies
• Setting up or modifying CI/CD workflows
• Implementing feature flags
• Updating README files or project documentation
• Establishing code review processes
• Maintaining changelogs or release notes
• Configuring linters, formatters, or pre-commit hooks
• Setting up development environments
• Managing monorepo or multi-package structures

Principles:

• Consistent file and directory organization
• Conventional commit messages
• Clear documentation
• Proper dependency management
• Automated quality checks
• Clear development workflows

Applies to: Configuration files (.env, package.json, requirements.txt, pyproject.toml, Dockerfile, docker-compose.yml, Makefile), directories (.github/, .gitlab-ci/, scripts/, docs/), documentation files (README.md, CHANGELOG.md, CONTRIBUTING.md)

Reference Files

For detailed standards documentation, load reference files as needed:

• `references/coding-style.md` - Detailed coding style guidelines, naming conventions, formatting standards
• `references/commenting.md` - Commenting best practices, docstring standards, when to comment
• `references/error-handling.md` - Error handling patterns, exception hierarchies, logging strategies
• `references/validation.md` - Validation patterns, schema definitions, security considerations
• `references/tech-stack.md` - Technology stack reference, framework patterns, dependency guidelines
• `references/conventions.md` - Project conventions, file structure, git workflows, CI/CD standards

When working on specific areas, load the appropriate reference file for detailed guidance.

Best Practices

Consistency First

• Follow existing patterns in the codebase
• When in doubt, match the style of surrounding code
• Maintain consistency across all files

Progressive Enhancement

• Start with simple, clear code
• Add complexity only when necessary
• Refactor for clarity and maintainability

Documentation

• Keep documentation up to date
• Document decisions and trade-offs
• Include examples in documentation

Quality Gates

• Use linters and formatters
• Run tests before committing
• Review code for standards adherence

Integration with Other Skills

• code-review: Use when reviewing code for standards adherence
• dead-code-removal: Follow coding style when cleaning up code
• debugging: Apply error handling standards when analyzing errors
• dependency-management: Follow tech stack standards when managing dependencies

Coding Style Standards

Detailed guidelines for coding style, naming conventions, and code organization.

Naming Conventions

Variables and Functions

• Use descriptive names that reveal intent
• Prefer full words over abbreviations
• Use camelCase for JavaScript/TypeScript
• Use snake_case for Python
• Use PascalCase for classes and types

Files and Directories

• Use kebab-case for file names
• Match file names to their primary export
• Use descriptive directory names

Code Organization

Function Size

• Keep functions small and focused
• Single Responsibility Principle
• Extract complex logic into separate functions

Structure

• Clear separation of concerns
• Logical grouping of related code
• Consistent indentation and formatting

DRY Principle

• Extract reusable logic into functions
• Avoid code duplication
• Use shared utilities and helpers

Formatting

• Consistent indentation (spaces or tabs per project)
• Proper spacing around operators
• Consistent line length limits
• Proper import organization

Commenting Standards

Guidelines for when and how to write code comments.

When to Comment

Do Comment

• Complex algorithms or business logic
• Non-obvious code decisions or workarounds
• Public APIs and interfaces
• Edge cases and known limitations
• Why code exists (not what it does)

Don't Comment

• Obvious code that's self-explanatory
• Code that simply restates what's already clear
• Outdated or irrelevant information

Comment Types

Docstrings

• Function and class documentation
• Parameter descriptions
• Return value documentation
• Usage examples when helpful

Inline Comments

• Explain complex logic
• Document workarounds
• Note important considerations

TODO Comments

• Include context and rationale
• Link to issues when possible
• Include priority or timeline

Best Practices

• Keep comments up to date
• Write comments that explain why, not what
• Use clear, concise language
• Remove outdated comments

Project Conventions

File structure, git workflows, and project organization standards.

File Structure

Organization

• Logical grouping of related files
• Consistent directory naming
• Clear separation of concerns
• Standard project layout

Naming

• Use kebab-case for files and directories
• Match file names to their purpose
• Use descriptive names

Git Workflows

Commit Messages

• Use conventional commit format
• Write clear, descriptive messages
• Reference issues when applicable
• Keep commits focused and atomic

Branching

• Use feature branches
• Follow branch naming conventions
• Keep branches up to date
• Clean up merged branches

Configuration Files

Environment Variables

• Use .env files for local development
• Document required variables
• Never commit secrets
• Provide .env.example template

Dependencies

• Keep dependency files organized
• Document dependency purposes
• Use lock files for reproducibility
• Regularly update dependencies

CI/CD

Workflows

• Automate testing and linting
• Run checks before merging
• Deploy automatically on merge
• Monitor deployment status

Quality Gates

• Require passing tests
• Enforce code style
• Check security vulnerabilities
• Validate configuration

Documentation

README

• Clear project description
• Setup instructions
• Usage examples
• Contributing guidelines

Changelog

• Document all changes
• Use semantic versioning
• Group changes by type
• Include migration notes

Error Handling Standards

Comprehensive error handling patterns and best practices.

Error Handling Patterns

Try-Catch Blocks

• Wrap code that may throw errors
• Catch specific exception types when possible
• Provide meaningful error messages
• Clean up resources in finally blocks

Custom Exceptions

• Create domain-specific exception types
• Build exception hierarchies
• Include context in error messages

Error Propagation

• Catch errors at appropriate boundaries
• Propagate errors when they can't be handled locally
• Transform errors at layer boundaries

Error Messages

User-Facing Errors

• Clear, actionable messages
• Avoid technical jargon
• Suggest solutions when possible

Developer Errors

• Include stack traces
• Provide context and state information
• Use appropriate logging levels

Logging

• Log errors with appropriate severity
• Include context and stack traces
• Use structured logging when possible
• Don't log sensitive information

Retry Logic

• Implement exponential backoff
• Retry only transient failures
• Set maximum retry limits
• Log retry attempts

Circuit Breakers

• Implement for external service calls
• Prevent cascading failures
• Monitor circuit breaker state
• Provide fallback behavior

Tech Stack Standards

Technology stack reference and consistency guidelines.

Framework Patterns

Frontend

• Follow framework-specific patterns (React hooks, Vue composition API, etc.)
• Use framework-recommended libraries
• Maintain consistency with existing code

Backend

• Follow framework conventions (Express middleware, FastAPI decorators, etc.)
• Use established patterns for API design
• Maintain consistency across services

Dependency Management

Adding Dependencies

• Evaluate necessity before adding
• Prefer existing tools over new ones
• Check for security vulnerabilities
• Document why dependency is needed

Version Management

• Pin versions for production
• Use semantic versioning
• Keep dependencies up to date
• Test updates before deploying

Technology Choices

Consistency

• Use established patterns
• Follow project conventions
• Document technology decisions
• Maintain architectural consistency

Evaluation Criteria

• Performance requirements
• Team expertise
• Maintenance burden
• Security considerations
• Cost implications

Validation Standards

Input validation patterns and security best practices.

Validation Principles

Client and Server

• Always validate on the server side
• Provide immediate feedback on the client
• Never trust client-side validation alone

Validation Libraries

• Use established libraries (Zod, Yup, Pydantic, Joi)
• Define schemas for consistency
• Reuse validation schemas across layers

Input Sanitization

Security

• Prevent XSS attacks
• Prevent SQL injection
• Prevent command injection
• Use allowlists over blocklists

Data Types

• Validate types, formats, and ranges
• Check required fields
• Validate nested objects and arrays

Business Rules

• Validate domain-specific rules
• Check sufficient balance, valid dates, permissions
• Implement custom validators when needed

Error Messages

• Clear, actionable validation errors
• Show errors near the relevant input
• Provide real-time feedback when possible

File Uploads

• Validate file size limits
• Check allowed file types
• Validate file content when possible
• Scan for malware if applicable