codebase-audit-pre-push

推送前代码库审查

作为一名高级工程师，你正在将代码推送到 GitHub 前进行最终审查。请仔细检查所有内容，并在发现问题时立即修复。

何时使用此技能

• 用户要求“审查代码库”或“推送前检查”
• 首次推送到 GitHub 前
• 将仓库设为公开前
• 生产环境部署前的审查
• 用户要求“清理代码”或“全面优化”

你的任务

逐个文件审查整个代码库。仔细阅读代码。发现问题后立即修复。不要只记录问题，还要进行必要的更改。

审查流程

1. 清理无用文件

首先，查找不应出现在 GitHub 上的文件：

检查以下候选文件；仅在授权范围内删除已确认无用的文件：

• 操作系统文件：.DS_Store、Thumbs.db、desktop.ini
• 日志：*.log、npm-debug.log*、yarn-error.log*
• 临时文件：*.tmp、*.temp、*.cache、*.swp
• 构建产物：dist/、build/、.next/、out/、.cache/
• 依赖项：node_modules/、vendor/、__pycache__/、*.pyc
• IDE 文件：.idea/、.vscode/（先询问用户）、*.iml、.project
• 备份文件：*.bak、*_old.*、*_backup.*、*_copy.*
• 测试产物：coverage/、.nyc_output/、test-results/
• 个人杂项：TODO.txt、NOTES.txt、scratch.*、test123.*

关键事项——检查机密信息：

• .env 文件（绝不应提交）
• 包含以下内容的文件：password、api_key、token、secret、private_key
• *.pem、*.key、*.cert、credentials.json、serviceAccountKey.json

如果在代码中发现机密信息，将其标记为“严重阻断问题”。

2. 修复 .gitignore

检查是否存在 .gitignore 文件，以及其规则是否完善。如果缺失或不完整，请更新文件，加入上述所有无用文件模式。确保存在 .env.example，其中包含键名但不包含值。

3. 审查每个源文件

检查每个代码文件中的以下内容：

潜在的死代码（删除前先确认使用方以及构建／运行时约定）：

• 注释掉的代码块
• 未使用的导入／require
• 未使用的变量（已声明但从未使用）
• 未使用的函数（已定义但从未调用）
• 不可达代码（return 之后的代码、if (false) 内的代码）
• 重复逻辑（多处出现相同代码——应合并）

代码质量（发现问题时及时修复）：

• 含义模糊的名称：data、info、temp、thing → 改为更具描述性的名称
• 魔法数字：if (status === 3) → 提取为具名常量
• 调试语句：删除 console.log、print()、debugger
• TODO/FIXME 注释：保留尚未解决的需求；只有在有证据且属于审查范围时才解决
• TypeScript any：添加合适的类型，或说明使用 any 的原因
• 在 JavaScript 中使用 === 而不是 ==
• 超过 50 行的函数：考虑拆分
• 嵌套层级超过 3 层的代码：使用提前返回进行重构

逻辑问题（严重）：

• 缺少 null／undefined 检查
• 对可能为空的数组执行数组操作
• 异步函数未使用 await
• Promise 未使用 .catch() 或 try/catch 处理
• 存在无限循环的可能
• switch 语句缺少 default

4. 安全检查（零容忍）

密钥： 搜索硬编码的密码、API 密钥和令牌。它们必须放在环境变量中。

注入漏洞：

• SQL：查询中不要拼接字符串——只使用参数化查询
• 命令注入：不要对用户提供的输入使用 exec()
• 路径遍历：未经校验，不要使用来自用户输入的文件路径
• XSS：不要对用户数据使用 innerHTML 或 dangerouslySetInnerHTML

认证/授权：

• 密码使用 bcrypt/argon2 哈希（绝不要用 MD5 或明文）
• 受保护的路由要检查认证
• 授权检查要在服务端进行，而不只是在 UI 中
• 避免 IDOR：验证用户是否拥有其正在访问的资源

数据暴露：

• API 响应不要泄露不必要的信息
• 错误消息不要暴露堆栈跟踪或数据库细节
• 列表端点要有分页

依赖：

• 运行 npm audit 或等效工具
• 标记严重过时或存在漏洞的软件包

5. 可扩展性检查

数据库：

• N+1 查询：循环中嵌套数据库调用 → 使用 JOIN 或批量查询
• WHERE/ORDER BY 列上缺少索引
• 无界查询：添加 LIMIT 或分页
• 避免 SELECT *：明确指定列

API 设计：

• 重操作（如邮件、报表、文件处理）→ 移到后台队列
• 对公开端点进行限流
• 对频繁读取的数据进行缓存
• 为外部调用设置超时

代码：

• 不要有全局可变状态
• 清理事件监听器（以避免内存泄漏）
• 流式处理大文件，而不是将其加载到内存中

6. 架构检查

组织：

• 清晰的文件夹结构
• 文件位于合理的位置
• 不要有 "misc" 或 "stuff" 文件夹

关注点分离：

• UI 层：只负责渲染
• 业务逻辑：纯函数
• 数据层：隔离的数据库查询
• 不要有 500+ 行的“上帝文件”

可复用性：

• 重复代码 → 提取到共享工具中
• 常量只定义一次并导入使用
• 类型/接口复用，而不是重复定义

7. 性能

后端：

• 高开销操作不要阻塞请求
• 尽可能批量执行数据库调用
• 正确设置缓存头

前端（如适用）：

• 实现代码分割
• 优化图片
• 不要为了小型工具引入庞大的依赖
• 对重型组件使用懒加载

8. 文档

README.md 必须包含：

• 项目功能的描述
• 安装和运行说明
• 所需的环境变量
• 运行测试的指引

代码注释：

• 解释 WHY，而不是 WHAT
• 为复杂逻辑提供说明
• 避免仅仅重复代码的注释

9. 测试

• 关键路径应有测试（认证、支付、核心功能）
• 代码中不应残留 test.only 或 fdescribe
• 避免没有说明的 test.skip
• 测试应验证行为，而不是实现细节

10. 最终验证

完成所有更改后，运行应用。确保没有任何东西被破坏。检查：

• 应用启动无错误
• 主要功能正常工作
• 测试通过（如果存在）
• 没有引入回归问题

输出格式

审计完成后，提供一份报告：

CODEBASE AUDIT COMPLETE  

FILES REMOVED:  
- node_modules/ (build artifact)  
- .env (contained secrets)  
- old_backup.js (unused duplicate)  

CODE CHANGES:  
[src/api/users.js]  
  ✂ Removed unused import: lodash  
  ✂ Removed dead function: formatOldWay()  
  🔧 Renamed 'data' → 'userData' for clarity  
  🛡 Added try/catch around API call (line 47)  

[src/db/queries.js]  
  ⚡ Fixed N+1 query: now uses JOIN instead of loop  

SECURITY ISSUES:  
🚨 CRITICAL: Hardcoded API key in config.js (line 12) → moved to .env  
⚠️ HIGH: SQL injection risk in search.js (line 34) → fixed with parameterized query  

SCALABILITY:  
⚡ Added pagination to /api/users endpoint  
⚡ Added index on users.email column  

FINAL STATUS:  
Status: report passed checks, unresolved findings and untested environments; no universal production-readiness certification

Scores:  
Security: list concrete findings and evidence
Code quality: list scoped findings
Scalability: state measured evidence or untested
Overall: state remaining blockers

关键原则

• 彻底阅读代码，不要略读
• 立即修复问题，不要只是记录它们
• 如果不确定是否要移除某些内容，询问用户
• 更改后进行测试
• 要彻底但务实——专注于真正的问题
• 安全问题就是阻碍——任何东西都不应在存在严重漏洞的情况下发布

相关技能

• @security-auditor - 更深入的安全审查
• @systematic-debugging - 调查具体问题
• @git-pushing - 审计后推送代码

局限性

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。

已跟踪的构建产物、供应商依赖项、测试夹具、备份和备注可能是有意保留的项目源文件。删除前，请阅读仓库约定并确认文件归属；不要仅为准备推送而删除本地 .env。如果凭据已泄露，请在报告中将其隐去，轮换或撤销凭据，并评估历史记录和构建产物；将凭据移至环境变量并不能消除泄露。请报告实际读取的确切文件和实际执行的检查；不要声称抽样审计已覆盖整个代码库。