codebase-brief

Run one command, get the codebase map your next engineer actually needs. 一条命令，生成新成员 10 分钟就能读懂的代码库入门包。

codebase-brief turns a stranger repository into a structured engineering onboarding pack — with sources, unknowns, and a Mermaid architecture map. It is deterministic static analysis: no LLM, no network, no uploads, no guessing.

Supported in v0.1.0: Python, TypeScript/JavaScript, Docker Compose. Any other language is reported as UNKNOWN — never faked as supported.

---

Demo / 演示

Real output of python scripts/scan_repo.py tests/fixtures/ts-monorepo, rendered as a terminal recording:

(Swap docs/demo.gif for a longer screen recording if you prefer; the frames above are rendered from a real scan.)

---

What it produces

File	Purpose
CODEBASE_BRIEF.md	What it is, how to run, core modules, key deps, risks
ARCHITECTURE_MAP.md	Mermaid module graph; every edge tagged EXTRACTED/INFERRED with source
ONBOARDING.md	Local start, tests, minimal first-change path
OPEN_QUESTIONS.md	Only what static analysis CANNOT confirm
codebase-inventory.json	Machine-readable inventory for tooling/CI

Every confirmed claim cites a file path. Inferences are labeled INFERRED. Unknowns go to OPEN_QUESTIONS.md. No fabrication, ever.

---

Install / 安装

Each skill installs separately — you do not need the whole bundle.

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

Run it on any repo

cd your-repo
python ~/.claude/skills/codebase-brief/scripts/scan_repo.py .

Requires Python 3.10+. No third-party packages.

---

Quick start

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

Use --out <dir> to redirect output to another folder.

---

Real sample output (flask-blog fixture)

python scripts/scan_repo.py tests/fixtures/flask-blog produces:

## 1. What this repository appears to be
- **Recognized languages:** python (3)
- **Package manifests:**  `requirements.txt` (python)
- **Detected entrypoints:**  `app.py` (python)

## 2. How to run (inferred)
- Primary entrypoint inferred: `app.py`
- `pip install -r requirements.txt` (or `poetry install`)

## 3. Core modules
- `app` (python)
- `posts` (python)

## 4. Key dependencies (external)
- `flask`

## 5. Risks & unknown items
- none identified

And the architecture map (Mermaid, with evidence):

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 — a developer joins the repo and pokes around for an hour:

"I think it's a Flask app? Not really sure what the modules do or where to start. There's a tests/ folder somewhere."

After — codebase-brief in 5 seconds:

A dated brief naming the entrypoint (app.py), the core modules (app, posts), the external dependency (flask, marked INFERRED), the run command, and an explicit note that the product's purpose is not derivable from code (in OPEN_QUESTIONS.md). The new engineer reads for 10 minutes and makes a real change.

---

Tests / 测试

14 pytest cases cover entrypoint detection (Python/TS/JS), dependency extraction (local EXTRACTED vs external INFERRED), Docker Compose services, unrecognized languages, evidence paths, Mermaid syntax, inventory schema, missing-tests risk, config detection, polyglot repos, and determinism.

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

GitHub Actions runs the same suite on every push and pull request.

---

Privacy / 隐私

• Runs fully locally. No API keys, no network calls, no telemetry.
• Never uploads your code. It only reads files you point it at.
• Deterministic: same repo in, same brief out.

---

License

MIT — Copyright (c) 2026 whaojie797-design.