whaojie797-design/codebase-brief

codebase-brief

运行一条命令，获得下一位工程师真正需要的代码库地图。
一条命令，生成新成员 10 分钟就能读懂的代码库入门包。

License: MIT
Python
Tests
Topics

codebase-brief 将一个陌生的代码库转化为结构化的工程入门包 —— 包含来源、未知项以及 Mermaid 架构图。它是确定性的静态分析：没有 LLM、没有网络、没有上传、没有猜测。

v0.1.0 支持：Python、TypeScript/JavaScript、Docker Compose。任何其他语言都会报告为 UNKNOWN —— 绝不会伪装成受支持。

Demo / 演示

python scripts/scan_repo.py tests/fixtures/ts-monorepo 的真实输出，
以终端录制形式呈现：

demo

（如果你愿意，可以把 docs/demo.gif 换成更长的屏幕录制；上面的
画面来自一次真实的扫描。）

它会产出什么

| 文件 | 用途 |
|------|---------|
| CODEBASE_BRIEF.md | 它是什么、如何运行、核心模块、关键依赖、风险 |
| ARCHITECTURE_MAP.md | Mermaid 模块图；每条边都标记为 EXTRACTED/INFERRED 并附来源 |
| ONBOARDING.md | 本地启动、测试、最小首次修改路径 |
| OPEN_QUESTIONS.md | 仅包含静态分析无法确认的内容 |
| codebase-inventory.json | 供工具/CI 使用的机器可读清单 |

每一条已确认的论断都会引用文件路径。推断内容标记为 INFERRED。
未知项归入 OPEN_QUESTIONS.md。绝不捏造。

Install / 安装

每个 skill 都单独安装 —— 你不需要整个包。

Claude Code
git clone https://github.com/whaojie797-design/codebase-brief ~/.claude/skills/codebase-brief

Cursor
git clone https://github.com/whaojie797-design/codebase-brief ~/.cursor/skills/codebase-brief

Codex / OpenAI Codex
git clone https://github.com/whaojie797-design/codebase-brief ~/.codex/skills/codebase-brief

在任意仓库上运行它
cd your-repo
python ~/.claude/skills/codebase-brief/scripts/scan_repo.py .

需要 Python 3.10+。无第三方依赖包。

快速开始

git clone https://github.com/whaojie797-design/codebase-brief
cd codebase-brief
python scripts/scan_repo.py tests/fixtures/flask-blog
writes CODEBASE_BRIEF.md, ARCHITECTURE_MAP.md, ONBOARDING.md,
OPEN_QUESTIONS.md, codebase-inventory.json into the target repo

使用 --out  将输出重定向到另一个文件夹。

真实示例输出（flask-blog fixture）

python scripts/scan_repo.py tests/fixtures/flask-blog 会生成：

1. 这个仓库看起来是什么
- 识别到的语言： python (3)
- 包清单： requirements.txt (python)
- 检测到的入口点： app.py (python)

2. 如何运行（推断）
- 推断出的主要入口点：app.py
- pip install -r requirements.txt（或 poetry install）

3. 核心模块
- app (python)
- posts (python)

4. 关键依赖（外部）
- flask

5. 风险与未知项
- 未识别到任何风险

以及架构图（Mermaid，附证据）：

flowchart LR
app["app"] -->|INFERRED| flask["flask"]
app["app"] -->|EXTRACTED| posts["posts"]
posts["posts"] -->|INFERRED| flask["flask"]

- app -> posts: app.py:2  from posts import get_posts

Before / After / 前后对比

Before —— 一位开发者加入仓库并摸索了一个小时：
“我觉得这是个 Flask 应用？不太确定这些模块是做什么的，也不知道该从
哪里开始。某个地方有个 tests/ 文件夹。”

After —— codebase-brief 只需 5 秒：
一份带日期的简报，列出了入口点（app.py）、核心模块（app、
posts）、外部依赖（flask，标记为 INFERRED）、运行
命令，并明确说明该产品的用途无法从代码中推导出来
（见 OPEN_QUESTIONS.md）。新工程师阅读 10 分钟后就能
做出真正的改动。

Tests / 测试

14 个 pytest 用例覆盖了入口点检测（Python/TS/JS）、依赖提取
（本地 EXTRACTED 与外部 INFERRED）、Docker Compose 服务、未识别的
语言、证据路径、Mermaid 语法、清单 schema、缺失测试的风险、
配置检测、多语言仓库以及确定性。

python -m pytest -c pytest.ini -q
14 passed

GitHub Actions 在每次推送和拉取请求时运行同一套测试。

Privacy / 隐私

- 完全在本地运行。没有 API 密钥，没有网络调用，没有遥测。
- 绝不上传你的代码。它只读取你指定的文件。
- 确定性：相同的仓库输入，相同的简报输出。

License

MIT —— Copyright (c) 2026 whaojie797-design。