Exercise: Creating CLAUDE.md for an Existing Project

Apply the agent mental model concepts from this module by creating a CLAUDE.md file for a real open source project.

Objective

• Experience how agents navigate an unfamiliar codebase without guidance
• Create a CLAUDE.md file using the WHAT/WHY/HOW framework
• Observe the measurable difference in agent performance with proper documentation
• Practice the discipline of high-signal, low-token documentation

Repository

Vectra is a local vector database for Node.js with file-based storage. It provides a lightweight alternative to cloud vector databases.

Setup

1. Clone the repository:

   git clone https://github.com/Stevenic/vectra.git
   cd vectra

2. Install dependencies:

   npm install

3. Verify the build works:

   npm run build

4. Explore the project structure:

   ls -la
   ls src/

Part 1: Baseline test without CLAUDE.md

Before creating documentation, observe how an agent performs without project-specific guidance.

Start a Claude Code session and ask the agent to perform these tasks:

Task A: Understanding the codebase

What is the architecture of this project? What are the main components and how do they interact?

Task B: Making a simple change

Add a new method to LocalIndex called `count()` that returns the number of items in the index.

Record any hesitation, incorrect assumptions, or need for clarification. These gaps represent the inference boundary.

Part 2: Create CLAUDE.md

Use the WHAT/WHY/HOW framework:

• Gather the WHAT Check package.json and tsconfig.json for tech stack, key dependencies, and available commands.
• Understand the WHY Why is the index stored in a specific format? Why are there multiple index types?
• Document the HOW How does someone build, test, and verify changes?

Starting template

# Vectra

[One-sentence description]

## Tech Stack
- Language: TypeScript [version from package.json]
- Runtime: Node.js
- Key dependencies: [list from package.json]

## Commands
- `npm run build`: [description]
- `npm run test`: [description]
- [other relevant commands]

## Structure
- `src/`: [purpose]
- `bin/`: [purpose]
- `samples/`: [purpose]
- `indexes/`: [purpose]

## Architecture
[Key concepts: LocalIndex, LocalDocumentIndex, metadata handling, vector storage format]

## Code Patterns
[Conventions you noticed in the codebase]

## IMPORTANT: Do Not
[Any restrictions or sensitive areas]

## Verification
[What should be checked after making changes]

Part 3: Test with CLAUDE.md

Start a fresh Claude Code session (/clear or restart) and repeat the same tasks.

Task A: Understanding the codebase

Compare: Is the response faster? More accurate? Does it mention concepts from your CLAUDE.md?

Task B: Making a simple change

Compare: Does the agent follow the patterns you documented? Does it know how to verify the change?

Part 4: Iterate and improve

1. Did the agent miss anything important? Add it to CLAUDE.md.
2. Did the agent follow all your guidance? If not, rephrase unclear instructions.
3. Was any content ignored or redundant? Remove it to reduce token overhead.
4. Run one more test task:

   Add a CLI command to the bin/ tools that displays index statistics (count, last modified, size on disk).

Success criteria

• CLAUDE.md file created in repository root
• File length between 50-80 lines (not too sparse, not bloated)
• Includes all essential sections: tech stack, commands, structure, patterns
• Includes at least one "Do Not" restriction
• Includes verification steps
• Second test shows measurable improvement in agent accuracy or confidence
• At least one iteration cycle completed based on testing results

Reflection questions

Inference boundary. What information did the agent need explicitly that it could not infer from the code? How did this match your expectations?

Token economy. Looking at your final CLAUDE.md, is there anything you could remove without losing effectiveness? Anything you wish you had added?

Maintenance burden. If the project's structure changed, how would you update CLAUDE.md? Is your file organized for easy updates?

Transferability. Would your CLAUDE.md work for other developers on the team? Does it assume knowledge that should be explicit?

Extension (optional)