tech-debt-audit

技术债务审计协议

针对 oh-my-openagent（OMO）的模型无关技术债务审计。使用 OMO 内置工具（grep、glob、bash 配合 sg、read、lsp_diagnostics、task）。生成有依据、可引用的 TECH_DEBT_AUDIT.md 文档。

输出

将结果写入仓库根目录下的 TECH_DEBT_AUDIT.md，包含：

1. 执行摘要 — 3-5 句话：整体健康状况、问题最严重的维度、快速见效项数量
2. 思维模型 — 用 1 个段落说明仓库的架构（用途、技术栈、模块边界）
3. 发现表 — 列：ID、类别、文件:行号、严重程度（Critical/High/Medium/Low）、工作量（小时）、描述、建议
4. 优先级前 5 项 — 按影响与工作量之比排序
5. 快速见效项清单 — 每项耗时少于 30 分钟
6. “看起来糟糕但其实没问题” — 看似技术债、实则有意为之的模式
7. 待明确问题 — 维护者应澄清的事项

阶段 0：了解项目

标准（始终运行）

1. glob("**/*.ts") / glob("**/*.py") 等 — 梳理语言技术栈
2. glob("**/package.json") + read() — 查看依赖和构建工具
3. bash("git log --oneline -200") — 分析变更频率：找出改动最多的文件
4. glob("**/*") + 基本计算 — 找出最大的文件（>300 LOC 的文件可作为候选）
5. 交叉比对高变更频率文件和大文件 = 技术债热点区域
6. 在自己的工作上下文中写下思维模型段落

阶段 1：从 9 个维度进行审计

每个维度都使用 OMO 工具。在每个维度内并行调用工具。每条发现都必须引用 file:line:col。

1. 架构退化

标准（始终运行）

• bash("sg -p \"import { $$$ } from '$SRC'\" -l ts .") — 梳理模块图，查找循环模式
• bash("sg -p \"class $NAME { $$$ }\" -l ts .") — 检查是否存在上帝类
• grep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP") — 查找带标记的技术债
• 在看似同步的文件中使用 grep("async|await") — 查找放置不当的异步边界
• 对阶段 0 找到的每个大文件运行 bash("wc -l <file>")

需要标记的问题

• 500 LOC 的文件（上帝文件）

• 80 LOC 或嵌套层级 > 4 的函数

• 方法数 > 15 或 > 400 LOC 的类
• 导入循环（A → B → A）
• 死导出：已定义但未在其他地方导入的函数/类（使用 lsp_find_references 确认）
• 注释掉的代码块（连续超过 3 行）

2. 一致性退化

标准（始终运行）

• bash("sg -p \"import $CLIENT from '$PKG'\" -l ts .") — 查找多个 HTTP 客户端
• grep("console.log|console.error|console.warn") — 对比直接使用 console 与使用日志记录器的情况
• bash("sg -p \"try { $$$ } catch ($$$) { $$$ }\" -l ts .") — 检查错误处理模式
• grep("as any|@ts-ignore|@ts-expect-error|as unknown") — 查找类型绕过
• grep("eslint-disable|prettier-ignore") — 查找 lint 禁用项

需要标记的问题

• 以 3 种或更多方式实现同一件事（HTTP、日志、验证、配置）
• 命名约定混用（camelCase + snake_case + PascalCase）
• 使用多个日期/时间处理库
• 各模块的错误响应格式不一致

3. 类型与契约债务

标准（始终运行）

• bash("sg -p \"$VALUE as any\" -l ts .") — 查找运行时类型绕过
• grep("@ts-expect-error") — 查找被抑制的错误
• grep("@ts-ignore") — 查找被抑制的错误（旧式）
• bash("sg -p \"$NAME: any\" -l ts .") — 查找类型标注为 any 的项
• lsp_diagnostics(filePath="<src-dir>") — 检查当前类型错误

需要标记的问题

• 公共 API 和导出接口中的 any 类型
• 未标注类型的函数参数
• API/IO 边界缺少 schema 验证
• 按文件归类的 LSP 类型错误

4. 测试债务

标准（始终运行）

• glob("**/*.test.ts") — 查找所有测试文件
• bash("bun test 2>&1 | grep -E '(fail|skip|todo)'") — 检查当前测试健康状况
• 将阶段 0 中变更频率高的文件与测试文件是否存在进行交叉比对

需要标记的问题

• 关键路径文件没有任何测试
• 已跳过的测试（test.skip、describe.skip）
• 测试断言实现细节而非行为
• 缓慢的测试（每项 >1s）

5. 依赖与配置债务

标准检查（始终运行）

• bash("npm audit --omit=dev 2>&1 | head -40") — 检查已知 CVE（如果存在 node_modules）
• read("package.json") — 检查依赖数量和过时依赖
• grep(".env|process.env|Bun.env") — 检查环境变量用法
• 在非配置文件中执行 grep("API_KEY|SECRET|PASSWORD|TOKEN") — 检查硬编码配置

需要标记的问题

• 已过时的主版本依赖
• 功能相同的依赖（重复库）
• README 中未记录的引用环境变量
• 硬编码的特定环境值

6. 性能与资源规范

标准检查（始终运行）

• bash("sg -p \"for ($$$ of $$$) { $$$ await $$$ }\" -l ts .") — 检查循环中的异步操作
• grep("await.*map|await.*filter|await.*forEach") — 检查顺序执行的异步迭代
• grep("Promise\\.all|Promise\\.allSettled") — 检查现有并行模式（良好信号）
• 检查 addEventListener|on\\(|subscribe，且附近没有 removeEventListener|off\\(|unsubscribe — 检查监听器规范

需要标记的问题

• for/of 循环中的 await（有并行处理可能，却采用顺序执行）
• N+1 查询模式
• 事件监听器、定时器、句柄缺少清理
• 不必要的序列化／反序列化

7. 错误处理与可观测性

标准检查（始终运行）

• bash("sg -p \"catch ($$$) { $$$ }\" -l ts .") — 检查 catch 块
• grep("catch.*{}|catch.*{\\s*}") — 检查空 catch 块
• grep("console.error|logger\\.error|log\\.error") — 检查实际错误日志
• bash("sg -p \"throw new $ERR($$$)\" -l ts .") — 检查使用的错误类型

需要标记的问题

• 空 catch 块（最严重的问题）
• 没有恢复处理的通用 catch (e) { console.error(e) }
• 各模块中的错误结构不一致
• 关键路径缺少结构化日志
• Promise 链中吞掉错误（.catch(() => {})）

8. 安全规范

标准检查（始终运行）

• 在源文件中（不包括配置文件或环境文件）执行 grep("api[Kk]ey|api_secret|password|secret|token|credential")
• grep("SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM") — 检查 SQL 构造
• grep("innerHTML|dangerouslySetInnerHTML") — 检查 XSS 攻击向量
• grep("eval\\(|Function\\(|setTimeout\\(.*string|setInterval\\(.*string") — 检查代码注入

需要标记的问题

• 源代码中硬编码的密钥
• 通过字符串拼接构造 SQL
• 使用 innerHTML／dangerouslySetInnerHTML
• 使用 eval() 或基于字符串的 setTimeout／setInterval
• 过于宽松的 CORS 或身份验证中间件

9. 文档偏差

标准检查（始终运行）

• read("README.md") — 检查文档描述是否符合实际情况
• grep("@param|@returns|@throws") — 检查文档注释覆盖情况
• grep("FIXME|TODO|HACK|XXX|WORKAROUND") — 检查待处理标记密度
• 将 README 中的 API 示例与实际签名进行比较

需要标记的问题

• README 声称存在实际并不存在的功能
• 公共函数没有任何文档注释
• 注释与代码相矛盾
• 过时的架构决策记录（ADR）（如果存在）

阶段 2：深入检查（并行子 Agent）

对于大型代码库（>50k LOC），将复杂维度委派给并行子 Agent。每个子 Agent 针对其负责的维度运行标准工具检查：

task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 1 (Architecture) and 2 (Consistency). [REQUEST] Run ast_grep and grep searches for dimensions 1-2 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity: Critical/High/Medium/Low.")
task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 3 (Type debt) and 7 (Error handling). [REQUEST] Run searches for dimensions 3 and 7 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity.")

针对最复杂的维度启动 2-3 个子 Agent，并行收集结果，然后综合分析。

阶段 3：综合并交付

1. 收集直接工具调用和子 Agent 结果中的所有发现
2. 去重——合并多个维度提到的同一问题
3. 对严重程度分类：
   • 严重 — 导致行为错误、数据丢失或安全漏洞
   • 高 — 将导致生产环境问题；阻碍维护
   • 中 — 降低可维护性；违反约定
   • 低 — 外观问题；处理相关代码时应修复
4. 保守估算每项发现的工时
5. 编写包含所有必需章节的 TECH_DEBT_AUDIT.md
6. 向用户报告摘要

严重程度标准

Critical = actively causing bugs or security holes
High     = will cause problems under normal operation; blocks changes
Medium   = reduces maintainability; inconsistent; violates team conventions
Low      = cosmetic; would be nice to fix when nearby

完成前快速检查

• 每个具体发现都附有 file:line:col 引用
• 没有缺乏证据的笼统说法
• “看起来有问题但实际上没问题”部分至少解释了 2～3 种模式
• 按影响／工作量对优先级前 5 项进行排序
• 快速改进项均可在 30 分钟内单独修复