global-standards

项目标准

此技能提供全面的项目级编码标准、约定和最佳实践指南，适用于整个代码库，不受语言或框架限制。

何时使用此技能

在以下情况下使用此技能：

• 编写代码 —— 确保符合项目标准
• 做出架构决策 —— 遵循既定模式
• 入职 —— 了解项目约定
• 代码审查 —— 检查是否遵循标准
• 重构 —— 在修改过程中保持一致性
• 设置新功能 —— 遵循项目约定

核心标准领域

1. 编码风格

适用场景：

• 为变量、函数、类、模块或文件命名
• 组织代码，使其易于阅读和维护
• 确定函数的大小和单一职责
• 删除未使用的代码、已注释掉的代码块或无用的导入
• 提取可复用逻辑以避免重复
• 采用一致的格式和缩进
• 重构代码以提升清晰度和简洁性

原则：

• 使用清晰、描述性强且能体现意图的名称
• DRY（Don't Repeat Yourself）原则
• 单一职责原则
• 通过结构实现代码自解释
• 在整个代码库中保持格式一致

适用于： 所有代码文件（.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 文件或项目文档
• 建立代码审查流程
• 维护变更日志或发行说明
• 配置代码检查器、格式化工具或提交前钩子
• 设置开发环境
• 管理单体仓库或多软件包结构

原则：

• 保持文件和目录组织一致
• 使用约定式提交消息
• 文档清晰
• 妥善管理依赖项
• 自动执行质量检查
• 明确开发工作流

适用范围： 配置文件（.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 标准

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

最佳实践

一致性优先

• 遵循代码库中的现有模式
• 如有疑问，请采用周边代码的风格
• 在所有文件中保持一致性

渐进式增强

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

文档

• 保持文档更新
• 记录决策和权衡
• 在文档中加入示例

质量门禁

• 使用代码检查工具和格式化工具
• 提交前运行测试
• 检查代码是否符合规范

与其他技能集成

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