Why Signing a CLAUDE.md Contract Is the First Step to Mastering Claude Code

After installing Claude Code, the first and most crucial task is to define a contract with the AI by creating a CLAUDE.md file. This file acts as the agent’s "constitution," allowing Claude Code to understand project structure, coding style, test commands, and common pitfalls each time a new session starts.

What Is CLAUDE.md?

When using Claude Code for a while, you’ll notice it often forgets basic programming rules you repeatedly tell it, such as using strict types or keeping diffs minimal. CLAUDE.md solves this by letting the AI follow your constraints in different scopes.

Constraint System

Claude Code reads multiple CLAUDE.md files in order. The hierarchy consists of three levels:

Global CLAUDE.md – typically located at ~/.claude/CLAUDE.md, applies to all projects for long‑term coding preferences.

Project CLAUDE.md – located at ./CLAUDE.md or ./.claude/CLAUDE.md, contains project‑specific architecture, commands, naming conventions, and traps.

Local CLAUDE.md – located at CLAUDE.local.md in the project root, used for personal notes and should not be committed to Git.

General Writing Tips

Do not overload the file with unnecessary details; excessive content consumes tokens and can cause Claude Code to miss important rules. The creator’s own file contains about 2,500 tokens (~100 lines). In practice, keep the file under 80 lines, never exceeding 200 lines.

Start with a minimal CLAUDE.md and iteratively add rules whenever Claude Code makes a mistake. You can even ask Claude Code to write the rule for you after it fails.

Guideline: Write only what Claude cannot infer from the code; omit what it can read automatically.

Auto‑Generated Rule Example

Using a previously built index.html project, we let Claude Code generate rules, then refined them:

After refinement, Claude Code applied the concise rules to optimize the index.html code successfully.

Global CLAUDE.md Practice

Create the file if it does not exist: touch ~/.claude/CLAUDE.md Typical global rules (keep them concise):

## Communication
- Default language Chinese, code/commands/variables English

## Code Style
- Comments only in English
- Follow DRY, KISS, YAGNI

## Error Handling
- Always throw explicit errors, never silence them
- Include request parameters, response body, and status code in error messages
- Use structured logging

## Terminal Usage
- Prefer non‑interactive commands, e.g., `git --no-pager diff`
- Use `rg` for searching code

## Claude Code Workflow
- Read existing code and relevant CLAUDE.md before modifying
- Keep changes minimal and scoped to the current request
- Match the repository’s existing style even if it differs from personal preference
- Run test or lint commands before finishing if the task modified code

These examples can be moved to project‑level files when they are project‑specific.

Project CLAUDE.md Practice

Initialize a project‑level file with the /init command:

/init

The generated draft looks like this:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a simple static HTML demo page that displays a "Hello, Claude Code!" message with a Matrix‑style falling characters animation. The project consists of a single `index.html` file with embedded CSS and JavaScript.

## Development

To view the page, open `index.html` in a web browser directly, or serve it with any static file server:

```bash
# Using Python
python3 -m http.server 8000

# Using Node.js (npx)
npx serve .
```

After reviewing, you can ask Claude Code to translate the content to Chinese or further refine the rules.

Repeatedly iterating this process yields richer, more useful constraints.

Conclusion

The core takeaway is that defining a well‑structured CLAUDE.md hierarchy—global for universal preferences and project for specific constraints—is essential for getting the most out of Claude Code. Start small, let the AI suggest rules when it errs, and continuously refine the file as you discover new patterns.