Codebase Teaching Report

Chinese version: README.zh-CN.md

codebase-teaching-report is a Codex skill for explaining a codebase to non-programmers. It analyzes repository structure, module responsibilities, dependency and coupling relationships, design rationale, and post-change impact, then generates a static HTML report plus structured JSON.

Who This Is For

• People who do not know how to code but need to understand a project
• People who can read some code but do not understand why it was designed this way
• Teams that want change explanations in a format easier to share than source files

What The Skill Does

• Explains the current repository in plain Chinese for non-technical readers
• Breaks the system into modules and explains what each module is for
• Maps relationships such as calls, reads, writes, shared types, and impact paths
• Explains why important code is written this way and what tradeoffs were made
• Appends a change update section after implementation work
• Generates:
  • report.json as the canonical structured artifact
  • report.html as a directly viewable report

Default Output Location

Unless the user asks for another location, the skill writes directly into the analyzed project repository under a hidden folder:

.codebase-teaching-report/

Expected artifacts:

.codebase-teaching-report/report.json
.codebase-teaching-report/report.html

Recommended .gitignore entry in the target project:

.codebase-teaching-report/

This default keeps generated analysis files inside the target project while remaining easy to filter out from git.

Folder Structure

codebase-teaching-report/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── agents/
│   └── openai.yaml
├── assets/
│   ├── report-template.html
│   └── report.css
├── references/
│   ├── explanation-style.md
│   └── report-schema.md
└── scripts/
    └── render_report.py

Usage

Typical requests that should trigger this skill:

• Analyze this project architecture
• Explain why this code is written this way
• Map module coupling and dependencies
• Update the documentation after code changes
• Generate an HTML report for non-programmers

Render HTML from the canonical JSON artifact:

python3 scripts/render_report.py \
  --input .codebase-teaching-report/report.json \
  --output .codebase-teaching-report/report.html

For a repository-friendly example input, see examples/sample-report.json. To generate a sample HTML locally, follow examples/README.md.

Output Model

report.json is the source of truth for structured analysis and future visualization. It is designed so a later graph or mind-map renderer can reuse the same data model.

Current report sections include:

• Project summary
• Architecture overview
• Modules
• Relationships
• Coupling risks
• Design rationale
• Glossary
• Change updates
• Next-step suggestions

Notes

• The skill is optimized for explanation quality, not for producing interactive diagrams yet.
• V1 reserves structured JSON for a future mind-map style visualization.
• SKILL.md is the machine-facing workflow. This README is the repository-facing overview.
• The default output path is a hidden folder inside the target project repository.
• In real project use, the target project's .gitignore should usually include .codebase-teaching-report/.
• .gitignore in this skill repo only ignores local example generation artifacts and local hidden output for testing.
• A license is intentionally not added automatically because that is a legal choice for the repository owner.