software-development-maintainer.md

July 28, 2026 · View on GitHub

基本原则

这是长期维护的正式项目，不是一次性 Demo。

修改代码时优先保证：

正确性和安全性
不破坏现有功能
复用现有实现
最小改动
可维护性和可测试性

编码前

开始修改前，先搜索项目中是否已有类似实现，包括：

函数、类、组件
Service、Repository、Hook
API 封装
类型、常量、配置
校验、转换、错误处理逻辑

优先顺序：

直接复用
扩展现有实现
抽取公共逻辑
确实无法复用时再新增

禁止在未检查现有代码的情况下重新实现相同功能。

复杂任务开始前，先简要说明：

相关现有实现
可复用模块
准备修改的文件
是否需要新增文件
主要风险

小改动无需写冗长计划。

禁止重复造轮子

禁止：

创建与现有功能高度相似的新函数、类或组件
复制已有代码后只修改少量内容
重复定义类型、常量、枚举、错误码和接口地址
绕过现有 Service、Repository 或 API Client 重写调用逻辑
在多个位置分别实现同一业务规则
引入与现有依赖功能重复的新依赖

相同业务规则应只有一个权威实现。

文件与函数规模

行数只作为预警，不是硬性限制。禁止为了减少行数而机械拆分。

参考范围：

函数建议不超过 80 行
函数超过 100 行时检查是否职责过多
组件或类建议不超过 500 行
业务文件建议不超过 800 行
文件超过 1200 行时优先评估拆分
文件超过 1500 行且包含多个职责时应拆分

以下情况即使代码不长，也应考虑拆分：

一个模块承担多个无关职责
嵌套过深或条件分支过多
相同逻辑重复出现
难以测试、阅读或复用
修改一个功能经常影响无关功能

以下文件可适当放宽：

自动生成代码
类型声明
静态配置或数据
Schema
数据库迁移
集中式路由或注册文件

拆分必须依据业务职责，不得创建大量无意义的小文件。

修改原则

优先最小改动
不做与当前需求无关的重构
不为小需求重写整个模块
不擅自修改公共接口、数据库结构或返回格式
保持现有目录、命名、风格和架构
不创建 new、final、v2、copy、backup 等重复文件
不保留废弃代码、注释代码、调试输出和无意义 TODO
不随意新增依赖

发现架构问题时，优先采用渐进式改造，不要一次性重写。

代码设计

每个函数、类、组件和文件应有明确职责。

避免：

UI、请求、状态和业务逻辑全部写在一个组件
Controller 同时处理校验、业务和数据库操作
巨型 utils、constants、types 文件
过深嵌套
大量布尔参数
隐藏副作用
硬编码配置和业务值
大量 any
空 catch
吞掉异常

不要过度抽象。只有在逻辑重复、稳定或需要复用时才抽取公共模块。

安全与错误处理

必须考虑：

参数非法
空值和边界值
权限校验
网络或数据库失败
外部服务超时
并发和重复提交
文件操作失败
敏感信息泄漏

禁止：

硬编码密码、Token 或密钥
关闭安全校验
记录敏感信息
SQL 注入、命令注入、XSS、路径穿越等明显风险
捕获异常后不处理

优先复用项目现有错误类型、日志和权限机制。

测试与验证

修改完成后检查：

是否重复实现已有功能
是否出现复制粘贴代码
是否存在超长函数或职责混乱
是否破坏已有接口
是否存在未使用代码或导入
是否遗漏错误处理和边界条件
是否需要新增或更新测试

根据项目情况实际运行：

测试
Lint
类型检查
构建
格式检查

没有实际运行的检查，不得声称已经通过。

输出要求

修改多个文件时，先列出文件变更清单。

输出结果应说明：

复用了哪些现有实现
修改、新增或删除了哪些文件
核心改动是什么
是否存在兼容性风险
实际运行了哪些验证命令

不要输出冗长的过程说明，不要无意义重复整个文件。