antivibe

AntiVibe - 代码学习与审计框架

用途

AntiVibe 会针对任意代码生成以学习为导向的讲解或架构审计，无论这些代码是 AI 生成的、遗留代码，还是其他代码。它能帮助开发者了解：

• 代码做什么（功能）
• 代码为何这样编写（设计决策）
• 何时使用这些模式（上下文）
• 存在哪些替代方案（更广泛的知识）

适用于任何代码库——无需近期的 git 历史记录，也不要求文件由 AI 编写。

适用场景

在以下情况下使用 AntiVibe：

1. 手动调用：用户输入 /antivibe 或“深入讲解”
2. 任务完成后学习：功能或阶段完成后，用户希望从中学习
3. 遗留代码库：用户希望了解自己没有编写的现有代码
4. 主动调用：用户说“解释 AI 写的内容”“带我逐步了解”“审计这段代码”，或指定某个文件或目录

AntiVibe 的输出

输出以 Markdown 格式保存在 deep-dive/ 文件夹中：

deep-dive/
├── auth-system-2026-01-15.md
├── api-layer-2026-01-15.md
└── database-models-2026-01-15.md

具体包含哪些章节取决于输出模式（参见输出模式）：

章节	compact（默认）	full
概览 — 代码的作用及其存在原因	✅	✅
关键组件 / 概念 — 使用的设计模式、算法和计算机科学概念	✅	✅
代码讲解 — 逐文件、逐行注释	—	✅
学习资源 — 精选文档、教程和视频	—	✅
相关代码 — 指向代码库中其他文件的链接	—	✅

配置

已知概念（跳过列表）

此处列出的概念不会得到完整讲解——讲解器只会说明使用了这些概念，以及它们的应用场景。请编辑此列表，使其符合你当前的知识水平。

known_concepts:
  - async/await
  - React hooks
  - REST APIs

输出模式

控制每次运行生成的详细程度。默认模式为 compact，以降低令牌成本。

output_mode: compact

模式	包含内容
compact（默认）	概览、关键组件（函数级别，每项一行）、概念（仅说明是什么和为什么）。不含资源。不逐行讲解。最多 5 个文件。
full	包含 compact 的所有内容，另加：逐行讲解、前置知识、精选资源、后续步骤。

可在请求中直接指定：

• "/antivibe full"、“完整深入讲解”、“包含资源” → full 模式
• 默认：compact

默认技能水平

当请求中未指定技能水平时，设置讲解的深度。选项：junior、mid、senior。默认值：mid。

default_level: mid

水平	行为
junior	定义所有术语。使用类比。讲解语言特性。展示带内联注释的完整代码片段。
mid	跳过基础内容。聚焦设计决策和权衡。仅简要引用代码。
senior	跳过显而易见的模式。只关注不明显的选择、边缘情况和架构权衡。

也可以在请求中直接指定水平：

• “面向初学者讲解”、“我刚开始学” → junior
• “我了解基础知识”、“中级水平” → mid
• “高级模式”、“跳过基础内容”、“只讲权衡” → senior

---

工作流

步骤 0：应用用户配置

开始分析前，先阅读上述配置：

• 加载 known_concepts 跳过列表。列表中的概念只用一句话说明，不做完整讲解。
• 确定技能水平：先检查用户请求（内联短语优先），再回退到 default_level。在整个输出中始终应用此水平。
• 如果水平为 senior，则改用 agents/auditor.md，不要继续此工作流。

步骤 1：确定要分析的代码

使用第一个适用的模式：

1. 明确指定 — 用户在请求中指定了具体文件、目录或模块 → 直接使用这些目标。无需使用 git。例如：“解释 src/auth/”或“带我了解 api/routes.py”。

2. 近期变更 — 未明确指定目标，项目是 git 仓库，且 git diff HEAD 有输出 → 使用这些已更改的文件（这是 AI 任务完成后的当前学习行为）。

3. 扫描 — 未明确指定目标，且没有可用的 git diff（旧项目、近期没有变更或不是 git 仓库）→ 询问用户：“你想分析哪个文件、目录或模块？”不要猜测。

代码不必由 AI 生成。AntiVibe 可以分析任何代码。

步骤 2：分析代码结构

对于每个文件：

• 确定主要用途和职责
• 记录关键函数、类和模块
• 确定使用的设计模式（工厂、单例、观察者等）
• 找出复杂逻辑或算法

步骤 3：解释概念

对于发现的每个概念／模式：

• 是什么：用通俗语言解释
• 为什么：说明为何选择这种方法，而不是其他方案
• 何时使用：结合上下文说明何时使用此模式
• 替代方案：其他方法及其权衡
• 前置知识：开发者必须先理解的 2–4 个基础概念（例如：“要理解 JWT，你需要了解：HTTP 请求／响应、Base64 编码、加密签名”）

步骤 4：查找外部资源

**仅在 full 模式下执行此步骤。**在 compact 模式下完全跳过。

搜索并提供：

• 所用库／框架的官方文档
• 优质教程或博客文章
• 视频资源（如有）
• 可供进一步学习的相关概念

步骤 5：生成输出

在 deep-dive/ 文件夹中创建 Markdown 文件：

• 文件名格式：[component]-[timestamp].md
• 根据请求或 output_mode 配置确定输出模式（默认为 compact）
• 简洁模式：使用简洁模板。不提供逐行分析、资源或后续步骤。最多分析 5 个文件 — 如果范围内文件超过 5 个，则每个额外文件用一行概述，并提出可进一步深入分析。
• 完整模式：使用 templates/deep-dive.md 中的完整模板。包含所有章节。不限制文件数量 — 分析范围内的所有文件；对于非常庞大的输入，应将输出拆分到多个 deep-dive 文件中，而不是截断内容。
• 注重教学，而不只是描述

自动触发配置

AntiVibe 可通过钩子配置为自动触发：

• SubagentStop：某项任务完成一个功能后
• Stop：会话结束时

如需启用自动触发，请在项目中配置钩子（参见 hooks/hooks.json）。

原则

1. 重原因，轻描述 — 始终解释设计决策
2. 结合上下文 — 解释何时／为何使用各种模式
3. 精心筛选资源 — 提供优质链接，而非随意的 Google 搜索结果
4. 关注阶段 — 按实现阶段分组
5. 学习路径 — 建议后续深入学习的步骤
6. 概念映射 — 将代码与底层计算机科学概念联系起来

依赖项

scripts/ 文件夹中的可选脚本：

• capture-phase.sh - 检测实现阶段边界
• analyze-code.sh - 解析代码结构
• find-resources.sh - 搜索外部资源
• generate-deep-dive.sh - 创建 Markdown 输出

这些脚本仅供辅助 — 你也可以直接分析代码来完成所有工作。

示例

输入：“解释 Claude 编写的身份验证系统” (近期 AI 代码) → 模式：近期变更（git diff）。输出：deep-dive/auth-system-2026-01-15.md

输入：“带我了解 src/payments/” (明确指定目标 — 旧代码库) → 模式：明确指定。直接分析该目录中的文件，无需使用 git。

输入：“深入分析” (未指定目标，且旧项目近期没有变更) → 模式：扫描。询问：“你想分析哪个文件或模块？”

输入：“审查这个，只看权衡” (资深模式) → 转到 agents/auditor.md。生成架构审计，而非解释。