Config Version Control & Migration

GEMINI.md is code. It belongs in version control, it deserves pull request reviews, and it needs a migration strategy when conventions change. The most common failure mode is a GEMINI.md that was written once, checked in, and never updated. Six months later, the architecture has evolved, new conventions have emerged, and the AI is operating on stale instructions. Configuration rot is the silent killer of AI-assisted development workflows.

Migration strategies depend on team size. Small teams (2-5 developers) can update GEMINI.md in a single PR and communicate the change in standup. Larger teams need a more structured approach: version the config with a date header, maintain a changelog section within the file, and use custom commands that validate the config version against a minimum requirement. When a major convention changes — say, migrating from REST to GraphQL — the GEMINI.md update should be part of the same PR as the code migration.

# Project Config v2026.04.21
<!-- Config changelog: see git log for this file -->

## Migration Notes
- 2026-04-21: Added GraphQL conventions, removed REST endpoint rules
- 2026-04-01: Switched from Jest to Vitest — test commands updated
- 2026-03-15: Added security review persona for /review-security command

## Architecture
[current architecture — always reflects the latest state]

## Commands
[current commands — kept in sync with package.json scripts]

## Conventions
[current conventions — updated when team standards evolve]

1. Version your config Add a version date at the top of GEMINI.md. Update it with every change. This makes it easy to correlate AI behavior with configuration state.
2. Maintain a changelog section Keep a brief changelog in the file itself — three to five recent entries. For full history, rely on git log. The inline changelog helps developers quickly understand recent changes without leaving the file.
3. Couple config updates with code changes When architecture or conventions change, update GEMINI.md in the same PR. Never leave the config out of date — stale instructions actively harm AI output quality.