freeradiantbunny.org

Best Practices for Using GEMINI.md with Gemini CLI

Purpose of GEMINI.md

• Acts as the long-term memory or workspace definition for the Gemini CLI.
• Provides persistent system instructions and contextual grounding.
• Enables multi-turn reasoning across sessions in the same directory.

Best Practices

1. Define the Project or Task Scope Clearly

# GEMINI.md
	  This is a TypeScript CLI tool for analyzing CSV data and generating reports. It will be used by non-technical users and should be robust against malformed inputs.
      

2. Include Key Design Decisions

Use Deno instead of Node.js. Prefer functional programming style. Minimize third-party dependencies.
      

3. Specify Coding Conventions or Style

Follow Google TypeScript Style Guide. Unit tests must be written using Deno.test. Avoid using `any` type.
      

4. State Goals and Subgoals

## Current Goals
	  - Add support for multi-file CSV merges.
	  - Improve error handling for missing headers.
	  - Write unit tests for `analyze.ts`.
      

5. Track AI Interaction Expectations

Avoid rewriting files unless explicitly asked. Provide minimal diffs and explain the rationale.
      

6. Use Structured Markdown

Use sections with headings: ## Goals, ## Constraints, ## Known Bugs, etc. for better parsing.

7. Avoid Overloading with Logs or Irrelevant Content

Keep GEMINI.md focused and relevant—don’t use it as a README or error log.

8. Update Frequently

Maintain accuracy as the project evolves. Capture behavioral notes about Gemini itself.

9. Keep Instructions Stable Between Sessions

Archive outdated context instead of deleting it outright.

10. Keep It Under ~1,500 Tokens

Excessively long files can cause truncation of important sections in the context.

Example Template

# GEMINI.md
	  This is a command-line Python tool that analyzes server logs and produces error summaries in Markdown.
	  ## Project Goals
	  - Parse `.log` files and extract errors, warnings.
	  - Output summary report with counts and examples.
	  - Add timestamp filtering option (`--since`, `--until`).
	  ## Constraints
	  - Must run with Python 3.10+
	  - Avoid using pandas or other heavy libraries
	  - Must run on Ubuntu with no special dependencies
	  ## Style Guide
	  - Use snake_case for functions
	  - Docstrings in Google style
	  - Write unittests using pytest
	  ## Current Work
	  - Refactor `parser.py`
	  - Add test for `summarize()` function
	  ## Gemini Instructions
	  - Provide Python code suggestions with inline comments
	  - Only write one file at a time unless told otherwise
      

Using Context Engineering Documents with Gemini CLI

The Gemini CLI allows developers to interact with Google's Gemini models. To apply context engineering principles effectively, it's important to organize and supply structured context to the model.

Recommended Directory Structure

project-root/
	│
	├── context/
	│   ├── background.md
	│   ├── glossary.md
	│   ├── architecture.md
	│   └── tone_guidelines.md
	│
	├── prompts/
	│   ├── initial_prompt.txt
	│   └── refine_prompt.txt
	│
	├── src/
	│   └── ...
    

• context/: Holds reusable context engineering documents.
• prompts/: Contains initial and refining prompt templates.
• src/: Source code or other content relevant to the task.

💡 Supplying Context to Gemini CLI

You can include context manually or via scripting using command-line options:

gemini chat \
	--prompt "$(cat prompts/initial_prompt.txt)" \
	--context "$(cat context/architecture.md context/tone_guidelines.md)"
    

Or, with a merged input file:

cat context/*.md prompts/initial_prompt.txt > final_prompt.txt
	  gemini chat --input_file final_prompt.txt

Standard Workflow Summary

1. Organize context documents in a context/ folder.
2. Compose final prompt by concatenating selected context files with a base prompt.
3. Pass the composed prompt to Gemini CLI using --prompt or --input_file.
4. Automate with a shell script, Makefile, or Python runner for repeatability.

Optional: Prompt Composition Script

Example shell script:

#!/bin/bash
    cat context/*.md prompts/initial_prompt.txt > final_prompt.txt
    gemini chat --input_file final_prompt.txt

Learn More

• Gemini Developer Site
• Gemini API & CLI Tutorials
• Gemini CLI & API Docs on GitHub