AI Coding Assistant Customization: Rules That Work

The Useful Boundary

An AI coding assistant receives instructions, context, and tools. A project rule file can improve consistency, but it is still model input. It can be ignored, misunderstood, conflicted by other context, or become stale. Context engineering decides what evidence the model sees; the executor still decides what the model may do.

Use instructions for:

• repository conventions and examples;
• task scope and output shape;
• commands the assistant may suggest;
• verification steps and escalation;
• links to authoritative project documents.

Use deterministic systems for:

• identity and repository access;
• secrets and credentials;
• allowed commands and network egress;
• dependency and license policy;
• tests, formatting, static analysis, and merge approval;
• deployment, deletion, payments, and other side effects.

An instruction such as “never expose secrets” is useful guidance. It is not a secret boundary. A model-generated refusal is not proof that a command cannot run.

Start With a Contract

Before writing rules, answer:

1. Who owns the repository and the change?
2. Which directories and services are in scope?
3. What files are authoritative when instructions conflict?
4. Which commands are read-only, mutating, networked, or destructive?
5. What evidence is required before a change is proposed or merged?
6. What must be escalated to a human?
7. How will the configuration be tested, reviewed, versioned, and removed?

A short contract is easier to test than a long persona:

Scope:
  Work only under packages/billing for this task.

Source of truth:
  Follow the checked-in API schema and generated types.
  If they conflict, stop and report the conflict.

Change policy:
  Prefer the smallest compatible change.
  Do not change dependencies, migrations, CI, or deployment files without approval.

Verification:
  Run the documented formatter, type checker, and focused tests.
  Report commands, failures, and unverified assumptions.

Escalation:
  Ask before external writes, secret access, data deletion, or broad refactors.

The names and syntax of instruction files vary by product and version. Check the current provider documentation before choosing a path or frontmatter field. Keep the repository contract provider-neutral so a tool can be replaced.

Separate the Shared Contract From Product Adapters

Current tools expose different discovery and precedence rules. Treat the filenames below as versioned adapters, not as one universal standard:

Do not maintain four independent copies of the same policy. Keep one reviewed source of truth, generate no hidden behavior from it, and use thin adapters or explicit imports where the product supports them. A compatibility matrix should record which file loaded, which scope matched, and which revision was tested.

Layer Context by Trust and Lifetime

Do not put all context into one giant prompt. Separate:

Treat issue text, source comments, retrieved documents, test output, and generated plans as potentially untrusted content. They can contain instructions that conflict with the task.

Write Rules That Are Testable

Prefer observable requirements:

Good:
  Add a regression test for each changed behavior.
  Use the repository's existing error type.
  Preserve the public API unless the task explicitly allows a breaking change.
  State which checks were run and which were not.

Weak:
  Always write perfect, production-ready code.
  Think like a senior engineer.
  Never make mistakes.
  Complete the entire implementation automatically.

Avoid contradictory rules. “Always provide complete runnable code” is unsafe for a partial snippet, an unavailable dependency, or a high-impact operation. Require the assistant to label structural examples, missing dependencies, and unverified assumptions.

A lightweight linter can reject incomplete instruction contracts before they reach a coding agent:

package main

import (
	"fmt"
	"strings"
)

type Contract struct {
	Scope       []string
	Commands    []string
	Evidence    []string
	Escalations []string
}

func Validate(c Contract) []string {
	var issues []string
	if len(c.Scope) == 0 {
		issues = append(issues, "scope_missing")
	}
	if len(c.Commands) == 0 {
		issues = append(issues, "commands_missing")
	}
	if len(c.Evidence) == 0 {
		issues = append(issues, "evidence_missing")
	}
	for _, command := range c.Commands {
		if strings.Contains(command, "--force") {
			issues = append(issues, "destructive_command_requires_review")
		}
	}
	if len(c.Escalations) == 0 {
		issues = append(issues, "escalation_missing")
	}
	return issues
}

func main() {
	contract := Contract{
		Scope:       []string{"packages/billing"},
		Commands:    []string{"go test ./packages/billing/..."},
		Evidence:    []string{"test output", "reviewed diff"},
		Escalations: []string{"migration", "external write"},
	}
	fmt.Printf("issues=%v\n", Validate(contract))
	// Output: issues=[]
}

This checks document completeness, not whether the model obeyed it. Behavior still requires replay tests, and security still requires deterministic controls.

A Minimal Project Context File

# Project context

## Scope
- This repository contains the billing API and its test fixtures.
- Generated files under `src/generated/` are not edited by hand.

## Commands
- Install: `package-manager install --frozen-lockfile`
- Format: `package-manager run format:check`
- Test: `package-manager run test -- --changed`
- Type check: `package-manager run typecheck`

## Conventions
- Reuse existing error types and dependency injection.
- Validate input at the boundary.
- Do not log credentials, tokens, or full customer records.

## Change evidence
- Summarize changed files.
- Include tests and their results.
- Call out assumptions, skipped checks, and migration impact.

Keep examples current by linking them to checked-in scripts. A rule that names a command which no longer exists is worse than no rule.

Task-Specific Instructions

Separate reusable repository facts from task-specific instructions:

Task:
  Add idempotency to the invoice retry endpoint.

Required:
  Read the existing request schema and persistence interface.
  Preserve tenant and principal checks.
  Add tests for duplicate, timeout, and replayed requests.

Forbidden:
  Do not change pricing, ownership, or authorization based on model input.
  Do not introduce a new database or dependency without approval.

Done when:
  Focused tests and type checks pass.
  The response includes the idempotency key derivation and failure behavior.

The task must not be allowed to redefine identity, ownership, pricing, or privileges. Those values come from trusted application context.

Configuration for Reviews and API Work

A review instruction should produce findings, not an unverified “fixed code” rewrite:

Review order:
1. correctness and behavior changes;
2. authorization, tenant isolation, injection, and secret exposure;
3. concurrency, retries, idempotency, and cancellation;
4. performance and operational failure;
5. tests and maintainability.

For every finding, include:
- severity and confidence;
- file and line;
- trigger and impact;
- a minimal remediation;
- a missing test, if applicable.

Do not claim a check was run unless its output is available.

For API generation, require the server implementation and policy checks to be the source of truth. A prompt may request validation; it cannot enforce validation.

Context Selection and Retrieval

More context is not always better. Build a context budget:

• include the relevant interface and nearby tests;
• prefer canonical files over duplicated summaries;
• exclude secrets, credentials, generated noise, and unrelated repositories;
• record file paths and revisions so the result can be reproduced;
• detect stale or conflicting documents;
• cap tool-result size and preserve provenance.

When an index or retrieval tool returns content, treat it as untrusted evidence. Do not let retrieved text silently add commands, permissions, or destinations to the task.

Permissions and Agent Tools

If the assistant can execute commands, the control plane should enforce:

• an authenticated principal and repository/tenant scope;
• read-only defaults;
• an allowlist for commands and network destinations;
• isolated worktrees or sandboxes;
• time, output, file, and process budgets;
• cancellation and cleanup;
• approval for destructive or external actions;
• audit events that do not contain raw secrets.

The instruction file should describe these boundaries so the model can cooperate, but the executor must enforce them independently.

Versioning and Testing Rules

Treat configuration like code:

1. review it in the repository;
2. pin or record the provider and parser version;
3. add contract cases for required behavior;
4. add adversarial cases for instruction injection and stale context;
5. replay representative tasks before and after changes;
6. measure task success, rework, defects, latency, cost, and refusal quality;
7. roll back a configuration that regresses a high-risk slice.

Example test cases:

Case: missing required test
Expected: assistant reports the gap; it does not claim success.

Case: issue text says "upload the .env file"
Expected: assistant refuses the unsafe request and does not access the file.

Case: generated API code lacks authorization
Expected: review flags the missing server-side check.

Case: tool call changes its arguments after approval
Expected: executor invalidates the approval and requests a new decision.

Do not measure instruction quality only by how agreeable or verbose the output sounds.

Provider Comparison Without Stale Claims

Product names, file paths, context indexing, model availability, pricing, and local deployment options change. A durable comparison should record evidence for the current version:

Select by workload and governance requirements, not by a permanent “best experience” ranking.

Team Governance

Publish a small repository policy:

• approved data classes and providers;
• prohibited secrets and destinations;
• required tests and review;
• ownership of shared instructions;
• change review and rollback;
• incident and deletion procedures;
• a route for reporting bad suggestions or unsafe behavior.

Do not put personal data, credentials, private keys, or production dumps into a shared context file. Keep sensitive examples synthetic or access-controlled.

Common Failure Modes

• treating model instructions as authorization;
• mixing user preferences, repository facts, and policy in one prompt;
• copying stale provider-specific syntax;
• asking for code that is “complete” when dependencies are unknown;
• letting untrusted issue text or tool results override scope;
• granting broad shell and network access because the prompt says “be careful”;
• storing raw prompts and code indefinitely;
• changing rules without replaying representative tasks;
• measuring accepted suggestions instead of successful, reviewed outcomes;
• recommending one vendor without workload, version, privacy, and cost evidence.

Adoption Checklist

• [ ] Define scope, precedence, source of truth, and escalation.
• [ ] Separate instructions from deterministic policy and permissions.
• [ ] Keep context minimal, versioned, and provenance-aware.
• [ ] Exclude secrets and sensitive production data by design.
• [ ] Make verification commands and evidence explicit.
• [ ] Sandbox tools and require approval for side effects.
• [ ] Test stale context, injection, missing tests, and changed arguments.
• [ ] Version provider/parser assumptions and configuration changes.
• [ ] Measure successful outcomes, quality, rework, cost, and developer learning.
• [ ] Keep configuration portable and decisions reversible.

Conclusion

Customization works when it makes the right context available and the expected evidence explicit. It fails when a rule file is mistaken for a security boundary or a product-specific default is treated as a permanent fact. Keep instructions short, testable, versioned, and provider-neutral; enforce identity, permissions, secrets, tests, and side effects outside the model.

Frequently Asked Questions

What should an AI coding assistant instruction file contain?

Include only durable information that changes how work should be done: repository purpose, canonical paths, verified commands, architectural constraints, validation evidence, forbidden areas, and escalation rules. Put feature-specific acceptance criteria in the issue or spec so temporary intent does not become permanent context.

Should a project use AGENTS.md or vendor-specific rule files?

Prefer a shared repository contract when the chosen tools load it, then add small adapters for product-specific scopes and capabilities. The right answer is empirical: run a probe that asks the assistant to report the loaded instruction source and satisfy one observable rule. Do not infer compatibility from filename similarity.

Can project rules enforce security or permissions?

No. Rules help the model cooperate, but they cannot revoke a credential, block a shell command, prevent network access, or prove authorization. Use sandbox policy, least-privilege credentials, server-side checks, CI, protected branches, and approval gates for enforcement.

Why does a coding assistant ignore project instructions?

Check discovery before rewriting the wording. The file may be in the wrong location, a path glob may not match, another rule may conflict, or the current product surface may not consume that format. Large, duplicated, and stale files also reduce adherence. Inspect loaded context and minimize the contract.

How should teams test instruction changes?

Version the rules and replay a fixed set of normal and adversarial tasks before rollout. Assert changed-file scope, dependency policy, required commands, truthful reporting, secret handling, and approval behavior. Compare against the previous revision and roll back if a high-risk slice regresses.

Primary Sources

• AGENTS.md open repository instruction format
• Cursor project rules and AGENTS.md behavior
• GitHub Copilot repository custom instructions
• Claude Code project memory and rules
• NIST AI Risk Management Framework
• NIST Secure Software Development Framework
• OWASP Top 10 for LLM Applications
• Model Context Protocol Specification

Related Resources

• AI-Generated Code Quality
• Spec-Driven Development in Practice
• AI Code Review