| name | code-audit |
| description | Audit a whole project for code quality, architecture, security, performance, and engineering maturity. Use when the user asks to "audit the project", "code review", "review the codebase", produce a technical-debt report, or fill an audit template. Works for Python / TS / Go / Rust monorepos including agent projects. |
Code Audit
按"先证据、后判断、再路线图"的顺序产出一份能落地的审计报告。
工作铁律
- 不要凭印象填表。每次开工先跑
scripts/recon.sh 拿硬数据，所有评分必须有命令输出 / 文件:行号兜底。
- 每个问题三件套：
file:line + 代码片段（≤ 6 行）+ 修复 patch（伪代码或具体 diff）。少一件就不算合格。
- 风险 = 缺陷 × 部署上下文。同一个
shell=True，CLI 个人脚本 = 低；暴露端口的 WebUI = 极高。审计前先问清楚"打算给谁用 / 怎么部署"。
- 三段式路线图，不开扁平 todo：P0 止血（安全 / 数据正确性） → P1 提质（测试 / 日志 / 工程化） → P2 升级（架构 / 商业化）。
- 诚实打分，不调和。0 测试给 0/10；后面写"作为个人项目可接受"的语境注脚就行。
- 节省 round-trip。Bash 调用尽量串多条命令；同一个文件优先 outline（grep
def/class）再按行号 sed。
五阶段流程
阶段 0 · 定调（≤ 30 秒，一次到位）
跟用户或当前上下文确认三件事，三件都不知道就先问再做：
- 项目类型：Web 前端 / 后端 / 全栈 / Agent / 库 / CLI 工具
- 部署上下文：纯本地脚本？SaaS？多租户？开源给极客？
- 审计目的：拿来评 PR / 准备发版 / 决定是否商业化 / 接手二开
定调决定后续每个评分的语义。没有部署上下文就给安全打分是没意义的。
阶段 1 · 侦察（≤ 5 分钟，跑脚本）
调用 scripts/recon.sh。它一次性产出：
- 顶层目录 + 工程化文件存在性（pyproject、Dockerfile、CI、lint 配置 …）
- LoC 排序前 15 文件（god class 嫌疑）
- 总代码量
- 测试文件计数
- print / logger / except 计数
- 依赖文件原文（requirements / package.json / go.mod 等）
- git 基本信息（提交数、贡献者、热点文件、最近 90 天 churn）
- 危险代码 pattern grep（
shell=True、eval(、exec(、pickle.loads、明文密钥模式）
把脚本输出整段贴到草稿区，全部审计结论从这里取证。脚本输出本身不直接进最终报告，是工作底稿。
阶段 2 · 定向探查（按发现深入）
根据侦察结果挑 ≤ 5 个最可疑点深读，每点用 Read/grep -n 拿到精确 file:line。常见入口：
- 最大文件 → outline 是否单一职责
- 安全敏感文件（auth/security/shell/filesystem/upload）→ 围栏检查
- 配置回传路径（config payload / bootstrap API）→ 密钥脱敏检查
- 异常处理热区 → 是否吞 traceback
- 公网入口（HTTP/WS handler）→ 鉴权 + 输入校验
每点产出一段笔记：现状代码片段 + 问题机制 + 影响 + 修复 sketch。
把第 1–2 阶段的笔记填进模板。规矩：
- 每个"分析"段落 ≤ 5 行；超 5 行说明在塞水。
- 每个评分给一行依据：
X/10 —— 因为 [证据]。
- "解决方案"必须给具体 patch（10–30 行内），不写"建议加日志"这种废话。
- 最后"下一步最优先 3 件事"按工时估算（4h / 半天 / 1 天），让用户能立即排期。
阶段 4 · 自检（提交前）
读自己的报告一遍，碰到这些信号就退回去补：
- 出现"建议提高 / 加强 / 优化"等动词无宾语 → 改成具体动作
- 出现整段没有
file:line 或代码块 → 加证据
- 评分跨度 < 4 分（全 6/10）→ 多半在和稀泥，重新盘
- 路线图扁平没分阶段 → 拆 P0/P1/P2
- 安全章节没"如果在公网会怎样"的反例 → 补
红旗目录（按出现频率排）
详见 references/red-flags.md。最常见 10 项：
subprocess.run(..., shell=True) 无 timeout / 无 cwd 限制 → RCEPath(user_input).resolve() 无 relative_to(workspace) → 路径穿越/api/config 等返回 config.raw 含 apiKey → 密钥泄露except Exception + 仅 print(exc) → 吞 tracebackprint() 满天飞 + 已声明 logger 依赖未用 → 工具配置半成品requirements.txt 钉死全部传递依赖（pip freeze 风格）→ 升级矩阵爆炸- 直接依赖列在 deps 里但代码 0 import → 死依赖
- 单文件 > 500 LoC、单函数 > 80 LoC → god class / god function
tests/ 不存在 → 直接 0/10- CI 不存在 + lint 不存在 + pre-commit 不存在 → 工程化 ≤ 2/10
评分尺（重要）
详见 references/scoring-rubric.md。核心准则：
- 0/10：完全没有（0 测试、0 logger、0 类型注解）
- 3/10：尝试过但本质不可用（写了 print 当日志、TODO 留了一堆）
- 5/10：能跑但不可演进（无回归保护、维护靠记忆）
- 7/10：日常使用稳定，重构无安全网但 review 能挡
- 9/10：可商业化、多人协作、有完整监控
- 10/10：业内标杆
不允许给 8.5/10 这种。整数即可，少装精确。
反模式（写报告时必须避免）
- ❌ "代码质量较低，建议改进" → 没量化、没动作
- ❌ "应该使用 [框架 X]" → 不给现状失败的证据
- ❌ "整体良好" + 同时存在 RCE → 自相矛盾
- ❌ 全维度均匀打 6/10 → 没分辨力
- ❌ 列 30 个 P1 → 等于没排序
- ❌ 给"上层抽象"建议但不给落地代码 → 等于没说
资源索引
