Product case study · October 23, 2026

Gemini CLI GEMINI.md: Check Context Before You Code

Create a small GEMINI.md fixture, inspect loaded instructions, reload an edited rule, and separate visible context from verified agent behavior.

Reading time
6 min
Checked
Oct 23, 2026
Charcoal inspection frame over a muted blue paper instruction card beside stacked cream sheets and an ochre card
Make one instruction visible, change it, and verify the reload before trusting the next response.
Bottom line

Inspect loaded context before debugging the prompt. A visible instruction is evidence of loading, but only a reviewed result demonstrates compliance.

If Gemini CLI keeps missing a project convention, first check whether the instruction reached the session. Repeating the same prompt cannot tell you whether a file was discovered, whether an edit was reloaded, or whether the model ignored an active rule.

This exercise gives each question a separate check. You will create one synthetic instruction file, inspect it inside the CLI, change a marker, and review a short response.

Sources checked October 23, 2026. This is a documentation-backed lab. We have not run an authenticated Gemini CLI session here; the expected checks below are acceptance criteria, not reported model results. You need Bash, Git, an installed Gemini CLI and configured authentication. Check your account’s data and billing terms before sending material; use only the synthetic input below.

Make one context file you can recognize

The official GEMINI.md guide describes reusable instructions loaded from global and workspace locations, with more specific context discoverable during tool access. This means a project file may coexist with other instructions. Our lab avoids nested files so the first check stays small.

Run these shell commands outside your working repositories. mktemp creates a fresh directory; keep its printed path for later review.

lab_dir=$(mktemp -d /tmp/gemini-context-lab.XXXXXX)
cd "$lab_dir"
pwd
git init -q
gemini --version > cli-version.txt
cat > GEMINI.md <<'CONTEXT'
# Synthetic context inspection lab

Context marker: paper-crane-v1

For the lab response:
- Begin with the active context marker on its own line.
- Then provide exactly two bullet points.
- Use only the synthetic facts in the user's message.
- Do not edit files or execute shell commands for this response.
CONTEXT
cat GEMINI.md
gemini

Keep normal approval prompts enabled. The instruction against tool execution expresses the task’s scope; it is not an access-control mechanism. Decline any unexpected tool request. Do not put credentials or private project details in this file.

Inspect before asking for an answer

Inside the interactive CLI, enter:

/memory show

The command reference documents this as the view of combined loaded instructions. Search the displayed text for paper-crane-v1 and the two-bullet rule. Record the relevant excerpt locally. Avoid sharing the entire output: unrelated global instructions might contain private details.

A file count in the footer is insufficient. Your first acceptance criterion is the actual marker and rule appearing in loaded context. If they are absent, stop before trying the response prompt.

Now submit:

Synthetic facts: The sample project is called Lantern. Its review day is Friday.
Summarize these facts using the lab response format. Do not use tools.

Review the answer against this human-written checklist:

  • The first line is paper-crane-v1.
  • Exactly two bullet points follow.
  • The answer preserves Lantern and Friday without adding people, deadlines or claims.
  • No tool execution or file change was requested or performed.

Passing this case shows compliance on one simple input. It does not establish reliability across coding tasks.

Change the marker while the session stays open

In another terminal, open the printed scratch-directory path and edit only GEMINI.md: replace paper-crane-v1 with paper-crane-v2. Save it. Do not ask the agent to make this edit; you want an independent change to test reloading.

Return to the same Gemini CLI session:

/memory reload
/memory show

The context guide documents reload. The command reference also documents refresh; official pages differ in naming. If your installed version rejects reload, inspect /help and use /memory refresh if supported. Keep the version and the command that worked in your notes.

Check that the loaded instruction block now contains paper-crane-v2 and no longer contains paper-crane-v1. Repeat the synthetic prompt. The answer should now begin with v2 and retain the two-bullet format. An answer that repeats v1 fails this check even if its factual content is correct.

Earlier conversation messages can still mention v1. Inspect the loaded instruction block separately from chat history. If that distinction remains unclear, start a fresh session from the same directory and inspect context again.

Diagnose the failed layer

ObservationInspect next
Neither marker appearsConfirm launch directory, saved filename and effective context settings.
v1 remains in loaded instructionsConfirm the edit was saved at the correct path, then retry the supported reload command.
Both markers appear in loaded instructionsLook for duplicate context files or imports; remove ambiguity before continuing.
v2 loads but the answer uses v1Record a compliance failure; retry in a fresh session rather than claiming reload failed.
Output adds unsupported factsTighten the task and review again; context visibility does not validate factual accuracy.

The configuration reference exposes context.fileName, which can select a different filename or several names. It also documents discovery limits and ignore settings. Inspect effective settings before renaming files or widening discovery. The context guide describes just-in-time loading, while the configuration page also describes recursive discovery; do not assume every nested file is loaded at startup on every version.

For this lab, retain the default filename and one root file. Leave global configuration unchanged. You are testing a small observable contract, not redesigning your entire instruction hierarchy.

Keep the evidence small

Save the CLI version, your two file revisions, the relevant loaded-context excerpts, and both reviewed answers in the scratch folder. Record failures too. Do not commit account settings or full session dumps merely to prove that a marker loaded.

Before using this technique in a real project, replace the marker exercise with one actual convention and a small reviewable task. For example, ask for a proposed change using your documented test command, then inspect the proposal before allowing execution. Retest after changing the instruction file.

Exit the CLI when finished. Keep or manually remove only the scratch directory you created. The agent harness comparison lesson provides a broader framework for choosing where repository work and persistent automation belong.

Official source notes

All checked October 23, 2026:

  • Provide context with GEMINI.md files: context locations, inspection and reloading.
  • CLI commands: /memory show, refresh naming and interactive help.
  • Gemini CLI configuration: configurable context filenames and discovery settings. Its discovery description differs from the context guide, so the lab checks observed loading instead of promising one universal traversal order.

Put this to work

Distinguish instruction discovery, reloading and compliance.

Try

Create a scratch project with one synthetic context marker and a response format rule.

Prove it worked

Record the loaded marker before and after an edit, then review a small answer against the rule.

Keep in view

  • A GEMINI.md file supplies reusable instructions to Gemini CLI.
  • Inspect the loaded text before assuming your project rule is active.
  • Check a changed marker and the resulting answer as separate proofs.
Learn the workflow: Compare agent harnesses and their working boundaries