learn-something

Learn Something

Generate comprehensive, structured learning repositories for any technical concept — combining theory documentation (八股) and engineering practice code (可运行 demo), organized in the proven theory/ + demos/ + Makefile pattern.

Core Workflow

When activated, execute this three-phase process:

Phase 1: Clarify & Plan

Before generating anything, confirm three things with the user:

1. Topic: What concept/technology to learn
2. Language: Which programming language for demos (default: Go)
3. Directory: Where to create the project (suggest ~/Code/learn/learn-<topic>/)

Then research the topic thoroughly:

• Core concepts, architecture, and data models
• Key mechanisms (routing, persistence, reliability, clustering)
• Advanced features and common patterns
• Client library APIs in the target language
• Classic interview questions for this technology

From the research, produce a learning plan with:

• 6-10 theory files (numbered, with titles and one-line summaries)
• 10-20 demos grouped into 5-8 categories (each demo maps to a theory concept)
• Present this plan to the user for approval before writing code

Phase 2: Build

Execute in three parallel tracks:

Track A — Theory: Write all .md files in theory/ plus theory/README.md. Each file 200-500 lines of deep architectural explanation with ASCII diagrams.

Track B — Demos: Write all Go code in demos/. Each demo is a self-contained main.go with verbose Chinese comments, command-line mode switching, and graceful shutdown. Also write pkg/<topic>/ shared helpers.

Track C — Infrastructure: Write go.mod, Makefile, root README.md, demos/README.md.

Reference references/project-template.md for the exact directory layout convention and references/code-patterns.md for the Go code template to follow.

Phase 3: Validate

After all files are written:

cd <project-dir>
go mod tidy && go build ./... && go vet ./...

Fix any compilation errors. Then spot-check:

• 2-3 theory files for depth and accuracy
• 2-3 demo files for correctness and comment quality
• Makefile targets are all valid
• theory/README.md and demos/README.md have correct links

Use references/quality-checklist.md as the validation rubric.

Key Design Principles

Theory Documents

• Self-contained yet sequential: Each readable independently, but numbered for progressive learning
• Depth over breadth: Explain why design decisions were made, not just what the API does
• Visual: ASCII architecture diagrams for component relationships and data flow
• Interview-ready: Every theory set includes an interview chapter with 10-20 classic questions

Demo Code

• One concept per demo: Never combine unrelated features
• Tutorial-quality comments: Chinese comments explain rationale and trade-offs, not just mechanics
• Production patterns: Graceful shutdown, context propagation, error handling
• Independently runnable: Each demo works without depending on other demos

Project Organization

• No monolithic files: Theory split into 6-10 focused documents; demos grouped into numbered categories
• Makefile for discoverability: make help lists all targets; make run-<name> for each demo
• Index files: Both theory/README.md and demos/README.md with tables and learning paths

Language Detection

• User writes in Chinese → all docs and comments in Chinese; code identifiers in English
• User writes in English → all docs and comments in English; code identifiers in English
• Interview (八股) questions in the same language as surrounding docs

Reference Files

For detailed templates, code patterns, and quality standards, consult:

• references/project-template.md — Complete project structure spec with naming conventions and file templates
• references/code-patterns.md — Go code templates for demos, Makefile, README, pkg helpers
• references/quality-checklist.md — Validation rubric for theory depth, code correctness, and project completeness

Load these references when writing theory docs, demo code, or validating the completed project.