Write Project Instructions Files That AI Coding Agents Actually Follow

A practical approach

Step 1

Start with commands: how to install, run, test, lint and type-check the project, exactly as typed.

Step 2

State versions and non-obvious technology choices, especially where they differ from common defaults the agent might assume.

Step 3

List rules that must not be broken, such as generated files to leave alone, secrets handling and required review steps.

Step 4

Point to example files that show preferred patterns instead of describing patterns in the abstract.

Step 5

Keep the file short and current; review it when the agent repeats a mistake and add the specific rule that would have prevented it.

Worked example

An agent repeatedly edits files in a generated client directory, and its changes are overwritten on the next generation. Adding one line, 'Do not edit src/generated; change the OpenAPI spec and run npm run generate', stops the problem. A second line naming the test command means the agent now runs the right tests before reporting a task as done.

A mistake to avoid

Do not put secrets, internal URLs that should stay private or personal data in instruction files. They are committed to the repository and sent to the tool as context.

Try it yourself

Write an instructions file for one of your projects with four sections: commands, technology versions, rules and example files. Ask an agent to complete a small task and note whether it follows each rule.

Your implementation checklist

• Exact commands for running and testing are listed
• Unusual versions and choices are stated
• Hard rules are explicit and specific
• Example files illustrate preferred patterns
• The file is short, current and free of secrets