Instruction Files That Make Generated Code Match Your Conventions

Tier: Core · Workflow area: Feature development

This playbook covers writing one that measurably changes behavior, and using it to make boilerplate generation actually convention-conformant.

When to use

• •
  You correct the same stylistic or architectural mistakes in AI output repeatedly.
• •
  Onboarding agents (or humans) to a repo with strong conventions.
• •
  Before any scaffold-heavy work: CRUD endpoints, DTOs, serializers, test files.

Skip elaborate instruction files for throwaway repos and spikes.

Prerequisites

• •
  A tool that reads repo instruction files (most agents and Copilot do; check your tool's filename convention).
• •
  Three to five real examples of AI output your team had to correct — instructions grounded in observed failures beat aspirational style guides.
• •
  Agreement (or at least non-objection) from the team: this file speaks for everyone.

The workflow

1. 1.

   Collect the correction log. Skim recent PR comments and your own fixes to AI output. Write each as a rule candidate: "used raw asyncpg query → must go through app/repositories/", "invented error format → must use ApiError".

2. 2.

   Write the file: facts, rules, and pointers. Keep it under ~150 lines. Structure that works:

   Copy

   # Project notes for AI assistants
   
   ## Stack facts
   - FastAPI + SQLAlchemy 2.0 (async), Postgres, Alembic migrations.
   - Tests: pytest + pytest-asyncio; run `make test-fast` (no network).
   
   ## Hard rules
   - All DB access goes through app/repositories/*. Never inline SQL in routes.
   - Errors: raise ApiError(code, http_status) from app/errors.py. Never
     return ad-hoc {"error": ...} dicts.
   - Logging: `logger = structlog.get_logger()`; no print(), no f-string logs.
   - New endpoints: router in app/api/<domain>.py, schema in app/schemas/,
     repository method, and a test in tests/api/ - all four, every time.
   
   ## Look at these examples first
   - app/api/orders.py - canonical endpoint shape.
   - tests/api/test_orders.py - canonical test shape.
   

3. 3.

   Test it with an A/B generation. In a scratch branch, run the same scaffold request twice — once before committing the file, once after:

   Copy

   Add a CRUD endpoint set for "warehouses" (id, name, region, active).
   Follow project conventions.
   

   Diff the outputs against your rules. Rules the model still violates are worded too vaguely — rewrite them as imperatives naming files ("use X from Y"), not prose ("prefer clean error handling").

4. 4.

   Use pointers over prose. The single highest-leverage line is "copy the shape of app/api/orders.py". Models follow concrete exemplar files far more reliably than abstract rules.

5. 5.

   Maintain it like code. When a new correction pattern shows up twice in review, it becomes a rule. When the stack changes (SQLAlchemy 2.0 migration done, logger swapped), prune stale rules the same day — a wrong instruction file is worse than none.

Tool variants

• Claude Code:CLAUDE.md at repo root (plus per-directory files for monorepos); loaded automatically every session.
• GitHub Copilot:.github/copilot-instructions.md conditions chat, agent mode, and code review; path-scoped *.instructions.md files for per-area rules.
• Cursor / others:.cursor/rules (or AGENTS.md, an emerging cross-tool convention). Same content works across all three — write once, symlink or duplicate.

Verification

• •
  The A/B test in step 3 shows concrete behavior change (repository layer used, correct error type, test file created unprompted).
• •
  A scaffolded endpoint passes review with fewer than three convention comments.
• •
  Grep the file monthly against reality: every named path and command still exists.
• •
  New teammates confirm the file also works as human onboarding notes — if it confuses humans, it confuses models.

Pitfalls

• The 600-line style bible. Long files dilute attention; models silently drop mid-file rules. Cap it, and cut anything a linter already enforces.
• Aspirational rules. "Write clean, SOLID code" changes nothing. Every rule should be checkable by grepping the diff.
• Set-and-forget. Stale instructions ("we use Flask" — you migrated last quarter) actively corrupt output.
• Duplicating the linter. If ruff/ESLint/mypy already blocks it, the instruction file should not spend lines on it — point the agent at the linter command instead.

Restricted-environment variant

Instruction files are part of the repo and never leave it — they work unchanged with client-sanctioned enterprise tools (Copilot Business reads copilot-instructions.md from the client repo). For local-model workflows, paste the instruction file at the top of each session as the system-style preamble; keep a short version (under 40 lines) for small local models, which follow fewer rules reliably. Never encode client-confidential architecture secrets in the file if the repo is ever shared with third-party contractors.

Success criteria

• •
  Convention corrections on AI-assisted PRs drop visibly within two weeks.
• •
  Scaffolding a standard endpoint (all four files) is a one-prompt operation.
• •
  The file is under 150 lines, reviewed in normal PRs, and no rule is stale.
• •
  Two different tools (e.g., Copilot and a terminal agent) produce convention-conformant code from the same file content.