🧠

Git Best Practices
& Agentic Coding

How Git discipline amplifies
in the age of AI coding agents

May 2026 · Research Synthesis · 42 slides

Agenda

▸ Part I

Git Best Practices & Branching Strategies

▸ Part II

Git Anti-Patterns — The 10 Deadly Sins

▸ Part III

Agentic Coding — Principles, Practices & Patterns

▸ Part IV

Git + Agents — Mandatory Rules, Workflows & Agent-Specific Anti-Patterns

▸ Part V

Implementation Guide & Key Takeaways

I

Git Best Practices
& Branching Strategies

The foundations every team should master

The Atomic Commit Principle

The foundational unit of good Git hygiene. An atomic commit represents one logical change — not one file, not a day's worth of unrelated work.

Good Focused & intentful

fix(auth): handle expired JWT tokens
     with 401 redirect

feat(search): add debounced input
     with 300ms delay

Bad Unfocused & vague

WIP — end of day, lots of stuff

Fixed search and also the login
bug and changed CSS and fonts…

Key practice: Stage selectively with git add -p. Split messy commits with git rebase -i before pushing.

Conventional Commits

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type	When	Example
`feat`	New feature	`feat(auth): add biometric login`
`fix`	Bug fix	`fix(search): handle empty query`
`refactor`	Code change, no behavior	`refactor(api): extract pagination`
`test`	Adding tests	`test(auth): add token refresh tests`
`docs`	Documentation	`docs(readme): add setup guide`
`chore`	Tooling/deps	`chore(deps): bump lodash`

Enables: Automated changelogs · Semantic versioning · Machine-readable history · Clean git log

Branching Strategies — Overview

GitFlow Complex

main + develop + feature/* + release/* + hotfix/*

Scheduled releases, regulated teams. High overhead for CI/CD.

GitHub Flow Simple

main + short-lived feature/* branches

Continuous delivery. Always-deployable main. Minimal overhead.

Trunk-Based Modern

Single main trunk; branches live hours/days.

Feature flags hide incomplete work. Fastest feedback loop.

GitLab Flow Balanced

main + environment branches + features

Environment visibility with simplicity.

GitFlow — The Classic Model

feature/* ──┐ │ main ◄── hotfix/* develop ◄── feature/* ▲ ▲ └── release/* ──────────┘

Pros

Clear versioning and structure
Isolates new dev from production
Great for scheduled releases + QA
Supports parallel version lines

Cons

Many branches to manage
develop branch drifts from main
High merge conflict overhead
Poor fit for continuous deployment
Even Vincent Driessen now recommends simpler models

Trunk-Based Development

feature/A ──┐ feature/B ──┐ │ │ ▼ ▼ ══════════════════════════════════════════════════ main (always deployable) ══════════════════════════════════════════════════

Branches live hours or days, not weeks
Work broken into small, independently shippable pieces
Feature flags hide incomplete features from users
CI runs on every commit and every PR
Merge frequently — avoid integration shock

Modern default for SaaS teams. Less merge pain, simpler mental model, fits continuous delivery.

Strategy Comparison

Factor	GitFlow	GitHub Flow	Trunk-Based
Release cadence	Slow/medium	Fast	Continuous
Branch lifetime	Weeks–months	Days	Hours–days
CI/CD maturity	Low–medium	Medium–high	High
Regulatory fit	Good	Poor	Needs flags
Merge conflict risk	High	Low	Very low

No one-size-fits-all. Most modern teams use a hybrid — trunk-based with occasional release branches.

Writing Great Commit Messages

Structure

fix(auth): prevent session race on
          concurrent logins

When multiple login requests arrive
simultaneously, the session token
could be overwritten. This adds a
version counter to detect and reject
out-of-order updates.

RACE-42

Rules

Subject: ≤72 chars, imperative
Body: explain what and why
Footer: ref issues, breaking changes
Blank line between subject & body

Could a colleague understand the full intent without reading the diff?

Everyday Git Hygiene

🔧 `.gitignore`

Configure at project start. Exclude build artifacts, IDE files, .DS_Store, node_modules/, .env*.

🧹 Branch Cleanup

Delete branches after merge. Automate with git branch -d. Prevent the "branch cemetery."

🔐 Protect `main`

Require PR reviews, passing CI. No direct pushes or force pushes. Main always deployable.

📦 Git LFS

For large binaries: use Git LFS instead of committing directly. Keeps repos lean, clones fast.

⚠️ Environment Branching Is Brittle

dev branch → dev environment staging branch → staging environment prod branch → production environment

Problem: Mapping branches to environments creates drift, complex cherry-picks, and confusion about what is running where.

Modern Alternative

main is the single source of truth
Pipelines deploy specific commits from main to dev, staging, production
Rollbacks: redeploy a previous commit — don't switch branches
Hotfixes: small PR → main → deploy the fix commit everywhere

Workflow: Small SaaS Team

1. Branch→ 2. Feature flag→ 3. PR→ 4. CI+Review→ 5. Squash merge→ 6. Deploy

git switch main && git pull origin main
git switch -c feature/billing-upgrade
git commit -m "feat(billing): add plan upgrade behind flag"
git push -u origin feature/billing-upgrade
# ... PR review, CI passes, squash merge ...
git tag -a v2.3.0 -m "Release v2.3.0"

Workflow: Regulated Enterprise

feature/* → main → release/Jan → QA (30 days) → Production ↑ hotfix/critical → main → backport to release/Jan

# Cut a release from main
git switch main && git switch -c release/1.5.0

# After QA, merge & tag
git switch main
git merge --no-ff release/1.5.0
git tag -a v1.5.0 -m "Release 1.5.0"

Use release branches only when needed — long QA cycles, regulatory freezes, backporting to a specific version line.

II

Git Anti-Patterns

The 10 deadly sins of version control

Anti-Patterns #1–5

#1 The Kitchen Sink Commit

One commit across 20+ unrelated files. Fix: atomic commits, git add -p, interactive rebase.

#2 Vague Commit Messages

"fix", "WIP", "magic do not touch". Fix: Conventional Commits, imperative mood.

#3 Force Push on Shared Branches

Erases colleagues' work. Fix: use --force-with-lease, never force-push protected branches.

#4 Storing Secrets in Git

API keys, passwords committed. Fix: .env in .gitignore, secrets managers, git-filter-repo.

#5 Storing Large Binary Files

Videos, PSDs committed directly. Fix: Git LFS, external asset storage.

Anti-Patterns #6–10

#6 Branch Cemetery

Hundreds of stale merged/abandoned branches. Fix: delete after merge, automate cleanup.

#7 Neglecting `.gitignore`

Build artifacts, .DS_Store, node_modules/ tracked. Fix: template at project start.

#8 Long-Lived Feature Branches

Weeks without merging → massive conflicts. Fix: short-lived branches, feature flags.

#9 Zombie Rebase

Rebasing branches others based work on. Fix: only rebase private, unpushed branches.

#10 Centralized Git Mindset

Treating Git like SVN — fear of branching. Fix: embrace branching, forks, local history.

III

Agentic Coding

Principles, practices & patterns for AI-assisted development

What Is Agentic Coding?

Collaborating with AI coding agents that autonomously read, write, modify code, execute commands, run tests, and manage Git — operating at the task level, not just autocompleting lines.

Traditional AI Assist

Line-by-line autocomplete
Chat Q&A about code
Developer drives all actions
Single-turn interactions

Agentic Coding

Multi-file implementation from specs
Runs tools: tests, linters, git, CLI
Agent plans, writes, validates, commits
Multi-turn, multi-session workflows

The shift: "Implement user authentication" → Agent plans, codes, tests, commits, opens a PR. Developer reviews, guides, approves.

The 6 Principles of Agentic Coding

1. Developer Accountability

The developer, not the AI, owns quality, security, and maintainability.

2. Understand & Verify

Never accept generated code without understanding it.

3. Security & Confidentiality

Never paste sensitive data into prompts. Exclude sensitive files.

4. Code Quality & Standards

Generated code must meet team conventions and pass quality gates.

5. Human-Led Design

Architecture and critical logic must be human-led. AI supports.

6. Recognize AI Limits

AI hallucinates, has outdated knowledge, lacks deep context.

Source: agentic-coding.github.io

28 Practices — Setup & Strategy

A Preparation & Setup

Agent rules files: AGENTS.md, CLAUDE.md with project conventions
Structure & design context: directory roles, data flow patterns, library conventions
Technology stack: versions, commands, coding standards — documented

B Strategic AI Usage

Classify tasks: AI-driven (features, refactors, tests) vs. Human-led (architecture, sensitive logic)
Adapt when stuck: switch models, provide more context, request deeper thinking
Multi-agent: one codes, another reviews; parallel task execution

28 Practices — Interaction & Prompting

🎯 Specific, Clear Prompts

State goal (What), context (Where), constraints (How). AI cannot infer omitted context.

📦 Decompose Tasks

Break into manageable units. Not too granular (loses coherence), not too large (overwhelms).

📋 Few-Shot Prompting

Include existing code examples. Agent learns style, structure, and patterns from real code.

🗺️ Explore → Plan → Code

Explore the codebase first. Create a plan. Review it. Then implement.

Critical: Monitor and interrupt when the agent goes off-track. Avoid fully autonomous modes.

28 Practices — Review & Verification

🔍 Immediately review generated code

Don't let errors compound. Catch misunderstandings early.

🚫 Never use incomprehensible code

If you can't explain it to a colleague, don't commit it.

✅ Run automated quality checks

Linters, formatters, CodeHealth scores — every commit.

🧪 Validate the tests themselves

Ensure correct assertions, adequate coverage, edge case handling.

📚 Cross-verify against docs

API usage, library versions may be hallucinated or outdated.

👥 Prepare for peer review

Indicate AI involvement so reviewers focus on agent-specific pitfalls.

28 Practices — Quality & Workflow

E Quality, Standards & Security

Enforce team standards — linters + formatters before every commit
Use .env / secrets managers; never hardcode secrets
Configure tool-specific exclusions for sensitive files
Always refactor generated code — it's a first draft, not final

F Workflow & Mindset

Checkpoint frequently: commit after each sub-task → cheap rollback points
Use AI for debugging: error analysis, log inspection, root cause identification
Share team knowledge: successful prompts, agent mistakes, lessons learned
Experiment fearlessly — with good checkpoints, rollbacks are cheap

Context Engineering & Agent Primitives

From GitHub's three-layer framework for reliable AI workflows:

🔤 Layer 1
Prompt Engineering

Markdown guides AI reasoning. Headers, lists, links as context injection points. Validation gates.

🧩 Layer 2
Agent Primitives

Reusable files: .instructions.md, .prompt.md, .spec.md, .memory.md. Modular & composable.

🎯 Layer 3
Context Engineering

Session splitting. Targeted instructions. Memory-driven dev. Domain-bound chat modes.

Agent primitives are software — these .md files need the same infrastructure as code: versioning, distribution, CI/CD integration.

Code Health Gates for Agentic Workflows

"Speed amplifies both good design and bad decisions." — Adam Tornhill, CodeScene

1. Pull Risk Forward

Assess code health before agent work. AI performs best at Code Health ≥9.5.

2. Safeguard Generated Code

Pre-commit and PR pre-flight checks. Agent enters refactoring loop on quality issues.

3. Refactor to Expand Surface

review → plan → refactor → re-measure loop. Break large legacy functions.

4. Encode Principles for Agents

AGENTS.md with workflow sequencing. Individual tools become predictable workflows.

5. Coverage as Guardrail

Strict coverage gates catch agent shortcuts (deleting failing tests).

6. Automate End-to-End

E2E tests validate full system behavior. At AI speed, this becomes non-negotiable.

Spec-Driven Development

The bridge between human intent and agent execution:

📝 `proposal.md`

Functional analysis — What, Why, Scope, Success criteria. The intent.

🏗️ `design.md`

Technical design — affected areas, endpoints, components, models. The blueprint.

✅ `tasks.md`

Ordered implementation plan with dependencies. The execution path.

Tools: OpenSpec (open-source), GitHub SpecKit. Use for large features. For small fixes, direct prompting is fine.

AGENTS.md — The Single Source of Truth

# AGENTS.md

## Technology Stack
- Flutter 3.x, Dart 3.x, BLoC for state management
- Supabase for auth/data, SQLite for local storage

## Commands
- Build: `flutter run`   ·  Test: `flutter test`
- Lint: `flutter analyze`  ·  Format: `dart format lib/`

## Git Policy
- Conventional Commits: feat:, fix:, refactor:, test:
- Atomic commits — ONE logical change per commit
- Branch: <issue>-<slug> from main, delete after merge
- Run `just format && just analyze` before every commit

## Recurring Mistakes to Avoid
- Don't store absolute paths for images (filename-only)
- Don't hardcode strings (use ARB l10n pipeline)

Review and update regularly. Ask the agent to update it after introducing new patterns.

IV

Git + Agents

Mandatory rules, workflows & agent-specific anti-patterns

Why Git Matters MORE for Agents

Agents operate at 2–3× human speed. This amplifies everything — good and bad.

Human Consequence	Agent Amplification
One bad commit → minor cleanup	10 bad commits in 5 minutes → history damage
Vague message → confusion later	50 vague agent commits → unreadable log
Accidental secret commit → remediation	Agent adds secrets from training data → undetected
Force push on shared → team disruption	Agent force-pushes autonomously → catastrophe
Forgot to run linter → CI catches it	Agent skips validation for speed → 50 unchecked commits

Lesson: "Nice to have" practices become mandatory guardrails when agents are operating.

5 Mandatory Git Rules for Agents

Rule 1 Atomic Commits Only

One logical change per commit. Conventional Commits format. Never git add -A. No "WIP" messages.

Rule 2 Branch Discipline

Short-lived feature branches from main. Delete after merge. No direct commits to shared branches. No force push.

Rule 3 Never Commit Secrets

Explicitly forbid .env files, API keys, tokens. .env* in .gitignore. Pre-commit secrets check.

Rule 4 Pre-Commit Validation Pipeline

Every commit must pass: formatting → linting → tests (at minimum changed code) → CodeHealth check.

Rule 5 Commit After Every Step

Commit at logical checkpoints. Creates natural rollback points and a clean, reviewable history.

The Agentic Git Workflow

1. EXPLORE → Read relevant files, understand context (No commits yet) 2. PLAN → Create plan.md or spec docs Commit: docs(plan): add implementation plan for X 3. IMPLEMENT → Implement step by step Commits: feat(auth): add JWT refresh logic test(auth): add token refresh tests 4. VALIDATE → Run tests, linters, formatters Commit: fix(auth): address linter warnings 5. SAFEGUARD → Pre-commit CodeHealth review, PR pre-flight 6. SUBMIT → Open PR with clear description 🔒 Agent does NOT merge — human reviews

Agent-Specific Anti-Patterns #1–4

#1 Autonomous Merging

Agent merges its own PR without review. Fix: never grant merge permissions. Require human approval.

#2 Churning Rewrites

Agent rewrites the same file repeatedly. Fix: "3-strike rule" — escalate to human after 3 failed attempts.

#3 Context Window Amnesia

Agent forgets earlier decisions, contradicts commits. Fix: .memory.md, split long tasks into sessions.

#4 Speculative Git Operations

Agent runs rebase, reset --hard, push --force speculatively. Fix: restrict dangerous commands.

Agent-Specific Anti-Patterns #5–7

#5 Deleting Failing Tests

Agent deletes tests that fail instead of fixing code. Fix: coverage gates in PR. Rule: "Never delete a test without human approval."

#6 Monolithic Agent Commits

Entire feature in one massive commit. Fix: task decomposition in spec. Enforce "commit after each task item."

#7 Ignoring `.gitignore`

Agent commits build artifacts, IDE files. Fix: pre-configure comprehensive .gitignore. Pre-commit artifact detection.

Pattern: every human inconvenience becomes a potential systemic failure with agents.

Human vs. Agent: The Amplification Gap

Anti-Pattern	Human Impact	Agent Impact
Kitchen sink commits	Harder to review	20+ bad commits/session. History destroyed.
Vague messages	Confusion later	50 "update"/"fix" commits. `git log` useless.
Force push on shared	Team disruption	Autonomous push to main. Data loss risk.
Secrets in repo	Remediation needed	Injects secrets from training data. Harder to detect.
Long-lived branches	Merge conflicts	Agent keeps rebasing → conflict loop.
Deleting failing tests	Rare (intentional)	Agent shortcut. Silent regression.

Commit Policy Template

Drop this into your AGENTS.md:

## Git Commit Policy

Every commit: <type>(<scope>): <imperative description>

Types:  feat | fix | refactor | test | docs | chore

Examples:
  feat(auth): add biometric login support
  fix(search): handle empty query returning 500
  refactor(api): extract pagination logic to util

Rules:
  • Commit after every logical sub-task
  • Never use `git add -A`; stage files explicitly
  • Run linter + formatter + tests before committing
  • Verify no secrets or build artifacts are staged
  • Never amend commits that have been pushed

V

Implementation Guide
& Key Takeaways

Putting it all into practice

Minimum Viable Agent-Git Setup

1. Create `AGENTS.md`

Tech stack, commands, conventions, Git policy, branch naming, pre-commit checklist.

2. Configure `.gitignore`

Comprehensively — before any agent work. Cover all artifacts, IDE files, .env*.

3. Pre-Commit Hooks or CI Checks

Formatting · Linting · Tests (at minimum changed files) · Optional CodeHealth via MCP.

4. Protect `main` Branch

Require PR reviews · Require passing CI · No direct pushes · No force pushes.

5. Document the Strategy

Write it in CONTRIBUTING.md. Keep lightweight. Revisit as the team evolves.

The Well-Armed Agent Stack

┌─────────────────────────────────────────────────────┐ │ AGENTS.md │ │ Always-loaded rules, tech stack, conventions │ ├─────────────────────────────────────────────────────┤ │ .github/instructions/ │ │ frontend.instructions.md (applyTo: **/*.tsx) │ │ backend.instructions.md (applyTo: **/*.py) │ │ testing.instructions.md (applyTo: **/test/) │ ├─────────────────────────────────────────────────────┤ │ .github/prompts/ │ │ code-review.prompt.md │ │ feature-spec.prompt.md │ ├─────────────────────────────────────────────────────┤ │ .agents/skills/ angular · dotnet · design │ ├─────────────────────────────────────────────────────┤ │ .memory.md Cross-session knowledge │ ├─────────────────────────────────────────────────────┤ │ specs/feature/ │ │ proposal.md · design.md · tasks.md │ └─────────────────────────────────────────────────────┘

Branching Strategy Recommendation

Most Teams

Trunk-Based Development

Single main, always deployable
<issue>-<slug> branches, 1–2 day max
Feature flags for incomplete work
Squash merge with clean message
CI on every PR and main merge
Delete branch after merge

Regulated Teams

Light GitFlow Hybrid

main as source of truth
release/* for QA stabilization
hotfix/* for urgent fixes
No develop branch
Features still short-lived from main
Release branches deleted after deploy

Key Takeaways

1 Git fundamentals are amplified

Atomic commits and clean branching aren't "nice to have" — they're mandatory guardrails at agent speed.

2 Agents need explicit rules

Humans absorb culture. Agents need it in AGENTS.md. If it's not documented, it doesn't exist.

3 Spec-driven dev is the bridge

proposal.md → design.md → tasks.md before code. Prevents scope creep and iteration waste.

4 Pre-commit gates are mandatory

Format, lint, test every commit. Manual review can't keep pace with agent velocity.

5 Never let agents merge

Human review is the final gate. Agent proposes; human disposes.

6 Checkpoint frequently

Commit after every sub-task. Cheap rollbacks. Clean history. No downside.

7 Context is the new prompt engineering

Session splitting, .memory.md, domain-scoped instructions. Treat context like a scarce resource.

8 Engineering discipline > coding speed

Agentic coding demands more discipline, not less. Code health and safeguards are the real enablers.

⚡

Git Discipline × Agent Speed

Explicit rules · Automated gates · Human oversight
These are the pillars of successful AI-assisted development.

"Speed amplifies both good design and bad decisions."
— Adam Tornhill, CodeScene

Git Best Practices& Agentic Coding

Agenda

▸ Part I

▸ Part II

▸ Part III

▸ Part IV

▸ Part V

Git Best Practices& Branching Strategies

The Atomic Commit Principle

Good Focused & intentful

Bad Unfocused & vague

Conventional Commits

Branching Strategies — Overview

GitFlow Complex

GitHub Flow Simple

Trunk-Based Modern

GitLab Flow Balanced

GitFlow — The Classic Model

Pros

Cons

Trunk-Based Development

Strategy Comparison

Writing Great Commit Messages

Structure

Rules

Everyday Git Hygiene

🔧 .gitignore

🧹 Branch Cleanup

🔐 Protect main

📦 Git LFS

⚠️ Environment Branching Is Brittle

Modern Alternative

Workflow: Small SaaS Team

Workflow: Regulated Enterprise

Git Anti-Patterns

Anti-Patterns #1–5

#1 The Kitchen Sink Commit

#2 Vague Commit Messages

#3 Force Push on Shared Branches

#4 Storing Secrets in Git

#5 Storing Large Binary Files

Anti-Patterns #6–10

#6 Branch Cemetery

#7 Neglecting .gitignore

#8 Long-Lived Feature Branches

#9 Zombie Rebase

#10 Centralized Git Mindset

Agentic Coding

What Is Agentic Coding?

Traditional AI Assist

Agentic Coding

The 6 Principles of Agentic Coding

1. Developer Accountability

2. Understand & Verify

3. Security & Confidentiality

4. Code Quality & Standards

5. Human-Led Design

6. Recognize AI Limits

28 Practices — Setup & Strategy

A Preparation & Setup

B Strategic AI Usage

28 Practices — Interaction & Prompting

🎯 Specific, Clear Prompts

📦 Decompose Tasks

📋 Few-Shot Prompting

🗺️ Explore → Plan → Code

28 Practices — Review & Verification

🔍 Immediately review generated code

🚫 Never use incomprehensible code

✅ Run automated quality checks

🧪 Validate the tests themselves

📚 Cross-verify against docs

👥 Prepare for peer review

28 Practices — Quality & Workflow

E Quality, Standards & Security

F Workflow & Mindset

Context Engineering & Agent Primitives

🔤 Layer 1Prompt Engineering

🧩 Layer 2Agent Primitives

🎯 Layer 3Context Engineering

Git Best Practices
& Agentic Coding

Git Best Practices
& Branching Strategies

🔧 `.gitignore`

🔐 Protect `main`

#7 Neglecting `.gitignore`

🔤 Layer 1
Prompt Engineering

🧩 Layer 2
Agent Primitives

🎯 Layer 3
Context Engineering

📝 `proposal.md`

🏗️ `design.md`

✅ `tasks.md`

#7 Ignoring `.gitignore`

Implementation Guide
& Key Takeaways

1. Create `AGENTS.md`

2. Configure `.gitignore`

4. Protect `main` Branch