Writing Effective Instructions

Overview

Having the right sections in your CLAUDE.md is only half the battle. The other half is writing instructions that agents actually follow correctly. Poorly written instructions -- vague, ambiguous, or contradictory -- lead to the same guessing behavior you would see without a CLAUDE.md at all.

This lesson covers the craft of writing instructions that are specific enough to be actionable, concise enough to fit in context, and clear enough to leave no room for misinterpretation.

The Specificity Spectrum

Instructions exist on a spectrum from vague to precise. Agents perform best with instructions near the precise end.

The specificity spectrum from vague to precise: Vague instructions like 'Write good tests' and 'Handle errors properly' are ineffective. Better versions like 'Write unit tests for new functions' add some clarity. Precise instructions like 'Write tests using vitest. Place test files adjacent: foo.ts → foo.test.ts' and 'Use tryCatch() from src/lib/result.ts. Never throw raw exceptions.' are the most effective.

The key difference is actionability. A vague instruction like "write good tests" forces the agent to decide what "good" means. A precise instruction like "write tests using vitest, place test files adjacent to source" leaves no ambiguity.

Rule 1: Use Imperative Mood with Exact Commands

Imperative mood means giving direct commands: "Run this," "Use that," "Never do this." Avoid passive or descriptive language.

The bad version describes the project. The good version tells the agent what to do. The agent does not need to know that you use ESLint -- it needs to know to run pnpm lint.

Rule 2: Include the "Why" for Non-Obvious Rules

Most rules are self-explanatory: "run pnpm test before committing" needs no justification. But some rules are surprising or counterintuitive. For these, include a brief why to prevent the agent from "optimizing away" the rule.

The "why" does not need to be long -- one sentence is usually enough. The goal is to signal that the rule exists for a specific technical reason, not an arbitrary preference.

Rule 3: Show Examples of What NOT to Do

For code style rules, showing a bad example alongside the good is more effective than describing the rule in prose. Agents learn patterns well from examples.

This format -- bad then good with real code -- is especially effective because the agent can pattern-match against it. When it encounters a situation requiring error handling, it has a concrete template to follow.

Rule 4: Be Specific About Scope

When a rule applies only to certain parts of the codebase, state the scope explicitly. Otherwise the agent will apply it everywhere.

Scope is especially important in monorepos where different packages may have different conventions. A rule that is correct for your API package might be wrong for your frontend package.

Rule 5: Keep It DRY -- Reference, Don't Repeat

If a convention is already encoded in a config file, do not duplicate it in CLAUDE.md. Instead, reference the config file.

This approach has two benefits: it keeps CLAUDE.md shorter (saving context window), and it avoids the risk of CLAUDE.md contradicting the config file when one gets updated but not the other.

Common Anti-Patterns

Here are the most common mistakes people make when writing CLAUDE.md instructions, and how to fix them.

Anti-Pattern 1: The Wall of Text

Agents parse structured, bulleted instructions better than dense paragraphs. Use headings, bullet points, and whitespace to make the document scannable.

Anti-Pattern 2: Stale Instructions

Stale instructions are worse than no instructions -- they actively mislead the agent. When you update a tool, framework, or pattern, update the CLAUDE.md in the same commit.

Tip: Add "update CLAUDE.md" to your migration checklists. When switching from Jest to Vitest, from npm to pnpm, or from one pattern to another, updating CLAUDE.md should be part of the migration.

Anti-Pattern 3: Contradictory Rules

When CLAUDE.md contains contradictory rules, the agent may follow either one unpredictably. Review your CLAUDE.md periodically for internal consistency, especially after multiple people have contributed to it.

Anti-Pattern 4: Context Window Waste

Project history and team structure are valuable for humans but useless for agents. Every line in CLAUDE.md consumes context window tokens. Be ruthless about removing content that does not help the agent write correct code.

A Checklist for Good Instructions

Before adding an instruction to your CLAUDE.md, run it through this mental checklist:

• Is it actionable? -- Can the agent do something specific based on this instruction?
• Is it unambiguous? -- Is there only one way to interpret it?
• Is it current? -- Does it reflect the codebase as it exists today?
• Is it necessary? -- Would the agent make a mistake without this instruction?
• Is it scoped? -- Is it clear where this instruction applies?
• Is it concise? -- Can you say it in fewer words without losing meaning?

If an instruction fails any of these checks, revise it before adding it. A shorter CLAUDE.md with high-quality instructions outperforms a longer one with mixed quality.

Summary

• Write instructions in imperative mood with exact commands -- "Run pnpm test" not "tests should be run"
• Be specific and actionable -- vague instructions like "follow best practices" are effectively invisible
• Include the "why" for non-obvious rules so the agent does not discard them
• Show bad and good examples side by side for code style rules
• Scope your rules explicitly when they apply only to certain directories or file types
• Reference config files instead of duplicating their contents
• Avoid anti-patterns: walls of text, stale instructions, contradictions, and context window waste
• Use the six-point checklist (actionable, unambiguous, current, necessary, scoped, concise) before adding any instruction