Claude Code Project Setup

Welcome to Applying What You've Learned! This is the first lesson of the course, and we are starting with something fundamental: setting up Claude Code to work effectively with an existing project.

When we work with Claude Code on a real codebase, we cannot simply jump in and start making changes. Claude needs to understand the project's structure, conventions, and boundaries. Think of it as onboarding a new team member: they must learn the codebase, understand the coding standards, and know what they can and cannot touch. That is exactly what we will accomplish in this lesson.

By the end of this unit, we will have configured Claude Code for a Todo API project, creating the three essential configuration files: CLAUDE.md for project documentation, .claudeignore for excluding unnecessary files, and settings.json for permissions management. We will also verify that everything works correctly.

Before we create any configuration, we need to explore the existing project. This step is critical because our configuration files should reflect the actual patterns and conventions already present in the codebase.

When Claude Code encounters a new project, it can use its built-in tools to explore the structure. The most useful tools for this purpose are:

• Bash for listing directories and running commands
• Read for examining individual files
• Grep for searching across files

The exploration phase helps us identify key information, such as the technology stack, project structure, coding patterns, error handling conventions, and testing approach. Only after we understand these aspects can we document them properly in our configuration files.

Let us start by exploring the Todo API codebase structure. We can ask Claude to help us understand the layout by running a simple directory listing:

ls -R src/

This reveals the project organization:

src/
├── server.js
├── routes/
│   ├── todos.js
│   └── users.js
├── middleware/
│   ├── auth.js
│   └── validate.js
└── models/
    └── Todo.js

From this structure, we can already see several important patterns:

• Modular organization with separate folders for routes, middleware, and models
• Multiple route files suggesting feature-based organization
• Dedicated middleware folder indicating reusable logic
• A models folder for data structures

This gives us a solid foundation for understanding how the project is organized.

Now let us examine the actual code to identify conventions. We will start with the main server.js file:

// Express app with JWT auth, SQLite database
const express = require('express');
const jwt = require('jsonwebtoken');
const Database = require('better-sqlite3');

const app = express();
// ... setup code

Next, let us look at a route file to understand the API patterns:

// Standard CRUD operations, middleware-based validation
router.get('/', authenticateToken, async (req, res) => {
  try {
    const todos = await getTodos(req.user.id);
    res.json({ data: todos });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Finally, let us examine a test file to understand the testing approach:

const request = require('supertest');
const app = require('../src/server');

describe('Todo API', () => {
  test('GET /api/todos returns todos', async () => {
    const res = await request(app)
      .get('/api/todos')
      .set('Authorization', `Bearer ${authToken}`);
    
    expect(res.status).toBe(200);
  });
});

From examining these files, we can identify several key patterns:

• All routes use async/await syntax instead of callbacks
• Error responses follow the format { error: "message" }
• Success responses follow the format { data: {...} }
• Middleware is used for validation and authentication
• The project uses Jest with supertest for testing

These patterns are crucial because we will document them in CLAUDE.md to ensure Claude follows the same conventions when making changes.

Now we are ready to create CLAUDE.md, which serves as the project's operating manual for Claude Code. Let us start with the overview and technical stack:

# Todo API Project

## Overview
REST API for todo management with user authentication

## Tech Stack
- Node.js 20+
- Express 4.x
- SQLite with better-sqlite3
- JWT authentication
- Jest for testing

This section immediately informs Claude about the project type and the technologies in use. Notice how we specify version ranges: This prevents Claude from suggesting outdated approaches or incompatible libraries. The overview is concise yet informative, providing sufficient context without excessive detail.

The heart of CLAUDE.md is the coding standards section, which documents the patterns we discovered:

## Coding Standards
- Use async/await (no callbacks)
- Validation in middleware (src/middleware/)
- Error responses: { error: "message" }
- Success responses: { data: {...} }
- All routes need error handling
- JSDoc comments for functions

## Testing
- Run: npm test
- Use Jest + supertest
- Minimum 80% coverage

## Security
- Never log tokens or passwords
- Validate all inputs
- Use parameterized queries

Each guideline serves a specific purpose. The coding standards ensure consistency when Claude modifies code. The testing section tells Claude how to run tests and what coverage threshold to maintain. The security guidelines prevent Claude from accidentally introducing vulnerabilities, such as logging sensitive data.

These are not arbitrary rules; they reflect the actual patterns already present in the codebase, ensuring Claude Code works with the existing conventions rather than against them.

Just as .gitignore tells Git what to ignore, .claudeignore tells Claude Code which files to exclude from its context. This is important for performance, focus, and security:

# Dependencies
node_modules/

# Test artifacts
coverage/
*.test.db

# Logs
*.log
logs/

# Sensitive data
.env
*.key
*.pem
secrets/

Let us break down why we exclude each category:

• node_modules/: Contains thousands of dependency files that Claude does not need to read.
• coverage/: Generated test coverage reports that change frequently.
• *.test.db: Temporary database files created during testing.
• *.log and logs/: Log files that contain runtime data, not source code.
• .env, *.key, *.pem, secrets/: Files containing sensitive data that should never be included in Claude's context.

By excluding these files, we ensure Claude focuses on the actual source code and does not waste context window space on generated artifacts or dependencies. More importantly, excluding sensitive files prevents credentials, API keys, and other secrets from being inadvertently exposed to Claude's context. Even with Read permission, Claude should never have access to sensitive data files.

The final configuration file is settings.json, which controls what Claude can do without asking for permission. Let us create it in the .claude directory:

{
  "model": "claude-sonnet-4-5",
  "permissions": {
    "allow": ["Read", "WebSearch"],
    "ask": ["Edit", "Write", "Bash"]
  }
}

This configuration establishes a safe default behavior:

• Read is auto-approved because it does not modify files. However, this assumes you have properly configured .claudeignore to exclude sensitive data—otherwise, Claude could read credentials or secrets into its context.
• WebSearch is auto-approved for convenience, but be aware this makes external requests that could potentially expose information about your project to search engines. Consider setting this to ask if working with proprietary or sensitive projects.
• Edit, Write, and Bash require confirmation because they change files or execute commands.

The permission model follows the principle of least privilege: Claude can freely gather information, but any action that modifies the project requires explicit approval. Remember that "non-destructive" does not automatically mean "without risk"—always audit what files are accessible and consider your project's security requirements when configuring permissions. As we become more comfortable with Claude's suggestions, we can adjust these permissions, but this conservative starting point balances convenience with safety.

Now let us verify that our configuration works correctly. When we ask Claude about the authentication system, it should automatically use the Read permission without prompting:

> Now tell me about the authentication system in this project

● Read(src/middleware/auth.js)
  [Auto-approved - no prompt!]
  ⎿ Read 25 lines

● This project uses JWT authentication:
  
  - authenticateToken middleware verifies JWT
  - Token expected in Authorization header: "Bearer <token>"
  - Token contains user ID
  - Protected routes use this middleware
  - Tokens generated at login (/api/users/login)
  
  Following your CLAUDE.md standards, the middleware:
  - Returns error format: { error: "message" }
  - Uses async/await
  - Includes proper error handling

Notice two key points in this interaction. First, Claude automatically used the Read tool without requesting permission because we configured it as allow. Second, the response from Claude references the patterns from our CLAUDE.md. It specifically mentions the error format and async/await usage we documented. This proves that our configuration is working correctly.

In this lesson, we have set up Claude Code to work effectively with an existing project. We explored the codebase structure, identified coding patterns, created CLAUDE.md to document project standards, configured .claudeignore to exclude unnecessary files, and set up permissions in settings.json. We then verified that everything works by asking Claude about the authentication system.

These three configuration files form the foundation for productive collaboration with Claude Code. The CLAUDE.md ensures consistency, the .claudeignore optimizes performance, and the settings.json maintains safety. Together, they transform Claude from a generic coding assistant into a team member who understands your specific project.

Now it is time to put this knowledge into practice! In the upcoming exercises, you will configure Claude Code for different types of projects, reinforcing these concepts through hands-on experience.