Skip to content

ci(docs): fail CI when root AGENTS.md exceeds 24 KiB - #208

Merged
Harold Hunt (huntharo) merged 1 commit into
mainfrom
ci/agents-md-size-limit
Nov 19, 2026
Merged

Harold Hunt (huntharo) merged 1 commit into
mainfrom
ci/agents-md-size-limit

Conversation

@huntharo

Copy link
Copy Markdown
Contributor

Summary

Adds a CI guard that fails when the repository-root AGENTS.md grows past 24 KiB (24,576 bytes).

Codex reads at most project_doc_max_bytes of AGENTS.md (32 KiB by default) and silently drops the rest, and Claude Code loads the whole file into every thread's first turn. PwrSnap's AGENTS.md grew to 212 KB and Codex agents saw it cut off near line 760 of 3,603. 24 KiB leaves headroom for nested AGENTS.md files. PwrRoute's root AGENTS.md is 12,383 bytes, so this only adds the guard. It matches pwrdrvr/PwrAgent#3918.

  • scripts/check-agent-instructions-size.mjs: a dependency-free Node script with an exported pure checkAgentInstructionsSize() and the 24 KiB constant. The failure message says how many bytes over the file is and how to fix it.
  • scripts/check-agent-instructions-size.test.mjs (node:test): sweeps sizes across the boundary for several limits, checks the limit is under Codex's 32 KiB, and checks that the classifier job runs the check before classifying, without continue-on-error.
  • Classify Changes job: a sparse checkout of AGENTS.md and the script, then a step that runs it. Docs-only PRs pass through this job.
  • cargo xtask lint runs the new test and the check, so Typecheck runs it too.
  • One line in AGENTS.md › Docs & conventions gives the limit and the command.

Required checks

The "Protect main" ruleset requires Typecheck, Build and Test. A skipped required check counts as passing. All three jobs already use !cancelled() && (needs.changes.result != 'success' || …), and classify-changes.test.cjs covers that. So when the size step fails Classify Changes, Typecheck still runs, repeats the check through cargo xtask lint, and turns red. No workflow if: or ruleset change is needed.

Verification (macOS, local)

  • actionlint .github/workflows/ci.yml: clean
  • node --test scripts/check-agent-instructions-size.test.mjs scripts/ci/classify-changes.test.cjs: 93/93 pass
  • node scripts/check-agent-instructions-size.mjs: AGENTS.md is 12383 of 24576 bytes. A 24,577-byte copy fails with exit 1 and (1 over); a 24,576-byte copy passes.
  • cargo fmt --check and cargo check -p xtask: pass
  • I did not run the full cargo xtask lint (clippy, cargo-deny, notices) locally; CI's Typecheck runs it.

@huntharo
Harold Hunt (huntharo) merged commit fd1ae13 into main Nov 19, 2026
13 checks passed
@huntharo
Harold Hunt (huntharo) deleted the ci/agents-md-size-limit branch November 19, 2026 04:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant