diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 44549d03d5..439f776e1c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -145,6 +145,17 @@ }, "source": "./plugins/security-guidance", "category": "security" + }, + { + "name": "teach", + "version": "1.0.0", + "description": "Incrementally teach Claude Code about your project's conventions, patterns, and architecture. Claude actively explores the codebase and saves what it learns to CLAUDE.md.", + "author": { + "name": "LvienOeria", + "email": "120090440@link.cuhk.edu.cn" + }, + "source": "./plugins/teach", + "category": "learning" } ] } diff --git a/plugins/teach/.claude-plugin/plugin.json b/plugins/teach/.claude-plugin/plugin.json new file mode 100644 index 0000000000..ce57ef5609 --- /dev/null +++ b/plugins/teach/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "teach", + "version": "1.0.0", + "description": "Incrementally teach Claude Code about your project's conventions, patterns, and architecture — one topic at a time. Claude actively explores the codebase and saves what it learns to CLAUDE.md.", + "author": { + "name": "LvienOeria", + "email": "120090440@link.cuhk.edu.cn" + } +} diff --git a/plugins/teach/README.md b/plugins/teach/README.md new file mode 100644 index 0000000000..b429383ca4 --- /dev/null +++ b/plugins/teach/README.md @@ -0,0 +1,85 @@ +# Teach Plugin + +Incrementally teach Claude Code about your project — one topic at a time. + +## The Problem + +Claude Code has two ways to learn about your project: + +- **`/init`**: A broad, one-shot scan that creates a general CLAUDE.md. Good for initial setup, but can't capture nuance. +- **Manual editing**: You can edit CLAUDE.md and memory files directly. Powerful, but you have to do all the work yourself. + +What's missing is an **incremental, interactive way** to teach Claude about specific topics as you work. + +## The Solution: `/teach` + +`/teach ` tells Claude to actively explore your codebase, understand a specific aspect of it, and save what it learns to CLAUDE.md — with your approval. + +### How it works + +1. You pick a topic: `/teach error handling` +2. Claude searches the codebase, reads files, identifies patterns +3. Claude presents what it learned in a clear summary +4. You review and approve (or reject) the proposed CLAUDE.md update +5. Claude saves the knowledge — and uses it in every future session + +### What you can teach + +| Topic Type | Example | +|---|---| +| **Conventions** | `/teach logging patterns` | +| **Architecture** | `/teach authentication flow` | +| **Patterns** | `/teach state management` | +| **Workflows** | `/teach deployment process` | +| **Gotchas** | `/teach common pitfalls` | + +### Why this matters + +Each `/teach` session makes Claude Code smarter about your project. After a few sessions, Claude will: + +- Follow your conventions without being told +- Know which files are authoritative for each concern +- Avoid repeating mistakes you've already fixed +- Work more autonomously because it understands your patterns + +## Usage + +``` +/teach +``` + +### Examples + +``` +/teach error handling +/teach auth flow +/teach database patterns +/teach testing conventions +/teach API design +/teach component structure +/teach logging patterns +/teach state management +``` + +## Requirements + +- Claude Code installed +- A project with code to explore + +## Installation + +This plugin is available in the Claude Code plugin marketplace: + +``` +/plugin install teach +``` + +Or install from the bundled plugins directory. + +## Author + +LvienOeria + +## License + +Apache-2.0 diff --git a/plugins/teach/commands/teach.md b/plugins/teach/commands/teach.md new file mode 100644 index 0000000000..64650d2622 --- /dev/null +++ b/plugins/teach/commands/teach.md @@ -0,0 +1,186 @@ +--- +description: Teach Claude about a specific aspect of your project — conventions, patterns, architecture, or workflows. Claude actively explores the codebase, synthesizes findings, and saves them to CLAUDE.md with your approval. +argument-hint: +allowed-tools: [Read, Glob, Grep, Bash, Edit, Write] +--- + +# /teach — Incrementally Teach Claude About Your Project + +You are helping a developer teach you about their project. They want you to learn about a specific topic so you can work more effectively in future sessions. + +The topic the user wants to teach you about is: **$ARGUMENTS** + +## Core Principles + +- **Explore actively, don't just ask**: Search the codebase systematically. The user is teaching you so you should do the work of finding and reading relevant code. +- **Synthesize, don't just list**: Identify the *patterns and conventions*, not just what files exist. The user wants you to understand the "why" and the "how," not just the "where." +- **Be concise**: CLAUDE.md consumes context tokens. Every line you propose adding must earn its place. +- **Confirm before saving**: Always show your findings and ask for approval before modifying any files. + +## Process + +### Step 1: Understand the Topic + +Parse the topic from `$ARGUMENTS`. If the topic is vague or ambiguous, ask ONE clarifying question before proceeding (e.g., "Did you mean error handling in the API layer, or across the full stack?"). + +Map the topic to concrete search strategies: +- **Conventions** (error handling, logging, naming, imports) → search for recurring patterns across files +- **Architecture** (auth flow, data pipeline, routing) → trace execution paths through the codebase +- **Patterns** (state management, API design, testing) → find and compare multiple instances +- **Workflows** (build process, deployment, CI/CD) → check config files, scripts, and docs + +### Step 2: Explore the Codebase + +Use a systematic approach: + +1. **Broad search first**: Use Glob and Grep to find relevant files and patterns. Cast a wide net — look for related config files, test files, and documentation, not just source code. +2. **Read deeply**: Read the most important files identified. Don't skim — understand the actual implementation. +3. **Compare multiple instances**: If looking at a pattern (e.g., error handling), find at least 3-4 examples to distinguish conventions from one-offs. +4. **Check existing CLAUDE.md**: Read any existing CLAUDE.md files (root, local, and in relevant subdirectories) so you don't duplicate what's already documented. + +### Step 3: Synthesize Findings + +Organize what you've learned into teachable insights: + +- **The convention**: What is the standard approach? (e.g., "All API handlers wrap errors with `handleError()` from `src/lib/errors.ts`") +- **The pattern**: How is it structured? (e.g., "Error objects must include `code`, `message`, and `statusCode` fields") +- **The rationale**: Why this way? (e.g., "This matches the ErrorResponse type expected by the error middleware in `src/middleware/errorHandler.ts`") +- **Gotchas**: What would surprise someone? (e.g., "Never throw errors directly in async handlers — the wrapper won't catch them") +- **Files to know**: Which files are the authoritative sources? + +Focus on what would help a future Claude session work correctly on the first try. Prioritize: +1. Conventions that, if violated, would break things +2. Patterns that are project-specific (not obvious from the language/framework) +3. Files that are the source of truth for this topic + +### Step 4: Present Findings + +Format your findings clearly: + +``` +## What I learned about [topic] + +**The convention:** +[1-2 sentences describing the standard approach] + +**Key patterns found:** +- [pattern 1 with file:line reference] +- [pattern 2 with file:line reference] +- [pattern 3 with file:line reference] + +**Authoritative files:** +- `src/path/to/file.ts` — [what this file defines] +- `src/path/to/other.ts` — [what this file defines] + +**Gotchas:** +- [thing that would go wrong if done differently] +``` + +If you find NOTHING systematic (the codebase has no clear convention for this topic), say so honestly and suggest whether one should be established. + +### Step 5: Propose CLAUDE.md Update + +Draft a concise addition to CLAUDE.md. Each line must be one of these forms: + +``` +- : () +- : Use — +- : Never — +``` + +Keep it SHORT. One line per concept. Example: + +``` +- Error handling: All API handlers must wrap errors with `handleError()` from `src/lib/errors.ts` — otherwise error middleware won't catch them +``` + +Show the proposed additions as a diff: + +```diff ++ - Error handling: Use `handleError()` from `src/lib/errors.ts` — the error middleware in `src/middleware/errorHandler.ts` requires the `code`/`message`/`statusCode` shape it produces +``` + +Then ASK: "Should I add these to CLAUDE.md?" + +**Do NOT edit files until the user approves.** + +### Step 6: Save (on Approval) + +When the user approves: +1. Determine the right file: `CLAUDE.md` (team-shared, checked in) vs `CLAUDE.local.md` (personal, gitignored). Default to `CLAUDE.md` unless the content is personal preference. +2. If the file doesn't exist, create it with a brief header. +3. Add the new content under an appropriate section. If no sections exist, add a `## Conventions` heading. +4. If updating an existing section on this topic, integrate; otherwise, add a new bullet. + +## Examples + +### Example 1: Learning error handling + +``` +User: /teach error handling + +Claude: +[searches for try/catch, error classes, error middleware...] +[reads src/lib/errors.ts, src/middleware/errorHandler.ts, 5 API handlers...] + +## What I learned about error handling + +**The convention:** +All API route handlers use the `handleError()` utility, never bare `try/catch`. +Errors must extend `AppError` with `code`, `message`, `statusCode`. + +**Key patterns found:** +- `handleError(err, res)` used in all route handlers under `src/api/` +- Custom errors extend `AppError` in `src/lib/errors.ts:15` +- Error middleware in `src/middleware/errorHandler.ts:23` expects AppError shape + +**Authoritative files:** +- `src/lib/errors.ts` — AppError base class and handleError utility +- `src/middleware/errorHandler.ts` — Express error middleware + +**Gotchas:** +- Throwing non-AppError objects bypasses the error middleware and returns 500 with no body +- Async handlers must be wrapped with `asyncHandler()` from `src/lib/asyncHandler.ts` + +**Proposed CLAUDE.md addition:** + +```diff ++ - Error handling: Use `handleError()` from `src/lib/errors.ts` for all API routes — throw `AppError` subclasses only. Async handlers must use `asyncHandler()` wrapper. +``` + +Should I add this to CLAUDE.md? +``` + +### Example 2: No clear convention found + +``` +User: /teach database migrations + +Claude: +[searches for migration files, schema changes, ORM config...] + +## What I learned about database migrations + +**No clear convention found.** The codebase has: +- 3 raw SQL files in `db/migrations/` (unnumbered, no naming convention) +- 2 Knex migrations in `src/knex/` (appear to be from an earlier approach) +- Prisma schema in `prisma/schema.prisma` (active ORM, but no migration history) + +**Recommendation:** Standardize on Prisma migrations (`prisma migrate dev`) and document the workflow. The mixed approaches suggest an incomplete migration. + +**Proposed CLAUDE.md addition:** + +```diff ++ - Database: Use Prisma for schema management. Run `prisma migrate dev` to generate migrations. Legacy SQL and Knex files in `db/` and `src/knex/` are deprecated. +``` + +Should I add this to CLAUDE.md? +``` + +## Anti-Patterns to Avoid + +1. **Don't be passive**: Don't ask the user to explain the convention — explore the codebase to discover it. The user is teaching you the *topic*, not the *details*. +2. **Don't over-document**: CLAUDE.md is not a wiki. Every line costs tokens. If the convention is standard for the framework, don't document it. +3. **Don't write essays**: One line per insight. Link to files for detail. +4. **Don't duplicate**: Check existing CLAUDE.md first. If it already documents this, tell the user and suggest improvements instead of adding duplicates. +5. **Don't save without asking**: Always present findings and get explicit approval before editing files.