Instructions Hygiene – What Frontier Models Still Need You to Say

What happened

The given summary is only a teaser. I’ll pull the original .NET Blog post so the paragraphs use real names and details instead of invented figures.I have the post URL. Next I’ll read the full article so the write-up stays on verified details.The .NET Blog published Instructions Hygiene – What Frontier Models Still Need You to Say, written by Wendy Breiding, Senior Manager of Product Management. The post’s claim is narrow: teams get more out of the latest models by giving them the right level of instructions, not a longer file. Instructions files, she writes, grow in only one direction. A model makes a mistake, so someone adds a rule. A tool changes, so someone adds a workaround. A new model arrives, and the old guidance stays. Before long the repository file reads like an onboarding guide, a style manual, a troubleshooting diary, and a prompt-engineering time capsule at once. That accumulation can make an AI coding agent less effective even though it feels safer than leaving something out. Modern frontier models need less procedural coaching than earlier ones. They explore repositories, recognize common frameworks, follow established patterns, and recover from ordinary errors. They still cannot know the private decisions, hidden constraints, and operational knowledge that live in a team’s heads. Hygiene is not a race to the shortest file. It is keeping the smallest set of high-signal information that reliably changes the outcome.

An instructions file is part of the context the model sees on every applicable request, so every line competes with the developer’s task, the relevant code, tool output, conversation history, and other instructions. A larger context window does not make every extra token free. Breiding cites Anthropic’s framing of effective context engineering as finding the smallest set of high-signal tokens that maximizes the likelihood of the desired result, and GitHub’s guidance that a concise project overview, technology stack, coding guidelines, project structure, and pointers to important resources is enough. The useful question is not what you could tell the model about the repository. It is what the model needs that it cannot reliably discover, infer, or retrieve for itself. Frontier models still need five classes of that local knowledge: non-obvious facts about the system, the shortest reliable path to validation, choices the codebase cannot settle consistently, hard constraints that prevent expensive mistakes, and pointers to where the source of truth lives. Models can inspect a folder tree. They cannot reliably infer which boundary is intentional, which old-looking component is still critical, or which source file is generated unless the repository says so.

The technical detail

The examples are concrete .NET ones. Billing.Api owns the public HTTP contract; Billing.Worker must not expose endpoints. Domain rules belong in src/Core, not in controllers or persistence models. The legacy directory is still used in production and is not reference-only code. Generated clients in src/Clients/Generated must be updated through the generator, never edited by hand. Authoritative commands matter more than prose: restore App.slnx before the first build, build with --no-restore, run the targeted API test project for API changes, run verify-generated.ps1 after contract changes, and do not run Docker-backed integration tests in parallel. Keep only commands you have validated. An incorrect command repeated with confidence is worse than no command at all. Local decisions such as MSTest for new tests, Minimal APIs rather than controllers, Result of T for expected domain failures, a shared TimeProvider instead of DateTime.UtcNow, and existing repository abstractions over a new dependency are the instructions that change an implementation. Absolute language such as always, never, and must is reserved for rules that are genuinely absolute: preserve the public JSON contract unless a breaking change is explicit, never place customer data in logs, keep database migrations backward-compatible with the previous application version, and do not modify files under infra/production without an explicit deployment task.

Why it matters for builders

For engineers wiring agents into a real repo, the post is a subtraction guide as much as a writing guide. Generic advice to write clean maintainable code, follow best practices, use meaningful variable names, handle errors appropriately, consider performance and security, and write high-quality tests does not resolve a decision a frontier model cannot already make. Instead of handle errors appropriately, say map validation failures to 400, missing resources to 404, and concurrency conflicts to 409 using the existing ProblemDetails helpers. Exhaustive directory listings go stale and duplicate what the model can retrieve in seconds. Formatting rules the formatter already applies, and compiler or linter settings the tools already enforce, should collapse to a single command such as dotnet format --verify-no-changes. Copying the README, architecture guide, and contribution guide into the instructions file raises maintenance cost and contradiction risk. Prompt folklore such as take a deep breath, think step by step, act as a world-class senior engineer, be extremely meticulous, read every file before making a change, or never stop until the solution is perfect is not project knowledge. Capable reasoning models do not need theatrical encouragement, and rigid procedural directions can cause unnecessary exploration or conflict with the tools available in a given environment. Describe the outcome, the constraints, and the validation instead. A workaround belongs in the file only while it is still necessary. Once the script, dependency, or platform issue is fixed, remove the warning or agents keep routing around problems that no longer exist.

The market context is the GitHub Copilot instruction surface Microsoft is teaching .NET teams to use: repository-wide instructions in .github/copilot-instructions.md, path-specific files under .github/instructions/, and agent instructions such as AGENTS.md. When repository-wide and matching path-specific instructions are both present, both are used. That is Microsoft aligning Copilot’s product mechanics with the same progressive-disclosure idea Anthropic published for agents and that OpenAI documents in the GPT-5 prompting guide listed in the post’s further reading. The competitive implication is that the differentiator is no longer a longer system prompt or a model-specific ritual. Model upgrades are a reason to review instructions, but files should not become branches that say inspect three files first if using Model A, ask for confirmation if using Model B, or reason step by step if using Model C. Model availability and behavior change faster than repository architecture. Prefer model-independent statements about the work: the outcome required, the local constraints, the authoritative commands, the evidence needed before completion, and the places where human approval is required. When a newer model succeeds without an old piece of scaffolding, remove the scaffolding. When it fails because it lacks repository knowledge, document that knowledge rather than prescribing a model-specific ritual.

Market and competitive context

The review method is keep, remove, move, verify, and it should run whenever a team adopts a materially more capable model, changes the build system, reorganizes the repository, or notices agents repeatedly ignoring or misapplying guidance. Keep an instruction when it is still true, consequential, and hard to infer. Remove it when the model already handles it, a tool enforces it, it is vague, or it is obsolete. Move it when it is useful but belongs in a path-specific file or a linked document. Verify any command, workaround, version, or dependency that may have changed. Then test the smaller file on representative work: ask the current frontier model to complete a common, bounded task, observe actual failure modes rather than imagined ones, add the minimum instruction needed to prevent a repeated failure, and test again on a different task. That reverses the usual anti-pattern of carrying every old instruction forward until someone proves it is unnecessary. A React component-test rule should not consume attention during a database migration; it belongs in a path-specific file for the front-end test directories. Include instruction changes in ordinary pull request review. Ask whether a new rule is broadly reusable or only fixes one task. Assign an owner for operational commands and environment requirements. Delete temporary workarounds in the same pull request that fixes the underlying issue. Recheck commands after SDK, framework, test runner, or build pipeline upgrades.

What to watch next

The post is explicit that compactness is not an arbitrary target. A 30-line file with incorrect commands is worse than a 100-line file that documents necessary monorepo boundaries. Do not measure quality by line count alone. The compact example aims at a Contoso Orders API plus fulfillment worker: public contracts owned by src/Orders.Api, business rules in src/Orders.Core, target the .NET version specified in global.json, use Minimal APIs and the existing Result of T pattern, use TimeProvider, do not edit files under src/Generated, run generate.ps1, build Orders.slnx, run the unit and API test projects, run verify-generated.ps1 on contract changes, preserve public JSON contracts, never log secrets, tokens, or customer payloads, and keep migrations compatible with the previous deployed version. What is missing on purpose is a complete file tree, generic coding advice, a long persona, and detailed instructions for how the model should think. The open question for teams is whether they will treat the instructions file as engineering maintenance or as a scrapbook. Periodically asking a frontier model to identify duplicated, vague, conflicting, or discoverable instructions is useful only if a human then verifies the suggestions. As models improve, Breiding says the best files will not disappear. They will become more focused on the facts only the team can provide: what the system is, where the important boundaries are, which local choices are intentional, how to build and validate reliably, what must never be broken, and where deeper truth can be retrieved.