Cheatsheet: AI-authored commits and PRs

Voice anchor

Git stores snapshots. Every other command is just navigating those snapshots.

Trailer reference

Purpose	Trailer
Credit AI co-author	Co-Authored-By: Claude Opus 4.7 <[email protected]>
Flag the tool used	Generated with [Claude Code](https://claude.com/claude-code)
Credit human co-author	Co-Authored-By: Pat Doe <[email protected]>
DCO sign-off	Signed-off-by: Your Name <your@email>
Credit reviewer	Reviewed-by: Reviewer Name <r@e>

Trailer placement

Always at the BOTTOM of the commit message body. Each trailer on its own line. Blank line between body and trailers. Example:

Brief one-line summary of the change

Optional longer body describing the change, with paragraphs
explaining the why and any non-obvious details.

Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 <[email protected]>

When to include, quick reference

Situation	Include trailer?
Agent typed >50% of the diff	yes
Agent drafted the commit message	yes
Agent did the structural work (you reviewed)	yes
You typed; consulted agent for one library question	no
Agent provided typeahead only, you structured	no
Agent pair-programmed (sounding board, didn’t type)	judgment call; usually no
Honest about substantial AI contribution	always include

Review lens checklist (paste into PR comment templates if useful)

For AI-assisted PRs:

- [ ] API calls verified to exist (especially newer/less-documented libraries)
- [ ] Logic walked through with concrete sample inputs (not just "looks right")
- [ ] Test assertions check meaningful properties (not just truthiness)
- [ ] Docstrings match the actual code behavior
- [ ] Edge cases enumerated and handled
- [ ] Style consistency NOT used as a proxy for correctness
- [ ] Any unfamiliar idioms verified against documentation
- [ ] No "happy path only" coverage where edge cases matter
- [ ] Author understands every line in the diff

Trailer-writing drill, model answers

1. AI refactor of a 200-line function (you reviewed):

Refactor user-profile validation into three focused functions

Splits validate_profile() into validate_required_fields(),
validate_format(), and validate_uniqueness(). Behaviorally
equivalent; tests unchanged. Improves readability and makes
each validation path easier to test in isolation.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

2. AI-written migration, then DBA-feedback hand-modifications:

Add weekly_digest_subscriptions table

Adds the table backing the new weekly digest feature.
Columns: user_id (FK), enabled (bool), sent_at (nullable
timestamp), created_at. Indexed on (user_id, enabled) for
the dispatch query.

Initial AI-generated version revised based on DBA review:
swapped INTEGER for SMALLINT on enabled, added the (user_id,
enabled) composite index, dropped the redundant updated_at.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

(The trailer is appropriate because the AI did the initial substantial typing, even though humans modified afterward.)

3. Hand-written feature, AI consulted for research only:

Add rate limiting to /api/auth/login

Implements a simple leaky-bucket rate limiter at 5 attempts per
IP per minute on the login endpoint. Failed attempts beyond the
limit return 429.

Researched bucket algorithms via Anthropic Claude. Implementation
typed by hand.

No trailer. The “researched via Claude” mention in the body is optional honesty; it’s not co-authorship.

4. Claude Code typed 250 lines of tests, human added 30:

Add comprehensive test coverage for the billing module

Adds unit tests for invoice generation, payment processing,
refund flows, and error handling. Increases module coverage
from 38% to 91%.

The human reviewer added the edge-case tests for currency
rounding and subscription mid-cycle changes.

Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 <[email protected]>

Review-lens drill, model answers

Snippet 1 (find_or_create_by_email): Hallucinated API. SQLAlchemy doesn’t have a built-in find_or_create_by_email method on User. The function would need to either query for the user and create if not found (an actual SQLAlchemy pattern) or use a library that provides find-or-create semantics. Fix: rewrite using actual SQLAlchemy patterns.

Snippet 2 (assert result is not None): Trivial test assertion. The test asserts that calculate_tax returns something non-None, but doesn’t check that it returns the CORRECT value. The function could return -1 or “hello” and the test would still pass. Fix: assert the expected value (e.g., assert result == 10.00).

Snippet 3 (E.164 formatting): Confident-but-wrong docstring. The function claims to return E.164 format (+12025551234), but only strips dashes and spaces. It doesn’t add the country code prefix or validate format. Fix: either rewrite the function to actually produce E.164 (use a phonenumbers library) or correct the docstring to describe what the function actually does.

Snippet 4 (recent orders): Looks fine; missing edge cases. Doesn’t handle: negative days (would return future-dated cutoff), days=0 (would return all orders), days too large (would silently return orders from years ago). Also no test that the function correctly handles a user with no orders. Fix: add input validation and tests for edge cases.

PR description drill, model answer

## CSV export for admin dashboard

Adds CSV export to the admin dashboard. Users can export the
current filtered view as a CSV file.

AI-assisted with Claude Code. The agent typed ~80% of the code
(the export logic in services/csv_export.py and the CSV formatter).
I typed the rest (route registration in routes/admin.py and the
integration test in tests/test_admin_export.py).

### Test plan
- [ ] Filter dashboard by date range, export, verify CSV contents match
- [ ] Filter by user role, export, verify CSV contents match
- [ ] Empty filter results: export should produce a valid CSV with headers only
- [ ] Large result set (10k+ rows): export should not time out
- [ ] CSV column ordering matches dashboard column ordering

### Notes for reviewer
- The agent's CSV formatter uses Python's csv module; please verify
  the quoting/escaping is correct for fields containing commas/quotes.
- The agent added retry logic for very large exports. Please check if
  that's necessary (we may want to limit export size instead).

Release-notes drill, model answer

User-facing:

## v2.5.0, Released 2026-06-15

Twelve improvements this release including the new weekly
digest emails, CSV export for the admin dashboard, and faster
search results. This release was produced with assistance from
Claude Code. Thanks to all contributors.

Internal changelog:

## v2.5.0, engineering notes (internal)

### AI involvement summary
Of 12 PRs in this release, 5 (42%) included AI-assisted commits
per Co-Authored-By trailers.

### Patterns observed
- CSV export PR: agent typed the export logic cleanly. Human added
  integration tests and tweaked retry behavior in review.
- Search performance PR: agent's index design hit a hallucinated
  Postgres syntax; caught in review before merge.
- Weekly digest PR: agent typed ~70%; human added user-opt-in flow
  by hand because the agent misunderstood the spec on the first pass.

### Process notes
- Continue current review checklist (hallucinated API focus has
  caught 4 instances in the last 6 weeks)
- Consider adding "verify against real DB" gate for PRs touching
  Postgres-specific syntax
- Sprint metric: AI-assisted PR throughput up 35% vs Q1, defect
  rate unchanged

Common mistakes and fixes

Mistake	Fix
Skipping the trailer when AI substantially helped	Add the trailer. It’s a 20-second convention.
Adding the trailer when you typed everything yourself	Don’t. Dilutes the signal. Be honest.
Reviewing AI code as if it were senior human code	Apply the specific failure-mode lenses; AI confidence isn’t human confidence
Pasting AI chain-of-thought as PR description	Write a human PR description; reviewers don’t need the reasoning trail
Hiding AI involvement in user-facing copy	Light release-level acknowledgment is the honest middle path
Hand-wavy “this PR was AI-assisted” without specifics	State which parts; reviewers may need to focus on specific files

What’s in L16

The closing lesson. Speculative-but-grounded look at where git might evolve in an AI-collaborative world. What new primitives might emerge. Where conventions might shift. How to stay calm as the tooling changes. Voice anchor reinforcement one last time.