The Conventions Prompt: Make AI Code Changes Blend Into Your Repo

If you’ve ever asked an assistant to “just add the feature”, you know the pain:

• It adds a new folder structure you’ve never used.
• It formats code almost like your repo, but not quite.
• It invents patterns your team consciously avoided.

The result isn’t necessarily wrong — it’s just foreign. And foreign code is expensive code.

I use a simple technique to fix this: the Conventions Prompt. It’s a small, reusable block of instructions that makes every change look like it was written by someone who has lived in your codebase for months.

The idea

Most assistants are great at solving the problem and mediocre at matching your way of solving problems.

Your repo already has a culture:

• naming conventions
• error handling rules
• logging style
• preferred libraries
• “we don’t do that here” constraints
• architecture boundaries

The Conventions Prompt captures that culture in one place and attaches it to every request.

Think of it as a style+architecture contract.

What goes into a Conventions Prompt

Keep it short enough that you’ll actually use it, but specific enough to prevent drift.

I aim for 20–60 lines, grouped into sections:

1. Project shape (folders, modules, boundaries)
2. Code style (imports, naming, TypeScript settings, lint rules)
3. Runtime conventions (errors, logging, tracing, metrics)
4. Testing expectations (where tests go, what framework, what to mock)
5. Output format (diff-only, file list, or step plan)

Here’s a template you can copy.

CONVENTIONS (read first, follow strictly)

Architecture
- Don’t introduce new top-level folders.
- Keep business logic in /src/domain.
- Keep I/O (HTTP, DB) in /src/adapters.
- No cross-imports from adapters -> domain.

Code style
- TypeScript, ESM. Prefer named exports.
- Prefer early returns over nested ifs.
- Don’t change unrelated formatting.
- Use existing utilities instead of adding new helpers.

Errors & logging
- Never swallow errors.
- Throw AppError(code, message, cause?).
- Log with logger.info|warn|error({ ...context }, message).

Testing
- Use Vitest.
- Tests live next to files as *.test.ts.
- Prefer fakes over heavy mocks.

Output
- Provide:
  1) A brief plan (3–6 bullets)
  2) A unified diff only (no extra commentary)
- If any convention conflicts with the request, ask a clarifying question before editing.

That last line is important. It’s the “break glass” clause that prevents confident wrongness.

How to build it (fast) from an existing repo

You don’t need to write this from scratch. You can mine it.

1) Start with the repo’s “signals”

Look at:

• .editorconfig, eslint, prettier, ruff, go fmt rules
• tsconfig.json (strictness, module settings)
• existing endpoints/services for patterns
• test layout and mocking style
• a couple of recent PRs that reviewers liked

Write down only the rules that show up repeatedly.

2) Add 2–3 “negative constraints”

These are the rules that save you the most review time:

• “Do not add new dependencies.”
• “Do not introduce a new abstraction layer.”
• “Do not refactor unrelated code.”

Assistants love refactors. Most teams don’t love surprise refactors.

3) Add one tiny example

Examples beat descriptions.

If your repo has a canonical pattern (e.g., error handling), include one small snippet.

// Example error handling pattern
try {
  const user = await repo.getUser(id)
  if (!user) throw new AppError('NOT_FOUND', 'User not found')
  return user
} catch (err) {
  logger.error({ err, id }, 'getUser failed')
  throw err
}

The assistant will copy this like a human does.

A concrete example: adding an endpoint without style drift

Let’s say you have a TypeScript API and you want a new endpoint:

Add POST /api/projects/:id/archive that marks a project archived and returns the updated project.

Without conventions, you might get:

• a new “service layer” folder
• a new error type
• a new logging library

With a Conventions Prompt attached, the assistant has a guardrail.

A good request looks like this:

[Paste CONVENTIONS here]

Task
- Add POST /api/projects/:id/archive
- Reuse the existing auth middleware
- Return 404 if project doesn’t exist
- Add tests

Context
- Existing project routes live in src/adapters/http/routes/projects.ts
- Domain logic for projects is in src/domain/projects/

Notice what’s missing: a long explanation. You don’t need it. The conventions + two file paths are enough.

Where to store it so it’s not annoying

You have three practical options:

1. A snippet file in your editor (fastest)
2. A repository file like PROMPTS/conventions.md (best for teams)
3. A “seed” message in your assistant workspace (best for repeated sessions)

Teams usually do (2) so it can be reviewed like code.

Two upgrades that make it dramatically more reliable

Upgrade #1: The “lint is the oracle” clause

If your repo has strong linters/formatters, make them the source of truth:

• “Assume ESLint + Prettier will run. Don’t fight them.”
• “If you’re unsure about imports, follow existing files.”

This keeps the assistant from inventing style rules.

Upgrade #2: Ask for minimal diffs

If you want changes to blend in, you want small diffs.

Add:

• “Keep changes localized to the smallest number of files.”
• “Avoid moving code unless necessary.”
• “Don’t reorder imports unless you touched the file.”

The goal is a PR your reviewer can scan in 2 minutes.

Common failure modes (and quick fixes)

“It followed the style, but the architecture is off”

Your conventions are probably too code-style heavy.

Fix: add boundaries:

• allowed imports
• where domain logic lives
• which layer owns validation

“It keeps adding new helpers”

Fix: add a constraint:

• “Before adding a helper, search for an existing one and reuse it.”

(If your assistant can’t actually search your repo, give it the file names where helpers live.)

“It changed unrelated formatting”

Fix: add:

• “Do not reformat unrelated code.”
• “Do not change quotes/semicolons unless required by the linter.”

And request diffs only.

The punchline

The Conventions Prompt isn’t about making assistants smarter.

It’s about making outputs predictable, reviewable, and team-compatible.

If you only do one thing this week: write a 30-line Conventions Prompt and attach it to your next 5 coding tasks. Your future self (and your reviewers) will notice.

— Nova