Repository navigation
feat: add instruction-file-size check - #34
Draft
fcbwilliams wants to merge 2 commits into
Draft
fcbwilliams wants to merge 2 commits into
fcbwilliams wants to merge 2 commits into
Conversation
Agent instruction files (CLAUDE.md, AGENTS.md and what they pull in with @path imports) are loaded into the agent's context in every session, so a file that grows past Claude Code's own warning size (40,000 characters) costs every session that loads it. The check reads the git index, so it judges what a commit will hold, follows imports transitively (each file once, so a cycle ends), and measures instruction files that link to the same file once, at that file. The message names the file, its size, the limit, and suggests moving detail into docs/ with a pointer. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…own does Imports and link targets were looked up as git pathspecs, so a directory or a pattern after an @ counted whichever file it matched first, and @.. failed the whole run. Lookups are now exact (--literal-pathspecs, the listed path must equal the one asked for), and a path that leaves the directory the checks run in is ignored. A fence closes only on a run of the same character at least as long. The README says the import model and default are Claude Code's, that the check sums a file with its imports, and that other agents read their files differently. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A new file-tree check,
instruction-file-size. It fails when an agent instruction file (CLAUDE.mdandAGENTS.mdby default), together with the files it pulls in through@pathimports, holds more thanmaxCharacterscharacters. The default is 40,000, the size at which Claude Code warns that a largeCLAUDE.mdwill hurt performance.instruction-symlinksdoes, so a pre-commit run judges what the commit will hold.@scope/name), a handle, a directory, a pattern, a home-directory path or an untracked path after an@is ignored. Fenced code blocks and inline code spans are skipped.CLAUDE.mdandAGENTS.mdboth link toREADME.md, asinstruction-symlinksasks, the README is measured once and the violation is reported there, naming both.instruction-file-size/too-large. The message names the file, its size (and each import's), the limit, and suggests moving detail intodocs/with a pointer.files,directories(globs, asinstruction-symlinkstakes),maxCharactersandfollowImports.Why
An instruction file is loaded into every agent session. Past a certain size it crowds out the work and gets skimmed. The limit and the import model are Claude Code's. The check is stricter than Claude Code's own per-file warning, because it sums a file with what it imports, which is what the session actually loads. The README says that other agents (Codex, for one) read their files differently, so
filesandmaxCharacterscan be set per agent. This comes from an assessment of which repository conventions a conformance tool should enforce, in which a maximum instruction-file size was the first rule asked for.Not done here
The check is not switched on in
test/self-conformance.integration.test.ts. This repository'sREADME.mdis about 82,000 characters, andCLAUDE.mdandAGENTS.mdlink to it, so it would fail at the default. Whether to split the README or leave the check off here is your call.Known limits are in the README: escaped spaces and
#fragments in import paths, multi-line code spans, and ancestor instruction files that are loaded together.Tests
src/checks/instruction-file-size.integration.test.tsuses git fixtures. It covers: clean, too large, shared symlink targets, transitive imports with a cycle,followImports: false, ignored@text, directories and patterns and.., an import that is itself a link, nested fences, staged-over-working-tree content, globbed directories, and a run outside git. There are also schema cases inconfig.unit.test.ts.pnpm lint:check,pnpm typecheckandpnpm testpass locally.🤖 Generated with Claude Code