The landscape of software development is continually evolving, with Artificial Intelligence (AI) rapidly integrating into our daily workflows. Command-line interface (CLI) agents represent a significant leap in this evolution, bringing the power of Large Language Models (LLMs) directly into the developer’s terminal.
These AI assistants are designed to accelerate development by understanding natural language prompts and executing complex coding tasks, from generating and explaining code to refactoring and debugging. This direct integration eliminates the need to constantly switch between web applications and the terminal, fostering a more efficient and seamless developer experience.
Google’s Gemini CLI is a prominent example of such an open-source AI agent, offering unmatched access to Gemini’s capabilities directly from the command line. It provides a versatile utility for a wide range of tasks, including content generation, problem-solving, deep research, and task management. For professional developers, programmers, and anyone interested in AI coding, Gemini CLI, especially when guided by project-specific context, can significantly enhance productivity and code quality. Gemini CLI shares technology with Gemini Code Assist, offering AI assistance in both the terminal and VS Code.
Understanding GEMINI.md
To truly harness the power of Gemini CLI and similar AI agents in a production codebase, it’s not enough to simply ask them to “write code”. These intelligent agents perform optimally when provided with structure, constraints, and clear intentions. This is where the GEMINI.md file becomes indispensable, acting as your project’s persistent AI memory and instruction set.
What is GEMINI.md?
GEMINI.md is a special Markdown file that provides instructional context to the Gemini model. It functions as a configuration file for the AI, setting its rules, guiding its behavior, and tailoring its responses to your specific project’s needs. By defining project goals, key folders, coding standards, and special instructions within this file, you can ensure that the AI’s generated content is consistent and aligned with your project’s standards.
How GEMINI.md Works:
The Gemini CLI supports a hierarchical memory management system using GEMINI.md files. This means that the AI combines instructional context from multiple locations, with more specific files overriding or supplementing content from more general ones. The loading order, from most general to most specific, is:
- Global Context:
~/.gemini/GEMINI.mdapplies system-wide instructions to all your projects. This could include general coding styles or communication preferences. - Project/Ancestor Context: The CLI searches from your current directory up to the project root (identified by a
.gitfolder) forGEMINI.mdfiles, providing project-specific context. - Sub-directory Context:
GEMINI.mdfiles located in subdirectories allow for component-specific or module-specific instructions.
This hierarchical approach allows for highly granular control over the AI’s behavior, ensuring it has the most relevant information at any given time. You can view the combined content of all loaded GEMINI.md files using the /memory show command, and reload them with /memory refresh.
Why GEMINI.md Works?
The effectiveness of GEMINI.md stems from its ability to provide the AI with a comprehensive understanding of the project’s ecosystem. Without this context, Gemini might act on its own assumptions, leading to inconsistent style or logic. By explicitly defining expectations and constraints, GEMINI.md helps the AI to:
- Follow conventions: Your project documentation effectively becomes the AI’s instruction set, eliminating the need for custom prompts for every task.
- Enhance accuracy: Tailored instructions lead to more accurate and relevant generated content.
- Improve consistency: By setting coding standards and team norms, the AI ensures consistency across the codebase.
- Reduce “cognitive overhead”: Just as deep nesting or package explosion can confuse human developers, clear documentation in
GEMINI.mdhelps the AI navigate and understand the project.
GEMINI.md Examples and Samples
Let’s look at practical examples of how GEMINI.md can be structured to guide Gemini CLI:
1. General Project Overview and Guidelines (./GEMINI.md)
This file, placed at the root of your repository, provides a high-level technical overview and general implementation standards.
# Loanchy - Technical Overview
This document provides a technical overview of the Loanchy project, intended for development and maintenance purposes.
## Project Structure
- **Framework**: [Next.js](https://nextjs.org/) (React)
- **Language**: [TypeScript](https://www.typescriptlang.org/)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/)
- **UI Components**: [Shadcn/UI](https://ui.shadcn.com/)
- **State Management**: React Context API, [React Hook Form](https://react-hook-form.com/) for forms
- **Data Fetching/Backend**: [Firebase](https://firebase.google.com/) (Firestore, Authentication)
- **AI Integration**: [Genkit](https://firebase.google.com/docs/genkit)
- **Package Manager**: npm
## Key Scripts
- `npm run dev`: Starts the development server.
- `npm run build`: Creates a production build.
- `npm run start`: Starts the production server.
- `npm run lint`: Lints the codebase for errors.
- `npm run typecheck`: Runs the TypeScript compiler to check for type errors.
## Architectural Notes
- The application follows a standard Next.js App Router structure.
- Reusable UI components are located in `src/components`.
- Firebase configuration and utility functions are in `src/lib/firebase.ts`.
- Global styles and Tailwind CSS configuration are in `src/app/globals.css` and `tailwind.config.ts` respectively.
- The application is a Progressive Web App (PWA), with configuration in `public/manifest.json`.
- Firebase Firestore rules are available in `firebaserules.txt` file.
## Implementation standard.
- DO NOT over engineer things. Start with the simplest implementation.
- Always keep the performance and security as a first priority.
- Ask for any clarification rather just guessing things if you are not clear about anything.2. Specific Library Guidelines (~/.gemini/GEMINI.md or project-level GEMINI.md)
This type of GEMINI.md can provide detailed instructions on coding style, JSDoc comments, functional programming paradigms, and dependency management for a specific language or library.
# Project: My Awesome TypeScript Library
## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 18+.
## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).
## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.
## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.3. “Plan Mode” Configuration (~/.gemini/GEMINI.md or project-level GEMINI.md)
You can configure Gemini CLI to operate in a strict “Plan Mode,” where it only researches, analyzes, and creates detailed implementation plans, without generating code or modifying files. This is useful for complex tasks requiring approval before execution.
# Gemini CLI Plan Mode
You are Gemini CLI, an expert AI assistant operating in a special 'Plan Mode'. Your sole purpose is to research, analyze, and create detailed implementation plans. You must operate in a strict read-only capacity. Gemini CLI's primary goal is to act like a senior engineer: understand the request, investigate the codebase and relevant resources, formulate a robust strategy, and then present a clear, step-by-step plan for approval. You are forbidden from making any modifications. You are also forbidden from implementing the plan.
## Core Principles of Plan Mode
- **Strictly Read-Only:** You can inspect files, navigate code repositories, evaluate project structure, search the web, and examine documentation.
- **Absolutely No Modifications:** You are prohibited from performing any action that alters the state of the system. This includes:
- Editing, creating, or deleting files.
- Running shell commands that make changes (e.g., `git commit`, `npm install`, `mkdir`).
- Altering system configurations or installing packages.
## Steps
1. **Acknowledge and Analyze:** Confirm you are in Plan Mode. Begin by thoroughly analyzing the user's request and the existing codebase to build context.
2. **Reasoning First:** Before presenting the plan, you must first output your analysis and reasoning. Explain what you've learned from your investigation (e.g., "I've inspected the following files...", "The current architecture uses...", "Based on the documentation for [library], the best approach is..."). This reasoning section must come **before** the final plan.
3. **Create the Plan:** Formulate a detailed, step-by-step implementation plan. Each step should be a clear, actionable instruction.
4. **Present for Approval:** The final step of every plan must be to present it to the user for review and approval. Do not proceed with the plan until you have received approval.
## Output Format
Your output must be a well-formatted markdown response containing two distinct sections in the following order:
1. **Analysis:** A paragraph or bulleted list detailing your findings and the reasoning behind your proposed strategy.
2. **Plan:** A numbered list of the precise steps to be taken for implementation. The final step must always be presenting the plan for approval.
NOTE: If in plan mode, do not implement the plan. You are only allowed to plan. Confirmation comes from a user message.4. GitHub Action Development Guidelines (GEMINI.md for specific repositories)
For specific projects like developing a GitHub Action, GEMINI.md can outline core principles and roles.
# Gemini Assistant Guidelines for Developing this GitHub Action
This project is a **composite GitHub Action**, designed to be reusable, efficient, and secure for other developers.
Your primary goal is to ensure that any changes you make adhere to the best practices for creating high-quality GitHub Actions.
### Core Principles for This Action
1. **Understand the `action.yml` Manifest:**
- This is the heart of the action. It defines inputs, outputs, branding, and the execution steps.
- When adding or modifying functionality, ensure the `action.yml` is updated clearly and correctly.
- Inputs should have clear descriptions and indicate whether they are required.
2. **Embrace Composability:**
- This is a composite action, meaning it runs a series of shell commands. This makes it lightweight and fast.
- Prefer using standard, portable shell commands (`sh`) to ensure compatibility across different runners.
- Avoid introducing complex dependencies that would require a containerized action unless absolutely necessary.
3. **Security is Paramount:**
- **Never expose secrets.** Use `inputs` for required tokens and keys, which users will provide via `secrets` in their workflows.
- **Principle of Least Privilege:** When documenting required permissions for the action (in the `README.md`), always recommend the minimum set of permissions necessary for the action to function.
4. **Prioritize User Experience:**
- **Clear Documentation:** The `README.md` is our user manual. It must be kept up-to-date with any changes to inputs, outputs, or required permissions. Usage examples are critical.
- **Informative Logging:** The action should produce clear log output that helps users understand what it's doing and diagnose problems.
- **Graceful Failure:** If the action encounters an error, it should exit with a non-zero status code and provide a meaningful error message.
5. **Maintain Workflow Examples:**
- The files in the `/examples` directory are crucial for demonstrating how to use this action.
- Ensure they are kept in sync with the latest features and best practices.
### Your Role in Development
When asked to modify the action, you should:
1. **Analyze the Request:** Understand how the requested change impacts the `action.yml`, the shell scripts, and the documentation.
2. **Plan Your Changes:** Propose a plan that includes modifications to all relevant files.
3. **Implement and Verify:** Make the changes and ensure the action still functions as expected. While we can't run the action here, you should mentally trace the execution flow.
4. **Update Documentation:** Ensure the `README.md` and any relevant examples are updated to reflect your changes.Best Practices for Maximizing Effectiveness
To truly leverage GEMINI.md and make your codebase AI-friendly, consider adopting these best practices, many of which also benefit human developers:
- Documentation as Code: Place comprehensive
README.mdfiles at the root of your project and in each package. Create aCONTRIBUTING.mddocument that explains coding practices, PR expectations, and test coverage requirements. Add inline documentation near source files or directly within files to explain non-obvious goals or techniques. Your AI will read these documents and follow them, making your project documentation its instruction set. - Minimize Package Explosion: Use a minimal number of packages with clear boundaries. AI agents, like new team members, struggle to navigate numerous packages, which add cognitive overhead.
- Simplify Project Structure: Opt for flatter directory structures with semantically meaningful names. Group related functionality rather than fragmenting it across many small files and deep nested folders. This reduces implementation time for new features for AI.
- Avoid Re-exports and Indirection: Limit re-exports to the package level. Internal re-exports (e.g., using
index.tsfiles at every level) create indirection that makes it harder for the AI to trace dependencies. - Prefer Compile-Time Validation Over Runtime Checks: Push as much validation as possible to compile time using strong typing and static analysis. This dramatically improves the AI’s ability to understand and modify code correctly, as it can rely on type checking to catch errors rather than inferring implicit conventions.
- Consolidate Linting and Formatting at the Root Level: Centralize ESLint and Prettier configurations to the root level in monorepos. This ensures consistency across packages and simplifies maintenance, as the AI doesn’t need to understand multiple different configurations.
- Avoid Overly Interdependent Configuration Systems: Favor self-contained, independent configuration files for each package or module, even if it means some duplication. This makes each package easier for the AI to understand and modify without worrying about breaking other packages or tracing complex hierarchies.
- Type-Driven Development: Define comprehensive type systems that capture the domain model and constraints. AI agents thrive on strong type signatures, which help them implement functionality correctly and reduce logical errors.
- Consistent File Organization Patterns: Implement predictable patterns for file organization within components or modules. This consistency helps AI models predict where to find related code and how components should be structured, reducing cognitive load for both AI and human developers.
- Test-Case Driven Documentation: Use well-written tests as living documentation that clearly demonstrates the expected behavior of functions and components. Tests explicitly show inputs, outputs, and expected behavior, serving as excellent guides for AI agents and ensuring documentation stays in sync with the code.
- Lean Into AI Mistakes as Feedback: When an AI assistant makes mistakes, view it as a signal that your code organization or naming might be confusing. These “mistakes” often mirror challenges a new human developer would face, providing an opportunity to refactor for clarity.
- Use AI to Refactor Your Codebase for AI: You can instruct Gemini CLI to analyze and refactor your codebase to be more AI-friendly, creating a virtuous cycle where the AI improves the codebase, making future work easier for both AI and humans.
- Be Blunt About Non-Negotiables: Clearly state in your
GEMINI.mdor session if you want Gemini to avoid certain actions (e.g., “DO NOT modify or open .env or terraform.tfstate. Ever.”). Gemini learns these rules as part of its memory and will generally respect them. - Regularly Update
GEMINI.md: As your project evolves, update yourGEMINI.mdfile to reflect changes in code style, architecture, or project goals. - Modularize Context with Imports: For larger projects, you can organize
GEMINI.mdfiles by importing other Markdown files using the@file.mdsyntax. This helps manage complex context efficiently. - Use
gemini init: For new projects, use thegemini initcommand to set up the basicGEMINI.mdfile, allowing Gemini CLI to scan your folder and prepare to assist.
Benefits to Developer Experience and Efficiency
The effective use of GEMINI.md alongside Gemini CLI’s capabilities translates directly into significant improvements in developer experience and efficiency.
- Accelerated Workflows: Gemini CLI automates repetitive tasks like code generation, test scaffolding, and documentation, allowing developers to focus on higher-value problems.
- Contextual Assistance: With
GEMINI.md, the AI has a deep understanding of the codebase, enabling it to provide relevant and accurate suggestions, fix bugs, and refactor code efficiently. - Reduced Debugging Time: Its ability to observe its own work through shell integration and file reading, coupled with self-repair capabilities, means Gemini can often identify and fix defects or misconfigurations it introduces.
- Consistent Code Quality: By adhering to documented standards in
GEMINI.md, the AI helps enforce coding styles, naming conventions, and architectural patterns across the team. - Improved Onboarding: Well-documented
GEMINI.mdfiles make it easier for new developers (and AI agents) to understand project conventions and get up to speed quickly.
Performance Insights
Google’s Gemini CLI is powered by powerful models like Gemini 2.5 Pro, offering a massive 1 million token context window. This large context enables the AI to work with extensive code files and many types of input without losing track.
Performance benchmarks indicate Gemini’s strong capabilities:
- WebDev Arena agentic task: Gemini 2.5 Pro achieved a +147 ELO (Top Rank), demonstrating its ability to create web applications quickly and accurately.
- HumanEval (code generation): Gemini 2.5 Pro showed an approximate 82% pass@1 accuracy, indicating its proficiency in generating correct code.
- SWE-Bench Verified (agentic coding): Gemini reached 63.8% accuracy, closely trailing Claude (70.3%) which benefits from a specialized thinking mode.
- Aider polyglot benchmark: Gemini came in second place with 76.9% correctly solved tests, outperforming Claude (64.9%) and showcasing its versatility across multiple programming languages.
- AIME 2024 math competition: Gemini exhibited approximately 92% accuracy, highlighting its strength in complex mathematical problems.
Studies suggest that Gemini, along with GPT-4 and Code Llama, are among the best models for code fixing and natural language processing tasks. Gemini CLI itself boasts fast startup times (0.8 seconds) and quick response times (100–200 milliseconds for commands), with low memory usage, making it efficient on most machines. Its ability to catch errors and mark them for review further streamlines the development process.
Integrating GEMINI.md as a core part of your development workflow with Gemini CLI transforms how you interact with your codebase. By providing clear, structured context, you empower the AI agent to be a highly effective pair programmer, leading to cleaner code, faster development cycles, and a more enjoyable coding experience for both human and artificial intelligence.