Back to Details

global-standards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

1. 编码风格

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)
适用场景：
  • 变量、函数、类、模块或文件的命名
  • 代码结构化以提升可读性与可维护性
  • 确定函数大小与单一职责
  • 移除未使用代码、注释块或无效导入
  • 提取可复用逻辑以避免重复
  • 应用一致的格式与缩进
  • 重构代码以提升清晰度与简洁性
原则：
  • 清晰、表意明确的命名
  • DRY（不要重复自己）原则
  • 单一职责原则
  • 通过代码结构实现自文档化
  • 全代码库格式一致
适用范围： 所有代码文件（.py,.js, .ts,.jsx, .tsx,.vue, .rb,.go, .java,.rs, .cpp,.c, .swift,.kt）

2. Commenting Standards

2. 注释标准

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

3. 错误处理

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)
适用场景：
  • 使用try-catch或try-except块包裹代码
  • 创建自定义异常或错误类
  • 实现错误边界（React等）
  • 处理API调用返回的HTTP错误
  • 展示用户友好的错误信息
  • 实现带指数退避的重试逻辑
  • 在finally块中清理资源
  • 决定捕获还是传播错误
  • 按适当严重级别记录错误
  • 为外部服务实现断路器模式
  • 以结构化响应处理验证错误
原则：
  • 用户友好的错误信息
  • 正确的异常类型与层级
  • 优雅降级
  • 带上下文的全面日志记录
  • 在finally块中清理资源
  • 合理的错误传播
  • 针对瞬时故障的重试逻辑
适用范围： 所有可能抛出错误的代码（API处理器、服务函数、数据处理、文件操作、外部集成、网络请求、数据库操作）

4. Input Validation

4. 输入验证

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
适用场景：
  • 在前端验证表单输入
  • 验证API请求体、查询参数与请求头
  • 实现服务端验证逻辑
  • 创建验证模式（Zod, Yup, Pydantic, Joi）
  • 清理用户输入以防止XSS、SQL注入
  • 验证数据类型、格式、范围及必填字段
  • 实现业务规则验证
  • 展示验证错误信息
  • 为领域特定规则编写自定义验证器
  • 处理文件上传验证
原则：
  • 客户端与服务端双重验证
  • 使用验证库保证一致性
  • 清理输入以防止安全漏洞
  • 提供清晰、可操作的错误信息
  • 在系统边界处进行验证
  • 优先使用允许列表而非阻止列表
适用范围： 表单组件、API处理器、请求验证器、输入清理器、模式定义、验证中间件、文件上传、Webhook、外部API集成

5. Tech Stack Consistency

5. 技术栈一致性

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
适用场景：
  • 为新功能选择库或包
  • 使用框架特定模式实现功能
  • 搭建新服务、集成或第三方API
  • 配置数据库连接、ORM设置或查询构建器
  • 添加认证、授权或安全功能
  • 搭建测试框架、工具或测试实用程序
  • 配置部署、CI/CD流水线或基础设施
  • 评估是否添加新依赖
  • 实现缓存、监控、日志或可观测性
  • 在替代方案中做选择
原则：
  • 与现有技术选择保持一致
  • 遵循框架特定模式与惯用写法
  • 优先使用现有工具而非添加新依赖
  • 记录技术决策
  • 保持架构一致性
适用范围： 前端、后端、数据库、基础设施、测试、部署、第三方集成

6. Project Conventions

6. 项目约定

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)
适用场景：
  • 组织文件与目录结构
  • 编写Git提交信息或PR描述
  • 管理环境变量、配置与密钥
  • 添加或更新项目依赖
  • 搭建或修改CI/CD工作流
  • 实现功能开关
  • 更新README文件或项目文档
  • 确立代码评审流程
  • 维护变更日志或发布说明
  • 配置代码检查器、格式化工具或提交前钩子
  • 搭建开发环境
  • 管理单仓或多包结构
原则：
  • 一致的文件与目录组织
  • 规范化的提交信息
  • 清晰的文档
  • 合理的依赖管理
  • 自动化质量检查
  • 清晰的开发工作流
适用范围： 配置文件（.env, package.json, requirements.txt, pyproject.toml, Dockerfile, docker-compose.yml, Makefile）、目录（.github/, .gitlab-ci/, scripts/, docs/）、文档文件（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.
如需详细标准文档，可按需加载以下参考文件：
  • references/coding-style.md
     - 详细编码风格指南、命名约定、格式标准
  • references/commenting.md
     - 注释最佳实践、文档字符串标准、注释场景
  • references/error-handling.md
     - 错误处理模式、异常层级、日志策略
  • references/validation.md
     - 验证模式、模式定义、安全注意事项
  • references/tech-stack.md
     - 技术栈参考、框架模式、依赖指南
  • references/conventions.md
     - 项目约定、文件结构、Git工作流、CI/CD标准
处理特定领域内容时，加载对应参考文件获取详细指导。

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
  • code-review：评审代码是否符合标准时使用
  • dead-code-removal：清理代码时遵循编码风格
  • debugging：分析错误时应用错误处理标准
  • dependency-management：管理依赖时遵循技术栈标准