AI coding guidelines template for engineering teams

01 / Decision

Separate guidance from enforcement

An instruction can shape behavior, but it does not guarantee compliance. Put conventions in readable guidance, encode objective invariants in automated checks, and use real permissions or sandboxing when an action must be impossible.

02 / Workflow

Build the guidelines in six passes

Start from a real workflow and the failures you need to prevent. The first version should be short enough to test this week and explicit enough that a teammate can tell when to stop.

1. 01

   Set the non-negotiable boundaries

   List prohibited data, destinations, credentials, production actions, and legal or security decisions. Name the approved escalation path. Do not hide these boundaries inside a general style guide.

   Output: A short boundary section reviewed by the people who own security, privacy, and production access.

2. 02

   Separate guidance by scope

   Keep rules that apply everywhere at the organization or repository level. Put directory-specific architecture notes near the relevant code, and move detailed task procedures into focused playbooks or skills.

   Output: A small map showing which instruction source owns each kind of decision.

3. 03

   Define the task contract

   For each repeated workflow, state the trigger, required inputs, expected output, allowed tools, and definition of done. A task contract is more actionable than a collection of prompt tips.

   Output: One repeatable task with observable inputs, outputs, and stop conditions.

4. 04

   Name authoritative context

   Point to the current architecture notes, conventions, examples, commands, and source files the agent should trust. Prefer links and scoped references over copying large documents into every instruction file.

   Output: A minimal context pack with a canonical source and owner.

5. 05

   Make verification and handoff explicit

   List the checks the agent can run, the evidence it must report, and the decisions a human still owns. Require a stop when permissions, requirements, sensitive data, or destructive effects are unclear.

   Output: A verification checklist plus an unambiguous human handoff rule.

6. 06

   Test, publish, and assign an owner

   Run the same representative fixture with the intended tools and a teammate who did not write the guidelines. Fix ambiguous instructions, publish the working version, and define the events that trigger review.

   Output: A reproducible result, named owner, review date, and change trigger.

03 / Record

A copyable AI coding guidelines template

Replace the brackets with your team’s reality. Delete sections that do not change a decision, and link repeated procedures to focused playbooks instead of expanding this file indefinitely.

Purpose and scope

Who and which repositories or workflows these guidelines cover.

Allowed work

Tasks agents may perform and the permissions each task can use.

Data boundaries

Secrets, personal data, customer data, and destinations that are prohibited or restricted.

Authoritative context

Canonical conventions, architecture notes, commands, examples, and owners.

Verification and handoff

Required checks, evidence, stop conditions, and decisions reserved for humans.

Ownership

Maintainer, review date, and events that require the guidelines to be tested again.

# AI-assisted development guidelines

Owner: [team or person]
Applies to: [repositories, paths, and workflows]
Last reviewed: [date]

## 1. Allowed work
- Agents may: [approved tasks]
- Agents may use: [approved tools and access]
- A human must approve: [decisions or effects]

## 2. Data and access boundaries
- Never provide: [secrets, personal data, customer data]
- Never send data to: [prohibited destinations]
- Stop when: [permission or identity is unclear]

## 3. Authoritative context
- Repository guidance: [canonical file or URL]
- Architecture and conventions: [canonical sources]
- Commands and fixtures: [tested sources]

## 4. Working rules
- Inspect the relevant code and instructions before editing.
- Keep changes inside the requested scope.
- Do not invent requirements, APIs, metrics, or compatibility claims.
- Report assumptions and conflicts before they affect the result.

## 5. Verification
- Run: [tests, type checks, linters, or review fixture]
- Confirm: [security, privacy, performance, or product checks]
- Report: [evidence required with the handoff]

## 6. Stop and hand off
Stop when the task requires [production access, destructive action,
unclear authority, sensitive data, or another team-owned decision].
Escalate to: [role or team]

## 7. Reusable workflows
For each repeated task, link one focused playbook or skill with its
trigger, inputs, output, tools, checks, canonical source, and owner.

## 8. Review triggers
Test these guidelines again when [tool, model, repository architecture,
permissions, regulation, or repeated failure] changes.

04 / Pitfalls

What makes guidelines fail

05 / Checklist

Ready to share with the team?

• The guidelines name their owner, scope, and review trigger.
• Sensitive data, access, and prohibited actions are explicit.
• Organization, repository, path, and task guidance are kept separate.
• Each repeated workflow has a trigger, expected output, and stop condition.
• Verification requires observable checks and a truthful handoff.
• A second teammate reproduced the workflow with the intended agent path.