SuperAPI AI 工具集

coding-rules

编程与开发

查看项目

更新于 10-16 09:27

技能介绍

这是一套语言无关的编码规范,目标是在实现功能、重构、代码质量评审时统一标准,优先考虑长期可维护性而非速度。核心原则包括:简单优先(YAGNI)、设计收敛(用最少的新设计面满足当前需求)、显式优于隐式、删除无用代码而非注释掉。规范定义了“设计面”概念:持久状态、公共契约或跨边界字段、行为模式与开关、可复用抽象、抽取的服务、共享工具、组件拆分等属于维护面元素,仅在当前需求、已验证约束、已观察问题或有据可依的重大风险要求时才新增;私有局部变量、无外部观察者的内部辅助函数、测试夹具等不算。代码质量方面要求命名取自问题域、提取魔法数字与字符串为常量、代码自解释。函数设计:每函数 0-2 个参数(3+ 用对象)、单一职责、少于 50 行、尽量使用纯函数、早返回使嵌套不超过 3 层、显式注入外部依赖。错误处理要求必须处理每个错误,禁止静默抑制,快速失败并屏蔽敏感数据。依赖管理强调依赖抽象而非具体实现。引用代表性要求采纳现有代码模式前先确认其在仓库中具有代表性,依赖版本证据不足时应升级处理而非猜测。性能上先测量再优化。代码组织要求每文件单一主职责、文件不超过 500 行。注释只写为什么、限制、边界情况或公共 API 契约,不写历史信息。重构遵循安全变更协议:理解现状、做一个小改动、运行测试确认通过、重复。安全方面要求密钥经环境变量或密钥管理器存储、参数化查询、标准加密库与安全随机数、输入在入口校验、按渲染上下文编码输出、认证覆盖所有处理用户数据或触发状态变更的入口、逐资源校验授权、最小权限。知识截止补充(2026-03)提到 OWASP Top 10:2025 转向根因、新增软件供应链失败与异常条件处理不当,AI 生成代码的访问控制缺口较多,OpenSSF 发布面向 AI 代码助手指令的安全指南。版本控制要求原子化提交、提交可测试通过的代码、不提交调试代码或密钥。TypeScript/React 的具体规则见 references/typescript.md,详细检测模式见 references/security-checks.md。安装与使用方式暂未提供。