claude-professor

claude-professor

A Claude Code plugin that turns vibe coding into a personalized learning experience.

claude-professor is a learning layer for AI-assisted development. It ensures you understand the concepts behind any code before it gets written — maintaining your skills and preventing knowledge atrophy while using AI coding tools.

The Problem

Vibe coding — accepting AI-generated code without deeply understanding it — erodes your ability to reason about systems independently. You trade short-term velocity for long-term skill atrophy. The paradox: the better you are at coding, the more effectively you can use AI tools. But over time, vibe coding erodes the very skills that make it effective.

claude-professor solves this by embedding a teaching layer directly into your development workflow. Before you build, the professor makes sure you understand why, not just what.

What It Does

/whiteboard — Design With Teaching

The primary entry point. Conducts a domain-agnostic design conversation for any feature or system, teaching concepts as they arise:

1. Phase 0 — Init / Resume — whiteboard.js init-session (new) or resume-session (continue). v5 session schema.
2. Phase 1 — Requirements (Concerns) — picks 5-8 concerns from data/concerns.json (19 research-backed concerns), iterates them one-by-one via next-concern; the matcher resolves concepts per concern and the professor teaches them inline before each concern is discussed.
3. Phase 2 — High-Level Design (HLD) — registers components, iterates them via next-component; teaches the L1 concepts central to each component decision before discussion.
4. Phase 3 — Low-Level Design (LLD) — optional; creates L2 implementation concepts dynamically under registry L1 parents.
5. Phase 4 — Deliverable — export-design-doc writes the design to docs/professor/designs/, finish closes the session.

The JIT iterator in scripts/whiteboard.js structurally enforces the "teach before discuss" contract: next-concern / next-component return the unit and the concepts that must be taught before discussion. gate.js checkpoint runs post-hoc as an audit (2-outcome: passed / blocked).

Supports init-session --force-new to discard v4 sessions that cannot be auto-migrated.

/analyze-architecture — Map Your Codebase

Scans your codebase and produces a high-level architecture graph:

docs/professor/architecture/
├── _index.md                    # Component index + overview
├── components/
│   ├── auth-service.md          # Wiki-linked component files
│   └── ...
├── data-flow.md                 # Mermaid diagrams
├── tech-stack.md                # Dependencies, versions
└── concept-scope.json           # Detected domains + tech stack

Supports --update (refresh) and --branch {name} (delta from base).

/professor-teach — Single Concept Teaching

Teaches a single concept inline in the whiteboard conversation (the user sees the teaching directly — it is never dispatched as a background subagent). Structured output contract:

1. Analogy (~100 words) — concrete, visual everyday comparison; always synthetic
2. Real-world production example (~150 words) — grounded in a web search anchor snippet if available, otherwise from training data
3. Task connection (~100 words) — tied to what you're building; references same anchor snippet for coherence
4. Recall question — application, not definition; grounded in same anchor scenario

Action (taught / reviewed / skipped) is determined by FSRS status from lookup.js concept-state. Writes notes into the concept's ## Teaching Guide section.

Web search integration (v5.1): The whiteboard skill prefetches one search result per concern at phase-start and passes it to professor-teach via --search-results. Professor-teach selects a single anchor snippet (concept-match then task-context domain as tiebreaker) and threads it through the real-world example, task connection, and recall question blocks. On degradation (empty, malformed, or timed-out results), an inline signal appears at the top of teaching output with the specific failure reason and search query — teaching always continues from training data.

What It Is NOT

• Not a pair programmer — It doesn't write code or guide you through implementation
• Not a code generator — It never writes code. Ever.
• Not a code reviewer — It doesn't review existing code quality
• Not a planner — It produces designs for your planning tool of choice

Installation

From GitHub (Recommended)

# Add the marketplace (one-time)
/plugin marketplace add theadityamittal/claude-professor

# Install the plugin
/plugin install claude-professor

# Reload
/reload-plugins

Requirements

• Claude Code CLI
• Node.js (already required by Claude Code — no additional dependencies)

Known Limitation: Opus 4.7 (1M context) sessions