name: global-standards description: 项目范围内的编码标准和规范专家。在编写代码、制定架构决策或建立项目规范时主动使用。涵盖所有语言和框架的编码风格、注释、错误处理、验证、技术栈一致性和项目规范。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

项目标准

本技能提供全面的指导，涵盖整个代码库的项目级编码标准、规范和最佳实践，无论使用何种语言或框架。

何时使用本技能

在以下情况使用本技能：

编写代码 - 确保与项目标准保持一致
制定架构决策 - 遵循既定模式
新成员入职 - 理解项目规范
代码审查 - 检查标准遵守情况
重构 - 在更改过程中保持一致性
设置新功能 - 遵循项目规范

核心标准领域

1. 编码风格

何时应用：

命名变量、函数、类、模块或文件
为可读性和可维护性构建代码结构
决定函数大小和单一职责
删除未使用的代码、注释掉的代码块或死导入
提取可重用逻辑以避免重复
应用一致的格式和缩进
重构代码以提高清晰度和简洁性

原则：

清晰、描述性的名称，能揭示意图
DRY（不要重复自己）原则
单一职责原则
通过结构实现自文档化代码
整个代码库的格式一致

适用于： 所有代码文件（.py,.js, .ts,.jsx, .tsx,.vue, .rb,.go, .java,.rs, .cpp,.c, .swift,.kt）

2. 注释标准

何时应用：

决定代码是否需要注释
记录复杂算法或非显而易见的业务逻辑
编写文档字符串或函数文档
审查现有注释的相关性
删除过时或误导性的注释
解释非显而易见的代码决策或变通方法

原则：

最少但有用的注释
解释“为什么”，而不是“是什么”
通过清晰的命名保持代码自文档化
注释应解释复杂逻辑或业务规则
避免重复代码功能的注释
保持注释常新且相关

适用于： 整个代码库中的所有代码文件

3. 错误处理

何时应用：

将代码包装在 try-catch 或 try-except 块中
创建自定义异常或错误类
实现错误边界（React 等）
处理来自 API 调用的 HTTP 错误
显示用户友好的错误消息
实现具有指数退避的重试逻辑
在 finally 块中清理资源
决定在何处捕获错误与传播错误
以适当的严重级别记录错误
为外部服务实现断路器
使用结构化响应处理验证错误

原则：

用户友好的错误消息
正确的异常类型和层次结构
优雅降级
具有上下文的全面日志记录
在 finally 块中清理资源
适当的错误传播
针对暂时性故障的重试逻辑

适用于： 所有可能抛出错误的代码（API 处理程序、服务函数、数据处理、文件操作、外部集成、网络请求、数据库操作）

4. 输入验证

何时应用：

在前端验证表单输入
验证 API 请求体、查询参数和标头
实现服务器端验证逻辑
创建验证模式（Zod、Yup、Pydantic、Joi）
清理用户输入以防止 XSS、SQL 注入
验证数据类型、格式、范围和必填字段
实现业务规则验证
显示验证错误消息
为特定领域规则编写自定义验证器
处理文件上传验证

原则：

在客户端和服务器端都进行验证
使用验证库以确保一致性
清理输入以防止安全漏洞
提供清晰、可操作的错误消息
在系统边界进行验证
使用允许列表而非阻止列表

适用于： 表单组件、API 处理程序、请求验证器、输入清理器、模式定义、验证中间件、文件上传、Webhook、外部 API 集成

5. 技术栈一致性

何时应用：

为新功能选择库或包
使用特定于框架的模式实现功能
设置新服务、集成或第三方 API
配置数据库连接、ORM 设置或查询构建器
添加身份验证、授权或安全功能
设置测试框架、工具或测试实用程序
配置部署、CI/CD 管道或基础设施
评估是否添加新依赖项
实现缓存、监控、日志记录或可观测性
在替代方法之间进行选择

原则：

与现有技术选择保持一致
遵循特定于框架的模式和惯用法
优先使用现有工具而非添加新依赖项
记录技术决策
保持架构一致性

适用于： 前端、后端、数据库、基础设施、测试、部署、第三方集成

6. 项目规范

何时应用：

组织文件和目录结构
编写 git 提交消息或 PR 描述
管理环境变量、配置和机密信息
添加或更新项目依赖项
设置或修改 CI/CD 工作流
实现功能标志
更新 README 文件或项目文档
建立代码审查流程
维护变更日志或发布说明
配置 linter、格式化程序或预提交钩子
设置开发环境
管理 monorepo 或多包结构

原则：

一致的文件和目录组织
常规的提交消息
清晰的文档
正确的依赖项管理
自动化的质量检查
清晰的开发工作流程

适用于： 配置文件（.env、package.json、requirements.txt、pyproject.toml、Dockerfile、docker-compose.yml、Makefile）、目录（.github/、.gitlab-ci/、scripts/、docs/）、文档文件（README.md、CHANGELOG.md、CONTRIBUTING.md）

参考文件

有关详细的标准文档，请根据需要加载参考文件：

references/coding-style.md - 详细的编码风格指南、命名约定、格式标准
references/commenting.md - 注释最佳实践、文档字符串标准、何时注释
references/error-handling.md - 错误处理模式、异常层次结构、日志记录策略
references/validation.md - 验证模式、模式定义、安全注意事项
references/tech-stack.md - 技术栈参考、框架模式、依赖项指南
references/conventions.md - 项目规范、文件结构、git 工作流程、CI/CD 标准

在处理特定领域时，加载相应的参考文件以获取详细指导。

最佳实践

一致性优先

遵循代码库中的现有模式
如有疑问，匹配周围代码的风格
在所有文件中保持一致

渐进增强

从简单、清晰的代码开始
仅在必要时增加复杂性
为清晰度和可维护性进行重构

文档

保持文档最新
记录决策和权衡
在文档中包含示例

质量门控

使用 linter 和格式化程序
在提交前运行测试
审查代码是否符合标准

与其他技能的集成

code-review：在审查代码是否符合标准时使用
dead-code-removal：在清理代码时遵循编码风格
debugging：在分析错误时应用错误处理标准
dependency-management：在管理依赖项时遵循技术栈标准