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