Lab 1.3: Building the Project Brain

Module: 1.3 - Providing Context with CLAUDE.md | ← SlidesDuration: 30 minutes Sample Project: node-express-mongoose-demo

Learning Objectives

By the end of this lab, you will be able to:

• Create a CLAUDE.md file for a project
• Document build commands, testing instructions, and coding conventions
• Test that Claude follows your documented instructions

Prerequisites

• Completed Lab 1.2 (Codebase Exploration)
• Sample project ready (node-express-mongoose-demo)

Setup

# Navigate to the sample project
cd sample-projects/node-express-mongoose-demo

# Make sure you're in the project root
pwd

---

Step 0: Sizing Your CLAUDE.md

Time: 2 minutes

Before you start, understand the sizing guidelines:

• Recommended range: 300-800 lines (~2-5K tokens)
• Default target: 300-500 lines for most projects
• Upper limit: 800 lines for large, complex projects

Keep your CLAUDE.md focused and concise. Avoid walls of text. Use headers, bullets, and code blocks for readability.

---

Task 1: Create the CLAUDE.md File

Time: 10 minutes

Create a new CLAUDE.md file in the project root:

touch CLAUDE.md

Open it in your preferred editor and add the following sections:

1. Building & Running

# node-express-mongoose-demo - Claude Instructions

## Building & Running
- `npm install` — Install dependencies
- `npm start` — Start the application (default port 3000)
- `npm run dev` — Start with nodemon for development

2. Testing

## Testing
- `npm test` — Run the test suite
- Tests use Mocha as the test framework

3. Coding Conventions

## Coding Conventions
- All new functions must have JSDoc comments
- Use async/await instead of callbacks or promise chains
- Follow the existing MVC pattern: routes → controllers → models

---

Task 2: Add Project-Specific Context

Time: 10 minutes

Expand your CLAUDE.md with additional context:

Architecture

## Architecture
- Express.js web application with MongoDB backend
- Uses Mongoose for ODM (Object Document Modeling)
- Pug templates for server-side rendering
- Session-based authentication with Passport.js

Known Issues

## Known Issues
- The `imager` module is legacy code for image processing
- Some configuration is in `config/` directory (environment-based)

---

Task 3: Test Your CLAUDE.md

Time: 10 minutes

Start a new Claude session and verify it reads your instructions:

claude

Test Prompts

Try these prompts and check Claude's responses:

Prompt 1:

How do I build this project?

Expected Response

Claude should respond with npm install and npm start from your CLAUDE.md.

Prompt 2:

How do I run the tests?

Expected Response

Claude should mention npm test and Mocha.

Prompt 3:

Write a new utility function that validates email addresses.

Expected Response

Claude should include a JSDoc comment (following your coding convention).

---

Success Criteria

• [ ] Claude references the correct build commands
• [ ] Claude follows the JSDoc convention when writing new code
• [ ] Claude understands the project architecture

---

Tips for Success

Do	Don't
Be specific: "Use async/await"	Be vague: "write good code"
Include actual commands: npm run build	Say "build the project"
Explain unusual things: "Don't modify X because..."	Leave confusing code unexplained
Use headers, bullets, code blocks	Write walls of text

---

Troubleshooting

Claude doesn't seem to use CLAUDE.md

• Make sure the file is saved
• Make sure you started claude from the same directory as CLAUDE.md
• Try exiting and restarting Claude

Claude ignores a convention

• Your direct instructions override CLAUDE.md
• Try being more specific in CLAUDE.md
• Remind Claude: "Remember the coding conventions in CLAUDE.md"

---

Advanced: Using /init for Auto-Generation

Instead of creating CLAUDE.md manually, you can use the /init command:

claude
/init

Claude will analyze your project and generate an initial CLAUDE.md with:

• Detected build commands
• Test commands
• Project structure overview
• Basic conventions

TIP

The auto-generated file is a starting point. Always review and customize it for your specific needs.

---

Advanced: CLAUDE.md Rules for Common Problems

Add these rules to your CLAUDE.md to improve Claude's behavior:

Reduce Hallucinations (Read Before Edit)

## Important Rules
- NEVER propose changes to code you haven't read
- Always read a file before editing it
- If asked to modify a file, read it first to understand existing patterns

Adjust Eagerness

Claude Opus 4.5 is eager and asks for forgiveness, not permission. To make it more conservative:

## Behavior
- Ask before making large changes (>50 lines)
- Confirm understanding before modifying critical files
- Prefer small, incremental changes

Enable Parallel Tool Calls

For faster execution on independent operations:

## Performance
- When multiple independent tasks are requested, execute them in parallel
- Use parallel tool calls for file reads that don't depend on each other

---

Advanced: Subdirectory CLAUDE.md Files

You can place CLAUDE.md files in subdirectories for localized rules:

project/
├── CLAUDE.md              # Project-wide rules
├── src/
│   └── CLAUDE.md          # Frontend-specific rules
├── api/
│   └── CLAUDE.md          # API-specific rules
└── tests/
    └── CLAUDE.md          # Testing-specific rules

Claude merges these rules, with more specific (deeper) files taking precedence.

WARNING

Use /clear frequently during long sessions to reset context and maintain focus.

---

Final CLAUDE.md Template

Here's the complete example:

# node-express-mongoose-demo - Claude Instructions

## Building & Running
- `npm install` — Install dependencies
- `npm start` — Start the application (default port 3000)
- `npm run dev` — Start with nodemon for development

## Testing
- `npm test` — Run the test suite
- Tests use Mocha as the test framework

## Coding Conventions
- All new functions must have JSDoc comments
- Use async/await instead of callbacks or promise chains
- Follow the existing MVC pattern: routes → controllers → models

## Architecture
- Express.js web application with MongoDB backend
- Uses Mongoose for ODM (Object Document Modeling)
- Pug templates for server-side rendering
- Session-based authentication with Passport.js

## Directory Structure
- `app/` — Main application code (controllers, models)
- `config/` — Configuration files (environment-based)
- `public/` — Static assets
- `test/` — Test files

---

Deliverables

At the end of this lab, you should have:

1. A CLAUDE.md file in the project root
2. Verified that Claude follows your documented instructions
3. Understanding of how CLAUDE.md improves Claude's responses

---

Next Steps

After completing this lab, move on to Lab 1.5: Connecting the Dots.

TIP

Module 1.4 (Skills) is optional and can be covered separately.