AI Coding Assistant Rule Files: How to Write and Tune Project Context Files

1. Problem Background: Models Need Project Facts, Not More General Knowledge

Most frustration with AI coding assistants does not come from the model’s general capability. It comes from missing project context. The assistant may not know what build system the repository uses, which dependencies the team prohibits, or which validation commands must be run before committing code. As a result, developers often have to repeat the same explanations in every conversation, the generated code may conflict with existing repository conventions, and the assistant may even call APIs that do not exist.

The engineering solution is to turn “the things that must be said every time” into a versioned, repository-scoped project rule file. In this article, AI_CONTEXT.md is used as a placeholder file name. The value of such a file is that it captures high-frequency constraints once and frees the assistant’s attention for tasks that actually require reasoning.

It is important to emphasize that this kind of rule file has no execution semantics. It does not run scripts, start services, invoke functions, or automatically change tool permissions. Its only purpose is to extend the context and change how the assistant handles subsequent requests.

2. How Rule Files Fit into an Agent Context

To write effective rule files, you need to understand how the context of a usable AI agent is organized. It can usually be divided into four layers, with decreasing priority and stability:

1. System instruction layer: platform-provided general behavior rules that developers cannot modify.
2. Project rule layer: the AI_CONTEXT.md discussed in this article, describing facts and constraints that are always true for the repository.
3. Task skill layer: domain-specific workflows injected dynamically when needed, such as “pre-release checks” or “database schema migration.” These are expanded only when the description matches the task.
4. Session layer: the current conversation history and retrieved code snippets. This layer changes the fastest.

The key mechanism is that the third layer is declarative. There is no algorithmic selector or separate intent recognition model. The assistant relies entirely on the wording in rule files and skill descriptions to decide whether to expand a workflow. In other words, the accuracy of the description directly determines whether the loading behavior is correct.

This leads to a counterintuitive but important design principle: a rule file should be as short as possible and should contain only content that is always true. Every constraint placed in the rule file consumes context budget in every turn of the conversation. Putting occasionally used workflows into the rule file increases both cost and the probability of false triggering.

3. Six Essential Modules of a Rule File

A high-quality rule file should feel like an onboarding cheat sheet for a new teammate, not a product marketing page. It can be organized into the following six modules.

1. Project positioning and technology stack facts

Describe what kind of system this is, the main language and framework, the package manager, and the target runtime. This helps the assistant align technical assumptions quickly and avoids proposing cross-language solutions.

2. Directory structure and responsibility boundaries

Clarify what each directory contains, which directories should not be modified, and where generated code should live. This module is especially important for reducing ineffective edits.

3. Coding conventions and naming rules

Only include conventions that cannot be automatically guaranteed by the toolchain. If formatters and static checkers already cover something, leave it to the tools and do not repeat it in documentation.

4. Command list

Write down build, test, validation, and local execution commands that can be copied and executed directly. This is usually the highest-return part of the rule file.

5. Prohibited actions and high-risk areas

Define red lines clearly, and provide an alternative for every prohibition. If the rule file only says “do not do this” without offering a viable path, the model may find another way around the restriction and repeat the same mistake elsewhere.

6. Change and delivery conventions

Specify commit message format, whether documentation must be updated at the same time, and whether configuration or dependency versions may be changed.

Here is an illustrative example. The content below is a generic sample.

# Project Context Rules
## Tech Stack
- Primary language: Go; package management uses the official module system.
- Service framework: internal in-house HTTP framework; use of other frameworks is prohibited.
- Configuration files use YAML uniformly; hard-coding environment addresses in code is prohibited.
## Directory Responsibilities
- `cmd/`: executable entry points; each binary has its own subdirectory.
- `internal/`: business implementation; must not be imported by external modules.
- `pkg/`: reusable libraries for external use; interface changes must remain backward compatible.
- Automatically generated code lives in `internal/gen/`; manual editing is prohibited.
## Common Commands
- Build: make build
- Unit tests: make test
- Full static check: make lint
- Test a single package: make test PKG=./internal/order
## Prohibited Items
- Do not introduce new logging libraries; use the internal/log wrapper.
- Do not read environment variables directly in business code; obtain them through internal/config.
- Do not modify historical versions of database migration scripts; add new migration files only.
## Delivery Conventions
- Commit messages use Conventional style: feat/fix/docs/refactor.
- When changing external interfaces, docs/api.md must be updated at the same time.

4. Writing Principles: Make Constraints Directly Executable

Commands are better than descriptions. Write make test instead of “please run the relevant tests first.” Commands remove ambiguity and leave no room for the assistant to guess the tool name.

Examples are better than abstractions. Instead of saying “follow the existing layering conventions,” provide a short code snippet that follows the convention and point to a reference file path.

Absolute paths are better than relative references. Use full paths relative to the repository root, and avoid vague references such as “that file mentioned above” or “the configuration directory” that require looking back at conversation history.

Negative constraints must come with an alternative path. If the rule says “do not use a certain type of client directly,” add guidance such as “call through the internal/client wrapper; see X for an example.”

Mark applicable conditions. For rules that apply only in specific scenarios, state the trigger condition, such as “applies only when writing database migrations,” to reduce irrelevant context injection.

Control file size and use hierarchical references. Large repositories can adopt a “main file plus subdirectory files” structure: the main file stays concise and contains only global constraints, while module-level details are placed under their respective directories and loaded when the assistant works in that directory. This preserves information completeness without exhausting the context window all at once.

AI_CONTEXT.md                # Global: tech stack, commands, red lines
internal/order/README.md     # Order module: state machine, idempotency conventions
internal/order/ai-note.md    # Common pitfalls and typical modification patterns for this module

5. Division of Labor Between Project Rule Files and Task-Level Skills

Project rule files and task-level skills are often confused with each other, but they are designed for different purposes. Mixing them can cause the rule file to expand quickly.

Dimension	Project rule file	Task-level skill
Trigger condition	Always active	Expanded on demand when the description matches
Content nature	Facts and constraints	Procedural workflows
Size requirement	Should be as concise as possible	Can carry longer steps and resource references
Typical content	Tech stack, commands, red lines	Release checklists, data migration steps, interface change templates

The judgment criterion is simple: if a piece of content is not needed in every conversation, it should be moved out of the rule file, rewritten as an independent workflow, and loaded by the model only when needed.

6. Common Anti-Patterns

• Writing prose: long background stories and historical narration provide little constraint value and consume context budget. Remove vague phrases such as “we believe” or “based on past experience.”
• Copying public knowledge: general language syntax and basic framework usage do not need to be included because the model already understands them.
• Being inconsistent with the code: if the build commands in the rule file differ from the repository’s real commands, the model will prefer the rule file and keep producing commands that cannot be executed. The rule file must be reviewed together with the code.
• Using vague wording: words such as “try to,” “if necessary,” and “depending on the situation” weaken constraints. Replace them with decidable expressions such as “must,” “prohibited,” or “when X happens, do Y.”
• Including sensitive information: credentials, tokens, internal network addresses, and personal information must never be placed in rule files. These files are often committed with the repository or synchronized into the context, creating a large exposure surface. Credentials should be injected through environment variables or a secret management service.
• Endless appending: piling every historical mistake into the file eventually dilutes critical constraints because the file becomes too large. It is recommended to perform a pruning review every quarter.

7. How to Measure and Iterate

Tuning a rule file should be quantifiable rather than based on intuition. Consider tracking the following metrics:

• First-pass success rate: the proportion of changes produced by the assistant that pass validation without manual modification.
• Rework count: the average number of iterations required for the same requirement.
• Invalid edit rate: the proportion of files created or modified by the assistant that should not have been touched.
• Validation failure rate: the first-time failure rate of generated artifacts during build, static checking, and testing.

A practical closed-loop process is to ask after each rework: “Can this error be prevented by one rule?” If yes, add that rule and attach the corresponding command or example. Repeated failure patterns should be distilled into task-level workflows rather than stuffed into the main rule file. Execution records and logs can be archived in a logging service or object storage for periodic regression analysis. Such workflows can be handled with common container platforms and logging services, without additional customization.

Finally, it is recommended to place the rule file under version control and code review, and update it together with the code. A reviewed AI_CONTEXT.md that stays within a reasonable size and contains only real project facts provides far more efficiency than stacking prompt techniques, because it solves not “the model is not smart enough” but “the model does not understand your project.”