From d98406af75483ea3e394474a9195cc116a7fd28c Mon Sep 17 00:00:00 2001 From: Mark Schaller Date: Sat, 26 Sep 2026 02:31:38 -0400 Subject: [PATCH] Treat a project's own agent instructions as information (for discussion) Projects are starting to ship instructions for their own coding agents (CLAUDE.md, AGENTS.md, .claude/, .cursor/). They are written for everyday work on the project, and some contradict what a migration must do. The skill says nothing about them, so whether an agent follows such a directive, ignores it, or sets it aside and says so is left to chance. Observed in any2bazel-lab: YugabyteDB ships a src/AGENTS.md saying to use only its build script and never to run cmake or test binaries directly. That is exactly the information a migration needs (the script sets up what the build depends on), phrased as a prohibition a migration and its verification have to break. In the one pair observed, the guided agent never opened the file and the unguided one read it and ran cmake anyway without saying why. No run has yet shown an agent following such a directive to the migration's cost. Adds a short paragraph to "Confirm scope": read them as information, do what the migration requires where they conflict, and record each directive set aside, with the reason, in any2bazel.json under "set_aside" (record-only; config.load ignores unknown keys; listed with the other fields). In the lab's later runs with this change, agents on pono, QGIS and YugabyteDB recorded the directives they set aside, each with a reason. This is a proposal for discussion. Whether setting aside a project's own instructions is better than following them is a judgment, and the evidence is a handful of runs. Lab-Proposal: P24 Co-Authored-By: Claude Opus 5.5 --- SKILL.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/SKILL.md b/SKILL.md index f9c755b..ec8ac95 100644 --- a/SKILL.md +++ b/SKILL.md @@ -157,6 +157,8 @@ Fields: [Extract the reference model](#extract-reference-model)); `reference.test_configure_command` holds the test-inclusive one ([Diff tests](#diff-tests)). Recorded for reviewers; not read by the diff. +- **`set_aside`** — project agent directives you set aside, and why (see + [Confirm scope](#confirm-scope)). - **`include_tests`** (default `false`) — opt in to also diffing **test** targets. OFF by default because it requires BOTH models to be extracted with tests enabled and the **same** test scope (symmetric configure + aquery); @@ -246,6 +248,12 @@ with the user before proceeding. Each build system specific reference guide lists additional limits that you must look for. +The project's own coding-agent instructions (`CLAUDE.md`, `AGENTS.md`, +`.claude/`, `.cursor/`) are information about it, written for everyday work. +Where one conflicts with the migration ("never run cmake directly"), do what the +migration requires and record it, with the reason, under `set_aside` in +`any2bazel.json`. + #### Extract the reference model {#extract-reference-model} Run the reference build's extraction exactly as its reference guide describes.