From 1257ef2fd0bda8b7cabc37dcc68a33f230106c4f Mon Sep 17 00:00:00 2001
From: Jon Ross-Perkins <jperkins@google.com>
Date: Thu, 5 Mar 2026 13:35:40 -0800
Subject: [PATCH] More GEMINI.md file work (#6840)

We may want to split some out to skills, I'm just trying to merge in
some info of my own now.

Assisted-by: Google Antigravity with Gemini 3 Flash

---------

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
---
 GEMINI.md | 134 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 95 insertions(+), 39 deletions(-)

diff --git a/GEMINI.md b/GEMINI.md
index ff91371fb3ed..5aaf6d6cb8b8 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -1,4 +1,4 @@
-# Gemini & AI Assistant Guide for Carbon
+# Gemini & AI assistant guide for Carbon
 
 <!--
 Part of the Carbon Language project, under the Apache License v2.0 with LLVM
@@ -10,41 +10,73 @@ This document provides high-density technical context for AI assistants (and
 humans!) contributing to the Carbon Language project. If you are an AI
 assistant, **read this first** to avoid common pitfalls.
 
-## Table of Contents
+## Table of contents
 
--   [Project Structure](#project-structure)
--   [Building and Testing](#building-and-testing)
--   [Debugging and Diagnostics](#debugging-and-diagnostics)
--   [C++ Coding Patterns](#c-coding-patterns)
--   [Common Pitfalls](#common-pitfalls)
+-   [General instructions](#general-instructions)
+-   [Project structure](#project-structure)
+-   [Toolchain architecture](#toolchain-architecture)
+-   [Building and testing](#building-and-testing)
+-   [Debugging and diagnostics](#debugging-and-diagnostics)
+-   [C++ coding patterns](#c-coding-patterns)
+-   [Common pitfalls](#common-pitfalls)
 
-## Project Structure
+## General instructions
 
--   **`toolchain/`**: The C++ implementation of the compiler (Toolchain).
-    -   `toolchain/check/`: Semantic analysis (SemIR generation).
-    -   `toolchain/parse/`: Parsing (Token -> Parse Tree).
-    -   `toolchain/lex/`: Lexing (Source -> Tokens).
-    -   `toolchain/sem_ir/`: Semantic Intermediate Representation (SemIR)
-        definitions.
-    -   `toolchain/lower/`: Lowering to LLVM IR.
--   **`proposals/`**: Evolution proposals.
+-   **Communication**: Be concise, professional, and technical. Use GitHub-style
+    markdown.
+-   **Verification**: Always run relevant tests.
+-   **Tool usage**: Use web search for any research outside the immediate
+    codebase or KIs.
 
-> **Note**: The **`explorer`** codebase (a prototype interpreter) has been moved
-> to its own repository. You may see references to it in old proposals or
-> documentation, but it is not part of the active `toolchain` development in
-> this repository.
+## Project structure
 
-## Building and Testing
+-   **[`common/`](common/)**: Common C++ utilities used across the project.
+-   **[`core/`](core/)**: The Carbon standard library (Core).
+-   **[`docs/`](docs/)**: Project documentation, design, and style guides.
+-   **[`examples/`](examples/)**: Example Carbon programs and code snippets.
+-   **[`proposals/`](proposals/)**: Evolution proposals.
+-   **[`testing/`](testing/)**: Testing utilities and infrastructure.
+-   **[`toolchain/`](toolchain/)**: The C++ implementation of the compiler
+    (Toolchain).
+    -   [`base/`](toolchain/base/): Base infrastructure and common utilities.
+    -   [`check/`](toolchain/check/): Semantic analysis (SemIR generation).
+    -   [`lex/`](toolchain/lex/): Lexing (Source -> Tokens).
+    -   [`lower/`](toolchain/lower/): Lowering to LLVM IR.
+    -   [`parse/`](toolchain/parse/): Parsing (Token -> Parse Tree).
+    -   [`sem_ir/`](toolchain/sem_ir/): Semantic Intermediate Representation
+        (SemIR) definitions.
 
-We use [Bazel](https://bazel.build/).
+## Toolchain architecture
 
-### Essential Commands
+-   **Documentation**: Refer to [`toolchain/docs`](toolchain/docs) for detailed
+    architecture design and patterns.
+    -   Refer to [Toolchain Idioms](toolchain/docs/idioms.md) for a
+        comprehensive list of patterns (for example, `ValueStore`, formatting
+        `.def` files, struct reflection) used throughout the implementation.
+-   **Phases**: Lex -> Parse -> Check -> Lower.
+-   **Definitions**: Many kinds (tokens, parse nodes, SemIR instructions) are
+    defined in `.def` files and expanded by way of macros.
+-   **Handlers**:
+    -   Parser: `Handle<StateName>` in `parse/handle_*.cpp`.
+    -   Checker: `HandleParseNode` in `check/handle_*.cpp`.
+    -   Lowering: `HandleInst` in `lower/handle_*.cpp`.
+-   **Iteration**: Prefer iterative algorithms over recursive ones to prevent
+    stack exhaustion on complex codebases.
 
--   **Test everything**: `bazel test //...`
--   **Test specific target**: `bazel test //toolchain/check:check_test`
--   **Build toolchain**: `bazel build //toolchain/...`
+## Building and testing
 
-### Updating Test Data
+AI assistants should use `bazelisk` instead of `bazel` for build and test
+commands, because some AI editors won't see `bazel` aliases.
+
+### Essential commands
+
+-   **Test everything**: `bazelisk test //...`
+-   **Test specific target**: `bazelisk test //toolchain/testing:file_test`
+-   **Test specific file**:
+    `bazelisk test //toolchain/testing:file_test --test_arg=--file_tests=<path_to_carbon_file>`
+-   **Build toolchain**: `bazelisk build //toolchain/...`
+
+### Updating test data
 
 Carbon tests often use `file_test` (for example,
 `//toolchain/testing/file_test`). If you change compiler behavior, you likely
@@ -59,16 +91,30 @@ of expected output.** Use the script:
 
 ### Pre-commit
 
-Running `pre-commit` is mandatory.
+Running `pre-commit` is mandatory. To run it on all files:
 
 ```bash
 pre-commit run -a
 ```
 
-## Debugging and Diagnostics
+To validate a specific list of files:
 
--   **Printing to stderr**: Use `llvm::errs() << "debug info\n";` or
-    `std::cerr`.
+```bash
+pre-commit run --files <files>
+```
+
+### Formatting
+
+-   **C++**: Always check `clang-format` on C++ files.
+-   **Carbon**: The toolchain's `format` command doesn't work well right now.
+    Instead, try to format Carbon code based on other Carbon files and the C++
+    style.
+-   **Markdown**: Use `pre-commit run prettier --files <file.md>` to format
+    markdown files correctly.
+
+## Debugging and diagnostics
+
+-   **Printing to stderr**: Use `llvm::errs() << "debug info\n";`.
     -   Avoid `std::cout` (it may interfere with tool output).
 -   **SemIR Stringification**:
     -   SemIR objects often have a `Print` method or `operator<<`.
@@ -78,31 +124,39 @@ pre-commit run -a
         but often running the binary directly from `bazel-bin/` is easier for
         debugging.
 
-## C++ Coding Patterns
+## C++ coding patterns
 
 Carbon's toolchain uses LLVM-style C++ with some specific conventions.
 
-### Error Handling
+-   **Style Guide**: Follow the
+    [Carbon C++ Project Style Guide](docs/project/cpp_style_guide.md).
+-   **Markdown style**: Follow the
+    [Google developer documentation style guide](https://developers.google.com/style).
 
--   **No Exceptions**: We do not use C++ exceptions.
+### Error handling
+
+-   **No exceptions**: Do not use C++ exceptions.
 -   **`ErrorOr<T>`**: Return `ErrorOr<T>` for fallible operations.
     -   Check with `if (auto result = Function(); result) { Use(*result); }`
 -   **`llvm::Expected<T>`**: Similar to `ErrorOr`, used when interfacing with
     LLVM.
 
-### Casting (LLVM Style)
+### Casting (LLVM style)
 
 -   Use `llvm::cast<T>(obj)` (checked, asserts on failure).
 -   Use `llvm::dyn_cast<T>(obj)` (returns null on failure).
 -   Use `llvm::isa<T>(obj)` (boolean check).
 -   **Avoid** `dynamic_cast` and standard RTTI.
 
-### Data Structures
+### Data structures
 
--   Prefer LLVM ADTs: `llvm::SmallVector`, `llvm::StringRef`, `llvm::DenseMap`.
+-   Prefer APIs in `common/` and `toolchain/base/` over LLVM ADTs. For example,
+    use `Map` instead of `llvm::DenseMap`.
+-   If no Carbon API exists, prefer LLVM ADTs over standard library ones (for
+    example `llvm::SmallVector`, `llvm::StringRef`).
 -   `StringRef` is a view; be careful with lifetimes.
 
-## Common Pitfalls
+## Common pitfalls
 
 1.  **Legacy `explorer` references**: The `explorer` prototype has been moved.
     Ignore references to it in proposals or old docs; focus on `toolchain`.
@@ -110,5 +164,7 @@ Carbon's toolchain uses LLVM-style C++ with some specific conventions.
     can do it for you.
 3.  **Using `std::string` unnecessarily**: Prefer `llvm::StringRef` for
     arguments.
-4.  **Header Includes**: We use specific include orders (often enforced by
+4.  **Header includes**: Use specific include orders (often enforced by
     `clang-format`).
+5.  **Parse node order**: Semantics processes parse nodes in post-order; ensure
+    your parser transitions support this.