Instruction Files That Actually Work

• Understand why instruction files matter so much
• Know the naming conventions for different tools
• Write effective instruction file content
• Structure files for maintainability
• Update instruction files as projects evolve

This lesson is part of the Developer Track. We will cover instruction files like CLAUDE.md, .cursorrules, and copilot-instructions. If you are not coding, skip to Unit 6.

Instruction files are the single biggest lever for improving AI coding assistant output. A good instruction file turns generic AI suggestions into contextually appropriate code that matches your project's patterns.

Without an instruction file, AI coding assistants know nothing about your project. They guess based on general patterns. With an instruction file, they understand:

• Your tech stack and frameworks
• Coding conventions and style
• File structure and patterns
• What to do and what NOT to do
• Project-specific terminology

The Difference in Practice

Without instruction file:

"Add a new API endpoint"

AI might generate Express.js when you use Fastify, use callbacks when you use async/await, or put files in the wrong directory.

With instruction file:

AI reads that you use Fastify with TypeScript, follows your controller-service-repository pattern, puts new endpoints in "src/routes/", and uses your standard error handling.

Same prompt. Dramatically different output quality.

The Compound Effect

Every AI interaction benefits from the instruction file. Over days and weeks, the time saved from not having to correct basic issues adds up significantly. Teams report 30-50% productivity improvements from good instruction files alone.

Different tools look for different files. Here is what to use for each:

Can I Use One File for Multiple Tools?

Yes, with some effort. Options:

1. Symlinks: Create the main content in one file, symlink others to it
2. Common sections: Keep a master doc, copy relevant sections to each tool's file
3. Pick your primary tool: Use that tool's file, accept less optimization for others

For most developers, maintaining 1-2 instruction files is practical. More than that becomes overhead.

File Priority

Claude Code, for example, reads files in priority order:

1. .claude/CLAUDE.md (project-specific)
2. CLAUDE.md (project root)
3. ~/.claude/CLAUDE.md (global defaults)

This lets you have global conventions plus project-specific overrides.

Here is a battle-tested instruction file structure:

The Essential Sections

1. Project Overview

What is this project? Tech stack? Key dependencies?

2. File Structure

Where does code go? Naming conventions? Important directories?

3. Coding Conventions

Formatting, style, patterns. How do you write code here?

4. Do Not Rules

Critical. What should AI never do? This prevents common mistakes.

5. Testing Approach

How do you test? What frameworks? Coverage expectations?

Example CLAUDE.md

Here is a real-world example:

Project: E-commerce API

Tech Stack:

• Node.js 20 with TypeScript (strict mode)
• Fastify web framework
• Prisma ORM with PostgreSQL
• Vitest for testing
• Zod for validation

File Structure:

• "src/routes/" - Fastify route handlers
• "src/services/" - Business logic
• "src/repositories/" - Database access
• "src/schemas/" - Zod validation schemas
• "src/types/" - TypeScript type definitions
• "tests/" - Test files (mirror src structure)

Conventions:

• Use async/await, never callbacks
• All route handlers call services, never access DB directly
• Error handling via Fastify error handler plugin
• Use named exports, not default exports
• Prefer composition over inheritance

Do Not:

• Do not use "any" type ever
• Do not write raw SQL; use Prisma
• Do not put business logic in route handlers
• Do not modify existing tests without explicit approval
• Do not install new dependencies without asking

Testing:

• Every service function needs unit tests
• Use vi.mock() for external dependencies
• Name test files *.test.ts
• Run tests with npm test

Keeping It Concise

Instruction files should be scannable. Aim for 100-300 lines. If yours is growing longer, consider:

• Linking to detailed documentation instead of duplicating
• Removing obvious conventions the AI would infer
• Splitting into base file plus supplementary docs

Instruction files are living documents. They need updates when:

• You add new frameworks or tools
• Conventions change
• New "do not" rules emerge from AI mistakes
• File structure evolves
• Team standards update

Update Triggers

Add to your definition of done:

"Did this change affect patterns that AI should know about? Update instruction file if yes."

Common trigger events:

• Major dependency updates
• Architecture changes
• New file/folder patterns
• Discovered AI misbehaviors

Version Control Your Instruction Files

Always commit instruction files. They are code. Benefits:

• Team sees changes in PR
• History of why rules were added
• New team members get current version
• Rollback if a change causes problems

Getting AI to Help Write Instruction Files

Bootstrap your instruction file with AI:

"Based on this codebase, help me write a CLAUDE.md file. What patterns and conventions should we document? Look at: package.json, tsconfig.json, and a few representative source files."

Then review and refine. AI can suggest, but you know what actually matters.

• Instruction files are high leverage: Single biggest improvement for AI coding quality
• Use the right filename: CLAUDE.md, .cursorrules, copilot-instructions.md depending on tool
• Include essentials: Stack, structure, conventions, DO NOTs, testing
• Keep it concise: 100-300 lines; link to detailed docs
• Maintain actively: Update when patterns change; version control always

Create an instruction file for a real project:

1. Pick a project you are actively working on
2. Create the appropriate file (CLAUDE.md, .cursorrules, etc.)
3. Include at minimum:

- Tech stack (3-5 bullet points) - File structure (where does code go?) - 3 coding conventions - 3 "do not" rules

1. Use the instruction file for a coding session
2. Note: Did AI output improve? What rules need adjustment?

Start minimal. Add rules as you discover AI misbehaviors in your specific context.

• Claude Code instruction files: https://docs.anthropic.com/en/docs/claude-code/memory
• Cursor rules documentation: https://cursor.sh/docs/customization/rules
• GitHub Copilot instructions: https://docs.github.com/en/copilot/managing-copilot/configuring-and-auditing-content-exclusion