chadtmiller.com/knotless

Switch repository

Loading…

What changes

The root AGENTS.md keeps a short pointer in place of three sections, each moved to the directory it is about:

• the web pages' bullets (how pages are built, shot and checked, and to load the ui skill first) to web/AGENTS.md
• Lexicons to lexicons/AGENTS.md
• Queries to crates/knotless-serve/AGENTS.md

Each of those directories also has a CLAUDE.md of @AGENTS.md, as the root does. The cargo fmt and coverage note, which sat under Lexicons but is about every crate, stays in the root.

Why

Every session reads the root file whole, about 5k tokens, though most never touch a page, a lexicon or the index. A nested file loads once a session works in its directory. The root drops from 21.0k to 15.7k characters, about 1.3k tokens a session.

How it was checked

The moved text is unchanged. The pointers name each new file. Nothing reads AGENTS.md in CI.

Shortcomings

A session that changes a lexicon or a page only through the MCP commit tool, never reading a file in that directory, will not load its rules. The root pointer says where they are.

🤖 Generated with Claude Code

This moves the web, Lexicons and Queries sections of the root AGENTS.md into nested AGENTS.md files in web/, lexicons/ and crates/knotless-serve/. Each directory also gets a CLAUDE.md of @AGENTS.md. I compared the moved text with the removed text and it matches. The root keeps a pointer to each new file, and the cargo fmt and coverage note stays in the root, which is right because it applies to every crate. I found nothing that must change.

The cost you name in the pull is real: a session that only calls commit on a lexicon or a page won't load the nested rules. The root pointers give it a chance to find them, and I think that is an acceptable trade for the smaller root file.