From b494018e9c4eb310ad68d5b47da1977658f71043 Mon Sep 17 00:00:00 2001 From: Loretta Date: Sat, 4 Apr 2026 20:52:57 +0200 Subject: [PATCH] Strengthen doc-first protocol and clarify Claude mapping Updated copilot-instructions.md to enforce stricter documentation-first and multi-repo rules, including cross-repo doc loading, per-question doc checks, and improved context recovery triggers. Broadened explicit consent to all file types. Updated CLAUDE.md with sequential execution override and tool mapping, ensuring Claude follows the same protocol and rule set. --- .github/copilot-instructions.md | 15 ++++++++++++--- CLAUDE.md | 16 ++++++++++++++++ 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a1d970d..bdbf15d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,11 +11,14 @@ You are operating in a multi-repo, documentation-first architecture. You MUST ST - If `[LOADED_DOCS: NONE]` applies, you **MUST STOP** and you are **STRICTLY FORBIDDEN** to use the following tools: `code_search`, `get_symbols_by_name`, `find_symbol`, or `get_file` (for non-markdown files). - Your VERY FIRST AND ONLY allowed tool calls must be `file_search` or `get_file` targeting the `.md` documentation in the relevant `docs/` folders or `README.md`. - Do not answer the user's core question until the `[LOADED_DOCS]` list is populated with the base architecture files. - - **CRITICAL EXCEPTION:** Do **NOT** re-read `.md` files that are already mapped in your context or `LOADED_DOCS` list (strictly maintain rule 18). + - **CRITICAL EXCEPTION:** Do **NOT** re-read `.md` files that are already mapped in your context or `LOADED_DOCS` list (strictly maintain rule 3). + - **CROSS-REPO HARD-GATE:** When navigating to an external repo (via `own-dep-repos` paths), read that repo's `docs/` and `README.md` BEFORE searching its source code. The hard-gate applies to EVERY repo you enter, not just your own. + - **PER-QUESTION DOC-FIRST:** Before searching source code for any user question, check whether there is a relevant `.md` file (folder `README.md`, other repo `docs/`, etc.) that has NOT yet been loaded. Read it first — it tells you where to look in the code, saving searches and tokens. Only after loading relevant docs should you search/read source files. 3. **STRICT NO-RE-READ POLICY (ANTI-LOOP):** You are PHYSICALLY FORBIDDEN from calling `get_file` or `file_search` on any `.md` file that is already listed in your `[LOADED_DOCS]` prefix. - - Once an `.md` file is in your context, it STAYS in your context. + - **Definition:** A doc is "in your context" ONLY if you have read its actual file content via a tool call in THIS conversation. Prior session summaries, compacted messages, and memory entries do NOT count — they are lossy compressions. + - Once an `.md` file is in your context, it STAYS in your context. - Re-reading them wastes tokens and breaks the protocol. - ONLY re-read an `.md` file if the user EXPLICITLY states "the file has changed on disk, read it again". - If the user simply mentions a glossary term or requests info found in a loaded doc, answer directly from memory. DO NOT search for it again. @@ -24,11 +27,17 @@ You are operating in a multi-repo, documentation-first architecture. You MUST ST If the user asks a domain/architecture specific question and you realize the essential `.md` files are NO LONGER in your current context (they dropped out of memory), you **MUST automatically re-read** the necessary documentation before answering. Do NOT wait for the user to explicitly tell you to re-read them. Prioritize scanning the `docs/` folders to recover the lost context. + **Auto-detection triggers (MUST treat ALL docs as NOT loaded):** + - Session starts with a summary of a previous conversation (context recovery/compaction) + - Message compaction or context compression occurred mid-session + - You cannot quote the exact content of a doc you claim to know + When any trigger fires → reset `[LOADED_DOCS: NONE]` and re-read per Rule #2. + Directories to read (when recovering context): - `docs/` (in this repository root) 5. **EXPLICIT CONSENT FOR MODIFICATIONS:** - NEVER rewrite, create, or delete code/files without the user's explicit permission. If the user does not specifically request a code modification (e.g., using phrases like "we are just thinking," "what do you think," "let's plan"), you MUST ONLY provide text-based analysis and planning. You are FORBIDDEN from using file-modifying tools (`replace_string_in_file`, `edit_file`, `create_file`, etc.) until the user explicitly says "ok", "go ahead", "implement", or a similar unambiguous approval. + NEVER rewrite, create, or delete any file (code, documentation, configuration, memory, or otherwise) without the user's explicit permission. If the user does not specifically request a code modification (e.g., using phrases like "we are just thinking," "what do you think," "let's plan"), you MUST ONLY provide text-based analysis and planning. You are FORBIDDEN from using file-modifying tools (`replace_string_in_file`, `edit_file`, `create_file`, etc.) until the user explicitly says "ok", "go ahead", "implement", or a similar unambiguous approval. ## Workspace Dependencies # own-dep-repos: "name: path" — paths are relative to this repo root (.github/..) diff --git a/CLAUDE.md b/CLAUDE.md index 577d61b..d8a5d03 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1,17 @@ CRITICAL: Your FIRST action in every session MUST be reading `.github/copilot-instructions.md`. Execute ALL session-start instructions found there before responding to any user query. It is the single source of truth for this repo. + +## SEQUENTIAL EXECUTION OVERRIDE +The AI AGENT CORE PROTOCOL in copilot-instructions.md requires STRICT SEQUENTIAL execution. This OVERRIDES your default parallelization behavior. Do NOT parallelize doc reads with code searches. The sequence is: +1. Read copilot-instructions.md → process its rules FULLY +2. Read ALL docs/ .md files listed in the protocol → wait for completion +3. Output [LOADED_DOCS: ...] prefix +4. ONLY THEN respond to the user's query or search code + +## Tool mapping for AI AGENT CORE PROTOCOL +The copilot-instructions.md references Copilot tool names. Map them to Claude Code tools: +- `get_file` / `file_search` → `Read`, `Glob`, `Grep` +- `code_search` / `get_symbols_by_name` / `find_symbol` → `Grep`, `Glob` +- `replace_string_in_file` / `edit_file` → `Edit` +- `create_file` → `Write` + +Follow the protocol using YOUR tools. The rules (LOADED_DOCS prefix, hard-gate, no-re-read, context recovery, explicit consent) apply equally to Claude Code.