GC-301a · Module 3

Shared Team Configurations

3 min read

A team-shared GEMINI.md checked into version control is the single highest-leverage configuration decision you can make. Without it, every developer's Gemini CLI session operates with different context, different rules, and different conventions. The result is inconsistent AI output that requires constant correction. With a shared config, every session starts from the same baseline — same architecture context, same constraints, same commands. Inconsistency drops to near zero for well-covered topics.

The shared config should contain only objective, team-agreed facts: architecture decisions, build and test commands, naming conventions, forbidden patterns, and domain-specific terminology. Personal preferences — response verbosity, model selection, thinking budget, editor integration — belong in the developer's global config or in a gitignored override file. The dividing line is simple: if every team member should follow the rule, it goes in the shared config. If it is a personal preference, it stays local.

Companion settings.json files (.gemini/settings.json) follow the same shared-versus-personal split. MCP servers that the whole team uses (GitHub, Jira, internal APIs) belong in the project .gemini/settings.json. Personal MCP servers (Notion, personal knowledge bases) belong in ~/.gemini/settings.json. The shared settings file should also define project-specific tool permissions — which tools are allowed, which are blocked, and which require confirmation.

  1. Bootstrap with /init Run /init to generate a starter GEMINI.md. Review the output as a team, remove inaccurate suggestions, and add your specific architecture decisions and conventions.
  2. Separate shared from personal Audit every instruction: does the whole team need this? If yes, it goes in the repo-level file. If no, it goes in ~/.gemini/GEMINI.md or a gitignored override.
  3. Add to PR template Include "GEMINI.md updated?" in your PR checklist. When architecture changes, the config should change with it. Stale configs produce stale AI output.