Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/andrewn6/claude-code-101


https://github.com/andrewn6/claude-code-101

Last synced: 10 days ago
JSON representation

Awesome Lists containing this project

README 

          
# claude-code-101



A plug-and-play setup for Claude Code that turns it into an adaptive learning environment and development companion. Drop it into any project — it figures out your stack, researches what it doesn't know, and meets you where you are, whether you're just getting comfortable with the terminal or you've been shipping production systems for a decade.



## What is this?



It's a `.claude/` directory packed with 12 skills (slash commands), 6 sub-agents, and 7 rule sets that cover the stuff most engineers deal with daily: APIs, databases, distributed systems, testing, debugging, system design, security, performance, infrastructure — all of it.



The key thing: **nothing is hardcoded to a specific stack.** It doesn't care if you're writing Go with gRPC, TypeScript with GraphQL, Python with FastAPI, or Rust with Axum. Every skill starts by detecting what's in your project and researching the specific technologies before giving you anything. So it's always relevant, always current.



## Who's it for?



Literally anyone writing code:



- **New devs** — Get analogies, step-by-step walkthroughs, and exercises that build real understanding. No "just read the docs" energy.

- **Mid-level engineers** — Understand the "why" behind patterns, get code reviews that teach, practice system design with real feedback.

- **Senior engineers** — Tradeoff analysis, failure mode discussions, architecture reviews, production-readiness checks. Skip the basics, get to the interesting stuff.



It detects where you are and adjusts. Or you can force a level with `--beginner` / `--senior` flags.



## Getting started



### Quick install (into an existing project)



```bash

git clone https://github.com/andrewn6/claude-code-101.git && claude-code-101/install.sh /path/to/your/project

```



This copies all skills, agents, and rules into your project's `.claude/` directory without overwriting anything you already have. Use `--dry-run` to preview first, or `--force` to overwrite.



### Manual setup



1. Clone this repo (or just copy the `.claude/` directory and `CLAUDE.md` into your project)

2. Open the project in Claude Code

3. Type `/` to see available skills



That's it. No config, no API keys, no setup.



## Skills (slash commands)



These are the main way you interact with the system. Type `/` and pick one.



### `/explain `



Explains anything — a language feature, a design pattern, a distributed systems concept, a specific library. Adjusts depth based on who's asking.



```

/explain consistent hashing

/explain React useEffect --beginner

/explain gRPC streaming vs WebSockets --senior

```



### `/design `



Interactive system design session. Doesn't dump a complete architecture at you — builds it up collaboratively, asking questions and walking through layers (core flow → data model → API boundaries → failure modes → scale).



```

/design URL shortener

/design payment processing system

/design real-time chat with presence

```



### `/debug`



Guided debugging that teaches you the methodology, not just the fix. Walks through reproduce → isolate → hypothesize → verify → fix. Even if it spots the bug immediately, it shows you how to find it yourself next time.



```

/debug the API returns 500 on POST /users

/debug tests pass locally but fail in CI

/debug

```



### `/review [target]`



Code review that teaches. Reviews your code for correctness, design, readability, performance, security, and testing — and explains the reasoning behind each piece of feedback.



```

/review staged          # review staged changes

/review branch          # review all commits on this branch

/review src/api/users.ts

```



### `/kata `



Generates a hands-on coding exercise in your actual project, with your actual stack. Creates starter files, failing tests, and progressive hints. You write the solution.



```

/kata caching

/kata database migrations --beginner

/kata rate limiting --senior

```



### `/quiz `



Tests your understanding with targeted questions. Adapts question style to your level — "what does X do?" for beginners, "what are the tradeoffs?" for seniors. Gives feedback after each answer and a summary at the end with gaps to work on.



```

/quiz SQL joins

/quiz distributed consensus --senior

/quiz REST API design --count 10

```



### `/research `



Deep-dive research brief on any technology, library, framework, or pattern. Searches the web for current information, cross-references sources, and gives you a practical brief with tradeoffs, getting-started steps, and honest opinions.



```

/research Drizzle ORM

/research gRPC vs REST for microservices

/research Redis Streams

```



### `/scaffold `



Generates project structure and boilerplate. Researches the framework's current conventions first, shows you the plan, then creates real runnable code (not stubs).



```

/scaffold REST API using Express and Prisma

/scaffold GraphQL server with authentication

/scaffold microservice with message queue

```



### `/refactor [target]`



Identifies improvement opportunities, does the work, and explains the reasoning. Distinct from `/review` — this one actually makes the changes while teaching you the patterns (Extract Method, Guard Clause, etc.).



```

/refactor src/api/users.ts

/refactor "error handling"     # scan codebase for the pattern

/refactor --dry-run             # analyze recently changed files without modifying

```



### `/migrate  to `



Guides and executes technology or pattern migrations — safely, incrementally, with rollback plans. Creates a migration plan, gets your approval, then executes step by step.



```

/migrate callbacks to async/await

/migrate Jest to Vitest

/migrate REST to GraphQL --scope src/api

```



### `/perf `



Performance analysis through measurement, not guesswork. Identifies bottlenecks, suggests targeted optimizations with expected impact, and researches stack-specific profiling tools.



```

/perf src/api/search.ts

/perf "database queries"

/perf startup time --profile

```



### `/doc `



Generates documentation artifacts from actual code — READMEs, API docs, architecture overviews, or inline docstrings. Different from `/explain` which teaches you; this produces files.



```

/doc project                    # project-level README

/doc src/api --type api         # API reference

/doc --type architecture        # system overview

/doc src/utils --type inline    # add docstrings to source

```



## Agents (sub-agents)



These work behind the scenes. Claude delegates to them automatically when the task is heavy enough to warrant isolation, or you can ask for them directly ("use the architect agent to review this").



### tutor



Extended teaching sessions. When you want to really dig into a topic — like spending 30 minutes understanding how consensus algorithms work — the tutor agent handles it without eating up the main conversation's context. Adapts to your level, uses your project for examples.



### architect



System design reviewer. Analyzes your architecture holistically: component boundaries, data flow, failure modes, scalability, operational readiness. Outputs a structured assessment with prioritized risks and specific recommendations.



### db-advisor



Database specialist. Schema design, query optimization, migration strategy, technology selection. Detects your specific database and ORM, researches version-specific features, and gives you actual SQL/code — not generic advice.



### researcher



Deep research on anything. Runs multiple web searches, cross-references sources, checks your codebase for existing usage, and returns a concise brief. Used by other skills when they need to research a technology they're not sure about.



### security



Security auditor. Assesses code for vulnerabilities, analyzes auth flows, checks dependencies for known CVEs, and provides actionable remediation. Traces data flow from input to storage to output — doesn't just grep for `eval()`.



### devops



DevOps and infrastructure specialist. CI/CD pipeline optimization, Dockerfile best practices, deployment strategies, IaC review, monitoring setup. Detects your specific toolchain (GitHub Actions, GitLab CI, Terraform, k8s, etc.) and researches it before advising.



## Rules (automatic guardrails)



These activate automatically based on what files you're working on. You don't invoke them — they're just there, quietly keeping things on track.



### distributed-systems



**Activates on:** queue, worker, event, pubsub, saga, message, broker, stream, gRPC, and proto files.



Enforces the stuff that bites you in production with distributed systems:



- **Idempotency** — Every message handler must handle duplicates. If it doesn't, this rule flags it.

- **Failure handling** — Network calls need timeouts, retries with backoff, and circuit breakers. No naked HTTP calls to other services.

- **Ordering assumptions** — Don't assume message ordering unless the system guarantees it. The rule researches your specific queue/broker to know what it actually guarantees.

- **Observability** — Correlation IDs for tracing async operations, logging at service boundaries, metrics on queue depth and processing latency.



### database



**Activates on:** db, database, models, schema, migrations, SQL files, and ORM-specific directories (Prisma, Drizzle, Sequelize, Knex, TypeORM, SQLAlchemy, Ent).



Catches the common database mistakes:



- **Schema hygiene** — Primary keys, timestamps, foreign keys, consistent naming.

- **Migration safety** — Reversible migrations, no modifying applied migrations, separate data migrations from schema changes, flags table locks on large datasets.

- **Query quality** — N+1 detection, SQL injection prevention (no string interpolation), index suggestions verified with EXPLAIN, no SELECT * in production.

- **ORM awareness** — Researches your specific ORM's quirks before commenting. Checks for lazy loading traps.



### api-design



**Activates on:** api, routes, handlers, controllers, endpoints, resolvers, GraphQL, proto, and OpenAPI/Swagger files.



Works for REST, GraphQL, gRPC, or whatever you're using:



- **General** — Consistent error formats, input validation at the boundary, auth checks on every protected endpoint, rate limiting for public APIs.

- **REST-specific** — Correct HTTP methods and status codes, plural noun resources, pagination for lists.

- **GraphQL-specific** — Depth limiting, DataLoader for N+1 prevention, complexity analysis, proper error handling (no leaked internals).

- **gRPC-specific** — Proto versioning, proper error codes, streaming vs unary decisions, deadline propagation.

- **Security** — No exposed internals in error responses, parameterized queries, resource-level authorization.



### testing



**Activates on:** test files, spec files, test directories (`__tests__/`, `test/`, `tests/`, `spec/`).



Keeps tests useful instead of just green:



- **Quality** — Test behavior not implementation. Tests shouldn't break when you refactor internals.

- **Structure** — Arrange/Act/Assert, independent tests, no test pollution, clean teardown.

- **Coverage focus** — Happy path, edge cases, error cases, integration points. Don't test framework internals or trivial getters.

- **Mocking discipline** — Mock at boundaries only. Don't mock what you own. Verify mocks match real interfaces.



### security



**Activates on:** auth, authentication, authorization, middleware, security, crypto, session, login, OAuth, JWT, password, `.env`, secrets, and credentials files.



Enforces security fundamentals across any stack:



- **Secrets management** — No hardcoded secrets, API keys, or tokens in source. `.env` must be in `.gitignore`.

- **Authentication** — Modern password hashing (bcrypt/scrypt/argon2), rate limiting on login, cryptographically random session tokens, constant-time comparison.

- **Authorization** — Resource-level checks (not just route-level), default-deny, ownership verification before mutations.

- **Input handling** — Parameterized queries, context-aware output escaping, file upload validation.

- **Error handling** — No leaked stack traces, generic auth failure messages, security event logging.



### frontend



**Activates on:** components, pages, views, layouts, styles, hooks, composables, stores, and `.tsx`/`.jsx`/`.vue`/`.svelte` files.



Stack-agnostic frontend quality enforcement:



- **Accessibility** — Keyboard navigation, semantic HTML, alt text, associated labels, ARIA only when needed. Non-negotiable.

- **Component design** — Single responsibility, explicit props, separate data fetching from presentation.

- **State management** — Keep state local, distinguish UI vs domain state, compute derived values.

- **Performance** — Avoid unnecessary re-renders, lazy load routes, don't block the main thread.

- **Error handling** — Error boundaries, loading/empty states, no white-screen crashes.



### infrastructure



**Activates on:** Dockerfile, docker-compose, GitHub Actions, GitLab CI, Jenkinsfile, CircleCI, k8s, Terraform, Pulumi, CloudFormation, Ansible, Helm, Makefile, and deploy/infra directories.



Keeps infrastructure and CI/CD safe:



- **Docker** — Multi-stage builds, pinned base images, non-root users, no secrets in layers, health checks.

- **CI/CD** — Fail-fast ordering, dependency caching, pinned action versions, platform secret management, deployment gates.

- **IaC** — Everything in code, pinned versions, remote state with locking, resource tagging, blast radius awareness.

- **Deployment** — Automated deploys, rollback procedures, health checks before traffic, progressive rollout for risky changes.



## How the adaptive depth works



Every skill and agent uses the same three-tier system:



| Level | What you get | How it detects you |

|-------|-------------|-------------------|

| **Beginner** | Analogies, step-by-step, jargon defined as it goes, "try this" exercises | Simple questions, basic vocabulary, asks "what" |

| **Intermediate** | Patterns, "why" explanations, tradeoffs, practical examples from your codebase | Feature-level questions, knows terminology, asks "why" or "how" |

| **Senior** | Tradeoff analysis, failure modes, production concerns, architectural nuance | System-level questions, precise vocabulary, asks "what are the tradeoffs" |



If it can't tell, it'll ask. You can also force it with `--beginner`, `--intermediate`, or `--senior` on any skill.



## How the stack detection works



Before giving any stack-specific guidance, the system checks:



1. **Package files** — `package.json`, `go.mod`, `Cargo.toml`, `requirements.txt`, `pyproject.toml`, `pom.xml`, etc.

2. **Config files** — `tsconfig.json`, `docker-compose.yml`, `Dockerfile`, `Makefile`, etc.

3. **Source code** — Scans for imports, framework patterns, directory structure.

4. **Your word** — If you say "I'm using X", it trusts that.



Then it researches the specific technology via web search before giving guidance. So it's always working with current docs and best practices, not stale training data.



## Project structure



```

claude-code-101/

├── CLAUDE.md                              # Master instructions Claude reads on startup

├── README.md                              # You're reading it

│

└── .claude/

    ├── settings.json                      # Permissions and config

    │

    ├── skills/                            # Slash commands

    │   ├── explain/SKILL.md               # /explain

    │   ├── design/SKILL.md                # /design

    │   ├── debug/SKILL.md                 # /debug

    │   ├── review/SKILL.md                # /review

    │   ├── kata/SKILL.md                  # /kata

    │   ├── quiz/SKILL.md                  # /quiz

    │   ├── research/SKILL.md              # /research

    │   ├── scaffold/SKILL.md              # /scaffold

    │   ├── refactor/SKILL.md              # /refactor

    │   ├── migrate/SKILL.md               # /migrate

    │   ├── perf/SKILL.md                  # /perf

    │   └── doc/SKILL.md                   # /doc

    │

    ├── agents/                            # Sub-agents for heavy tasks

    │   ├── tutor/agent.md                 # Teaching sessions

    │   ├── architect/agent.md             # Architecture review

    │   ├── db-advisor/agent.md            # Database specialist

    │   ├── researcher/agent.md            # Deep research

    │   ├── security/agent.md              # Security auditing

    │   └── devops/agent.md                # DevOps & infrastructure

    │

    └── rules/                             # Auto-activating guardrails

        ├── distributed-systems.md         # Distributed system patterns

        ├── database.md                    # Database best practices

        ├── api-design.md                  # API design patterns

        ├── testing.md                     # Test quality standards

        ├── security.md                    # Security enforcement

        ├── frontend.md                    # Frontend quality & a11y

        └── infrastructure.md              # CI/CD & infra safety

```



## Using it



### As a template (for sharing)



1. Fork/clone this repo

2. Copy the `.claude/` directory and `CLAUDE.md` into any project

3. Done — skills, agents, and rules are all active



### As a personal setup



Put the skills you want in `~/.claude/skills/` instead of the project's `.claude/skills/` — they'll be available in every project you open.



### Adding your own skills



Create `.claude/skills/your-skill/SKILL.md`:



```yaml

---

name: your-skill

description: What it does (Claude uses this to decide when to load it)

user-invocable: true

---



# Instructions for the skill



Write whatever you want Claude to do when this skill is invoked.

Use $ARGUMENTS to access what the user typed after the command.

```



### Adding your own rules



Create `.claude/rules/your-rule.md`:



```yaml

---

paths:

  - "**/*.py"

  - "**/your-directory/**"

---



# Your rule content



These instructions activate automatically when Claude touches files matching the paths above.

```



## What this is NOT



- Not a replacement for actual docs or courses — it's a companion

- Not locked to any stack, framework, or language

- Not a linter or CI tool — it's guidance, not enforcement

- Not static — it researches current best practices every time



## Contributing



Got a skill idea? A rule that'd help? Open a PR. The structure is simple — just add a `SKILL.md` or a rule markdown file and it works.

# claude-code-101