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

Source: Dev.to

The Problem

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. Foreign code is expensive code.

The Solution: the Conventions Prompt

A Conventions Prompt is 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.

• 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, acting as a style + architecture contract.

How to Write It

Keep it short enough that you’ll actually use it, but specific enough to prevent drift. 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.

Template (copy & adapt)

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.

The last line is the “break glass” clause that prevents confident wrongness.

Mining Existing Conventions

You don’t need to write this from scratch. Mine it from:

• .editorconfig, eslint, prettier, ruff, go fmt rules
• tsconfig.json (strictness, module settings)
• Existing endpoints/services for patterns
• Test layout and mocking style
• Recent PRs that reviewers liked

Write down only the rules that appear repeatedly; they save the most review time, e.g.:

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

Example Snippet

If your repo has a canonical error‑handling pattern, include a short example:

// 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.

Using the Prompt: a Sample Request

Task

• Add POST /api/projects/:id/archive that marks a project archived and returns the updated project.
• Reuse the existing auth middleware.
• Return 404 if the 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/.

A good request looks like:

[Paste CONVENTIONS here]

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

The conventions + the two file paths are enough; no long explanation is needed.

Practical Ways to Store the Prompt

1. Snippet file in your editor (fastest).
2. Repository file like PROMPTS/conventions.md (best for teams).
3. Seed message in your assistant workspace (best for repeated sessions).

Teams usually choose option 2 so the prompt can be reviewed like code.

Minimal Diffs

If you want changes to blend in, aim for small diffs:

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

Add constraints such as:

• “Before adding a helper, search for an existing one and reuse it.”
• “Do not reformat unrelated code.”
• “Do not change quotes/semicolons unless required by the linter.”

Request diffs only; the goal is a PR that a reviewer can scan in ~2 minutes.

Conclusion

The Conventions Prompt isn’t about making assistants smarter; it’s about making their 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 five coding tasks. Your future self (and your reviewers) will notice.

— Nova