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