Coding standards and AI workflows
for teams that ship fast and stay safe.

Protect main From Day One

Your main branch should always be deployable. Set up branch protection rules before you write a line of code:

Settings → Branches → Add branch protection rule for "main":
  ✓ Require a pull request before merging
  ✓ Require at least 1 approval
  ✓ Require status checks to pass before merging
  ✓ Require branches to be up to date before merging
  ✗ Allow force pushes (OFF)
  ✗ Allow deletions (OFF)

Trunk-Based vs. GitFlow

For most startups, use Trunk-Based Development. Everyone branches off main, works in small increments, and merges back quickly. Feature flags handle unfinished features.

	Trunk-Based	GitFlow
Best for	Startups, fast teams, CI/CD	Enterprise, long release cycles
Branch lifespan	Hours to 2–3 days	Days to weeks
Merge conflicts	Rare	Frequent
Junior-friendly	Yes (simpler mental model)	Can be confusing
AI tooling fit	Excellent	Okay

Branching Structure & Naming

main
├── feature/TICKET-123-add-video-scoring
├── feature/TICKET-124-dashboard-filters
├── fix/TICKET-125-null-pointer-on-upload
└── chore/update-dependencies

Naming rules: lowercase, hyphenated, include ticket number when one exists, 3–5 word descriptions. Delete branches after merging.

Feature Flags for AI-Heavy Teams

When Copilot helps a junior write a bigger feature than expected, resist keeping the branch alive for days. Use feature flags instead — merge incomplete features safely and activate per-environment:

# config/features.py
FEATURE_FLAGS = {
    "new_scoring_algorithm": os.getenv("FF_NEW_SCORING", "false").lower() == "true",
    "enhanced_dashboard": os.getenv("FF_DASHBOARD", "false").lower() == "true",
}

# usage
if feature_flags.is_enabled("new_scoring_algorithm"):
    result = new_algorithm.score(video)
else:
    result = legacy_algorithm.score(video)

Conventional Commit Messages

Use the Conventional Commits format. Good commit messages are your changelog, debugging breadcrumbs, and code review history in one.

<type>(<scope>): <short description>

[optional body]

[optional footer: TICKET-123, BREAKING CHANGE, etc.]

Good examples:

feat(scoring): add confidence threshold filter to video evaluation

fix(auth): handle null token on session expiry — closes TICKET-98

refactor(api): extract video upload logic into VideoService class

test(scoring): add edge case tests for zero-frame video input

Reject these in review: fix stuff, WIP, updates, asdf, Copilot suggestion

PR Size Guidelines

Large PRs are a code quality problem. AI tools make them larger (generating code is cheap). Set a soft limit and hold it:

• Under 400 lines changed: Ideal
• 400–800 lines: Okay with a good description
• 800+ lines: Requires justification. Break it up if possible.

PR Template

Create .github/pull_request_template.md in your repo so every PR answers the same questions:

## Summary
<!-- What does this PR do? One to three sentences. Be specific. -->

## Changes Made
- 
- 

## How to Test
1. 
2. 

## Screenshots / Demo
<!-- If UI changes, include a screenshot or Loom link -->

## Checklist

### General
- [ ] I have tested this locally
- [ ] I have written or updated tests for this change
- [ ] I have updated documentation if needed
- [ ] The PR is under 400 lines (or I've justified why it's larger)
- [ ] Branch is up to date with main

### Code Quality
- [ ] No hardcoded secrets, credentials, or API keys
- [ ] No debug logs, console.log, or print statements left in
- [ ] No TODO comments that should be tickets
- [ ] Variable and function names are clear without needing a comment
- [ ] Error cases are handled, not ignored

### AI-Generated Code
- [ ] I can explain every section of this code (including AI-assisted sections)
- [ ] I have reviewed AI suggestions critically and not merged blindly
- [ ] Edge cases have been considered, not just the happy path
- [ ] AI-generated logic has been verified against business requirements

### Safety-Critical (if applicable)
- [ ] This change has no effect on safety-critical paths, OR:
- [ ] I have tagged this PR safety-critical and requested senior review
- [ ] I have added/updated integration tests for affected safety logic
- [ ] I have documented the safety implications in this description

AI Review + Human Review: The Right Sequence

AI Review (automated — happens first): linting & formatting, static analysis, security scanning (Dependabot/Snyk), test coverage, GitHub Copilot PR review.

Human Review (happens second, with AI context):

• Business logic correctness — does it do what the spec says?
• Architecture and design decisions
• Edge case coverage — "what if X is null?" "what if the API errors?"
• Safety implications
• Team knowledge transfer — does the reviewer understand what's being built?

The reviewer's job is not to re-run the linter or count lines. The reviewer's job is to understand the change completely before approving.

Review Response Labels

Define what comments mean on your team. Left undefined, this creates friction.

Label	Meaning
Blocker / ❌	Must be fixed before merge
Suggestion / 💡	Take it or leave it — but acknowledge it
Nit	Tiny style thing, won't block merge
Question / ❓	Not blocking — just wants to understand
FYI	For awareness, no action needed

💡 Suggestion: You could extract this into a helper function — it's used in three places now.

❌ Blocker: This will crash if `user` is None. Need a null check here.

Nit: Prefer `is_valid` over `valid` for boolean variable names.

Review SLA

• Standard PR: Review within 1 business day
• Hotfix / unblocking: Review within 2 hours (ping the reviewer directly)
• Large PR (800+ lines): Reviewer may request a walkthrough call

Reviews that sit for more than a day create merge conflicts and kill developer momentum. Make this a cultural priority.

Pair Review for Juniors

For the first 90 days, require junior PRs to be reviewed by a senior. The fastest way to level up a junior is immediate, specific feedback on their actual code. After 90 days, adjust based on demonstrated judgment — some are ready to review peers at 60 days, some need more time. Be honest.

Python Standards

Formatter: Black — no configuration debates. Line length: 88 characters. Done.

Linter: Ruff — handles what Flake8 + isort + pep8 used to require separately, and it's much faster.

# pyproject.toml
[tool.ruff]
line-length = 88
select = ["E", "F", "W", "I", "N", "UP"]
ignore = ["E501"]  # Black handles line length

[tool.ruff.per-file-ignores]
"tests/*" = ["S101"]  # Allow assert in tests

Type hints: Required for all new code. Enable static analysis to catch bugs before runtime.

# BAD — no type hints
def calculate_score(video, weights):
    return sum(weights[k] * video[k] for k in weights)

# GOOD — explicit types with full docstring
def calculate_score(video: VideoAnalysis, weights: dict[str, float]) -> float:
    """Calculate weighted score for a video based on analysis results.

    Args:
        video: The analyzed video object containing scored dimensions.
        weights: A mapping of dimension names to their weight multipliers.

    Returns:
        A float between 0.0 and 1.0 representing the weighted overall score.

    Raises:
        KeyError: If a weight references a dimension not present in the video analysis.
    """
    return sum(weights[k] * getattr(video, k) for k in weights)

Run mypy --strict src/ in CI. Catch type errors before they reach production.

Naming Conventions

Clear naming is the single highest-leverage thing you can do for code quality. AI-generated code is often generic. Push back on generic names in review.

Context	Convention	Example
Variables	snake_case	video_score, user_id
Functions	snake_case, verb-first	calculate_score(), get_user()
Classes	PascalCase	VideoAnalysis, ScoringEngine
Constants	SCREAMING_SNAKE_CASE	MAX_RETRY_COUNT, DEFAULT_THRESHOLD
Booleans	is_, has_, can_, should_ prefix	is_valid, has_error, can_submit
Private	Leading underscore	_internal_helper()
Files/modules	snake_case	video_scoring.py, user_auth.py

Names to reject in review: data, info, stuff, temp, result, val, obj, thing, manager, handler, processor — these signal unclear responsibilities. Copilot often suggests result as a return variable. Rename it to what it is: scored_video, validated_user, parsed_config.

TypeScript Standards

Formatter: Prettier. Linter: ESLint with @typescript-eslint. Types: strict mode, always.

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

Never use any. If Copilot suggests it, reject it. If the type is genuinely unclear, use unknown and narrow it. any bypasses the entire type system.

Architecture Decision Records (ADRs)

When the team makes a significant technical decision, document it in /docs/decisions/. These are invaluable for onboarding, debugging six months later, and explaining choices to investors.

# ADR-001: Use PostgreSQL for primary data store

**Status:** Accepted
**Date:** 2026-01-15

**Context:**
Our data has strong relational structure (users → evaluations → videos → scores).
We need ACID guarantees for evaluation records.

**Decision:**
PostgreSQL, hosted on AWS RDS. ORM: SQLAlchemy.

**Consequences:**
- Schema migrations required (handled by Alembic)
- Better query performance for complex joins
- Team needs to learn SQL if they haven't yet

The 70/30 Rule

The most important mental model for AI-augmented development:

AI handles ~70%: boilerplate (CRUD, API endpoints, form validation), unit tests for well-defined functions, docstrings, error handling patterns, type annotations, refactoring repetitive code, data format conversions, SQL for standard operations, regex, commit messages, PR descriptions.

Humans own the 30%: architecture decisions, business logic (what the system should do), edge case identification, safety-critical path review, security/auth/authorization code, any code whose failure has real-world consequences, technical debt trade-offs, subtle context-dependent bugs.

The goal isn't to minimize AI use. It's to be intentional about it.

When to Use AI: The Traffic Light System

🟢 Green light — use AI freely:

• Writing a new CRUD endpoint you've written dozens of times before
• Generating unit tests for a function you just wrote
• Converting data structures between formats
• Writing docstrings for a function you just finished
• Generating boilerplate (Pydantic models, SQLAlchemy models, pytest fixtures)
• Asking "what's the idiomatic Python way to do X?"

🟡 Yellow light — use AI, but review carefully:

• Implementing business logic for the first time
• Code that touches the database schema
• Authentication and session handling
• Background jobs and async processing
• Code using third-party APIs

🔴 Red light — do not use AI as primary author:

• Security-critical logic (permissions, access control, encryption)
• Core safety-critical algorithms (see Chapter 6)
• Database migrations
• Code that processes PII or sensitive data
• Anything you don't understand well enough to explain line-by-line

Red light doesn't mean "never use AI here" — use it for reference, explaining concepts, checking your work. But the primary author must be a human who owns the logic.

The CARE Framework for Reviewing AI Code

C — Correctness: Does it actually do what it's supposed to? AI writes code that looks correct. Run it. Test edge cases. Don't just read it.

# Copilot might generate this — looks fine at first glance:
def get_user_by_email(email: str) -> User:
    return db.query(User).filter(User.email == email).first()

# What happens if email is None?
# What if there are two users with the same email?
# What does the caller do with None if no user is found?

A — Appropriateness: Is this the right approach for your system? AI doesn't know your architecture, performance requirements, or team conventions.

R — Robustness: AI tends to generate the happy path. Ask: what if the input is null? What if the network call fails? What if the list is empty?

E — Explainability: Can the developer explain every line? If not, the code does not merge. "Copilot wrote it" is not a valid explanation. This is non-negotiable.

Copilot Best Practices

1. Write intent first, let AI fill in implementation:

def calculate_driver_score(evaluation: DriverEvaluation) -> DriverScore:
    """
    Calculate final driver score from an evaluation.

    Weight the dimensions by importance:
    - Safety behaviors: 40%
    - Defensive driving: 30%
    - Vehicle control: 20%
    - Route efficiency: 10%

    Return a DriverScore with overall score and per-dimension breakdown.
    """
    # Copilot will now generate much better code because context is clear

2. Use Copilot Chat for understanding, not just generation:

• /explain — "Explain what this function does line by line"
• /tests — "Write unit tests including edge cases"
• /fix — "Here's the error I'm getting — what's wrong?"
• "What are the failure modes for this code?"
• "What security issues could this code have?"

3. Ask for tests in the same session. After Copilot helps write a function, immediately: "Write pytest tests for this function, including tests for null inputs and edge cases." Generate tests while the context is warm.

The "Explain It Back" Rule

Before any AI-generated code merges, the developer must be able to:

• Explain what the code does in plain English
• Identify the inputs, outputs, and side effects
• Describe what happens in at least three edge cases
• Explain why this approach was chosen over alternatives

If they can't do this, they need to spend more time understanding the code. This is a teachable moment, not a punishment.

Week 1: Foundation Before Code

The worst thing you can do with a new junior is throw them at tickets on day one. They'll copy-paste code they don't understand, and Copilot will help them do it faster. Week 1 is about building the map.

Day 1–2: Environment & Culture

Day 3–5: Read First, Write Second

Buddy system: Assign every new hire a code buddy — a more experienced person they can ask questions without feeling embarrassed. Junior developers will sit on a question for an hour rather than ask a "dumb question." The buddy system removes that barrier.

Weeks 2–4: Tiered First Contributions

Structure first tickets deliberately. Don't give them the hardest or most important ticket just because Copilot makes it look tractable.

Tier 1 (Week 2): Zero-stakes contributions

• Documentation improvements
• Adding missing docstrings to existing functions
• Writing tests for untested code
• Fixing linting warnings

These contributions are real, valuable, and safe. They also force the new hire to read and understand existing code.

Tier 2 (Week 3): Guided feature work

• Small, isolated bug fixes
• Adding a new API endpoint that mirrors an existing one
• Extending an existing model with a new field

First PR gets a thorough, teaching-focused review. The goal isn't just to catch problems — it's to explain why something is done differently and build judgment.

Tier 3 (Week 4): Independent feature work

• Small standalone features with full PR review process
• Must complete the full PR checklist independently
• Reviewer asks them to explain one AI-generated section

The AI Ramp-Up Path

New junior devs are often already comfortable with Copilot. The goal isn't to teach them to use it — it's to teach them judgment about when and how.

Week 1–2: AI-off exercises. Write one feature without Copilot. Turn it off. See if they can reason through the problem. This isn't hazing — it's building baseline understanding. You can't evaluate AI suggestions if you don't know what the code should look like without AI.

Week 3: AI-on, commentary required. When they use Copilot, they annotate: "Copilot suggested this. I changed X because Y. I verified it handles Z edge case."

Week 4+: Full workflow. AI tools on. But the first review of every Copilot-heavy PR includes the "Explain It Back" exercise from Chapter 4.

Code Review as Teaching

For junior developers, code reviews are the primary source of technical mentorship. The extra 30 seconds to explain why pays back in compounding improvement.

❌ Blocker: This will throw a `KeyError` if `video_id` isn't in the dict.

Instead, use `dict.get(key, default)` which returns None (or your default)
if the key doesn't exist. This is the idiomatic Python pattern for optional dict access.

dict.get(video_id) returns None if video_id isn't present.
dict.get(video_id, []) returns an empty list as default.

vs. the bad version: ❌ Blocker: This will break. — which teaches nothing.

Measuring Progress

Don't measure junior developers by hours logged or lines of code. Those metrics are meaningless with AI tools — Copilot inflates line count trivially.

Measure instead: tickets closed per sprint, PR quality improvement over time, bug introduction rate, independence (fewer clarifying questions over time), code review quality (catching real issues when reviewing others).

Review these metrics monthly in 1:1s. Developers who are improving but struggling deserve support. Developers who plateau at a low level despite support need an honest conversation.

VS Code Setup

# Install VS Code extensions
code --install-extension github.copilot
code --install-extension github.copilot-chat
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension charliermarsh.ruff
code --install-extension ms-python.black-formatter
code --install-extension eamodio.gitlens
code --install-extension streetsidesoftware.code-spell-checker
code --install-extension usernamehw.errorlens

Commit this file to the repo so all developers share the same settings:

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.ruff": "explicit",
    "source.organizeImports.ruff": "explicit"
  },
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "python.typeCheckingMode": "strict",
  "python.analysis.typeCheckingMode": "strict",
  "editor.rulers": [88],
  "editor.tabSize": 4,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "github.copilot.enable": {
    "*": true,
    "markdown": true,
    "yaml": false
  }
}

Python Environment Setup

# Install Python version manager (pyenv)
curl https://pyenv.run | bash

# Install target Python version
pyenv install 3.12.3
pyenv local 3.12.3

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dev dependencies
pip install -r requirements-dev.txt

requirements-dev.txt template:

# Core
-r requirements.txt

# Testing
pytest>=7.4
pytest-cov>=4.1
pytest-asyncio>=0.21
factory-boy>=3.3

# Type checking
mypy>=1.6

# Linting & formatting
ruff>=0.1
black>=23.0

# Development utilities
ipython>=8.0
python-dotenv>=1.0
structlog>=23.0

Git Configuration

git config --global user.name "First Last"
git config --global user.email "name@company.com"
git config --global pull.rebase true
git config --global fetch.prune true
git config --global init.defaultBranch main
git config --global diff.colorMoved zebra

GitHub Repository Setup Checklist

CI/CD Pipeline

A basic but complete GitHub Actions pipeline. CI must pass before a PR can merge — enforce this via branch protection.

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  quality:
    name: Code Quality
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dependencies
        run: pip install -r requirements-dev.txt

      - name: Lint with Ruff
        run: ruff check .

      - name: Check formatting with Black
        run: black --check .

      - name: Type check with mypy
        run: mypy --strict src/

      - name: Run tests with coverage
        run: |
          pytest tests/ \
            --cov=src \
            --cov-report=xml \
            --cov-report=term-missing \
            --cov-fail-under=80

      - name: Upload coverage report
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage.xml

Security Scanning

# Dependabot config — .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: pip
    directory: "/"
    schedule:
      interval: weekly
    open-pull-requests-limit: 5
    labels:
      - "dependencies"

# Bandit security scan — add to CI
- name: Run Bandit security scan
  run: |
    pip install bandit
    bandit -r src/ -ll  # Report medium and high severity

- name: Check for secrets in code
  uses: trufflesecurity/trufflehog@main
  with:
    path: ./
    base: ${{ github.event.repository.default_branch }}
    head: HEAD

Copilot for Teams

Copilot Business (vs. Individual) gives you: centralized license management, policy controls, audit logs, IP indemnification.

Recommended organization settings:
  ✓ Allow Copilot for all members
  ✓ Enable Copilot Chat in IDE
  ✓ Enable Copilot in GitHub.com (PR descriptions, code explanations)
  ✗ Disable: suggestions matching public code (reduces IP risk)

"Suggestions matching public code" disabled prevents Copilot from suggesting verbatim code from public repositories — reducing the risk of inheriting bugs or insecure patterns from public code.

The Setup Checklist

Use this as a day-one guide. Run it even if you think you already have everything — version mismatches bite.