Write repository instructions that prevent repeated AI coding mistakes

An assistant repeatedly imports a second database client, edits generated files, and returns private fields from public endpoints. Reviewers correct the same mistakes in every pull request. Adding “write high-quality code” to repository instructions does little because it does not describe the project's actual constraints.

Useful instructions capture recurring, consequential decisions that an assistant cannot reliably infer. They should be specific enough to change behavior and short enough to remain discoverable. Consider an illustrative application with one approved database helper, a generated API client, and separate public and administrative serializers.

Start from repeated evidence

Collect a few real review findings and describe their causes. “Used a new database connection instead of the shared helper” is actionable. “The assistant was careless” is not. Identify which errors recur, which carry meaningful risk, and which could instead be prevented by tooling.

A lint rule can forbid an import more reliably than a paragraph can. A generated-file header and CI check can prevent manual edits. Instructions still help explain the reason and direct the assistant toward the correct alternative. Prefer enforceable rules where available and use prose for judgment that tooling cannot express.

Do not turn every reviewer preference into a permanent mandate. An unusual one-off decision may belong in the task brief. Repository instructions should represent stable practices or high-value cautions, otherwise they grow into a contradictory history of individual comments.

Scope each instruction to the right work

A public API serialization rule should apply to public API changes. A migration rule should apply to migrations. Global instructions that mix all domains can obscure the relevant guidance and create unintended constraints on unrelated tasks.

Describe scope in ordinary terms and use the instruction mechanism supported by the chosen assistant. Tool-specific discovery and precedence can differ, so verify the current official documentation before relying on a filename or path rule. Do not assume that every assistant reads the same configuration files.

Where scoped guidance is unavailable, keep the global document compact and link to clearly named task-specific notes. An assistant working on CSS should not need to digest a long operational migration procedure before choosing a spacing token. Relevance improves compliance more than repetition.

Write rules with a reason and an alternative

A useful rule has three parts: the required behavior, the reason, and the approved path. “Use the shared database helper for server queries so connection reuse and tracing remain consistent; do not instantiate a new client in route handlers” provides direction that a bare prohibition lacks.

For generated code, say how to regenerate it and which source owns the output. For public responses, identify the serializer and explain that storage records contain fields the browser must not receive. Include one concise example when it removes ambiguity.

Avoid vague adjectives such as secure, robust, and idiomatic without a concrete property. “Return the public serializer's fields” can be reviewed. “Make responses secure” leaves the assistant to invent a policy. Rules should reduce decisions that were already made, while leaving legitimate implementation choices open.

Distinguish commands from guarantees

List the commands that provide relevant evidence, but state their boundaries. A unit test command may not run database integration tests. A type check may not verify authorization. An instruction to “run tests” is insufficient if the repository has several suites with different requirements.

Give the assistant a way to report unavailable checks honestly. For example, if integration tests need an isolated database, the final report should identify that requirement and which tests were skipped. It should not declare completion merely because the general test command succeeded.

Keep commands current. A stale script name creates wasted time and can encourage the assistant to invent a replacement. When scripts change, update their instruction references in the same change. The guide on evidence checklists explains how to separate performed checks from proposed ones.

Use AI to draft from reviewed patterns

Provide sanitized review findings and the existing conventions. Ask an assistant to draft a concise rule for each repeated problem, then remove overlap. This is a useful summarization task because the source evidence is bounded and the output can be inspected quickly.

An illustrative request is: “Convert these three review findings into repository guidance. For each rule, name the scope, required behavior, and verification. Do not add policies unsupported by the findings. Keep temporary migration details out of global guidance.” The instruction prevents the draft from becoming an expansive generic style guide.

Review every proposed requirement with the maintainers who own the affected area. The assistant may turn a suggested improvement into a hard rule or assume a helper is universally applicable. Instructions are project policy, so their authority should come from actual engineering decisions.

Test the instructions with representative tasks

Use a small, reversible task that previously triggered the error. Ask the assistant to add a public endpoint or adjust a generated client's source, then inspect its plan and diff. Did it select the shared helper? Did it identify the generated boundary? Did it apply the public serializer?

Do not judge only by whether the assistant repeats the rule in its explanation. Compliance appears in the code and verification. An assistant can say it preserved authorization while accidentally removing a predicate. The instructions improve odds; normal review remains necessary.

Compare failures before and after instruction changes where evidence is available, without inventing success rates. If the rule remains ineffective, inspect discoverability, ambiguity, and competing examples. A stronger sentence may help, but a tooling guard or architectural interface change may solve the problem more reliably.

Maintain a small living document

Give the instructions an owner and review them when conventions change. Remove rules that no longer apply, resolve contradictions, and keep links pointed at current source files. Long-lived stale guidance is worse than an explicit gap because it directs confident work toward an obsolete pattern.

Separate durable constraints from incident details. A past outage may justify a rule about bounded queries, but the global instruction need not contain the entire incident narrative. Link the background when useful and keep the operational requirement concise.

The best repository instructions make correct work easier to start and repeated mistakes easier to detect. They are not a replacement for tests, types, or review. Their value comes from encoding specific project knowledge at the point where an assistant needs it.

Sources

GitHub Copilot best practices discusses relevant context and verification.

GitHub: Adding repository custom instructions documents tool-specific instruction configuration.