Module 8: Capstone project: Your first project with Claude Code
Capstone Project: Your First Project with Claude Code
Capstone Project: Your First Project with Claude Code
Overview
This is the final module. Everything you learned in modules 1 through 7 converges here into a real project: you'll build a working CLI tool using Claude Code from start to finish, applying the complete professional workflow.
The project isn't about how complex the CLI you build is. It's about proving you command the full Claude Code workflow: a professional CLAUDE.md, custom skills, validation hooks, the Explore → Plan → Code cycle, tests generated by the agent, and semantic commits. The CLI is the vehicle — the workflow is the destination.
Project goal
Build a working CLI tool (Python or TypeScript) using the complete Claude Code workflow:
CLAUDE.md → Skills → Hooks → Explore → Plan → Code → Tests → Commit
By the end, you'll have:
- A project with a professional CLAUDE.md
- At least 2 custom skills, created and working
- At least 2 hooks, configured and active
- A CLI with 3 or more working commands
- Tests generated by Claude Code
- Everything committed with a descriptive message
This project is your calling card. It shows you know how to work with an AI agent professionally — not as someone who types casual prompts, but as someone who configures, plans, and executes with a system.
Why a CLI
We chose a CLI as the project format for concrete reasons:
| Reason | Explanation |
|---|---|
| Terminal-first | Claude Code lives in the terminal. A CLI is its natural territory |
| Framework-agnostic | You don't need React, Django, or any heavy framework |
| Tangible result | When you're done, you have a tool you can run and use |
| Controlled scope | A CLI with 3 commands is achievable in 1.5 hours |
| It proves the workflow | Every phase of the E→P→C cycle applies naturally |
You don't need prior experience building CLIs. Claude Code will guide the implementation — your job is to direct the process using the tools you learned.
What you built in previous modules
Each module handed you a piece of the puzzle. Here you put them all together:
┌─────────────────────────────────────────────────────────────┐
│ PREVIOUS MODULES │
│ │
│ M01: What Claude Code is → Fundamentals │
│ M02: Installation and setup → Tool ready │
│ M03: CLAUDE.md and memory → Persistent context │
│ M04: Agentic workflow (E→P→C) → Methodology │
│ M05: Skills and Hooks → Automation │
│ M06: Subagents → Delegation │
│ M07: Integrations → Ecosystem │
│ │
│ ───────────────────────────────────────────────────────── │
│ │
│ M08: CAPSTONE PROJECT → EVERYTHING together │
│ │
└─────────────────────────────────────────────────────────────┘
What you already know how to do
- CLAUDE.md: Create a professional context file with the 6 sections (Module 03)
- Skills: Create custom slash commands in
.claude/skills/(Module 05) - Hooks: Configure automatic scripts in
settings.jsonfor PreToolUse and PostToolUse (Module 05) - Explore: Analyze a project in read-only mode before acting (Module 04)
- Plan: Design an implementation plan before writing code (Module 04)
- Code: Implement step by step with the agent, steering it multi-turn (Module 04)
- Tests: Ask Claude to generate and run tests (Modules 04–05)
- Subagents: Delegate exploration and verification tasks (Module 06)
If any of these points feels fuzzy, review the matching module before you start the project.
Evaluation criteria
The project is evaluated across 6 dimensions. Each one reflects a competency from the previous modules:
| # | Criterion | Weight | Reference module | What gets evaluated |
|---|---|---|---|---|
| 1 | Well-structured CLAUDE.md | 20% | Module 03 | The 6 sections, < 200 lines, specific |
| 2 | 2+ skills created and working | 15% | Module 05 | Files in .claude/skills/, invocable |
| 3 | 2+ hooks configured | 15% | Module 05 | In settings.json, they fire correctly |
| 4 | Explore → Plan → Code workflow | 20% | Module 04 | Evidence that you followed the cycle |
| 5 | Working CLI with 3+ commands | 20% | Practice | Executable, commands operational |
| 6 | Tests generated by Claude Code | 10% | Modules 04–05 | At least 3 tests that pass |
Detailed rubric
CLAUDE.md (20%)
| Level | Description |
|---|---|
| Excellent | 6 complete sections, < 150 lines, specific conventions, runnable commands, actionable rules |
| Good | 5-6 sections, < 200 lines, clear conventions |
| Adequate | At least 4 sections, basic project information |
| Insufficient | Generic, vague, or more than 300 lines |
Skills (15%)
| Level | Description |
|---|---|
| Excellent | 2+ skills with clear instructions, examples, and rules. They invoke correctly |
| Good | 2 working skills with basic instructions |
| Adequate | 1 working skill |
| Insufficient | No skills, or they don't work |
Hooks (15%)
| Level | Description |
|---|---|
| Excellent | 2+ hooks with matchers, correct scripts, firing automatically |
| Good | 2 hooks configured correctly |
| Adequate | 1 working hook |
| Insufficient | No hooks, or they're misconfigured |
E→P→C workflow (20%)
| Level | Description |
|---|---|
| Excellent | Clear evidence of Explore (analysis), Plan (design), Code (incremental implementation) |
| Good | All 3 modes were used, even if not optimally |
| Adequate | At least 2 of the 3 modes were used |
| Insufficient | Went straight to Code with no Explore or Plan |
Working CLI (20%)
| Level | Description |
|---|---|
| Excellent | 3+ working commands, help text, error handling, formatted output |
| Good | 3 basic working commands |
| Adequate | 2 working commands |
| Insufficient | Fewer than 2 commands, or the CLI doesn't run |
Tests (10%)
| Level | Description |
|---|---|
| Excellent | Tests for every command, edge cases covered, all passing |
| Good | 3+ tests that pass |
| Adequate | At least 1 test that passes |
| Insufficient | No tests, or they don't pass |
Project ideas
You pick which CLI to build. Here are 5 ideas — take the one that interests you most, or invent your own:
Idea 1: File organizer
$ fileorg scan ./downloads
Found 47 files: 12 images, 8 documents, 15 code files, 12 others
$ fileorg organize ./downloads --by type
Organized 47 files into 4 directories:
images/ → 12 files
documents/ → 8 files
code/ → 15 files
others/ → 12 files
$ fileorg undo
Restored 47 files to original locations
Commands: scan, organize, undo
Suggested stack: Python + Click, or TypeScript + Commander
Idea 2: Notes CLI
$ notes add "Review the auth PR" --tag work
Note created: #42
$ notes list --tag work
#42 Review the auth PR [work] 2 min ago
#38 Deploy staging [work] 1 hour ago
#35 Code review pending [work] 3 hours ago
$ notes search "auth"
#42 Review the auth PR [work] 2 min ago
Commands: add, list, search
Suggested stack: Python + Click + JSON storage, or TypeScript + Commander + JSON
Idea 3: Git productivity tool
$ gitprod status
Branch: feature/auth (3 commits ahead of main)
Modified: 2 files | Staged: 1 file | Untracked: 0
$ gitprod summary --days 7
Last 7 days: 12 commits, 3 branches, +450/-120 lines
Top files: auth.py (8 changes), tests.py (5 changes)
$ gitprod quick "fix login validation"
Staged all changes → Committed → Pushed to feature/auth
Commands: status, summary, quick
Suggested stack: Python + Click + subprocess, or TypeScript + Commander + child_process
Idea 4: API health checker
$ healthcheck add https://api.example.com/health --name "Production API"
Endpoint added: Production API
$ healthcheck run
Production API https://api.example.com/health ✅ 200 (142ms)
Staging API https://staging.example.com/health ✅ 200 (238ms)
Payment Service https://pay.example.com/ping ❌ 503 (timeout)
$ healthcheck report --format json
{ "total": 3, "healthy": 2, "unhealthy": 1, "results": [...] }
Commands: add, run, report
Suggested stack: Python + Click + httpx, or TypeScript + Commander + fetch
Idea 5: Code analyzer
$ codestats scan ./src
Scanning ./src...
Language Files Lines Blank Comment
─────────────────────────────────────────────
Python 12 1,420 180 95
TypeScript 8 890 110 42
Markdown 3 220 30 0
─────────────────────────────────────────────
Total 23 2,530 320 137
$ codestats top --by lines
1. src/services/auth.py 342 lines
2. src/models/user.py 298 lines
3. src/routers/products.py 245 lines
$ codestats diff --since "2025-01-01"
Since Jan 1: +1,200 lines added, -400 lines removed
New files: 5 | Deleted files: 1
Commands: scan, top, diff
Suggested stack: Python + Click + pathlib, or TypeScript + Commander + fs
Choose your own adventure
You're not limited to these ideas. Any CLI with 3+ commands works. Just make sure that:
- It has at least 3 distinct commands
- Each command takes arguments or flags
- The CLI has help text (
--help) - It's something you can finish in ~1 hour of implementation
Timeline
The project is designed to be completed in 1.5 hours if you follow the capsules step by step:
┌──────────────────────────────────────────────────────────┐
│ PROJECT TIMELINE (1.5 hours) │
│ │
│ Capsule 02: Setup (25 min) │
│ ├── Create the project and CLAUDE.md 10 min │
│ ├── Create 2 skills 10 min │
│ └── Configure 2 hooks 5 min │
│ │
│ Capsule 03: Explore + Plan (15 min) │
│ ├── Explore: analyze the setup 5 min │
│ └── Plan: design the CLI 10 min │
│ │
│ Capsule 04: Build (35 min) │
│ ├── Implement command 1 10 min │
│ ├── Implement command 2 (with a skill) 10 min │
│ ├── Implement command 3 10 min │
│ └── Verify the full CLI 5 min │
│ │
│ Capsule 05: Test + Commit (15 min) │
│ ├── Generate tests 5 min │
│ ├── Review the code 5 min │
│ └── Commit and deliver 5 min │
│ │
│ Total: ~90 minutes │
└──────────────────────────────────────────────────────────┘
Don't worry if it takes you longer. The timeline is a guide, not a constraint. What matters is hitting all the evaluation criteria.
Prerequisites
Before you start, check that you have everything ready:
Technical
- Claude Code installed and authenticated (Module 02)
- Python 3.8+ or Node.js 18+ installed
- Git installed and configured
- A text editor available (VS Code, Cursor, Vim, etc.)
- A terminal with access to Claude Code
Knowledge
- Module 01: What Claude Code is — completed
- Module 02: Installation and setup — completed
- Module 03: CLAUDE.md and memory — completed
- Module 04: Agentic workflow — completed
- Module 05: Skills and hooks — completed
- Module 06: Subagents — completed
- Module 07: Integrations — completed
Quick check
Run these commands to confirm everything works:
# Claude Code
claude --version
# Python (if you choose Python)
python --version
pip --version
# Node.js (if you choose TypeScript)
node --version
npm --version
# Git
git --versionIf any of them fails, go back to Module 02 before continuing.
Project structure
The next 4 capsules walk you through it phase by phase:
| Capsule | Phase | What you'll do |
|---|---|---|
| 02 | Setup | CLAUDE.md + 2 skills + 2 hooks |
| 03 | Explore + Plan | Analyze the setup, design the CLI |
| 04 | Build | Implement 3 commands with Claude Code |
| 05 | Test + Commit | Tests, review, commit, delivery |
Each capsule is a self-contained session. You can pause between capsules — your CLAUDE.md, skills, and hooks persist on the filesystem.
Before you start
Choose your stack
| Option | CLI framework | Testing | Advantage |
|---|---|---|---|
| Python | Click | pytest | Familiar to most people, simple syntax |
| TypeScript | Commander | vitest | Type safety, good for JS/TS devs |
Both work perfectly with Claude Code. Pick the language you're most comfortable with.
Choose your project
Look over the 5 ideas in the previous section (or invent your own) and decide which CLI you'll build. Don't overthink it — they're all equivalent for demonstrating the workflow.
Mindset
This project isn't a programming exam. It doesn't matter if your CLI is simple or if the code isn't perfect. What matters is that you demonstrate command of the Claude Code workflow:
- Did you set up CLAUDE.md correctly?
- Did you create skills that automate repetitive tasks?
- Did you configure hooks that validate automatically?
- Did you follow the Explore → Plan → Code cycle?
- Did you let Claude Code do the heavy lifting while you directed?
If the answer to those questions is yes, the project is a success.
Summary
- Project: Build a working CLI with Claude Code using the complete workflow
- Duration: ~1.5 hours
- Evaluation: 6 criteria (CLAUDE.md, skills, hooks, workflow, CLI, tests)
- Language: Python (Click) or TypeScript (Commander) — you choose
- Requirement: 3+ working commands
- What matters: The workflow, not the complexity of the code
Next capsule: 02 - Setup: CLAUDE.md, skills, and hooks — the professional configuration of your project.