How to Write Effective AI Agent Instructions

By Tyler Cyert

Writing effective AI agent instructions is not prompt engineering — it is technical writing. Your instruction file is a document that gets loaded into every session, read by an LLM that follows directions literally, and shared with your team through version control. The same skills that make good documentation make good agent instructions.

This guide covers how to write instructions that produce consistent results across sessions, developers, and tools — whether you are writing a CLAUDE.md, AGENTS.md, or any other agent configuration file.

The Three Qualities of Good Instructions

1. Specific

Bad: "Use good coding practices." Good: "Use named exports. No default exports except for page components. Props interfaces must be named [ComponentName]Props."

Specific instructions produce specific behavior. Every time you write an instruction, ask: "Could an agent follow this without making any judgment calls?" If not, make it more specific.

2. Scoped

Bad: "When working with TypeScript files, React components, API routes, database queries, and test files, follow these conventions..." (300 lines of everything) Good: A focused CLAUDE.md with project-wide conventions, plus rules for file-specific patterns.

Every instruction that is not universally relevant wastes context window when it loads. Scope your instructions to match their relevance.

3. Testable

Bad: "Write clean code." Good: "All public functions must have a corresponding test in the same directory. Test files use the pattern [name].test.ts."

Testable instructions let you verify compliance. After the agent finishes, you can check: did it create test files? Are they in the right location? Do they follow the naming pattern?

What to Include

Project Context (Required)

Every instruction file needs a project description, stack summary, and build commands. Without these, the agent starts every session guessing.

Conventions (Required)

Coding style, naming patterns, and structural rules that the agent must follow:

• Import patterns (use @/ alias, named exports only)
• File naming (kebab-case files, PascalCase components)
• State management patterns (where state lives, how it flows)
• Error handling patterns (consistent error format, logging rules)

Guardrails (Recommended)

Explicit "do not" instructions prevent expensive mistakes:

• "Never modify migration files directly"
• "Never install new dependencies without approval"
• "Never commit .env files"
• "Never use any type — use unknown and narrow"

Guardrails are more effective when they explain why: "Never modify migration files directly — applied migrations cannot be safely changed."

Working Directory Map (For Multi-Agent)

If you use working directories or agent teams, include a directory map:

• specs/ — requirements and feature specifications
• src/ — implementation code
• tests/ — test suites
• docs/ — generated documentation

This map tells every agent in the system where to find inputs and where to put outputs.

Structuring Your Instructions

Flat Over Nested

Use H2 headings (##) for major sections. Avoid deep nesting — the agent processes flat structure better than nested subsections.

Lists Over Prose

Bullet points are more reliable than paragraphs. Each point is one instruction. The agent follows a list of five instructions more consistently than five sentences in a paragraph.

Tables for Reference

Use tables for mappings, comparisons, and quick-reference information. Tables are scannable and unambiguous.

Prioritize by Position

Put the most important instructions first. Context windows have recency and primacy bias — instructions at the beginning and end get more attention than those buried in the middle.

The 200-Line Rule

Keep your main instruction file under 200 lines. Every line loads into every session, whether relevant or not. Past 200 lines, instructions start competing with each other for the agent's attention.

When you pass 200 lines, extract content:

Cross-Platform Instructions

The instruction content — conventions, architecture, guardrails — is platform-agnostic. Whether the agent reads it from CLAUDE.md, AGENTS.md, or a Cursor rules file, the same clear writing produces the same good results.

Only the file paths and loading mechanisms differ. DotBox keeps the content in one graph and generates the setup prompt for either layout: CLAUDE.md and .claude/ for Claude Code, or AGENTS.md and .agents/ for Codex and other agents that read it.

Getting Started

1. Write your instruction file. Start with project context, stack, build commands, and three to five key conventions.
2. Test it. Start a session and give the agent a task. If it asks questions your instructions should have answered, add that information.
3. Iterate. After a week of use, review what you have corrected repeatedly and add those as explicit instructions.
4. Scope it. When the file grows past 150 lines, start moving content into rules and skills.

The best instruction files are living documents that evolve with your project and your understanding of what the agent needs to know.