Skip to content

CLAUDE.md

Latest commit

 

History

History
52 lines (43 loc) · 2.48 KB

CLAUDE.md

File metadata and controls

52 lines (43 loc) · 2.48 KB
Raw

Project: Codebase Explainer

This project IS a Claude Code tool — the .claude/skills/ and .claude/agents/ files here are the product, not scaffolding around it. When working on this repo, you're usually editing those files, not writing application code.

What this tool does

Given a path to some other codebase, /explain <path> produces:

  1. output/ARCHITECTURE.md — module-by-module map of the target repo
  2. output/ONBOARDING.md — a "start here" guide for a new engineer

Conventions

  • Module definition: a "module" is a top-level directory under the target repo's source root that contains multiple files, OR a directory explicitly exported/referenced from the project's manifest (package.json, pyproject.toml, go.mod, etc). Skip test directories, vendored dependencies, and build output when identifying modules.
  • Module cap: explore at most 10 modules per run. If a repo has more, pick the 10 largest/most-referenced and note the rest were skipped.
  • Subagent output format: every module-explorer subagent must return its findings as the structured markdown block defined in .claude/agents/module-explorer.md — the coordinator (/explain) relies on that exact structure to merge results.
  • Read-only: this tool never modifies the target repo. Only Read, Grep, and Glob are needed to explore it — no Write or Edit on target-repo files, ever.
  • Verifiable claims only: architecture summaries should reference real file paths and real code (e.g. "entry point: src/cli.py:main()"), not vague generalizations like "handles core logic."

Commands

  • Run the tool interactively: claude then /explain <path-to-target-repo>
  • Run the tool as a one-liner: bin/explain <path-to-target-repo>
  • Validate skill/subagent config: python scripts/validate_agents.py .
  • Run tests: pytest tests/ -v
  • All three of the above run in CI on every push — see .github/workflows/validate.yml.

Project layout notes

  • .claude/ is the actual product (skill + subagent definitions).
  • bin/, scripts/, tests/ are real Python/bash supporting this project itself (the CLI wrapper and its config validator) — not part of what /explain generates for a target repo.
  • examples/toy-repo/ is a demo fixture; examples/sample-output/ is real, hand-verified output from running this tool against it. If you change SKILL.md or module-explorer.md in a way that changes the output format, regenerate examples/sample-output/ to match.