A work contract for the CLAUDE.md file

1. What the file does

A good CLAUDE.md file is not pretty documentation. It is a work contract: what is allowed, what is not, how you check, and when you stop.

• Puts the agent into the project's context.
• Defines how you run checks and where to look first.
• Stops it from touching sensitive areas without approval.
• Sets what output counts as done.
• Saves you the lecture you give from scratch every conversation.

2. What goes into the file

• A short description of the project and the user.
• Run, test and build commands.
• Files that must be read before editing.
• Areas you do not touch without approval.
• Rules for style, scope, secrets and deploy.
• A finish check every task must return.

3. What does not go in

• A long history of every decision.
• Ideas that might happen someday.
• Full product documents.
• Secrets, tokens and passwords.
• Rules that contradict the reality in the code.

4. Skeleton to copy

# Project Instructions
  
  ## What This Project Does
  [one sentence about the product, the user, and the problem]
  
  ## Run Commands
  - Dev: [command]
  - Typecheck: [command]
  - Build: [command]
  - Tests: [command]
  
  ## Before Editing
  - Read [files]
  - Check [existing pattern]
  - Keep changes inside [scope]
  
  ## Do Not Touch Without Approval
  - [billing / payments / customers]
  - [production config]
  - [external send / publish / delete]
  
  ## Coding Rules
  - Keep changes scoped.
  - Reuse existing helpers.
  - No secrets in code.
  - Report unrelated dirty files without changing them.
  
  ## Done Means
  - [verification command]
  - [browser check if user-facing]
  - [known risk reported]
  - [files changed listed]

5. Quick check

• If the agent still asks where to start, context is missing.
• If it takes a risky action on its own, a boundary is missing.
• If it finishes with a summary and no evidence, a finish check is missing.
• If the file gets too long, split the rules into focused files.