Neo-ZQYY/.claude/commands/audit.md

/audit — 变更审计

回顾本次会话中你所做的所有文件变更，结合自动预扫描结果，执行审计落盘。

执行步骤

第 1 步：运行预扫描脚本（Python，零 token）

运行：

python scripts/audit/prescan.py

该脚本自动完成：

• 从 git status 获取所有变更文件
• 分类高风险文件 + 生成 risk_tags
• 合规检查：代码→文档映射、迁移 SQL 检测、DDL 基线检查

读取输出的 JSON。如果 audit_required: false，告知用户"无需审计"并结束。

备选：如果 git status 包含大量非本次会话的历史变更，可以用 --files 参数只传入本次会话的文件：

python scripts/audit/prescan.py --files "file1.py,file2.sql,..."

文件列表从你的对话记忆（本次会话的 Edit/Write 工具调用）中提取。

第 2 步：补充语义上下文

预扫描脚本能告诉你"哪些文件变了、是否高风险、文档是否缺失"，但它不知道为什么改。

从对话记忆中补充：

• 每个变更文件的修改原因（用户的需求是什么）
• 改动的技术思路和设计决策
• 与其他模块的关联影响

将预扫描 JSON + 语义上下文合并，作为第 3 步的输入。

第 3 步：委托子代理写审计记录

用 Agent 工具启动子代理，传入：

1. 预扫描 JSON 结果（完整）
2. 每个变更的原因和内容概要（你补充的语义上下文）

子代理的任务指令：

在 docs/audit/changes/ 目录下创建审计记录文件，文件名格式 <YYYY-MM-DD>__<英文短标识>.md。

使用以下格式：

# 变更审计记录：<中文标题>

| 字段 | 值 |
|------|-----|
| 日期 | YYYY-MM-DD HH:MM:SS |

## 操作摘要
<1-3 段，说清楚做了什么、为什么做>

## 变更文件
按新增/修改/删除分组，每个文件一行，简要说明改动内容。

## 改动注解
对每个变更文件写注解：
- 高风险文件（ETL 任务/后端路由/数据库迁移/金额相关）：写详细注解（变更类型、原因、思路、结果）
- 普通文件：一行简要说明
- 删除的文件：只记录删除原因

## 数据库变更（如有）
列出新建/修改/删除的表、字段、约束、索引。标注迁移执行状态。

## 风险与回滚
- 风险点（标注高/中/低）
- 回滚要点

## 验证
- 至少 1 条可执行的验证方式（测试命令 / SQL / 联调步骤）

## 合规检查
- 列出文档同步状态（已同步 / 待补齐 / 不适用）

当前北京时间通过 python -c "from datetime import datetime, timezone, timedelta; print(datetime.now(timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S'))" 获取。

审计记录语言使用简体中文。

完成后运行 python scripts/audit/gen_audit_dashboard.py 刷新审计一览表。

最终只返回：done / files_written / next_step。

第 4 步：补齐缺失的文档同步

根据预扫描 JSON 中 code_without_docs 列出的不合规项，逐项补齐：

• 读取对应代码文件当前内容
• 更新对应文档

如果补齐工作量大（>3 个文档），委托子代理处理。

第 5 步：向用户报告

简短回执：

• 审计记录文件路径
• 合规检查结果（全部通过 / N 项已补齐 / N 项待用户处理）
• 下一步建议（如 "commit when ready"）