DEV Community

Cover image for Chapter 2. Creating and Configuring a Project
UC Jung
UC Jung

Posted on

Chapter 2. Creating and Configuring a Project

#ai #cli #tooling #tutorial

2.1 Prerequisites

Item How to Verify
Claude Code installed claude --version
Git installed git --version
Authentication complete Prompt appears correctly when running claude
Diagnostics passing claude doctor

2.2 Creating a Project Folder

Windows PowerShell 

mkdir C:\Projects\my-first-project
cd C:\Projects\my-first-project
git init
Enter fullscreen mode Exit fullscreen mode

Ubuntu Terminal 

mkdir ~/projects/my-first-project
cd ~/projects/my-first-project
git init
Enter fullscreen mode Exit fullscreen mode

Git initialization (git init) is required. Claude Code uses the Git repository root as the project boundary.

2.3 /init — Initializing a Project

Run Claude Code inside your project folder and enter the /init command.

cd ~/projects/my-first-project
claude
Enter fullscreen mode Exit fullscreen mode 
> /init
Enter fullscreen mode Exit fullscreen mode

What /init Does

  1. Scans the project directory structure
  2. Analyzes configuration files such as package.json, tsconfig.json, and pyproject.toml
  3. Detects the tech stack, build/test commands, and code conventions
  4. Automatically generates a CLAUDE.md file in the project root based on the analysis

If a CLAUDE.md already exists, it will not be overwritten — instead, improvements will be suggested.

2.4 What Is CLAUDE.md?

CLAUDE.md is a project instruction file that Claude Code automatically reads at the start of each session.

Write your project's tech stack, build commands, code conventions, and architecture information in Markdown format. Claude Code will automatically load this context at the beginning of every session, ensuring consistent behavior throughout the project.

What to Include in CLAUDE.md

Item Example
Project overview "Weekly work report system built with NestJS 11 + React 18"
Tech stack TypeScript, PostgreSQL, Prisma
Build/test commands npm run build, npm test, npm run lint
Code conventions strict mode, 2-space indent, no default exports
Key directories src/api/, src/components/, tests/
Important notes "No direct commits to the main branch"

What NOT to Include in CLAUDE.md

  • Rules already enforced by linters/formatters (ESLint, Prettier, etc.)
  • A full listing of the file structure (discoverable through navigation)
  • General development common sense ("use meaningful variable names")

💡 Core principle: Keep CLAUDE.md concise — 200 lines or fewer.
Instructions become less effective as the file grows longer.

CLAUDE.md Example 

# My Project

## Tech Stack
- NestJS 11 + React 18 + TypeScript
- PostgreSQL + Prisma ORM
- Jest for testing

## Commands
| Command | Purpose |
|---------|---------|
| `npm run dev` | Start development server |
| `npm run build` | Production build |
| `npm test` | Run all tests |
| `npm run lint` | Run linter |

## Architecture
- `src/api/` — API routes and controllers
- `src/components/` — React components
- `src/services/` — Business logic
- `prisma/` — DB schema and migrations

## Rules
- TypeScript strict mode
- All tests must pass (`npm test`) before committing
- No direct commits to the main branch
Enter fullscreen mode Exit fullscreen mode

2.5 CLAUDE.md Hierarchy

CLAUDE.md can be placed in multiple locations. Claude Code merges and loads all of them at the start of each session.

┌─────────────────────────────────────────────────────────┐
│  ① Global (Personal)     ~/.claude/CLAUDE.md            │
│     → Personal preferences applied to all projects      │
├─────────────────────────────────────────────────────────┤
│  ② Project (Team-shared) ./CLAUDE.md                    │
│     → Committed to Git, shared across the team          │
├─────────────────────────────────────────────────────────┤
│  ③ Project Local         ./CLAUDE.local.md              │
│     → Personal use, not committed to Git                │
├─────────────────────────────────────────────────────────┤
│  ④ Subdirectory          ./frontend/CLAUDE.md           │
│     → Loaded on demand only when working in that folder │
└─────────────────────────────────────────────────────────┘

Priority: more specific takes precedence (④ > ③ > ② > ①)
When the same instruction appears at multiple levels, the more specific level wins.
Enter fullscreen mode Exit fullscreen mode

Real-World Usage Examples 

~/.claude/CLAUDE.md              ← "Respond in Korean", "Use Conventional Commits for commit messages"
~/projects/my-app/CLAUDE.md      ← Project stack, build commands, architecture
~/projects/my-app/CLAUDE.local.md ← "I handle the backend — ask me before modifying frontend code"
~/projects/my-app/frontend/CLAUDE.md ← "Use React Query, follow Tailwind class ordering rules"
Enter fullscreen mode Exit fullscreen mode

2.6 Memory (Claude.ai) vs CLAUDE.md (Claude Code)

These two may sound similar, but they are completely different systems.

Comparison Table

Memory (Claude.ai) CLAUDE.md (Claude Code)
Environment Claude.ai web/app conversations Claude Code CLI terminal
Scope Per person (applies to all conversations) Per project (applies only within that repo)
Storage Anthropic servers Local file (inside the project)
How to edit "Remember this" (natural language) Direct Markdown file editing
Auto-generation ✅ Derived automatically from conversations Created initially via /init
Version control ❌ ✅ Can be committed to Git
Team sharing ❌ Personal only ✅ Shared via Git
Nature of content Personal profile, preferences, work history Project rules, stack, commands

How to Configure by Perspective

Personal perspective — settings about "you"

What to configure Memory (Claude.ai) CLAUDE.md (Claude Code)
Work style "Prefer executive summaries for presentations" Write in ~/.claude/CLAUDE.md
Language preference "Respond in Korean" Write in ~/.claude/CLAUDE.md
Role information "R&D engineer on the P&T Advanced Research team" Write in ~/.claude/CLAUDE.md

Memory is set during a conversation by saying "remember this", while the global CLAUDE.md is edited directly as a file.

Project perspective — settings about "this project"

What to configure Memory (Claude.ai) CLAUDE.md (Claude Code)
Tech stack Accumulates automatically from conversation context Specify in ./CLAUDE.md
Build/test commands ❌ Not applicable Specify in ./CLAUDE.md
Code conventions ❌ Not applicable Specify in ./CLAUDE.md
Architecture rules ❌ Not applicable Specify in ./CLAUDE.md

Configuration File Locations Summary 

[Personal Settings]
  Claude.ai Memory     → Settings > Memory (web UI)
  Global CLAUDE.md     → ~/.claude/CLAUDE.md

[Project Settings]
  Project CLAUDE.md    → {project root}/CLAUDE.md        (team-shared, committed to Git)
  Local CLAUDE.md      → {project root}/CLAUDE.local.md  (personal, excluded from Git)
Enter fullscreen mode Exit fullscreen mode

2.7 Setting Up the Global CLAUDE.md

Configure personal preferences that apply across all projects.

Creating the File

Windows PowerShell

notepad $env:USERPROFILE\.claude\CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

Ubuntu Terminal

mkdir -p ~/.claude
nano ~/.claude/CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

Example Content 

# Global Preferences

## Language
- Write responses in Korean
- Use English Conventional Commits for commit messages

## Work Style
- Seek approval before applying changes to output
- Indicate when reasoning is speculative
- Explain the scope of impact before making code changes

## Git
- Branch names: use feature/, fix/, refactor/ prefixes
- Include the reason for the change in PR descriptions
Enter fullscreen mode Exit fullscreen mode

2.8 Setting Up a Project CLAUDE.md

Method 1: Auto-generate with /init (Recommended) 

cd ~/projects/my-project
claude
> /init
Enter fullscreen mode Exit fullscreen mode

Review the generated file and adjust it to match your team's conventions.

Method 2: Create Manually 

# Write directly at the project root
nano ~/projects/my-project/CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

Commit to Git 

git add CLAUDE.md
git commit -m "docs: add CLAUDE.md for project context"
Enter fullscreen mode Exit fullscreen mode

CLAUDE.local.md is automatically added to .gitignore.

2.9 What to Do When CLAUDE.md Gets Too Long

When CLAUDE.md exceeds 200 lines, instruction adherence starts to degrade. Use the following strategies to keep it manageable.

Method 1: Remove Unnecessary Instructions (Top Priority)

Remove anything Claude already does well without being told.

# ❌ Remove (obvious behavior)
- Use meaningful variable names
- Handle errors properly
- Do not include API keys in code

# ✅ Keep (things not inferable from the code)
- All tests must pass (npm test) before committing
- API responses must always follow the { success, data, error } format
Enter fullscreen mode Exit fullscreen mode

Method 2: Split into Subdirectories

For monorepos or large projects, distribute CLAUDE.md files across directories.
Subdirectory CLAUDE.md files are loaded on demand only when working in that folder, saving context.

my-project/
├── CLAUDE.md                  ← Common rules only (keep it concise)
├── frontend/
│   └── CLAUDE.md              ← React, Tailwind-related
├── backend/
│   └── CLAUDE.md              ← NestJS, Prisma-related
└── infra/
    └── CLAUDE.md              ← Docker, CI/CD-related
Enter fullscreen mode Exit fullscreen mode

Method 3: Reference External Documents with @import

Instead of putting everything in CLAUDE.md, reference existing documentation.

# Commands
See the Scripts section in @README.md

# API Convention
See @docs/api-convention.md

# Git Workflow
See @docs/git-workflow.md
Enter fullscreen mode Exit fullscreen mode

Claude Code reads those files when needed, so CLAUDE.md itself stays lightweight.

Method 4: Delegate to Linters/Hooks

Enforce repetitive rules through tooling rather than CLAUDE.md instructions.

Remove from CLAUDE.md Replace with
"Use semicolons" ESLint/Prettier configuration
"Commit message format" commitlint + husky
"Format on save" Hooks (PostToolUse)
"Commit only after tests pass" Hooks (PreToolUse)

2.10 Quick Reference 

# Initialize a project
cd ~/my-project
git init
claude
> /init                              # Auto-generate CLAUDE.md

# CLAUDE.md hierarchy
~/.claude/CLAUDE.md                  # Global (personal, all projects)
./CLAUDE.md                          # Project (team-shared)
./CLAUDE.local.md                    # Project local (personal)
./subfolder/CLAUDE.md                # Subdirectory (on demand)

# Add a memory during a session (inside Claude Code)
# (Press the # key during a conversation to instantly append to CLAUDE.md)

# Memory (Claude.ai) settings
# View and edit at Settings > Memory
# Add during a conversation with "remember this"
Enter fullscreen mode Exit fullscreen mode

References: https://code.claude.com/docs/en/best-practices | https://claude.com/blog/using-claude-md-files

Top comments (0)