A Claude Code skill that keeps a plain-language map of your codebase, written for the person who is building it through AI and cannot read the code themselves.
If you build software by directing an AI rather than writing code, you are trusting the AI on faith. When it says "fixed it" and it isn't fixed, or it quietly adds a library, or it changes how your data is stored, you have no way to check. The code is the source of truth and you can't read the source of truth.
codesplain gives you a second source of truth you can read: a single file, CODESPLAIN.md, that lives in your project and explains what each part does, why it exists, and what every consequential decision was, in plain language. It is written as you build, so it stays current, and it is short enough that you actually read it.
It does two jobs:
- Verification. When something breaks and the AI explains the cause, you can open the map, find the area it named, and judge whether the story holds together, including catching the AI contradicting what it told you last week.
- Learning. Fifty decisions in, you have absorbed what a dependency is, what "state" means, why your project has a server. Learned from your own project, which is the only version that sticks.
One file in your project root, CODESPLAIN.md, with three sections:
- Map — 5 to 10 areas you would recognize ("Turn resolution", "Saving games"), each a short paragraph: what it does, why, which files, what it talks to. Never a file-by-file dump.
- Decision Log — an append-only record. Each entry is 3 to 5 plain sentences: what was decided, why, the alternative, what could bite later.
- Glossary — every technical term, defined once.
Install by dropping this folder into your Claude Code skills directory:
~/.claude/skills/codesplain/
Then, inside any coding project:
- Start a map: run
/codesplain. On an existing project it reads the code and writes the initial map (guesses are flagged as inferred). On a brand-new project it lays down an empty skeleton, and every decision is captured from day one. - Ask a question:
/codesplain why is saving so slowanswers in plain language, grounded in the map. - Automatic capture: once
CODESPLAIN.mdexists, the skill keeps it current as you build. Two tiers:- Log and tell you — a new library, a new moving part, a deliberate workaround. Written down, with a one-line note in chat. No interruption.
- Stop and ask first — anything that costs money, locks you in, or could lose existing data. You decide before it happens, not after.
Trivial changes (typos, renames, refactors, tests) are never logged, so the record stays short enough to trust.
Add this to your global ~/.claude/CLAUDE.md so any project holding a CODESPLAIN.md turns the behavior on by itself:
## Codesplain activation
If the project root contains `CODESPLAIN.md`, invoke the `codesplain` skill and
follow its maintenance rules for the whole session.Anyone building real software through AI without a coding background. It was built for exactly that situation and tested against it.
MIT. See LICENSE.