From cec65014fc7efe94eae29de55e12a0688bc451cd Mon Sep 17 00:00:00 2001 From: Eduardo Dantas Date: Fri, 14 Aug 2026 19:18:54 -0300 Subject: [PATCH] docs(agents): document instruction loading budget (#1810) Document the repository AGENTS.md loading budget and keep detailed workflows outside the always-loaded instruction file. Main changes: - Add an AGENTS.md Loading Budget section. - Keep the root AGENTS.md focused on repository-wide invariants and precise routing gates. - Direct detailed workflows to versioned documentation or reusable skills instead of expanding the root instruction file. - Document that Codex applies a combined instruction budget across global, root, and nested guidance. - Record the default 32 KiB instruction limit and recommend preserving headroom for narrower scoped instructions. - Keep mandatory gates near the beginning of the instruction chain. - Recommend removing duplicated guidance and routing conditional details before increasing project_doc_max_bytes. - Preserve the existing client-assets routing contract and documentation reference unchanged. Validation: - Audited the effective global and repository instruction chain at 11,106 bytes. - Verified the instruction chain remains below the 24 KiB maintenance target and default Codex limit. - Verified the existing client-assets documentation route remains valid. - Reviewed the complete committed diff. - Ran Git whitespace validation successfully. - No build was run because this is a documentation-only change. This keeps repository instructions concise and scalable while preserving room for nested guidance and avoiding unnecessary duplication in the always-loaded AGENTS.md. --- AGENTS.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d71ceca89..cc02bfab3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,11 @@ # AGENTS.md +## AGENTS.md Loading Budget + +- Keep this root file limited to repository-wide invariants and precise routing gates; place detailed workflows in versioned documentation or skills. +- Codex applies a combined instruction budget (32 KiB by default) across global, root, and nested guidance. Keep mandatory gates first and preserve headroom for narrower scopes. +- Do not raise `project_doc_max_bytes` as the first response to oversized guidance; remove duplication and route conditional detail first. + ## Client Assets Gate (Mandatory) Any change touching client-assets auto-installation must preserve the runtime contract below: @@ -25,4 +31,3 @@ Any change touching client-assets auto-installation must preserve the runtime co - Explicitly state tested install paths and expected runtime load behavior. Reference: `docs/client-assets-auto-install.md` -