CLAUDE.md Configuration Guide

Using CLAUDE.md to provide Claude Code with project context and coding conventions

CLAUDE.md Configuration Guide ¶

CLAUDE.md is Claude Code's project-level configuration file. Every time Claude Code starts, it automatically reads the project's CLAUDE.md to learn about the project architecture, coding conventions, and special agreements, enabling it to understand your project more accurately.

Why You Need CLAUDE.md ¶

Without CLAUDE.md, you may need to repeatedly explain in every conversation:

"This project uses pnpm, not npm"
"The test command is yarn test:unit, not npm test"
"All components use TypeScript — no any types"

Write this information into CLAUDE.md and Claude will read it automatically on every startup, so you never have to repeat yourself.

File Hierarchy ¶

Claude Code reads and merges CLAUDE.md files from multiple levels:

Location	Scope
`~/.claude/CLAUDE.md`	Global configuration, applies to all projects
`<project root>/CLAUDE.md`	Project configuration, committed to Git for team sharing
`.claude/CLAUDE.md`	Private project configuration, can be added to `.gitignore`
`CLAUDE.md` in a subdirectory	Only read when Claude is operating in that directory

Quick Setup ¶

Use the /init command to generate one automatically:

/init

Claude will analyze the current project structure and auto-generate a CLAUDE.md populated with project information.

Basic Structure ¶

# Project Name

## Overview
Brief description of the project's purpose and tech stack.

## Tech Stack

- Runtime: Node.js 20
- Framework: Next.js 15
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma

## Common Commands

- Start dev server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`
- Lint code: `npm run lint`

## Coding Conventions

- Use TypeScript; no `any` types allowed
- Components use functional style
- Styling with Tailwind only — no inline styles
- Commit message format: `feat:` / `fix:` / `docs:` prefixes, etc.

## Project Structure

- `src/app/` — Next.js App Router pages
- `src/components/` — Reusable components
- `src/lib/` — Utility functions
- `prisma/` — Database schema and migrations

## Notes

- Do not modify `prisma/migrations/` — only create new migrations
- All API routes are under `src/app/api/`
- Image assets go in `public/images/`

Practical Tips ¶

1. Specify the Package Manager ¶

## Package Management
Use pnpm — do not use npm or yarn.
Install dependencies: `pnpm install`
Add a dependency: `pnpm add <package>`

2. Document Testing Conventions ¶

## Testing

- Unit tests: `vitest`, files end in `.test.ts`
- E2E tests: `playwright`, located in `tests/e2e/`
- Run unit tests: `pnpm test:unit`
- Run E2E: `pnpm test:e2e`
- New features must include tests

3. Specify Prohibited Actions ¶

## Prohibited Actions

- Do not use `console.log` — use the project's `logger` module instead
- Do not modify `package-lock.json` directly
- Do not commit directly to `main` — use feature branches

4. Provide Architectural Context ¶

## Architecture Overview
This project follows Hexagonal Architecture:

- `domain/` — Business logic, no external framework dependencies
- `application/` — Use cases, coordinating domain and infrastructure
- `infrastructure/` — External adapters for databases, HTTP, etc.
- `interfaces/` — Entry points such as web controllers and CLI

New features should follow this layering — do not introduce external dependencies in the domain layer.

5. Reference Other Documents ¶

## Further Reading

- API documentation: `docs/api.md`
- Deployment process: `docs/deploy.md`
- Database schema: `prisma/schema.prisma`

CLAUDE.md and Context Management ¶

The contents of CLAUDE.md consume context space. Recommendations:

Keep CLAUDE.md concise and focused on the most important information
For detailed architecture documentation, provide file path references in CLAUDE.md rather than copying content directly
In long sessions, CLAUDE.md always remains visible (it will not be removed by /compact)

Next Steps ¶

Learn about Context Management — master techniques for managing the context window
Learn about Permission Configuration — control which operations Claude is allowed to perform
Learn about Workflow Tips — establish an efficient Claude Code workflow

← Previous

Permission Configuration

Workflow Tips

🚀

Get Started with QCode — AI Coding Assistant

Official Claude Code relay, fast and reliable, ready to use

View Pricing Plans → Create Account