AI 智能体驱动：陌生代码库极速拆解与全自动二开通用指南（v4 终极多模态版）¶

本指南从 Claude Code 专属演进为通用 AI 智能体（Agent）工程化体系。旨在帮助开发者融合当前主流终端 Agent（如 Claude Code, OpenAI Codex CLI, OpenCode, Aider 等）的各自优势，通过“多 Agent 协同”与“开发者元技能（Meta-Skills）”，以最低的 Token 成本、最高的架构准确度，达成对任意开源项目的“极速吃透”与“安全二开”。

🛠️ 第一部分：多智能体（Multi-Agent）工具链矩阵选型¶

在实际工程中，没有一个 Agent 是万能的。根据任务特征切换工具，能让你事半功倍：

智能体工具	核心优势	最佳应用场景	成本/模型限制
Claude Code	极强的自主规划、全自动“修改-测试-修复”闭环、深度的逻辑推理。	复杂的跨模块全量重构、自动化 Bug 修复、首轮高层级架构推导。	较高。仅限 Anthropic 专属模型（如 Opus/Sonnet 系列）。
OpenAI Codex CLI	基准测试评分高，支持并行的多 Agent 协同与 `AGENTS.md` 规范。	大规模并行任务、团队级别的自动化 CI 流程。	绑定 OpenAI 体系（GPT 系列）。
Aider / OpenCode	模型无关（Provider-Agnostic）。内置 Token 极省的代码库地图（Repository Map），Git 原生紧密提交。	局部的精准修改、日常的低成本交互、使用本地或便宜模型（如 DeepSeek、Gemini）刷重复代码。	极低。自备 API Key，支持几乎所有云端与本地（Ollama）模型。
Cursor / Zed IDE	最优秀的可视化代码差异（Diff）审查与流畅的 IDE 原生交互。	人工介入审查 AI 代码、边看边改的结对编程阶段。	订阅制或使用自备 Key。

💡 终极工作流建议：用 Claude Code / Codex CLI 进行首轮的【架构解构与复杂功能链路追踪】（发挥高阶长上下文推理优势）；用 Aider / OpenCode 挂载低成本模型（如 Gemini 3.1 Pro 或 DeepSeek V4 Pro）进行日常的【二开编码与局部重构】（省 Token 且 Git 提交极其精准）。

🧠 第二部分：开发者核心“元技能”（Meta-Skills）拓展¶

要想真正榨干 AI 智能体的潜力，开发者需要有意识地训练以下四项核心协同技能：

技能一：上下文工程与 Token 裁剪（Context Pruning）¶

核心逻辑：AI 读的文件越多，不仅越贵，而且越容易产生“幻觉”和细节丢失。
操作技巧：
- 在项目根目录建立 .aiderignore 或 .claudeignore，把 node_modules/、dist/、大数据集、前端静态资源、大型图片或二进制打包产物彻底屏蔽。
- Repo Map 显式引导：如果使用支持 Repo Map 的工具（如 Aider），先让 AI 基于简化的代码树和 LSP（语言服务器）定义进行分析，而不是一开始就把所有源文件塞进上下文。

技能二：多模型阶梯调用（Multi-Model Tiering）¶

核心逻辑：将复杂的“脑力活”与简单的“体力活”解耦。
操作技巧：
- 架构理解/骨干编写（脑力活）：指定顶尖模型（如 Claude 3.5 Sonnet / Opus 4.8 / GPT-5.5）。
- 单元测试编写/文档格式化/国际化翻译（体力活）：切换到极低成本甚至免费的模型（如 OpenAI o4-mini、DeepSeek V4 Pro、Gemini 3.1 Pro），Token 消耗降低 70% 以上。

技能三：逆向追溯与探针工程（Trace-Driven Exploration）¶

核心逻辑：静态阅读代码无法完全看懂运行时的动态行为（如中间件拦截、异步解耦、反射机制）。
操作技巧：
- 日志/ Trace 反哺：自己在本地运行一次业务，把控制台打印的日志、网关 Trace ID 的调用链，或者报错的 Stack Trace 整体复制，在终端里直接“喂”给 Agent，说：“这是运行时的一段真实数据/错误轨迹，请帮我反向定位到源码，并解释这段代码在运行时的动态权重。”

技能四：双智能体影子审查（Dual-Agent Shadow Review）¶

核心逻辑：当局者迷。负责写代码的 Agent 往往容易陷入自己的逻辑死洞。
操作技巧：
- 让 Agent A（如 Claude Code）完成二次开发并跑通测试后，不要急于合并。
- 在 IDE（如 Cursor）中拉起另一个模型（如 GPT 或 Gemini），输入：“这是另一个 AI 刚刚针对本项目编写的代码修改 Diff，请你充当极其严苛的资深代码评审员（Code Reviewer），从性能、安全漏洞（如注入、内存泄漏）、可读性、设计模式契合度四个维度，挑出 3 个最致命的潜在缺陷。”

🛠️ 第三部分：工具无关的通用 Agent 实战指令模板¶

无论你最终选择哪款终端 Agent，这套精炼过的“通用指令”都能完美兼容（它将自动识别项目的特定配置文件，并融合了可视化要求与测试闭环）。

第一步：宏观拓扑扫描（防 Token 爆仓版）¶

Text Only
请扫描当前项目的核心配置文件与目录。如果这是一个大型项目（Monorepo），请先列出子模块清单，并聚焦于其核心业务目录（自发忽略构建产物、静态资源等非代码目录）。
请告诉我：
1. 该项目采用的主技术栈、核心依赖及入口文件。
2. 核心文件夹的职责划分。

第二步：垂直双轨链路追踪（正向业务 + 逆向安全/报错 + Mermaid 可视化）¶

Text Only
我想深入吃透本项目的某一核心功能（例如：【文档上传与向量化检索流程 / 订单创建与支付生命周期】）。请帮我同时追踪两条路径：
1. 【正向快乐路径】：从外层控制器/路由开始，向内经过中间件、服务层、领域模型，最终到达数据存储层的完整调用调用栈，列出关键文件及核心函数。
2. 【逆向与异常路径】：此流程中，身份认证（Auth）在何处拦截？全局异常/报错（Error Handling）由谁捕获？返回的错误协议格式是什么？

【输出要求】：请在回答的末尾，用 Markdown 的 `mermaid` 代码块分别生成一张【正向业务时序图】和一张【异常拦截流程图】。

第三步：水平扩展点与基础设施复用评估¶

Text Only
我计划基于当前代码进行二次开发（如扩展新驱动、外接新服务或重构部分逻辑）。请评估代码的可扩展性：
1. 如果进行上述修改，最符合项目解耦规范的【插桩位/目录】在哪里？
2. 项目中定义了哪些标准的接口（Interface）、基类（Base Class）或设计模式（如策略、工厂模式）是供开发者继承扩展的？
3. 有哪些现成的全局基础设施（如全局 Logger、配置管理器 Config、缓存/数据库连接池）是我可以直接复用或依赖注入的？

第四步：Agent 自动化改写与测试验证闭环¶

Text Only
现在，请充分调动你的本地工具（文件编辑、Shell 执行等），帮我完成一次代码修改与验证的闭环：
1. 帮我找出并运行针对上述核心业务模块的本地单元测试命令，并向我汇报当前的测试通过率。
2. 在不破坏现有业务的前提下，尝试在对应模块中新增一个轻量级的测试特性（或功能 Mock 桩）。在得到我确认后，请直接修改本地代码。
3. 修改后，在终端自动重新运行测试。若发生报错，请自动读取 Trace 日志并进行代码修复，直到测试完全通过。请向我展示你整个“修改-测试-报错-自动修复”的思考过程。

第五步：技术资产固化（构建本地 AI 导航大脑）¶

Text Only
请结合刚才我们推导出的全部架构结论、Mermaid 图表源码以及通过的测试命令，使用你的文件写入工具，在项目根目录下生成/更新以下两个顶级文档：
1. 创建 `ARCHITECTURE.md`：记录系统的整体架构、正逆向数据流图（嵌入 Mermaid 源码）以及二开规范。
2. 创建或完善 `CLAUDE.md`（或 `AGENTS.md`）：记录项目简介、技术栈版本、经过刚才你实际在终端验证通过且真实可用的【构建/格式化/单元测试命令】，以及严苛的代码风格约束。