Dashboard/Phase 3: Customization
🔬 Lab20 min25 XP

Lesson 22: Lab — Configure a Real Project for Claude Code

Day 22 of 50 · ~20 min hands-on · Phase 3: Customization

The Mission

You've learned how to customize Claude Code: CLAUDE.md teaches Claude about your project, permissions set boundaries, slash commands encode workflows, rules and memory guide Claude's learning, and skills package reusable knowledge.

Now it's time to put it all together.

Your mission: Pick a real project (or create a small one) and set it up for optimal collaboration with Claude Code. By the end, Claude will understand your project's conventions, follow your permission settings, and have access to custom tools that speed up common tasks.

What You'll Practice

This lab integrates concepts from all of Phase 3, plus foundations from earlier phases:

  • Reading code (Lesson 5) — You'll analyze a codebase to understand its structure
  • Prompting effectively (Lesson 11) — You'll write clear instructions in CLAUDE.md
  • Multi-file operations (Lesson 12) — You'll set up configuration across multiple files
  • CLAUDE.md (Lesson 17) — You'll write your project's conventions
  • Permissions (Lesson 18) — You'll configure safe autonomy levels
  • Slash commands (Lesson 19) — You'll create a custom workflow command
  • Rules and memory (Lesson 20) — You'll document project patterns
  • Skills (Lesson 21) — You'll package a reusable task

Setup

Pick a project. This should be:

  • A real project you work on (your own code, not someone else's)
  • At least a few files and some structure
  • Something you understand well enough to document conventions

If you don't have a suitable project, create a minimal one:

mkdir my-project
cd my-project
git init
npm init -y
mkdir src tests
echo "export const hello = () => 'world';" > src/index.js
echo "const { hello } = require('../src/index'); test('hello', () => expect(hello()).toBe('world'));" > tests/index.test.js

Create the .claude directory:

mkdir -p .claude/commands .claude/rules .claude/skills .claude/memory

You're ready to begin.

Step 1: Analyze and Document with CLAUDE.md (5 min)

What to notice: What's unique about this project? What will Claude ask about immediately?

Start by reading your project's key files:

  • package.json / pyproject.toml / language-specific config
  • The main entry point or source file
  • A test file (to understand your testing setup)
  • Build or deployment scripts

Create CLAUDE.md at the project root. Include:

  1. Project overview (1-2 sentences)

    • What does this project do?

  2. How to test

    • What command runs tests?
    • Where are test files located?
    • What testing framework?

  3. How to build/run

    • What command builds the project?
    • What command runs it locally?
    • Any environment setup?

  4. Code style

    • Language and any dialects (TypeScript, JSX, etc.)
    • Key naming conventions
    • Import style, indentation, key tools

  5. Project structure

    • /src or /app — where source code lives
    • /tests — where tests live
    • Any other important directories

  6. Key tools or dependencies

    • Major frameworks/libraries (React, Express, etc.)
    • Linting, formatting tools

Target: 40-80 lines. You're writing a cheat sheet, not a novel.

What to notice: How much context did you need to write this? Claude won't need to ask these questions again after reading CLAUDE.md.

Step 2: Configure Permissions (3 min)

What to notice: Which actions are safe and which need oversight in your workflow?

Create .claude/settings.json:

{
  "permissions": {
    "mode": "plan"
  }
}

Then think strategically:

  • Are there commands Claude should never run? (e.g., rm -rf, git push origin main)
  • Are there commands that are safe to run without asking? (e.g., npm test, git status)

Add a bypassTools section if appropriate:

{
  "permissions": {
    "mode": "plan",
    "bypassTools": {
      "allowed": ["bash:npm test", "bash:git status"],
      "blocked": ["bash:rm", "bash:git push"]
    }
  }
}

What to notice: How does plan mode change the feel of working with Claude versus asking every time? Are there actions you're confident Claude should handle silently?

Step 3: Create a Useful Slash Command (4 min)

What to notice: What's a workflow you run repeatedly that deserves its own shorthand?

Pick one of these common workflows or create your own:

  • /precommit — Run tests and show what changed
  • /check — Run linter and tests
  • /docs — Generate or update documentation
  • /setup — Install dependencies and set up the dev environment

Create .claude/commands/[command].md:

# /precommit

Prepare changes for commit. Runs tests, shows changes, suggests a commit message.

## Steps
1. Run tests: `npm test`
2. Show git status: `git status`
3. Show changes: `git diff` or `/review`
4. Ask me for a commit message suggestion

Save this file. This is your custom verb.

What to notice: When you run this command in a Claude conversation, how much faster is it than explaining the steps each time?

Step 4: Write Path-Scoped Rules (3 min)

What to notice: Are there different conventions in different parts of your project?

Pick one important directory (/src, /api, /components, /tests, etc.) and create .claude/rules/[dirname].rules.md:

# /src Directory Rules

## Code conventions
- All functions use async/await, not callbacks
- Functions start with a verb (getUserById, validateEmail)
- Use TypeScript for type safety

## Testing
- Write tests alongside source code
- Mock external dependencies
- Test both success and error cases

## Imports
- Use absolute imports with `@/` alias
- Group imports: local, then external

If your project has multiple distinct areas (frontend, backend, database, etc.), consider creating a rules file for each.

What to notice: How does this differ from CLAUDE.md? Rules are specific to a directory; CLAUDE.md is global.

Step 5: Start a Skill Library (3 min)

What to notice: What's a task you do often that deserves step-by-step documentation?

Create .claude/skills/[task].md. Pick something realistic for your project:

Example 1: Create a new component

# Create a React Component

## What this does
Creates a new React component with TypeScript and tests.

## Steps
1. Create `/src/components/ComponentName/index.tsx`
2. Export a React component
3. Create `/src/components/ComponentName/index.test.tsx`
4. Write at least one test
5. Export from `/src/components/index.ts`

## Template
index.tsx:
```typescript
export const ComponentName = () => {
  return <div>Component</div>;
};

EOF


**Example 2: Add an API endpoint**
```markdown
# Add an API Endpoint

## What this does
Adds a new REST API endpoint following the project's conventions.

## Prerequisites
- All endpoints validate input
- Use async/await
- Return { data: ... } or { error: ... }

## Steps
1. Create new file in `/api/routes/`
2. Define request handler with input validation
3. Add to router in `/api/index.js`
4. Write tests in `/tests/api/`

Your skill doesn't need to be perfect. It's a template Claude will refine over time.

What to notice: How specific can you be? The more detailed, the more consistent Claude's work will be.

Step 6: Create a Memory File (2 min)

What to notice: What have you learned about debugging or common pitfalls in this project?

Create .claude/memory/patterns.md:

# Project Patterns & Debugging

## Common errors and fixes
- "Cannot find module '@/...'" → Run `npm run build` then check tsconfig.json paths
- Test timeout → Check for unresolved promises or unclosed connections
- "ENOENT" → File path issue; always check relative vs absolute paths

## Build process
1. `npm install` — Install dependencies
2. `npm run build` — Compile TypeScript to JavaScript
3. `npm test` — Run test suite
4. `npm start` — Run development server

## Things Claude should know
- Main entry point is `/src/index.ts`
- Tests must pass before committing
- Always write tests for new features

This is where you capture lessons learned. Claude will use these hints to troubleshoot faster.

What to notice: You're not restricting Claude; you're helping it avoid repeating your mistakes.

Reflect

Answer these questions:

  1. CLAUDE.md — How much did your project need documented? Was 200 lines enough, or would you need more?

  2. Permissions — Did you allow Claude to run tests automatically? Why or why not?

  3. Slash commands — Which of your workflows felt most natural to encode as a command? What made it reusable?

  4. Rules vs. CLAUDE.md — Did you discover a place where rules made sense (different conventions in different directories)? Or is your whole project one unified style?

  5. Skills — Was it hard to break down a task into step-by-step instructions? What made it clearer?

  6. Memory — What's one mistake you'd like Claude to never make again? Did documenting it help?

Bonus Challenge

Option A: Extend your skill library. Create 2-3 more skills for other common tasks in your project. Build a small library that covers the main workflows your team uses.

Option B: Refine based on real use. Start a Claude Code conversation: claude. Ask Claude to do a task related to one of your skills. See what goes wrong, what goes right, and update your documentation based on what you learn.

Option C: Share with your team. If you work on a team, copy your .claude/ directory to a shared location or document it in a README. See if your team finds the configurations useful. Get feedback on what rules or skills they'd add.

What You've Done

You've transformed a plain project into a Claude-aware one. You've documented conventions, set boundaries, created shortcuts, and captured patterns.

Next time you (or someone else) runs Claude Code in this project, Claude will immediately understand:

  • How the project works
  • What it's allowed to do
  • What shortcuts are available
  • What patterns to follow
  • What mistakes to avoid

You've built institutional knowledge. This is what makes Claude Code scale from "nice experiment" to "actual team tool."

← Back to Curriculum · Lesson 23 →

←
Previous
21. Skills: Reusable Workflows
Next
23. Checkpoint — Phase 3 Review
→