Instruction files directed at AI coding agents need continuous review, not endless expansion. Whenever the model makes a mistake, a new rule is added; whenever a tool changes, a workaround is added, while previous model guidance remains even after newer models appear. The result may be a file that combines a developer setup guide, a style guide, a troubleshooting log, and a collection of old prompt-writing techniques.
According to the article, this accumulation may make a coding agent less effective. Modern models are increasingly capable of exploring repositories, recognizing common frameworks, following existing patterns, and handling typical errors. However, they do not know a team’s specific decisions, hidden constraints, or accumulated operational experience. Therefore, the goal is not to make the instruction file as short as possible, but to retain the smallest set of high-signal information that actually changes the outcome.
Treat Context as a Limited Resource
The instruction file is added to the model’s available context in every applicable request, and its lines compete for the model’s attention with the developer’s task, relevant code, tool outputs, the conversation history, and other instructions. A larger context window does not mean that every additional token is cost-free.
The practical question is not: What can the model be told about the repository? It is: What does the model need to know that it cannot reliably discover, infer, or retrieve? The article recommends focusing on information that is specific, consequential, and difficult to infer.
What Should Remain in the File?
The most valuable information includes non-obvious facts about the system, such as ownership boundaries between repository components, whether an old directory is still used in production, or whether certain files are generated and must not be edited manually. It is useful to clarify that a particular interface owns the public HTTP contract, or that domain rules belong to a specific layer, rather than leaving the model to infer these boundaries from directory names.
The shortest reliable path for building and validation should also be documented, limited to commands that have been tested. The article’s examples include running dotnet restore App.slnx before the first build, then using dotnet build App.slnx --no-restore, running targeted tests when APIs change, or using the generated-files validation tool after modifying contracts. Special requirements should be stated clearly, such as integration tests requiring Docker and not being runnable in parallel, because an incorrect command repeated confidently is worse than no command at all.
It is also useful to record local choices that the code cannot consistently resolve: the testing framework in use, a preference for Minimal APIs over controllers, the Result<T> pattern for handling expected domain errors, or the use of TimeProvider instead of calling the system clock directly. These are not general programming rules but decisions specific to the codebase, which makes them appropriate for the instruction file.
Strict constraints should reserve words such as “always,” “never,” and “must” for rules that are truly absolute, such as preserving the public JSON contract, not placing customer data in logs, making database migrations compatible with the previous version, or prohibiting changes to production-environment files without an explicit deployment task. Sources of truth can also be referenced instead of copying their contents, such as interface design guidelines, runtime version files, deployment documentation, and architecture decisions.
What Can Be Deleted or Moved?
The article recommends deleting general advice such as writing clean code, following best practices, using meaningful names, and handling errors appropriately. These statements do not settle a practical decision, whereas a specific local rule is more useful—for example, mapping validation errors to a 400 response, missing resources to a 404 response, and concurrency conflicts to a 409 response using the existing ProblemDetails utilities.
Files generally do not need a comprehensive directory inventory, because the model can quickly read the repository structure. Nor is there a need to repeat formatting rules enforced by tools; it is enough to mention the appropriate validation command, such as dotnet format --verify-no-changes. Full copies of the README, architecture guides, and contribution guides should be avoided so that maintenance costs do not rise and contradictions between documents do not appear.
The article also warns against old “prompt myths,” such as asking the model to take a deep breath, act as a senior engineer, or read every file before making any change. These statements add no project knowledge and may lead to unnecessary exploration. It is better to describe the desired outcome, constraints, and required validation: make the smallest change that addresses the root cause, preserve public behavior, and run targeted tests.
Temporary workarounds should be deleted after the problem that prompted them is fixed. Otherwise, the agent will continue avoiding a path that is no longer broken. Instructions should also be written for a model family rather than a particular version; instructions that branch into model-specific paths become fragile as models and their behavior change.
Choosing the Scope of Instructions and Reviewing Them
Not every directive belongs in the general repository file. GitHub Copilot supports general instructions in .github/copilot-instructions.md, path-specific files under .github/instructions/, and agent instructions such as AGENTS.md. The general instruction file is used together with the matching path-specific file when both exist.
System architecture, shared commands, and general constraints should be placed in the general scope, while framework rules, testing patterns, and generated files specific to a particular area should be moved to a path-specific file. Detailed explanations, decision histories, and rare procedures are better kept in linked documentation. This prevents a rule for React component tests from consuming the model’s attention during a database migration task.
The article proposes reviewing each directive according to four outcomes: keep it if it is correct, consequential, and difficult to infer; delete it if the model knows it, a tool enforces it, or it has become ambiguous or outdated; move it if it is useful but belongs to another path or document; and verify it if it refers to a command, a temporary workaround, or a version that may have changed.
Review should take place when adopting a more capable model, changing the build system, reorganizing the repository, or noticing that agents are ignoring instructions or applying them incorrectly. The smaller file should then be tested on a specific task, actual failures should be tracked, the fewest instructions needed to prevent recurrence should be added, and the file should be tested again on another task.
Part of Project Maintenance
The article calls for instruction-file changes to be reviewed in regular pull requests, with reviewers asking whether a rule is reusable or addresses only one task, and for an owner to be assigned to operational commands and environment requirements. Temporary workarounds should also be deleted in the same pull request that addresses the cause of the problem, and commands should be rechecked after updates to SDK packages, frameworks, testing tools, or the build pipeline.
The quality of the file should not be measured by its number of lines. A 30-line file containing incorrect commands may be worse than a 100-line file that describes the boundaries of a multi-project repository and information that the model cannot infer. The better criterion is whether the file enables a capable model to start work quickly by providing it with what only the team knows: what the system is, the important boundaries, local choices, how to build and verify, what must not be broken, and where to find the deeper details.