codebase-insight

Code Inventory

Read-only analysis of an existing codebase, outputting a structured inventory of the system's current state. No requirements derivation, no design judgment, no ID assignment.

Perspective: code archaeologist — faithfully record discovered facts, without explanation or recommendation.

Quick Start

One-liner: read-only analysis of the codebase, outputting system boundaries, core modules, and technical constraints.

Most common usage: /codebase-insight

Not suitable? Requirements definition→/requirements, project baseline→/retrofit, project handover→/onboard

Boundaries with other skills

skill	Responsibility	What codebase-insight does not do
retrofit	Establish project baseline (`00-baseline.md`: purpose boundaries / external hard constraints / guardrails / known unknowns)	Ask people, judge intent, assign safe default actions for uncertainty
onboard	Project context + progress + to-dos	Progress tracking, to-do aggregation
code-self-describe	Module-level CLAUDE.md + dependency graph	File-level descriptions, dependency graph generation
verify `--schema-drift`	Scan A/B class keel artifacts' `spec_version` metadata	This skill's `schema_version + commit_hash` independent mechanismis read by `--schema-drift` and presented in a separate section of the main report(not merged into A/B class main statistics, not included in realign orchestration; after invalidation, handled by this skill's own `--force` handling, see ../pipeline/references/realign.md § Relationship with codebase-insight)

Operating modes

/codebase-insight            → 智能检测（缓存命中则跳过）
/codebase-insight --force    → 强制全量重新扫描

Caching mechanism

Avoid repeated scans via commit hash; rescan when any of the three invalidation conditions is triggered:

Step 0: 缓存检查
    |
    +-- --force？→ 直接全量扫描
    |
    +-- docs/codebase-insight.md 不存在？→ 全量扫描
    |
    +-- 读取 frontmatter：
        ├── schema_version 不匹配 → 全量重新扫描
        ├── commit_hash != git rev-parse HEAD → 全量重新扫描
        └── 全部匹配 → 缓存命中（status: success, cache_hit: true）

Cache design principles: only check committed changes (commit hash) and schema version. Uncommitted changes are temporary state; when needed, use --force to force a rescan.

Workflow

Full scan

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

Output specification

File path:docs/codebase-insight.md

frontmatter (required fields)

---
generated_at: 2026-03-26T10:00:00+08:00
commit_hash: "a1b2c3d"
scan_scope: "src/"                 # 扫描根目录
tech_stack: "Node.js + Express + PostgreSQL"
schema_version: "1.0"
---

Section structure (titles and order fixed; consumers locate and parse by title)

# 代码盘点

## 系统边界
- 入口点：...
- 外部依赖/集成：...

## 核心模块
| 模块 | 路径 | 职责摘要 |
|------|------|---------|

## 公开接口
| 方法 | 路径/签名 | 所属模块 |
|------|----------|---------|

## 关键数据对象
| 对象 | 关键字段 | 关联 |
|------|---------|------|

## 技术栈与约束
- 语言/框架：...
- 数据库：...
- 已知约束/限制：...

## 未确定项
- [ ] 项目描述（每项为 checkbox 格式）

schema constraints

Section titles and order are fixed; cannot be added, removed, or reordered
frontmatter must contain generated_at、commit_hash、scan_scope、schema_version
Use - [ ] checkbox format for undetermined items
Table column count is fixed; may be empty but columns cannot be omitted

Multiple code roots

The inventory scope is workspace_context.code_roots each path (inline when it is a single item,path = absolute path of the repository root,this skill does not branch by topology). Code roots come from handshake workspace_context（shared/constraints.md §3 task/workspace-context; when not passed in, use inline default).When there is more than one code root：

Inventory each code root one by one, and the resulting modules / interfaces / data objects are all prefixed with <label>/ to avoid cross-repository name collisions
An additional "Inter-repository relationships" subsection must be produced: dependency direction (who calls whom), interface contract surface (cross-repository APIs / messages / shared data structures), version coupling points (places where changing one side requires changing the other side as well). The value of the multi-code-root scenario lies mainly here—in the single-repository case, this section does not exist
Artifacts are always written to <workspace_context.docs_dir>/codebase-insight.md，Do not write files to any code root(for the criteria, see capabilities.code_dir_write_policy）

Summary contract

skill: codebase-insight
status: success | partial | failed
summary:
  headline: "5 个模块、23 个接口、8 个数据对象"
  details:
    cache_hit: true | false
    prev_commit: "a1b2c3d"
    curr_commit: "e4f5g6h"
    schema_version: "1.0"
    module_count: 5
    interface_count: 23
    data_object_count: 8
    tech_stack: "Node.js + Express + PostgreSQL"
blockers: []
output_files:
  - docs/codebase-insight.md
new_ids: {}
next_recommended:           # 不硬编码，由调用方决定下一步
  skill: ""
  args: ""

On cache hit:

skill: codebase-insight
status: success
summary:
  headline: "缓存命中，代码无变更"
  details:
    cache_hit: true
    prev_commit: "a1b2c3d"
    curr_commit: "a1b2c3d"
    schema_version: "1.0"
blockers: []
output_files: []            # 缓存命中时未创建/修改任何文件
new_ids: {}
next_recommended:
  skill: ""
  args: ""

Language rules

Support questions in Chinese and English
Reply uniformly in Chinese
Generate documentation in Chinese