codebase-explorer

代码库探索（codebase-explorer）

在提出任何架构改建议之前，必须先有可信赖的全局图景。 基于 closure-orchestration-package 的 repo-system-cartographer 模式本地化。

知识导航表（执行前必须理解的概念根）

核心概念速查： ① 探索顺序：有文档→先读文档了解预期，再看代码了解实际；无文档→先扫描再输出 ② 差距 = 代码与文档不一致的地方（是 issue-tracker 的候选输入） ③ 输出架构理解文档 = K-object.create（K4项目规格）：写入 _内部总控/开发规范/架构理解/

激活后立即执行

Step 1  确认探索目标
        询问（如未说明）：
        「要探索的代码库路径是什么？探索目的是：
          ① 快速理解（输出架构概览）
          ② 深度分析（含差距分析和建议）
          ③ 接手开发（含与产品定义的对比）」

Step 2  用内置 explore 子智能体并行扫描（不占主对话 context）
        - 扫描顶层目录结构（文件树）
        - 读取 README.md / 开发规范.md / 产品定义.md（若存在）
        - 识别主要配置文件（package.json / requirements.txt / docker-compose.yml 等）

Step 3  识别技术栈与架构层次
        从扫描结果提取：
        - 前端技术（框架/构建工具/状态管理）
        - 后端技术（语言/框架/API 风格）
        - 数据层（数据库/ORM/迁移工具）
        - AI/ML 层（若有，LLM/向量库/调用方式）
        - 基础设施（部署/CI/CD/容器）

Step 4  读取核心文件（最多 5-8 个，聚焦最关键的）
        优先级：主入口文件 > 核心业务逻辑 > 数据模型 > API 定义

Step 5  提取架构模式与源真相
        识别：
        - 哪些文件是「真源」（source of truth）
        - 模块边界在哪里
        - 前后端如何通信
        - 数据流向是什么
        - 有哪些明显的技术债或架构风险

Step 5.5【浅层模块识别（improve-my-codebase）】
        对已识别的核心模块，评估「深度」：
        
        浅层模块（shallow module）特征——接口复杂但实现简单，认知成本高于价值贡献：
        □ 接口臃肿：调用方需要了解≥5个参数才能调用，或需要了解实现细节才能正确传参
        □ 实现轻薄：函数体≤10行，只做简单的格式转换/转发，没有真正的业务逻辑
        □ 多层传递：参数从A穿透B传到C，B不使用该参数（B是「中间人」）
        
        改进方向：将多个浅层模块的功能内聚到一个接口更简单的深层模块
        → 接口应该隐藏复杂度，而非暴露复杂度
        
        输出格式：
        | 模块 | 类型 | 问题描述 | 改进建议 |
        |---|---|---|---|
        | [模块名] | 浅层/深层 | [具体问题] | [合并/重构方向] |

Step 5.6【可测试性扫描（improve-my-codebase）】
        识别以下阻碍测试的代码模式：
        
        □ 隐式依赖：函数内部直接实例化依赖（new DatabaseClient()、硬编码 URL）
          → 改为：依赖注入（参数传入 / 配置注入）
        □ 无接口抽象：业务逻辑直接调用外部服务（DB、AI API、文件系统、时间函数）
          → 改为：引入接口/协议层（定义抽象，测试时可替换为 mock）
        □ 全局副作用：函数修改全局状态 / 写文件 / 发网络请求而不在签名中声明
          → 改为：纯函数提取（将副作用边界化，核心逻辑变纯函数）
        □ 超长函数：单个函数超过50行，难以独立测试各逻辑分支
          → 改为：提取子函数，每个子函数单独可测
        
        输出格式：
        | 文件/函数 | 问题类型 | 具体描述 | 改进优先级 |
        |---|---|---|---|
        | [路径] | 隐式依赖/无抽象/全局副作用/超长 | [描述] | P0/P1/P2 |

Step 6  与产品定义/需求对比（若存在）
        Read: 产品经理/产品定义.md（若存在）
        输出：
        - 已实现的功能
        - 架构就绪但未完全实现的功能
        - 产品要求但代码中完全缺失的功能
        - 与需求存在偏差的实现

Step 7  输出架构理解文档
        写入：技术架构师/[项目名]_架构理解_YYYYMMDD.md
        结构：
        - 一句话定位（这个系统是什么）
        - 技术栈全景
        - 分层架构图（文本形式）
        - 核心模块与职责
        - 真源声明（哪个文件/模块负责哪类数据）
        - 已发现的风险和模糊点
        - 与产品定义的差距（若做了 Step 6）