How to Write Project Conventions for AI Coding Assistants

When an AI coding assistant joins a project, it starts with none of your team’s implicit knowledge. If every session requires re-explaining the tech stack, layering conventions, forbidden practices, and known pitfalls from scratch, communication cost quickly turns into a double drain on context windows and API usage. A conventions file placed in the repository root and read at startup essentially turns your team’s shared agreement into a machine-readable pre-brief. You can work without one, but it’s like hiring a highly capable new developer who knows nothing about your business.

What Problem Does a Conventions File Solve?

Context windows are finite. An assistant typically understands a project by reading code, asking questions, and trial and error. A conventions file front-loads stable, infrequently changing information: what the system does, common commands, naming and layering rules, data access boundaries, and known pitfalls like time zones and callbacks. In practice, for a large backend repository, a single change often required several rounds of context-setting before conventions were written; afterward, the first proposal already aligned with standards, and repeated explanations dropped noticeably. The benefit comes from front-loading information, not from stuffing an entire handbook into every conversation.

One important caveat: longer is not better. Overly long text consumes significant context in every turn, crowding out the source code and error logs that actually need to be read. The goal is “short, precise, executable” — not an encyclopedia.

A Usable Structure Template

Use hierarchical headings so both humans and models can locate sections quickly. Here’s a sketch (replace the content with your own stack; don’t pile on irrelevant details):

# Project Conventions
## Project Overview
A backend service for user orders. State the language and framework versions, persistence approach, and primary database type. That's enough.
## Common Commands
- Local run: the run command for your build tool
- Tests: entry points for unit and integration tests
- Build: the packaging command that skips tests (note it's only for quick local verification)
## Code Standards
- Naming: camelCase in code, snake_case for table names
- Layering: the API layer handles validation and routing only; business logic lives in the domain/service layer
- Data access: no string-concatenated queries in business code — always go through mapping files or repository interfaces
## Known Pitfalls
- Timestamps in a certain business table are stored in UTC and must be converted to the local time zone for display
- Payment callbacks must use encrypted transport; local integration testing goes through a secure tunnel — never put internal network addresses into production config

Keep the overview to two or three sentences: what the service does and its main technical boundaries — no marketing copy. List only the commands the team actually types daily; don’t paste the entire build manual. Writing explicit “don’ts” and “where this logic must live” works far better than vague guidance like “write elegant code.” Only record pitfalls you’ve actually hit that still affect code changes, and delete outdated ones.

Why Writing It Saves Tokens

In every turn, the assistant includes the conventions text along with the files relevant to the current task. When the information is correct, you skip a round of “how does your order state machine work?” — one fewer full round trip. Incorrect or irrelevant long text, however, keeps occupying space. So the maintenance principle is: only write what the assistant can’t infer at a glance from the directory structure and where getting it wrong is costly. If the directory layout, public interfaces, or test names are already self-explanatory, don’t repeat them.

A useful mental model splits content into three tiers: startup essentials (overview, commands, hard rules), task-specific context (supplied by a human in the conversation as module notes), and archived knowledge (design documents live elsewhere in the repo; the conventions file only points to their paths — never paste them in full).

Length and Maintenance Boundaries

Aim to keep the root conventions file within one to two screens of reading. When a module is especially complex, use a subdirectory conventions file or a relative path pointing to a separate document, rather than endlessly appending to the root file. Review it regularly: update it when standards change, and remove pitfalls that have been fixed. Include the conventions file in code reviews so knowledge doesn’t live only in the original author’s head.

Common mistakes: turning personal preferences into team-wide mandates; committing secrets or internal network addresses into the repository; and writing long, conversational prose that the model can’t extract constraints from. Express rules as short, checkable statements, such as “the API layer must not contain transactions or inventory deductions.”

Pairing Conventions with Session Techniques

Conventions handle stable knowledge; dynamic issues still depend on the current conversation. When changing an endpoint, explicitly provide the entry class, expected behavior, and test command — far more reliable than just saying “fix the payment flow.” When the task requires external systems, browser access, or specialized protocol capabilities, describe it neutrally as “reading documentation or calling internal interfaces through controlled tool extensions,” and limit permissions and scope — never hand production secrets to a session environment.

When token usage spikes, first check whether you’ve been repeatedly stuffing an overly long conventions file, irrelevant logs, or whole-repository search results into the same session. Starting a fresh session, narrowing the working directory, and sharing just the failing test snippet instead of the full log are usually more effective than simply “compressing your writing style.”

A Launch Checklist

• A short conventions file exists in the repository root and is read by the assistant at startup
• It contains the overview, commands, hard rules, and still-valid pitfalls
• No secrets, no outdated design dumps, no duplicated source code
• The file is updated in sync during code reviews
• Validated with a real change: did the first-round proposal already follow the layering and naming rules?

Treat your project conventions file as a versioned engineering asset, not a one-time prompt. That’s what turns an AI coding assistant from “capable but clueless about your project” into “a collaborator that follows the team’s conventions.” The maintenance cost is low; what you save is the background explanation you’d otherwise repeat in every single turn.