TashanGKD 代码库探索（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 本地化，加入与产品定义对比步骤。
验证状态：🔵 待验证（下次接手代码库时验证）