top of page

Tutorial 10: Team Conventions for AI Tools

  • Contributor
  • 4 days ago
  • 2 min read

AI tools introduce new failure modes. Conventions keep the team aligned and quality high.

Step 1: Approved Tools List (10 min)

Approved:
- GitHub Copilot Business
- Cursor (with enterprise tier)
- Claude Code

Not approved:
- Personal free-tier consumer chat (sends code outside)
- Random new tools (vet before using)

Lock down which tools touch the codebase. IP / security concerns.

Update quarterly.

Step 2: PR Disclosure (10 min)

PR template:

## AI assistance
- [ ] Significant portions AI-generated
- [ ] Reviewed for security implications
- [ ] Tests verified

Disclosure normal; not punishment.

Reviewers know what bar to apply.

Step 3: Bar for AI-Generated Code (10 min)

Same as human:

  • Tests pass

  • Style matches

  • Security reviewed

  • No copy-pasted hallucinations

Don't lower the bar because "the AI wrote it." If AI's output isn't up to standard, push back.

Step 4: Sensitive Code Exclusions (10 min)

Document:

Don't use AI tools for:
- Auth / crypto code in /security/*
- PII handling in /data/*
- Billing logic in /payments/*

Off-limits areas. Either ban entirely or require strict review.

Step 5: Avoid AI on .env, secrets (5 min)

Most tools auto-detect; some don't.

Make sure:

  • .env in .gitignore + AI ignore

  • Secret files not sent to AI

  • API keys not pasted into prompts

A leaked secret via AI tool: same severity as git-committed.

Step 6: Review Standards (10 min)

For AI-heavy PRs:

  • Additional reviewer

  • Line-by-line review

  • Confirm AI didn't insert nonsense

  • Run the code, not just CI

Don't rubber-stamp AI changes.

Step 7: Education (10 min)

Onboarding includes:

  • What AI tools are approved

  • How to use them effectively

  • When NOT to use them

  • Review standards

New engineers don't know your conventions. Teach.

Step 8: Track Effectiveness (10 min)

Metrics worth tracking:

  • Time-to-ship per feature

  • Bug rate

  • Test coverage

  • PR review time

Compare pre / post AI adoption. Is it helping?

Anecdotes are unreliable. Data tells the story.

Step 9: Stay Current (10 min)

The space changes:

  • New tools

  • New models

  • New best practices

Quarterly:

  • Review your conventions

  • Try new tools (briefly)

  • Update guidance

Don't fossilize on 2024 advice.

Step 10: Don't Over-Mandate (10 min)

Mandate: "Everyone must use Copilot for all code"

Backfires. Some engineers work better without. Force = friction.

Better:

"Approved tools include X, Y, Z. Use what helps you ship quality."

Personal choice within the org's bounds.

What You Just Did

Team AI conventions: approved tools, disclosure, bar, exclusions, secrets, review standards, education, metrics, currency, no over-mandate. Standards that scale.

Common Failure Modes

No policy. Each engineer uses whatever; risks accumulate.

Over-restrictive. Engineers go around the rules.

No exclusions for sensitive code. Compliance issues.

No measurement. Don't know if AI helps.

Conventions stale. Industry moved on.

You're Done With Path 47

AI-assisted coding: tool selection, prompting, pair programming, review, refactoring, tests, debugging, agents, when not, team conventions. Modern engineering tooling.

Recommend Engineering Metrics and DORA — measure if AI is helping.

bottom of page