From a06d8bcf82c4c83545fe91fd732406224dfee14b Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Tue, 28 Apr 2026 23:50:42 +0200 Subject: [PATCH] Promote docs/lance.md to required-read every session Adds @docs/lance.md alongside @docs/invariants.md so the Lance index loads on every turn (Claude Code @-import; explicit-open instruction for other agents). Reframes the directive from "when you hit a Lance-shaped problem" to "consult before every task to identify which upstream pages are relevant." The Lance docs are the authoritative source for substrate behavior, so reasoning about them should start every change rather than be triggered conditionally. Co-Authored-By: Claude Opus 4.7 --- AGENTS.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 31dbee9..88c6ea6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,11 +2,15 @@ This file is the always-on map for AI coding agents (Claude Code, Codex, Cursor, Cline) working in this repo. It is loaded into context on every turn, so it stays as a **map plus the rules and invariants that need to be in scope at all times** — the encyclopedia content lives under [`docs/`](docs/). When you need depth, follow a pointer. -> **Required reading every session: [docs/invariants.md](docs/invariants.md).** Load this in full before proposing, reviewing, or implementing any change — the §IX deny-list and §X review checklist apply to every PR, not only architecture work. Tools that support `@`-imports (Claude Code) auto-include it via the import below; other agents must open it explicitly at the start of each session. +> **Required reading every session, every change:** +> +> 1. **[docs/invariants.md](docs/invariants.md)** — the architectural invariants and §IX deny-list. Apply to every PR, not only architecture work. +> 2. **[docs/lance.md](docs/lance.md)** — the curated index of upstream Lance docs. **Consult it before every task** to identify which Lance pages are relevant to what you're about to do, then fetch those upstream URLs before grepping our code or guessing. Lance is the substrate; behavior is documented there, not here. +> +> Tools that support `@`-imports (Claude Code) auto-include both files via the imports below. Other agents (Codex, Cursor, Cline, …) must open them explicitly at the start of each session. > > @docs/invariants.md -> -> **When you hit a Lance-shaped problem** (file format, fragments, indexes, transactions, branches/tags, compaction, schema evolution, vector / FTS internals): consult [docs/lance.md](docs/lance.md) and fetch the listed upstream URL before grepping our code or guessing. Lance is the substrate; behavior is documented there, not here. +> @docs/lance.md `CLAUDE.md` is a symlink to this file — there is exactly one source of truth. Edit `AGENTS.md`.