Instructions Files — AI Coding Assistants

Every software project has local knowledge: how tests are run, which patterns are trusted, what not to touch, and why old-looking code may still be right. Humans absorb this knowledge from teammates, reviews, and hard-won mistakes. An instructions file is a deliberate place to write it down for an artificial intelligence assistant, so the assistant starts each task with the habits and constraints of the project rather than guessing from the nearest code sample.

What an instructions file is

An instructions file is a plain text file, usually stored with a project, that tells an artificial intelligence assistant how to behave when working in that project. It is not the task itself. The task might be fix this bug or add this endpoint. The instructions file is the standing guidance that should apply across many tasks.

Think of it as a small handbook for a new teammate who is competent but unfamiliar with your codebase. It can explain the architecture, coding style, testing expectations, safety boundaries, naming conventions, and review norms. The best instructions files are short enough to be read often and specific enough to change behavior.

The file name and location vary by tool. Some assistants look for a conventional file in the repository root. Others allow nested files for different folders. The important idea is independent of any vendor: persistent project guidance belongs close to the work it describes.

Why they exist

A large language model is a system trained to predict useful text from patterns in data. It can reason from examples, but it does not automatically know which examples in your repository are current, which are legacy, and which were mistakes. Without guidance, it may copy the loudest pattern rather than the intended one.

Instructions files reduce that guessing. They give the assistant stable context before it reads the immediate task. This matters because many engineering choices are not obvious from code alone. A project may use one dependency injection pattern for historical reasons, avoid a popular library for licensing reasons, or require a particular migration sequence because production systems depend on it.

They also reduce repeated explanation. Instead of telling every assistant session to use the same test command, avoid the same generated folder, or prefer the same naming scheme, the team writes those expectations once and keeps them near the code.

📌

Context is not memory. An instructions file gives the assistant reusable context, but it does not prove the assistant understood or followed it.

What belongs in one

Good instructions focus on decisions the assistant is likely to face. They do not repeat everything in the documentation. They highlight the small set of rules that prevent bad edits, wasted time, or confusing pull requests.

The most useful entries are concrete. Prefer run tests with the command npm test -- --runInBand to make sure tests pass. That is better than be careful with tests. Prefer do not edit generated files under src/generated because they are overwritten by the schema compiler. That is better than avoid generated files.

Project purpose: what the system does and who it serves.
Architecture map: the main modules, boundaries, and ownership of responsibilities.
Coding conventions: naming, formatting, error handling, logging, and dependency rules.
Verification steps: test, lint, build, and local run commands that actually work.
Safety boundaries: secrets, generated code, migrations, production data, and risky scripts.
Review expectations: how to summarize changes, mention trade-offs, and flag uncertainty.

✅

Write for action. A strong instruction tells the assistant what to do, when to do it, and what evidence should confirm it worked.

Concrete instructions name exact commands and boundaries the assistant can act on.

How an assistant uses instructions

When an assistant starts work, it usually builds a working context. That context may include the user request, relevant files, tool outputs, previous conversation, and one or more instructions files. The model then generates a plan or an edit based on all of that material.

Instructions compete for attention with everything else in context. If the file is long, vague, contradictory, or full of obsolete details, the assistant may miss the important parts. If the guidance is concise and task-shaped, it is more likely to influence the result.

This is why instructions files should not be treated as magic policy engines. They are strong hints placed in the assistant's field of view. They are most effective when paired with tests, code review, automated checks, and clear ownership.

An assistant blends the request, files, tool outputs, and instructions into one context.

Writing durable instructions

Durable instructions are specific without being brittle. They name current commands, important boundaries, and project preferences, but they avoid restating implementation details that change every week. The goal is to guide many tasks, not to describe the entire system.

Use direct language. Say use the repository's existing Result type for recoverable domain errors. Do not say try to be idiomatic. The first sentence points to a local decision. The second sentence asks the assistant to infer what idiomatic means.

Prefer rules that can be checked. If an instruction says every database change must include a migration and a rollback note, reviewers and automated checks can look for that. If it says write high-quality code, no one can verify compliance in a consistent way.

Scope, precedence, and conflicts

Many teams need more than one level of guidance. A repository-level file may describe the whole system. A folder-level file may describe a mobile application, a service, or a package inside a larger codebase. A personal or workspace setting may add individual preferences.

Scope is the area to which an instruction applies. Precedence is the rule for what happens when two instructions disagree. Different tools handle these details differently, so teams should not rely on assumptions. They should document the intended hierarchy in the instructions themselves and keep the most important safety rules at the broadest level.

Conflicts are especially risky because the assistant may resolve them silently. For example, one file may say never edit generated files while another says update all files under a directory. A human would ask for clarification. An assistant may choose one. The safest approach is to remove conflicts rather than hope the model chooses correctly.

⚠️

Avoid hidden contradictions. If two instructions disagree, rewrite them until a new teammate could follow both without asking you.

Guidance flows from a broad repository file down to personal workspace settings.

The decisions leaders and practitioners face

Instructions files look small, but they raise real operating decisions. A team must decide who owns the file, who can change it, how changes are reviewed, and which instructions are mandatory rather than advisory. Those choices affect speed, safety, and accountability.

A practitioner usually cares about usefulness at the point of work. The file should answer the questions that come up while editing: which tests to run, which patterns to follow, and where the sharp edges are. A leader usually cares about consistency across teams: whether assistants are being guided toward secure practices, maintainable code, and predictable review behavior.

The practical compromise is to treat instructions files like lightweight engineering assets. They do not need a committee for every wording change, but they should be versioned, reviewed when they affect risk, and updated when they fail to prevent repeated mistakes.

Ownership: name the role or team responsible for keeping instructions current.
Review: require review for changes that affect security, data handling, release steps, or architecture.
Adoption: start with one high-value project before standardizing across an organization.
Measurement: look for fewer repeated review comments, fewer broken local workflows, and clearer assistant summaries.
Risk: never use instructions files as the only control for secrets, compliance, or production safety.

⚠️

Not a control plane. Instructions files can guide behavior, but they do not replace access control, automated policy checks, or human review.

Keeping instructions alive

An instructions file decays when the project changes and the guidance does not. Old commands, retired services, renamed directories, and abandoned conventions all teach the assistant the wrong lesson. Stale instructions can be worse than none because they sound authoritative.

Maintenance works best as a small loop. When a reviewer repeats the same correction, add or improve an instruction. When an instruction is ignored, make it shorter, clearer, or more checkable. When a command changes, update the file in the same pull request. When a section becomes background reading rather than active guidance, move it to documentation.

The file should earn its place in the repository. If it helps the assistant make better first attempts and helps humans explain fewer basics, it is doing its job.

Key takeaways

An instructions file is standing project guidance for an artificial intelligence assistant, not a replacement for the current task.
The best instructions are concrete, local, and checkable: they tell the assistant what to do and how to verify it.
Instructions files reduce repeated explanation, but they do not guarantee obedience or replace tests, reviews, and access controls.
Scope and precedence matter because broad, folder-level, and personal guidance can conflict.
Treat instructions files as maintained engineering assets that change when the project or its risks change.

When a correction repeats, add a rule, watch how it lands, and refine it.

Glossary

Instructions file: A plain text project file that gives an artificial intelligence assistant reusable guidance for working in that project.
Artificial intelligence assistant: Software that uses artificial intelligence to answer questions, write text, inspect code, or help perform tasks.
Large language model: A model trained on large amounts of text and other data to generate useful language-based responses.
Context: The information available to an assistant while it produces an answer or edit.
Repository: A versioned storage location for a project's files, history, and changes.
Scope: The part of a project or workspace to which an instruction is meant to apply.
Precedence: The ordering rule that decides which instruction wins when two instructions overlap or disagree.
Generated files: Files created by a tool from another source, usually meant to be regenerated rather than edited by hand.