From 4c66849c61de93bf254cefe59f1bfede98bb5d48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 4 Sep 2026 13:57:35 -0700 Subject: [PATCH] docs: link the guides instead of importing them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `@CONTRIBUTING.md` in an agents file is an import: the whole file is pulled into context at the start of every session, whether the task touches it or not. CONTRIBUTING.md is 595 lines here, which is around six thousand tokens spent before anyone has said anything. A markdown link is the lazy form — the agent opens it when the work calls for it, and can be pointed at one section rather than the lot. README.md already referred to it this way, so the two files disagreed about how to cite the same document. AGENTS.md disagreed with itself as well, naming docs/methodology.md as an import in one paragraph and as plain text three sections later. CLAUDE.md keeps its trailing @AGENTS.md. That one is deliberate: the file exists so Claude Code finds AGENTS.md, and importing it is the whole job. The prose mention above it no longer imports a second time. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- AGENTS.md | 16 ++++++++-------- CLAUDE.md | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3cf586762..de9266f2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,10 @@ Test: `just test` | Before committing: `just ready` -Read @CONTRIBUTING.md first. It covers prerequisites, setup, project structure, -code standards, testing, input validation, and how to add an API domain. All of -which apply to agents exactly as they apply to people. This file carries only -what is specific to agents. +Read [CONTRIBUTING.md](CONTRIBUTING.md) first. It covers prerequisites, setup, +project structure, code standards, testing, input validation, and how to add an +API domain. All of which apply to agents exactly as they apply to people. This +file carries only what is specific to agents. ## Running tools @@ -28,13 +28,13 @@ treating the failure as real. `go build ./...` and `go test ./...` fail in this repository. The UI is embedded via `//go:embed dist/*`, which requires `ui/dist/` to hold files at compile time. Use `just build`, `just test`, or `just ready`. Each builds the UI first. -See @CONTRIBUTING.md under "Building and running". +See [CONTRIBUTING.md](CONTRIBUTING.md#building-and-running). ## Where the rules come from -@CONTRIBUTING.md names the specification under "Before you start". When a -convention here and the specification disagree, the specification wins. Say so -rather than following the code. +[CONTRIBUTING.md](CONTRIBUTING.md#before-you-start) names the specification. +When a convention here and the specification disagree, the specification wins. +Say so rather than following the code. ## Commit trailer diff --git a/CLAUDE.md b/CLAUDE.md index b337e5b72..6c9ea9a48 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # Claude Code -All agent guidance lives in @AGENTS.md: how to invoke tools, why the Go -toolchain is never called directly, where the rules come from, the commit +All agent guidance lives in [AGENTS.md](AGENTS.md): how to invoke tools, why the +Go toolchain is never called directly, where the rules come from, the commit trailer, and task tracking. This file exists so Claude Code finds it; the content is upstream.