How to write Claude Code
CLAUDE.md instructions

What makes Claude Code different from other AI coding tools

Claude Code is an agentic command-line tool that reads CLAUDE.md files as its system prompt - giving it context about your project before it begins any autonomous coding, testing, or terminal task. Unlike Cursor or Windsurf which are IDEs with AI integrated, Claude Code operates from the terminal and can autonomously execute multi-step workflows: writing code, running tests, checking the output, fixing failures, and committing changes - all without manual intervention.

This agentic nature makes CLAUDE.md instructions especially important. Claude Code can make changes across many files in a single session. Without clear scope control and safety rules, it can make sweeping changes you did not intend.

What to include in CLAUDE.md

# Project: [Name]
Brief description of what this project does.

## Tech Stack
- TypeScript, Node.js 22
- Express for API routes
- PostgreSQL via Drizzle ORM
- Vitest for testing

## Architecture
- API routes in src/routes/ follow REST conventions
- Database access only through src/db/ layer
- Auth handled by src/middleware/auth.ts
- Types in src/types/ - check before creating new ones

## Coding Standards
- Named exports, no default exports
- Async/await throughout
- Write tests for all new functions
- Add JSDoc to all exported functions

## Safety Rules
- Only modify files in src/ and tests/
- Never modify package.json without noting the change
- Ask before making changes that affect more than 3 files
- Run npm test after every significant change

## Additional context
@docs/api-conventions.md
@src/components/README.md

System prompt vs master prompt vs user prompt in Claude Code

Common questions

How does Claude Code handle global vs project CLAUDE.md?

Claude Code reads both. The global ~/.claude/CLAUDE.md provides personal preferences. The project CLAUDE.md provides project-specific context. When they conflict, project CLAUDE.md takes precedence.

How is Claude Code different from Claude on claude.ai?

Claude Code is a terminal tool with autonomous capabilities. Claude on claude.ai is a chat interface. CLAUDE.md is only read by Claude Code. See our Claude guide for the claude.ai approach.

Can CLAUDE.md include shell commands?

You can include instructions about what commands to run (for example, "run npm test after every significant change"), but CLAUDE.md is not executable. It is a markdown document that Claude Code reads as context and then decides to run those commands based on your instructions.