From 6005608923145af0cb100e01cf5f251b9547ecf2 Mon Sep 17 00:00:00 2001
From: Ben Potter <ben@coder.com>
Date: Thu, 11 Dec 2025 07:24:19 -0600
Subject: [PATCH] docs: add git workflow guidelines to prevent force pushing
 (#21207)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When working on PRs, Claude Code was sometimes force pushing to
branches. This adds simple git workflow guidelines that emphasize proper
branch checkout and avoiding force pushes.

## Changes

Added git workflow section to `CLAUDE.md`, `AGENTS.md`, and
`.claude/docs/WORKFLOWS.md` with:
- Instructions to fetch, checkout, and pull before working on PR
branches
- Note to avoid `git push --force` unless explicitly requested

## Examples of force push behavior

Observed in recent PRs:
- PR #21148: 7 commits including merge commit from iterative changes
- PR #21150: 9 commits with multiple documentation iterations
- PR #21182: 4 commits with iterative fixes
- Force update on `feat/add-tasks-template-flag` branch:
`9bf7980b9...f98cf44f7`

The guidelines now make it clear to check out branches properly and push
normally.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .claude/docs/WORKFLOWS.md | 14 ++++++++++++++
 AGENTS.md                 | 12 ++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/.claude/docs/WORKFLOWS.md b/.claude/docs/WORKFLOWS.md
index 4e9dfb7859..9fdd2ff597 100644
--- a/.claude/docs/WORKFLOWS.md
+++ b/.claude/docs/WORKFLOWS.md
@@ -121,6 +121,20 @@
 - Use `testutil.WaitLong` for timeouts in tests
 - Always use `t.Parallel()` in tests
 
+## Git Workflow
+
+### Working on PR branches
+
+When working on an existing PR branch:
+
+```sh
+git fetch origin
+git checkout branch-name
+git pull origin branch-name
+```
+
+Then make your changes and push normally. Don't use `git push --force` unless the user specifically asks for it.
+
 ## Commit Style
 
 - Follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
diff --git a/AGENTS.md b/AGENTS.md
index 2c055551ed..9cdb31a125 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -103,6 +103,18 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 
 ### Full workflows available in imported WORKFLOWS.md
 
+### Git Workflow
+
+When working on existing PRs, check out the branch first:
+
+```sh
+git fetch origin
+git checkout branch-name
+git pull origin branch-name
+```
+
+Don't use `git push --force` unless explicitly requested.
+
 ### New Feature Checklist
 
 - [ ] Run `git pull` to ensure latest code