用途
codebase-insight 用于对已有代码库进行只读分析，输出结构化的系统现状盘点报告，不修改代码。它的定位是「代码考古学家」——忠实记录发现的事实，不加解释或推荐。不做需求推导、不做设计判断、不分配编号。
最常见用法为输入 /codebase-insight。
它与其他技能的边界：不太适合需求定义（对应 /requirements）、项目基线建立（对应 /retrofit）、项目交接（对应 /onboard）。其中 retrofit 负责建立项目基线，而 codebase-insight 不做问人、判断意图、给不确定性定安全默认动作；onboard 负责项目上下文、进度与待办，而 codebase-insight 不做进度追踪与待办汇总；code-self-describe 负责模块级 CLAUDE.md 与依赖图，而 codebase-insight 不做文件级描述与依赖图生成。
主要能力
全量扫描流程包括以下步骤：
Step 1 项目结构扫描：检测语言/框架（package.json、go.mod、Cargo.toml、pyproject.toml 等），进行目录结构分析（识别模块边界），定位入口文件（main、app、index、routes）。
Step 2 接口提取：扫描路由注册（Express routes、FastAPI decorators、Go handlers 等），提取 HTTP 方法 + 路径 + handler 函数，按模块归类。
Step 3 数据对象提取：扫描 ORM 模型/Schema 定义，提取字段和关联关系，按业务域归类。
Step 4 约束识别：识别配置文件（env、config）、环境依赖（Docker、CI）、版本约束（引擎版本、依赖版本）。
Step 5 输出 docs/codebase-insight.md，并更新 frontmatter 中的 commit_hash、scan_scope、schema_version、generated_at。
使用方式
运行模式有两种：
/codebase-insight 为智能检测（缓存命中则跳过）。
/codebase-insight --force 为强制全量重新扫描。
缓存机制通过 commit hash 避免重复扫描。三个失效条件任一触发即重新扫描：文档不存在时全量扫描；schema_version 不匹配时全量重新扫描；commit_hash 与当前 HEAD 不一致时全量重新扫描。全部匹配则缓存命中（status: success, cache_hit: true）。缓存设计原则是只检查已提交变更（commit hash）和 schema 版本，未提交变更属于临时状态，需要时用 --force 强制重扫。
输出文件路径为 docs/codebase-insight.md，其 frontmatter 必须字段包括 generated_at、commit_hash、scan_scope、tech_stack、schema_version。章节结构固定标题和顺序，供消费方按标题定位解析，包括：# 代码盘点、## 系统边界、## 核心模块、## 公开接口、## 关键数据对象、## 技术栈与约束、## 未确定项。
schema 约束：章节标题和顺序固定，不可增删或重排；frontmatter 必须包含 generated_at、commit_hash、scan_scope、schema_version；未确定项使用 - [ ] checkbox 格式；表格列数固定，可为空但不可省略列。
多代码根场景下，盘点范围为 workspace_context.code_roots 各路径。代码根多于一项时，逐个代码根盘点，产出的模块/接口/数据对象一律带 <label>/ 前缀限定，避免跨仓重名混淆；必须额外产出「仓间关系」小节，包含依赖方向、接口契约面、版本耦合点。产物恒写 <workspace_context.docs_dir>/codebase-insight.md，不往任何代码根写文件。
摘要契约包含 skill、status（success | partial | failed）、summary（headline、details 中的 cache_hit、prev_commit、curr_commit、schema_version、module_count、interface_count、data_object_count、tech_stack）、blockers、output_files、new_ids、next_recommended。缓存命中时 output_files 为空，未创建或修改任何文件。
语言规则：支持中英文提问，统一中文回复，使用中文生成文档。
适用场景
适用于需要了解已有代码库系统边界、核心模块、公开接口、关键数据对象与技术约束的场景，尤其是为后续建立 keel 基线（retrofit）提供现状基础。
限制
该技能为只读分析，不修改代码，不做需求推导、设计判断或编号分配。缓存仅检查已提交变更和 schema 版本，未提交变更需用 --force 强制重扫。