Learn

Learn

Autonomously analyzes a project's codebase to discover development patterns, conventions, and architectural decisions, then generates project rule files in .claude/rules/ for Claude Code to follow.

Overview

This skill acts as the Orchestrator in a two-agent architecture. It coordinates the overall workflow: gathering project context, delegating deep analysis to the learn-analyst sub-agent, filtering and ranking results, presenting findings to the user, and persisting approved rules to .claude/rules/.

The separation of concerns ensures the analyst operates with a focused forensic prompt while the orchestrator manages user interaction and file persistence.

When to Use

Use this skill when:

• User asks to "learn from this project" or "understand project conventions"
• User wants to auto-generate .claude/rules/ files from the existing codebase
• User asks to "extract project rules" or "discover patterns"
• User wants Claude Code to learn the project's coding standards
• After joining a new project and wanting to codify existing conventions
• Before starting a large feature to ensure Claude follows project patterns

Trigger phrases: "learn from project", "extract rules", "analyze conventions", "discover patterns", "generate project rules", "learn codebase", "auto-generate rules"

Instructions

Phase 1: Project Context Assessment

Before delegating to the analyst, gather high-level project context:

1. Verify project root: Confirm the current working directory is a project root (has package.json, pom.xml, pyproject.toml, go.mod, .git/, or similar markers)

2. Check existing rules: Scan for pre-existing rule files to understand what is already documented:

# Check for existing rules
ls -la .claude/rules/ 2>/dev/null || echo "No .claude/rules/ directory found"
cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"
cat AGENTS.md 2>/dev/null || echo "No AGENTS.md found"
ls -la .cursorrules 2>/dev/null || echo "No .cursorrules found"

3. Assess project size: Get a quick overview of the project scope:

# Quick project overview
find . -maxdepth 1 -type f -name "*.json" -o -name "*.toml" -o -name "*.xml" -o -name "*.gradle*" -o -name "Makefile" -o -name "*.yaml" -o -name "*.yml" | head -20
find . -type f -name "*.ts" -o -name "*.js" -o -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.php" | wc -l

4. Inform the user: Briefly tell the user what you found and that you are about to start analysis:
   • "I found a [TypeScript/NestJS] project with [N] source files and [M] existing rules. Starting deep analysis..."

Phase 2: Delegate to Analyst Sub-Agent

Invoke the learn-analyst sub-agent to perform the deep codebase analysis.

Use the Task tool to delegate analysis to the learn-analyst agent:

• Agent: learn-analyst
• Prompt: "Analyze the codebase in the current working directory. Follow your full process: discovery, pattern extraction, classification, and prioritization. Return your findings as a JSON report."
• Mode: Run synchronously to receive the JSON report directly

The analyst will return a structured JSON report with classified findings.

Phase 3: Review and Filter Results

Process the analyst's report:

1. Parse the JSON report returned by the analyst
2. Validate findings: Ensure each finding has:
   • A clear title
   • Evidence from at least 2 files
   • Impact score ≥ 4 (discard low-impact findings)
   • Well-formed markdown content
3. Deduplicate against existing rules: Compare each finding title and content against existing .claude/rules/ files. Skip findings that duplicate existing rules.
4. Select top 3: From the remaining findings, select the top 3 by impact score. If fewer than 3 remain after filtering, present whatever is left.
5. If zero findings remain: Inform the user that the project is already well-documented or no significant undocumented patterns were found.

Phase 4: Present to User

Present the filtered findings to the user in a clear, structured format:

I analyzed your codebase and found N patterns worth documenting as project rules:

1. **[RULE]** <Title> (Impact: X/10)
   <One-line explanation>

2. **[RULE]** <Title> (Impact: X/10)
   <One-line explanation>

3. **[RULE]** <Title> (Impact: X/10)
   <One-line explanation>

Then ask the user for confirmation using AskUserQuestion:

• Present choices: "Save all N rules", "Let me choose which ones to save", "Cancel — don't save anything"
• If the user wants to select individually, present each rule one by one with "Save / Skip" options
• Never save automatically — always require explicit user approval