Team GEMINI.md: shared AI conventions for multi-developer projects

When one engineer's Gemini CLI session produces different code shape than another's, the root cause is almost always context — not the tool. One person has a GEMINI.md with naming conventions; another doesn't. One has prohibited patterns listed; another discovers them through code review.

What we tried

We added a project-level GEMINI.md to the repo and had everyone pull it. That solved the conventions problem immediately. The remaining problem was personal preferences — verbosity, response language, preferred explanation style — that varied between team members.

What happened

We split the problem: project conventions go in the checked-in GEMINI.md; personal preferences go in each developer's ~/.gemini/GEMINI.md. The project file is a team contract. The user file is personal configuration.

What we learned

Two-layer structure:

repo/GEMINI.md         ← checked into git — the team contract
~/.gemini/GEMINI.md    ← local only — personal preferences

Both files load automatically. Conflicts resolve in favor of the project file.

What the project GEMINI.md should contain:

# Stack

Next.js 15 App Router, TypeScript strict, Tailwind CSS v4.
Path alias: @/* → src/*.

# Code conventions

- Functional components only, no class components
- `cn()` from src/lib/utils.ts for conditional classes
- No inline styles
- No `any` type without a comment explaining why

# File placement

- Components → src/components/
- Page-level logic → src/app/ route files only
- Shared utilities → src/lib/
- Never create a new file when editing an existing one solves the problem

# Commit conventions

Imperative subject line, under 72 chars. Format: `type(scope): message`
Types: feat, fix, refactor, docs, chore

# Do not

- Add console.log without removing it
- Install new dependencies without noting it in your PR description
- Suggest class components

What goes in the user-level file:

Personal preferences that don't affect code output:

# Personal preferences

- Keep explanations short — I'll ask follow-up questions if I need more
- When suggesting multiple approaches, lead with your recommendation
- Preferred language: English

Onboarding new developers:

Make GEMINI.md part of the onboarding checklist alongside .env.example and SSH key setup. A new developer who pulls the repo and has no GEMINI.md awareness will produce inconsistent output immediately. A new developer who reads the file understands team conventions before they write their first line of AI-assisted code.

Keeping it current:

GEMINI.md drifts if no one owns it. Assign ownership the same way you'd assign ownership of CONTRIBUTING.md — a specific person, a review in the same PR when conventions change. A stale GEMINI.md that contradicts the codebase is worse than no GEMINI.md.

Review it in retros:

Once a sprint, ask: what did Gemini CLI produce that required rework? If there's a pattern, add a rule. If a rule isn't preventing anything, cut it.