Split AGENTS.md into scoped documents by codebase - #1568
Conversation
The root `AGENTS.md` was ~1300 lines, and every agent session paid for all of it: an agent writing Rust loaded ~700 lines of TypeScript/JSDoc style, an agent fixing a changelog entry loaded the effects-chaining rules. It also half-duplicated `CONTRIBUTING.md`, `todo/README.md`, and `changelog/README.md`, so the copies could drift. The root file is now a 97-line map: a header brief (monorepo layout, issues in `todo/`, the check set, the two top principles) plus five brief-and-link sections. Each brief carries the one fact an agent must not violate without reading further, then links to the document that owns the detail — so every fact still has exactly one home. Detail moved to documents co-located with what they govern, following the same pattern `todo/` files already use: - `fjs/AGENTS.md` — §3 testing/proof coverage, §4 documentation, §6.1-6.6 coding style. - `nanvm-lib/AGENTS.md` — §1.6 cargo commands and §6.7 Rust style. - `DESIGN.md` — §5 design principles in full. They apply to both code bases, so neither scoped file was right; the repo root already holds `CONTRIBUTING.md` and `CONTRIBUTORS.md`, so this needs no new directory. This resolves the open question the issue left for implementation. - `CONTRIBUTING.md` absorbs §1 (the twelve-row runner table, Node test-runner compatibility, dependency updates) and §8.5 commit messages — title form and squash-merge are pull request process, not changelog content. - `todo/README.md` absorbs §7's GitHub-intake rules; `changelog/README.md` absorbs §8.3 entry rules and §8.4 breaking changes and versioning. Text was relocated rather than rewritten, so the diff is reviewable as a move; tightening any moved section is a follow-up. Deduplication happened only where a destination already stated the fact. All inbound references are repointed in this change: the four files with `AGENTS.md#` anchor links, the two commit-message `todo/` files added since the issue's inventory, and the `AGENTS.md §N.M` prose references in seven `todo/` files and six source comments. A checker over the touched documents confirms every relative link and anchor resolves, and no sentence appears in two of the seven documents. `npx tsc` is clean and `npm start test` passes 2709/2709. Changelog: none
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
functionalscript | 098349c | Commit Preview URL Branch Preview URL |
Aug 14 2026, 11:20 PM |
…-split-hfnc5f # Conflicts: # fjs/types/byte_set/todo/torangemap-payload.md
`fjs/media/revision/module.f.mjs` arrived on main with an `AGENTS.md §6.2` comment reference after the split's inventory ran. Point it at the section's new home, `fjs/AGENTS.md` §3.2.
o2alexanderfedin
left a comment
o2alexanderfedin
left a comment
There was a problem hiding this comment.
Verified against origin/main at db76410 (types/byte_set: toRangeMap carries a boolean, not an FSM payload (#1566)), tested at head 098349ce. Draft status is not a blocker. This implements the task proposed in #1560, which I reviewed; the four concerns raised there are all addressed. Approving.
Content preservation, checked mechanically
Line-level diffing is useless here — the split reflows everything — so I compared at paragraph level, whitespace-collapsed and reflow-insensitive, matching each of the old AGENTS.md's 254 paragraphs against the union of AGENTS.md, DESIGN.md, fjs/AGENTS.md, nanvm-lib/AGENTS.md, CONTRIBUTING.md, changelog/README.md, todo/README.md and docker/README.md by token-set similarity:
| match quality | count |
|---|---|
| exact (≥0.98) | 186 |
| near (≥0.70) | 30 |
| weak (0.40-0.70) | 20 |
| no match (<0.40) | 18 |
I traced all 18 no-match paragraphs by hand. Eleven are section headings that were renumbered by design (## 1. Development environment, ### 6.2 Types, …). The other seven all have homes:
- §2's numbered workflow list → prose at
AGENTS.md:46-50 - §7's
Situation | What to dotable → dissolved intotodo/README.md's existing sections, and this PR adds the two rows that were not already there (GitHub-as-intake, "do not leave a status-only tombstone") - §8.1 "only one feature/improvement with minimal code changes" →
AGENTS.md:85andCONTRIBUTING.md:161 - §8.2 "Ensure all of the checks in §2 pass" →
CONTRIBUTING.md:162 - §8.3's changelog-directory intro →
changelog/README.md - §1.1's tool/version table →
CONTRIBUTING.md; §1.6's Rust commands →nanvm-lib/AGENTS.md+AGENTS.md:77-79
I then spot-checked the load-bearing normative rules individually rather than trusting the aggregate — _-prefixed JSDoc typedefs (fjs/AGENTS.md:244-247, verbatim), the module-header blank line, recursive-constant @type/typeof, expectFailure/Node-26 test-runner compatibility (CONTRIBUTING.md), the Trigger requirement for todo/blocked/ (todo/README.md), "No regular expressions" (fjs/AGENTS.md:227-229, verbatim), and the **BREAKING CHANGES:** prefix. All present. Nothing is dropped.
Worth stating plainly, though: a fair amount is reworded and compressed, not moved verbatim — the root file goes 1362 → 97 lines. Every rule I checked survives with its normative force intact, but this is a rewrite-during-split rather than a pure move, and the PR description would be more useful to a future reader if it said so.
Links and anchors
- Anchors, repo-wide. I resolved every
[…](…#anchor)in every tracked.mdagainst the actual heading slugs of its target file: 7 broken onmain, the same 7 here, zero new. - The four inbound sources from #1560 all resolve to real anchors in their new destinations:
CONTRIBUTING.md→AGENTS.md#1-workflow(×2) andfjs/AGENTS.md#1-testing-and-proof-coverage✓docker/README.md→ retargeted fromAGENTS.md#14-ways-to-run-the-functionalscript-test-suitetoCONTRIBUTING.md#ways-to-run-the-functionalscript-test-suite✓changelog/README.md→DESIGN.md#2-the-api-is-the-most-important-part-of-quality✓fjs/bnf/todo/669-bnf-matcher-shared-core.md→../../AGENTS.md#place-curried-partial-applications-at-their-dependencys-scope(correctlyfjs/AGENTS.mdfrom that depth) and../../../DESIGN.md#2-…✓
- Broken-link sets (compared as sets, not counts): 129 on main, 129 here. The single delta is one entry moving from
AGENTS.mdtochangelog/README.md—[#NNN](url), the literal illustrative example of the old inline-PR-link style. No link is stranded. todo/agents-md-split.mdis deleted and nothing anywhere references it.- §8.5, which #1560 flagged as having no destination row, now lands as
### Commit messagesinCONTRIBUTING.md:169, reachable fromAGENTS.md:95viaCONTRIBUTING.md#opening-a-pull-request.
§-number cross-references in the moved text
The seven touched source files are JSDoc-comment-only edits that repoint AGENTS.md §N references. I checked each against the new headings rather than assuming:
AGENTS.md §6.2→fjs/AGENTS.md §3.2= Types ✓ (3 sites)AGENTS.md §6.3→fjs/AGENTS.md §3.3= Structure and scoping ✓AGENTS.md §6.4→fjs/AGENTS.md §3.4= Effects (fjs/effects) ✓AGENTS.md §5.6→DESIGN.md §6= Never precompute a size to predict whether something fits ✓ (2 sites, one of which also gains a §-number where it previously had only a bare file name)
All correct.
Gates
npx tsc --noEmit— exit 0.npm testfrom a cleaned tree — 2725 pass / 0 fail, byte-identical tomainatdb76410.npm run prepack— exit 0.- Emitted declarations, read directly rather than through
bin/extract.mjs: same.d.mtsfile set asmain; 5 files differ (media/json/rtti,media/revision,types/list,types/result,types/uint8array) and every difference is inside a JSDoc comment — stripping comment lines makes all five compare equal. No type-level surface change anywhere, so §6.2_-prefixing has nothing to apply to.
One judgement call to confirm (not a defect)
No changelog/unreleased/ entry. I think that is right — the rule exempts PRs that only touch todo/, AGENTS.md, or other documentation, and the emitted types here are provably identical. But this PR does edit seven .f.mjs/.ts files, and the published .d.mts comment text does change, so a consumer's editor tooltip will read fjs/AGENTS.md §3.2 instead of AGENTS.md §6.2. If you consider that user-visible, Changelog: none is the wrong call; if not — which is my reading — this is already correct as-is.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
3 participants
Reorganizes contributor documentation to reduce context load for AI agents and human contributors by splitting the monolithic 1300-line AGENTS.md into focused, scoped documents.
Summary
The root AGENTS.md is now a concise map (~90 lines) that links to detailed guidance co-located with the code it governs. This follows the same pattern already used for issues in
todo/directories: detailed instructions live next to what they describe.Key changes
Implementation details
https://claude.ai/code/session_01N1SYqxmeS6J6BePvGZ16Ah