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.