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