代码库探索（codebase-explorer）

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

---

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

层级	文档	需要理解的概念
D0 认知根（必读）	_内部总控/认知结构/L1_系统性文档/技术架构思维维度/技术架构方案.md	整体技术体系框架：各项目的技术选型/架构模式/层次划分（接手代码库时的全局视角）
D3 规范参考	_内部总控/开发规范/公共模块注册表.md	已有公共模块清单（探索时识别代码库对公共模块的使用情况）
D4 运行时数据	目标项目 技术架构.md（若存在）+ 项目代码根目录	已有架构文档（对比预期 vs 实际）+ 实际代码目录结构

核心概念速查： ① 探索顺序：有文档→先读文档了解预期，再看代码了解实际；无文档→先扫描再输出 ② 差距 = 代码与文档不一致的地方（是 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）

---

输出格式

# [项目名] 架构理解文档

**探索日期**：YYYY-MM-DD
**探索目的**：[快速理解/深度分析/接手开发]

## 一句话定位
[这个系统是什么，解决什么问题]

## 技术栈
| 层次 | 技术 | 版本/说明 |
|---|---|---|
| 前端 | | |
| 后端 | | |
| 数据层 | | |
| AI层 | | |
| 基础设施 | | |

## 分层架构
[文本形式的架构图]

## 核心模块
| 模块 | 路径 | 职责 | 真源？ |
|---|---|---|---|

## 已发现风险
- 🔴 Critical: [...]
- 🟡 High: [...]

## 浅层模块分析（Step 5.5）
| 模块 | 类型 | 问题描述 | 改进建议 |
|---|---|---|---|

## 可测试性扫描（Step 5.6）
| 文件/函数 | 问题类型 | 具体描述 | 改进优先级 |
|---|---|---|---|

## 与产品定义的差距（若适用）
| 功能 | 产品要求 | 实际状态 |
|---|---|---|

---

注意事项

• 先地图，后改造：不允许在完成 Step 7 之前提出重构建议
• 最小读取原则：不需要读完所有文件，聚焦能建立全局图景的最少文件集
• 真源声明：必须明确指出哪个文件/服务是某类数据的唯一权威来源

---

变更记录

v1.1 — 2026-03-20 — 集成 improve-my-codebase：新增浅层模块识别与可测试性扫描

根因：五条工程原则对照分析（TASK-20260320-01）证明：codebase-explorer 虽有通用风险识别，但缺少两个专项分析维度——「浅层模块」（John Ousterhout《A Philosophy of Software Design》概念）和「可测试性」（阻碍单元测试的四类代码模式）。

修改内容：

• 新增：Step 5.5「浅层模块识别」——判断接口臃肿但实现轻薄的模块，输出合并/重构建议表格
• 新增：Step 5.6「可测试性扫描」——识别隐式依赖/无接口抽象/全局副作用/超长函数四类阻碍测试的模式，输出改进优先级表格
• 修改：输出格式 → 新增「浅层模块分析」和「可测试性扫描」两节

验证结果：

• 正向验证：触发 codebase-explorer 扫描任意代码库 → 输出文档应包含浅层模块分析表格和可测试性表格（待验证）
• 负向验证：技术栈识别、核心模块、真源声明等原有分析步骤不变
• 冲突验证：Step 5.5/5.6 在 Step 5（通用风险）之后、Step 6（与产品对比）之前，不影响原有顺序

验证状态：🔵 待验证

---

v1.0 — 2026-03-19 — 初始创建

根因：历史对话分析发现「接手代码库、理解并推进」是最高频但无正式 Skill 覆盖的任务类型（~20次），是 PENDING-SKILLS P0 缺口。基于 closure-orchestration-package 的 repo-system-cartographer 本地化，加入与产品定义对比步骤。

验证状态：🔵 待验证（下次接手代码库时验证）